Mit diesem Modul können Multicast-Alarme verarbeitet werden. Dabei wird eine Alarmnachricht automatisch an mehrere Empfänger (RICs) verteilt.
### Funktionsweise
Multicast-Alarme funktionieren in zwei bis drei Phasen:
1.**Delimiter-Phase (Optional)**: Ein spezieller Delimiter-RIC markiert den Start eines neuen Multicast-Blocks und löscht vorherige wartende Tone-RICs. Der Delimiter selbst wird nicht als Alarm ausgegeben (automatische Filterung). Diese Phase ist optional - ohne Delimiter werden alle leeren Nachrichten als Tone-RICs behandelt.
2.**Tone-RIC-Phase**: Mehrere RICs empfangen (meist) leere Nachrichten. Diese definieren die Empfänger und "registrieren" sich im Modul als Empfänger für die nächste Multicast-Nachricht.
3.**Text-RIC**: Ein spezieller Message-RIC empfängt die eigentliche Alarmnachricht. Diese wird dann automatisch an alle zuvor gesammelten Tone-RICs verteilt.
Hinweis: Der Delimiter-RIC (0123456) wird mit multicastRole: delimiter markiert und durchgereicht. Downstream-Filter (z.B. filter.regexFilter) können ihn bei Bedarf ausfiltern.
**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. Falls keine Tone-RICs vorhanden sind, wird die Text-RIC als `multicastMode: single` ausgegeben.
## Unterstützte Alarmtypen
- POCSAG
## Resource
`multicast`
## Konfiguration
|Feld|Beschreibung|Default|
|----|------------|-------|
|autoClearTimeout|Auto-Clear Timeout in Sekunden - Nicht zugestellte Empfänger werden nach dieser Zeit als incomplete ausgegeben|10|
|delimiterRics|Komma-getrennte Liste von Startmarkern, die einen Multicast-Block beginnen (leert sofort vorherige Empfänger und werden mit multicastRole: delimiter markiert)|leer|
Das Multicast-Modul sollte **vor** den Plugins platziert werden, damit die generierten Alarme korrekt verarbeitet werden:
```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.
### Beispiel (Zusätzliche Wildcards werden noch später in diesem Readme erklärt):
```yaml
router:
- name: Router POCSAG
route:
- type: module
res: filter.modeFilter
config:
[...]
- type: module
res: filter.doubleFilter
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
- 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
- **Liste von Paketen**: Multicast-Verteilung, Router verarbeitet jedes Paket einzeln
- **None**: Normaler Alarm, Router fährt mit unveränderten Paket fort
---
## 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:
### Active Trigger System (Verlustfreie Paketauslieferung)
Das Modul verwendet ein aktives Trigger-System, um sicherzustellen, dass **keine Multicast-Pakete verloren gehen**:
1.**Deferred Delivery**: Bei einem Auto-Clear-Timeout werden die incomplete-Pakete nicht sofort ausgegeben, sondern in einer internen Queue gespeichert.
2.**Wakeup-Trigger**: Das Modul sendet ein spezielles Trigger-Paket via Loopback-Socket (Standard: 127.0.0.1:8080) zurück an den BOSWatch-Server.
3.**Queue-Flush**: Beim Empfang des Trigger-Pakets werden alle gespeicherten Pakete aus der Queue ausgegeben.
→ Werden getrennt verarbeitet, keine Vermischung möglich
```
### SubRIC-Erhaltung
**Wichtig:** Jeder Empfänger behält seine ursprüngliche SubRIC aus der Tone-RIC-Phase. Dies ist entscheidend, da SubRICs unterschiedliche Bedeutungen haben können, z.B.:
