[feat/multicast]: Add multi-instance multicast module with active trigger system

boswatch/router/router.py

@@ -10,8 +10,8 @@
                      by Bastian Schroll
 
 @file:        router.py
-@date:        01.03.2019
-@author:      Bastian Schroll
+@date:        03.07.2026
+@author:      Bastian Schroll, Claus Schichl
 @description: Class for the BOSWatch packet router
 """
 import logging
@@ -51,32 +51,72 @@ def runRouter(self, bwPacket):
         r"""!Run the router
 
         @param bwPacket: instance of Packet class
-        @return a instance of Packet class
+        @return an instance of Packet class, a list of packets, or False
         """
         self._runCount += 1
         tmpTime = time.time()
 
         logging.debug("[%s] started", self.name)
 
-        for routeObject in self.routeList:
+        # Start processing the route list recursively from index 0
+        final_result = self._process_route_recursive(bwPacket, 0)
+
+        logging.debug("[%s] finished", self.name)
+
+        self._routerTime = time.time() - tmpTime
+        self._cumTime += self._routerTime
+
+        return final_result
+
+    def _process_route_recursive(self, bwPacket, start_index):
+        r"""!Recursively process the route to support list branching (e.g. for multicast)
+
+        @param bwPacket: current packet to process
+        @param start_index: index of the routeList to start from
+        @return processed bwPacket, list of packets, or False
+        """
+        current_packet = bwPacket
+
+        for i in range(start_index, len(self.routeList)):
+            routeObject = self.routeList[i]
             logging.debug("[%s] -> run route: %s", self.name, routeObject.name)
-            bwPacket_tmp = routeObject.callback(copy.deepcopy(bwPacket))  # copy bwPacket to prevent edit the original
 
-            if bwPacket_tmp is None:  # returning None doesnt change the bwPacket
+            # State Isolation: pass a deep copy to prevent plugins from corrupting the RAM state of subsequent list items
+            bwPacket_tmp = routeObject.callback(copy.deepcopy(current_packet))
+
+            if bwPacket_tmp is None:
+                # returning None doesnt change the current_packet
                 continue
 
-            if bwPacket_tmp is False:  # returning False stops the router immediately
-                logging.debug("[%s] stopped", self.name)
-                break
+            if bwPacket_tmp is False:
+                # returning False stops the route immediately for this specific packet branch
+                logging.debug("[%s] stopped at route %s", self.name, routeObject.name)
+                return False
 
-            bwPacket = bwPacket_tmp
-            logging.debug("[%s] bwPacket returned", self.name)
-        logging.debug("[%s] finished", self.name)
+            if isinstance(bwPacket_tmp, list):
+                # Branching logic: A module returned a list of packets
+                logging.debug("[%s] route %s returned a list. Branching for %d packets.", self.name, routeObject.name, len(bwPacket_tmp))
+                results = []
 
-        self._routerTime = time.time() - tmpTime
-        self._cumTime += self._routerTime
+                for single_packet in bwPacket_tmp:
+                    # Recursively process the rest of the route (starting at next index) for each packet
+                    res = self._process_route_recursive(single_packet, i + 1)
+
+                    # Aggregate results
+                    if res is not False and res is not None:
+                        if isinstance(res, list):
+                            results.extend(res)
+                        else:
+                            results.append(res)
+
+                # The recursive calls already finished the rest of the route for all branches.
+                # We return the aggregated results immediately to break out of this current loop level.
+                return results if results else False
+
+            # Normal single packet path: update the packet for the next iteration
+            current_packet = bwPacket_tmp
 
-        return bwPacket
+        return current_packet
 
     def _getStatistics(self):
         r"""!Returns statistical information's from last router run

docu/docs/config-editor.html

@@ -569,6 +569,21 @@ <h3>Für Entwickler: neue Module/Plugins hinzufügen</h3>
           ]
         },
 
+        "multicast": {
+          kind: "module",
+          title: "Multicast",
+          creator: "BW3 Dev Team",
+          fields: [
+            { key: "autoClearTimeout", type: "number", label: "autoClearTimeout", default: 10, required: false },
+            { key: "delimiterRics", type: "text", label: "delimiterRics", required: false },
+            { key: "textRics", type: "text", label: "textRics", required: false },
+            { key: "netIdentRics", type: "text", label: "netIdentRics", required: false },
+            { key: "triggerRic", type: "text", label: "triggerRic", required: false },
+            { key: "triggerHost", type: "text", label: "triggerHost", default: "127.0.0.1", required: false },
+            { key: "triggerPort", type: "number", label: "triggerPort", default: 8080, required: false },
+          ]
+        },
+
         // Plugins
         "http": {
           kind: "plugin",

docu/docs/develop/ModulPlugin.md

@@ -89,7 +89,8 @@ Mögliche Rückgabewerte eines Moduls:
 
 - `return bwPacket` Gibt das modifizierte bwPacket an den Router zurück (Paket Modifikation)
 - `return None` Der Router fährt mit dem unveränderten bwPacket fort (Input = Output)
-- `return False` Der Router stopt sofort die Ausführung (zB. in Filtern verwendet)
+- `return False` Der Router stoppt sofort die Ausführung für dieses Paket (z. B. in Filtern verwendet).
+- `return [bwPacket1, bwPacket2, ...]` (Liste von Paketen) Der Router startet eine automatische Verzweigung ("Fan-out" bzw. "Auffächerung"). Für jedes Paket in der Liste wird der nachfolgende Rest der Route unabhängig und isoliert durchlaufen.
 
 ### Rückgabewert bei Plugins
 Plugins geben keine Pakete mehr zurück. Sie fungieren ausschließlich als Endpunkt.  

docu/docs/information/router.md

@@ -29,6 +29,15 @@ Nachfolgender Ablauf soll am Beispiel eines Alarms mit einem Pocsag Paket erklä
 
 Jetzt sind alle Routenpunkte abgearbeitet und die Alarmierung damit abgeschlossen.
 
+---
+## Verzweigung / Listen-Verarbeitung (Fan-out)
+
+Der Routing-Mechanismus kann auch mit der Aufspaltung von Alarmen umgehen. Wenn ein Modul statt eines einzelnen Alarms eine **Liste von Paketen** zurückgibt (wie z. B. das `multicast`-Modul bei Sammelalarmen), teilt der Router den Pfad automatisch auf:
+
+- Jedes Paket aus der Liste läuft ab diesem Punkt ganz unabhängig den **verbleibenden Rest der Route** ab.
+- Dabei wird im Hintergrund sichergestellt, dass sich die einzelnen Alarme nicht gegenseitig beeinflussen oder Daten überschreiben.
+- Diese Aufteilung funktioniert auch problemlos über mehrere, ineinander verschachtelte Router hinweg.
+
 ---
 ## Konfiguration