BOSWatch/BW3-Core
1
0
Fork 0
mirror of https://github.com/BOSWatch/BW3-Core.git synced 2026-04-21 06:03:50 +00:00
Code Issues Projects Releases Packages Wiki Activity
BW3-Core/docu/docs/modul/multicast.md

450 lines
20 KiB
Markdown
Raw Normal View History

[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
# <center>Multicast</center>
---
## Beschreibung
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Das Multicast-Modul verarbeitet komplexe Alarmsequenzen, bei denen eine Nachricht (Text-RIC) an eine Liste zuvor gesendeter Empfänger (Tone-RICs) verteilt wird. Es sorgt dafür, dass jeder Empfänger ein individuelles Paket mit dem Alarmtext erhält.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Das Modul filtert keine inhaltlich relevanten Pakete. Alle Pakete mit Alarminhalt werden mit `multicastRole` markiert und weitergereicht. Die Filterung nach Bedarf erfolgt nachgelagert, z.B. mit `filter.regexFilter`.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Das Modul unterstützt:
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
- **Multi-Instance Support:** Vollständige Isolation bei parallelem Betrieb in verschiedenen Routen.
- **Frequenz-Trennung:** Verhindert die Vermischung von Alarmen auf unterschiedlichen Kanälen.
- **Active Trigger System:** Nutzt TCP-Loopback, um auch bei Inaktivität des Funkkanals Timeouts sicher zu verarbeiten.
- **Dynamische Listen:** Generiert aggregierte Listenfelder (z. B. {RIC_LIST}) für Sammel-Alarmierungen.
- **Metadaten-Enrichment:** Markiert Pakete präzise für nachgelagerte Filter (z. B. RegEx).
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
### Funktionsweise
Multicast-Alarme funktionieren in zwei bis vier Phasen:
**Wichtig:** Das Modul arbeitet verzögert bei der Ausgabe der Text-RICs, um die Pakete anzureichern.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
1. **Delimiter-Phase (Optional)**: Ein spezieller Delimiter-RIC markiert den Start eines neuen Multicast-Blocks. Er wird als technisches Paket (`multicastRole: delimiter`) **sofort** durchgereicht, leert aber intern den RAM-Puffer für neue Empfänger. Diese Phase ist optional - ohne Delimiter werden alle leeren Nachrichten als Tone-RICs behandelt. Downstream-Filter (z.B. filter.regexFilter) können ihn bei Bedarf ausfiltern.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
2. **Tone-RIC-Phase**: Eingehende leere Nachrichten werden **nicht direkt als Pakete ausgegeben**, sondern im RAM zwischengespeichert. Das Modul gibt hier `False` zurück, wodurch der Router die Verarbeitung für dieses spezifische Paket vorerst pausiert.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
3. **Text-RIC**: Ein spezieller Message-RIC empfängt die eigentliche Alarmnachricht. Sobald eine Text-RIC empfangen wird, "kopiert" das Modul diesen Text in jedes einzelne der gespeicherten Tone-RIC-Pakete. Diese werden dann als **Liste von Paketen** gesammelt an den Router als `multicastMode: complete` übergeben. Falls keine Tone-RICs im Puffer liegen (z.B. Einzelalarm), wird die Text-RIC als `multicastMode: single` ausgegeben.
**Wichtig:** Die Text-RIC (Message-RIC) wird **nicht als separates Paket ausgegeben**. Sie dient nur als Nachrichtenträger, der seinen Text an alle gesammelten Tone-RICs verteilt. Ausnahme: Einzelalarm (Single)
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
4. **Timeout-Phase (Auto-Clear - Optional):** Läuft der `autoClearTimeout` ab, ohne dass ein Text-RIC eintrifft, werden die gepufferten RICs als `multicastMode: incomplete` (ohne Text) ausgegeben.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
## Unterstützte Alarmtypen
- POCSAG
## Resource
`multicast`
## Konfiguration
|Feld|Beschreibung|Default|
|----|------------|-------|
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
|autoClearTimeout|Zeit in Sekunden, nach der Tone-RICs ohne Text-Eingang als `incomplete` ausgegeben werden|10|
|delimiterRics|Komma-getrennte Liste von Startmarkern (leert Puffer, `multicastRole: delimiter`)|leer|
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
|textRics|Komma-getrennte Liste von RICs, die den Alarmtext tragen|leer|
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
|netIdentRics|Komma-getrennte Liste von Netzwerk-Identifikations-RICs (`multicastRole: netident`)|leer|
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
|triggerRic|RIC für das Wakeup-Trigger-Paket (optional, bei leer: dynamisch = erste Tone-RIC)|leer|
|triggerHost|IP-Adresse für Loopback-Trigger|127.0.0.1|
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
|triggerPort|Port für Loopback-Trigger (entspricht meist Server-Port)|8080|
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
**Hinweis:** Zahlen mit führenden Nullen müssen in Anführungszeichen gesetzt werden, z.B. `'0012345'`.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
### Konfigurationsbeispiel 1: Automatische Delimiter-Erkennung (oder nicht verfügbar im Netzwerk) (= Minimalkonfiguration)
```yaml
- type: module
res: multicast
name: Multicast Handler
config:
textRics: '0299001,0310001'
```
In diesem Modus werden **alle leeren Nachrichten** als toneRics behandelt (keine `delimiterRics` angegeben).
### Konfigurationsbeispiel 2: Mit Delimiter-Trenner (empfohlen)
```yaml
- type: module
res: multicast
name: Multicast Handler
config:
autoClearTimeout: 10
delimiterRics: '0988988'
textRics: '0299001,0310001'
```
In diesem Modus wird **0988988 als Trenner (= Delimiter)** behandelt und **alle anderen leeren Nachrichten als Empfänger**.
### Konfigurationsbeispiel 3: Mit expliziter Trigger-RIC
```yaml
- type: module
res: multicast
name: Multicast Handler
config:
autoClearTimeout: 10
delimiterRics: '0988988'
textRics: '0299001,0310001'
triggerRic: '9999999'
triggerHost: '127.0.0.1'
triggerPort: 8080
```
Verwendet eine feste RIC (9999999) für das interne Wakeup-Trigger-Paket.
### Konfigurationsbeispiel 4: Mit Netzident-Filterung
```yaml
- type: module
res: multicast
name: Multicast Handler
config:
autoClearTimeout: 10
delimiterRics: '0988988'
textRics: '0299001,0310001'
netIdentRics: '0000001'
```
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
Markiert Netzident-Pakete (RIC 0000001) mit multicastRole: netident. Downstream-Filter können sie gezielt ausfiltern (z.B. RegEx-Filter).
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
---
## Modul Abhängigkeiten
- keine
---
## Externe Abhängigkeiten
- keine
---
## Paket Modifikationen
### Hinzugefügte Felder
- `multicastMode`(string): Beschreibt das Ergebnis der Multicast-Verarbeitung, besitzt einen der Werte:
- `complete`: Vollständiges Multicast-Packet
- `incomplete`: Unvollständiges Multicast-Packet (meist fehlt die Text-RIC) (Timeout)
- `single`: Einzelner, "normaler" Alarm (Tone-RIC = Text-RIC)
- `control`: Netzwerk-Ident-RIC oder andere Verwaltung-RICs (Technik)
- `multicastRole`:
- `delimiter`
- `netident`
- `recipient` (Empfänger)
- `single`
- `multicastRecipientIndex` (string): Index dieses Empfängers (1-N), folgende Logik:
- Bei **recipient**: Zählt hoch (z.B. 1 von 5, 2 von 5...)
- Bei **delimiter / netident / single**: Immer **1**, da sie als eigenständige technische Pakete zählen
- `multicastRecipientCount` (string): Gesamtanzahl der Empfänger des Multicasts
- `<FELD>_list` (string): Liste von Werten aus allen Empfänger-RICs für jedes Originalfeld (z.B. `ric_list`, `subric_list`)
### Ergänzte Felder (von Text-RIC an Tone-RIC):
- `message`: Der Text wird aus der Text-RIC übernommen und in die Empfänger-Pakete eingefügt (Bei incomplete-Modus leer)
- `multicastSourceRic` (string): RIC des ursprünglichen Message-RICs
### Erhaltene Felder (Tone-RIC):
Diese Felder bleiben **unverändert** bestehen, damit die Zuordnung zum Endgerät korrekt bleibt:
- `ric`
- `subric`
- alle bereits zuvor hinzugefügten Felder (z.B. Descriptor-Modul)
### Rückgabewerte:
- **False**: Paket wurde intern konsumiert (z.B. Tone-RIC wurde in den Buffer aufgenommen), Router stoppt Verarbeitung für dieses Paket (Verhindert die Ausgabe leerer Nachrichten). Allerdings: Das Paket wird im RAM geparkt.
- **Liste von Paketen**: Tritt ein, sobald eine Text-RIC die Verteilung auslöst oder ein Timeout abläuft. Der Router verarbeitet jedes Element der Liste (die nun angereicherten Tone-RICs) als eigenständigen Alarm.
- **None**: Der Router verarbeitet das Original-Paket normal weiter.
---
## Zusätzliche Wildcards
Folgende Wildcards stehen in allen nachfolgenden Plugins zur Verfügung:
|Wildcard|Beschreibung|Beispiel|
|--------|------------|--------|
|{MCAST_SOURCE}|RIC des ursprünglichen Message-RICs|0299001|
|{MCAST_COUNT}|Gesamtanzahl der Empfänger dieses Multicasts.|3|
|{MCAST_INDEX}|Index des Empfängers (1-basiert für Recipients, 0 für Control-Pakete)|0, 1, 2, 3, ...|
|{MCAST_MODE}|Art der Multicast-Verarbeitung durch das Modul|complete, incomplete, single, control|
|{MCAST_ROLE}|Rolle des Pakets im Multicast-Ablauf|recipient, single, delimiter, netident|
### Erweiterung der Listen-Wildcards
Das Modul generiert Wildcards für alle gesammelten Felder (RICs, SubRICs, etc.) in Listenform. Diese sind besonders nützlich, um eine kombinierte Ausgabe (z.B. in Telegram) zu erstellen. Im Folgenden ein paar Beispiele:
|Wildcard|Beschreibung|Zugrundeliegendes Feld|Beispiel|
|--------|------------|--------|--------|
|{RIC_LIST}|Liste aller RICs der Empfänger (durch Komma getrennt).|ric_list|"0299001, 0299002"|
|{SUBRIC_LIST}|Liste aller SubRICs der Empfänger|subric_list|"4, 3"|
|{DESCRIPTION_LIST}|Liste aller (deskriptiven) Namen der Empfänger (BEISPIEL! **NUR** bei vorher durchlaufenen Descriptor-Modul)|description_list|"FF Musterstadt, BF Beispiel"|
|{<FELD>_LIST}|Liste der Werte für jedes Originalfeld aus dem Paket|<feld>_list|{FREQUENCY_LIST}, {BITRATE_LIST}|
**Wichtig:** Verwende die **originalen Feldnamen** (z.B. `frequency_list`), nicht die Wildcard-Namen (z.B. ~~`FREQ_list`~~).
### Verwendungsbeispiel in Plugins, z.B. Telegram-Plugin:
```yaml
- type: plugin
res: telegram
config:
message_pocsag: |
{CNAME}
{MSG}
RIC: {RIC} / SubRIC: {SRIC}
Multicast: {MCAST_INDEX}/{MCAST_COUNT} (Quelle: {MCAST_SOURCE})
{TIME}
```
---
# Funktionsweise im Detail
## Grundsätzliche Funktion
**Beispiel:**
```
10:31:16 - RIC: 0123456 SubRIC: 1 Message: (leer) → Delimiter-RIC
10:31:16 - RIC: 0234567 SubRIC: 4 Message: (leer) → Empfänger 1
10:31:16 - RIC: 0345678 SubRIC: 3 Message: (leer) → Empfänger 2
10:31:17 - RIC: 0456789 SubRIC: 1 Message: "B3 WOHNHAUS" → Message-RIC
Generierte Alarme:
→ RIC: 0234567 SubRIC: 4 Message: "B3 WOHNHAUS" (behält SubRIC 4!)
→ RIC: 0345678 SubRIC: 3 Message: "B3 WOHNHAUS" (behält SubRIC 3!)
```
**Wichtig:** Jeder Empfänger behält seine ursprüngliche SubRIC, da diese oft unterschiedliche Alarmtypen oder Prioritäten repräsentiert.
### Logik der hinzugefügten Felder
Um die Logik der Felder multicastMode, multicastRole, etc. zu verstehen, hilft eine tabellarische Gegenüberstellung:
**1) Szenario Der "Feldstärke-Alarm" (Netident/Delimiter)**
|Paket-Typ|RIC|multicastMode|multicastRole|sourceRic|Index|Count|
|--------|-------|-------|---------|------|--|--|
|Delimiter|0288088|control|delimiter|0288088|1|1|
|Netzident|0000001|control|netident|0000001|1|1|
Hinweis: Diese Pakete dienen der Systemsteuerung. Der Index ist immer 1, da sie "Einzelereignisse" im technischen Ablauf sind.
Beide RIC werden unmittelbar nach der Verarbeitung weitergereicht, d.h. es wird nicht auf die Netzident-RIC gewartet, um die Delmitier-RIC weiterzureichen.
**2) Szenario Echter Multicast-Alarm (Vollständig)**
Hier sieht man den Ablauf:
- Der Delimiter leert den Speicher und wird mit den ergänzenden Feldern angereichert und sofort weitergegeben.
- Zwei Tone-RICs sammeln sich an
- Die Text-RIC löst die Verteilung aus
**Beachte:** Die Text-RIC (0456789) dient als Nachrichtenträger und erscheint nicht als eigenes Paket im Output.
|Phase|Paket-Typ|RIC|multicastMode|multicastRole|sourceRic|Index|Count|
|-----|---------|---|-------------|-------------|---------|-----|-----|
|Start|Delimiter|0288088|control|delimiter|0288088|1|1|
|Sammler|Tone-RIC 1|0234567|-|(interner Buffer)|-|-|-|
|Sammler|Tone-RIC 2|0345678|-|(interner Buffer)|-|-|-|
|Auslöser|Text-RIC|0456789|(wird verteilt - keine Ausgabe)|(Nachrichtenträger)|-|-|-|
|Output 1|Alarm-Paket|0234567|complete|recipient|0456789|1|2|
|Output 2|Alarm-Paket|0345678|complete|recipient|0456789|2|2|
**3) Szenario Unvollständiger Alarm (Incomplete / Timeout)**
In diesem Fall fehlt die Text-RIC. Das System wartet bis zum Timeout und schickt dann die Empfänger mit leerer Nachricht raus (getriggert durch das Active Trigger System).
|Phase|Paket-Typ|RIC|multicastMode|multicastRole|sourceRic|Index|Count|
|-----|---------|---|-------------|-------------|---------|-----|-----|
|Start|Delimiter|0288088|control|delimiter|0288088|1|1|
|Sammler|Tone-RIC 1|0234567|-|(interner Buffer)|-|-|-|
|Sammler|Tone-RIC 2|0345678|-|(interner Buffer)|-|-|-|
|Event|Timeout|Kein Text|Auto-Clear nach standardmäßig 10s|-|-|-|-|
|Output 1|Incomplete|0234567|incomplete|recipient|0234567|1|2|
|Output 2|Incomplete|0345678|incomplete|recipient|0234567|2|2|
Der Delimiter wird mit den ergänzenden Feldern angereichert und sofort weitergegeben.
---
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
## Integration in Router-Konfiguration
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Das Multicast-Modul muss **vor** den Plugins platziert werden, damit die generierten Alarme korrekt verarbeitet werden:
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
```yaml
- name: Router POCSAG
route:
- type: module
res: filter.modeFilter
name: Filter POCSAG
config:
allowed:
- pocsag
# Multicast-Modul hier einfügen
- type: module
res: multicast
name: Multicast Handler
config:
textRics: '0299001,0310001'
delimiterRics: '0288088'
autoClearTimeout: 10
# Weitere Module und Plugins
- type: plugin
res: mysql
config:
# ...
- type: plugin
res: telegram
config:
# ...
```
## Beispielhafte Verwendung in Router-Konfigurationen
Das Multicast-Modul gibt für jedes RIC ein eigenes Paket aus UND generiert für konsistente Verarbeitung Listenfelder.
Dies ermöglicht es, entweder jede RIC einzeln zu verarbeiten oder die Listenfelder für eine gesammelte Ausgabe zu verwenden. Vor der weiteren Verarbeitung in Plugins empfiehlt sich eventuell eine Filterung mittels [RegEx-Filter](regex_filter.md).
Die folgenden Beispiele dienen zur Veranschaulichung der Möglichkeiten des Multicast-Modul in Verbindung mit RegEx-Filter.
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
### Beispiel (siehe auch "Zusätzliche Wildcards"):
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
```yaml
router:
- name: Router POCSAG
route:
- type: module
res: filter.modeFilter
config:
[...]
- type: module
res: descriptor
config:
[...]
- type: module
res: multicast
name: Multicast
config:
autoClearTimeout: 10
delimiterRics: '0123456' # Start eines Multicast-Alarms
textRics: '9909909' # Text-RIC
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
- type: module
res: filter.doubleFilter
config:
[...]
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
- type: router
res: RouterMySQL
- type: router
res: RouterTelegram
- name: RouterMySQL
route:
- type: module
res: filter.regexFilter
name: Filter MySQL
config:
- name: "Multicast Mode complete or single"
checks:
- field: multicastMode
regex: ^(complete|single)$
- type: plugin
res: mysql
config:
[...]
- name: RouterTelegram
route:
- type: module
res: filter.regexFilter
name: Multicast Recipient Index Filter # 1. Paket, da ist alles drin für einen kombinierten Alarm und ist immer vorhanden
config:
- name: "Multicast 1 Paket pro Alarm-Paket"
checks:
- field: multicastRecipientIndex
regex: ^1$
- type: plugin
res: telegram
config:
message_pocsag: |
<b>{CNAME}</b>
{MSG}
Alarmierte Einheiten [{MCAST_COUNT}]: {DESCRIPTION_LIST}
RICs: {RIC_LIST}
{TIME}
[...]
```
---
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
## Das Active Trigger System (Verlustfreie Paketauslieferung)
BOSWatch arbeitet **synchron**. Das bedeutet: Der Router "schläft", wenn kein Funk-Paket von außen eingeht. Ein Timeout im Hintergrund-Thread des Moduls kann den schlafenden Router nicht von alleine aufwecken, um die im RAM wartenden Pakete (`incomplete`) herauszuschieben.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
**Lösung:**
Das Modul verwendet ein aktives Trigger-System, um sicherzustellen, dass **keine Multicast-Pakete verloren gehen**
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
**Ausführung**
Das Modul sendet über via TCP (Loopback) ein minimales Trigger-Paket an den eigenen BOSWatch-Server. Dieser empfängt es wie einen normalen Funk-Alarm, weckt den Router auf und das Modul kann die wartenden Alarme (`incomplete`) sicher ausliefern.
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
**Trigger-RIC Auswahl** (3-stufige Fallback-Kette):
- **Explizit**: Wenn `triggerRic` konfiguriert ist, wird diese RIC verwendet
- **Dynamisch**: Wenn nicht konfiguriert, wird die erste Tone-RIC der aktuellen Gruppe verwendet
- **Fallback**: Falls keine Tone-RICs vorhanden sind (sollte nicht vorkommen), wird "9999999" verwendet
**Beispiel-Ablauf bei Auto-Clear:**
```
10:31:16 - Tone-RIC empfangen (0234567)
10:31:16 - Tone-RIC empfangen (0345678)
10:31:26 - Auto-Clear-Timeout (10s) erreicht
→ Incomplete-Pakete in Queue gespeichert
→ Trigger-Paket via Loopback gesendet (RIC: 0234567)
10:31:26 - Trigger-Paket durch BOSWatch-Server verarbeitet
→ Queue-Flush: Incomplete-Pakete werden ausgegeben
```
**Vorteile:**
- Keine Pakete gehen verloren, auch bei hoher Systemlast
- Saubere Trennung von Verarbeitung und Ausgabe
- Ermöglicht zeitlich versetzte Ausgabe ohne Race Conditions
### Zeitbasierte Verarbeitung
1. **Tone-RIC-Sammlung**: Tone-RICs (meist leere Nachrichten) werden empfangen und gespeichert
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
2. **Text-RIC-Verteilung**: Sobald ein Text-RIC empfangen wird, erfolgt die sofortige Verteilung an alle gesammelten Tone-RICs
3. **Auto-Clear**: Nach `autoClearTimeout` Sekunden ohne Text-RIC werden die Tone-RICs als incomplete ausgegeben (via Trigger-System)
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
4. **Hard-Timeout-Cleanup**: Nach 3x `autoClearTimeout` (oder max. 120s) werden veraltete Pakete aus dem Speicher gelöscht (Failsafe)
### Frequenz-Trennung
Das Modul trennt Multicast-Listen nach Frequenzen. Dies verhindert Vermischung von Alarmen verschiedener Sender.
**Beispiel:**
```
Frequenz 173.050 MHz: Tone-RICs [0234567, 0345678]
Frequenz 173.075 MHz: Tone-RICs [0456789, 0567890]
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
→ Werden getrennt verarbeitet, keine Vermischung möglich (wichtig für Multi-Client mit Single-Server)
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
```
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
## Paketmarkierung statt interner Filterung
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
Das Modul filtert keine inhaltlich relevanten Pakete.
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Alle Pakete werden mit `multicastRole` markiert und weitergereicht. Die Filterung nach Bedarf erfolgt nachgelagert, z.B. mit `filter.regexFilter`.
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
Eine Ausnahme bilden **Tone-RICs** (leere Nachrichten): Diese werden zuerst intern im Buffer gesammelt und bei einem complete-Alarm (und incomplete) in die Listenfelder aggregiert. Die Listenfelder werden an alle **Tone-RICs** angehängt und anschließend jede **Tone-RIC** angereichert ausgegeben.
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
Pakete und ihre Rollen:
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
- **Delimiter-Pakete**: Erhalten `multicastRole: delimiter`
- **Netzident-Pakete**: Erhalten `multicastRole: netident`
- **Empfänger-Pakete**: Erhalten `multicastRole: recipient`
- **Einzelalarme**: Erhalten `multicastRole: single`
Beispiel-Filter um Delimiter und Netident auszublenden:
```yaml
- type: module
res: filter.regexFilter
config:
- name: "Nur echte Alarme"
checks:
- field: multicastRole
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
regex: ^(recipient|single)$multicastIndex
[feat/multicast] refactor: move packet filtering from module to downstream Remove internal filtering of delimiter and netident packets from the multicast module. All packets are now passed through with multicastRole metadata set, allowing downstream filters (e.g. filter.regexFilter) to handle filtering as needed. Tone-RICs remain internally consumed as they carry no alarm-relevant information outside the module. Update documentation to reflect new behavior and add regexFilter example for filtering by multicastRole.
2026-03-28 15:41:54 +01:00
```
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
---
## Zusammenfassung: Was passiert mit den Daten?
- Der Delimiter: Wird sofort markiert und als technisches Paket weitergereicht. Er sorgt dafür, dass keine "Leichen" von alten, abgebrochenen Alarmen im Speicher liegen.
- Die Tone-RICs: Diese werden vom Modul "geschluckt" (return False). Sie verschwinden kurzzeitig aus dem Datenfluss und warten im RAM.
- Die Text-RIC: Wenn sie eintrifft, nimmt das Modul ihren Text (B3 WOHNHAUS) und kopiert ihn in die Tone-RIC-Pakete im RAM. Anschließend erfolgt die Ausgabe der Tone-RICs.
- Die Metadaten: Erst beim Erzeugen der Output-Pakete werden Felder wie multicastRecipientIndex berechnet, damit nachfolgende Plugins wissen, dass diese Pakete zusammengehören.
Technischer Hinweis:
Da die Text-RIC im complete-Fall "verbraucht" wird, um die Tone-RICs zu füllen, wird sie nicht als separates zusätzliches Paket ausgegeben. Das verhindert Dopplungen in der Datenbank. Nur wenn gar keine Tone-RICs da sind, wird die Text-RIC als `single` ausgegeben.
In diesem Fall (Single) ist es völlig egal, ob die Text-RIC mit Delimiter oder ohne empfangen wird - die Delimiter-RIC wird als Delimiter gekennzeichnet, das Text-RIC als Single (in `multicastMode` sowie in `multicastRole`, `multicastRecipientIndex: 1`, `multicastRecipientCount: 1`).
### Multi-Instanz-Betrieb
Das Modul unterstützt unbegrenzte parallele Instanzen durch vollständige Isolation:
[feat/multicast]: add multi-instance multicast module with active trigger system Introduce a robust multicast processing module for POCSAG that correlates empty tone-RICs (recipients) with subsequent text-RICs (content). Key Features: - Four Output Modes: Internally supports 'complete', 'incomplete', 'single', and 'control'. Functional alarms are delivered as the first three, while technical 'control' packets (Delimiters/NetIdent) are filtered by default. - Active Trigger System: Implements a loss-free deferred delivery mechanism using a loopback socket (TCP) to re-inject wakeup packets, flushing the internal queue during auto-clear timeouts. - Shared State & Multi-Instance: State is shared across instances but separated by frequency to prevent crosstalk in multi-frequency setups. - Data Aggregation: Automatically generates '{FIELD}_list' wildcards (e.g., RIC_LIST, DESCRIPTION_LIST) for all collected recipients, enabling consolidated notifications in downstream plugins. - Dynamic Filtering: Automatically blocks Delimiter and NetIdent RICs from reaching subsequent plugins if they are defined in the configuration. Infrastructural Changes: - ModuleBase: Expanded return semantics to support: * False: Explicitly blocks/drops a packet. * List: Allows a module to expand one input into multiple output packets. - PluginBase: Updated to handle lists of packets, ensuring a full setup->alarm->teardown lifecycle for every individual element.
2025-11-25 16:25:28 +01:00
[feat/multicast]: refactor: isolate module state by moving class variables to instance scope This commit refactors the internal state management to ensure true multi-instance capability. While previous commits shared state via class variables, this change encapsulates all buffers and flags within the individual instance. Key changes: - Migration of state: Moved `_tone_ric_packets`, `_last_tone_ric_time`, and processing flags from class variables to instance variables (`self`). - Thread Isolation: Shifted the cleanup logic to a per-instance `_cleanup_worker` thread, ensuring that timeouts are managed independently for each route/configuration. - Wildcard Safety: Isolated `_wildcards_registered` to prevent registration conflicts between multiple multicast instances. - Robust Hard-Timeout: Simplified `_cleanup_hard_timeout` to act strictly on the instance's own state. This refactoring resolves the "architectural dinosaur" of shared class state, making the module fully thread-safe and reliable for complex multi-route and multi-frequency deployments.
2026-04-12 15:27:41 +02:00
- **Encapsulated State:** Jede Instanz verwaltet ihren eigenen Tone-RIC-Speicher. Es gibt keine Vermischung zwischen verschiedenen Routen.
- **Isolated Cleanup:** Jede Instanz startet einen eigenen, internen Cleanup-Thread für präzises Timeout-Management.
- **Instance IDs:** Zur besseren Nachverfolgung im Log erhält jede Instanz eine eindeutige ID (z.B. MCAST_a1b2).
Reference in a new issue Copy permalink