Übersicht zur FX ROS-Systemintegration

Überblick

BATCAM FX unterstützt ab der Entwicklungs-Firmware-Version v1.0.3b die Datenübertragung auf Basis von ROS 2; diese Funktion ist in der offiziellen Release-Firmware v1.0.3 enthalten. Mit diesem Dokument können Sie die von BATCAM FX publizierten ROS 2 Topics (Beamforming-Map, Audio, Video, PRPD-Klassifikationsergebnisse) in einem ROS 2 Node auf dem Host-PC abonnieren und die Beamforming- und Overlay-Einstellungen über ROS 2 Actions steuern.

Der ROS 2 Datenkanal arbeitet unabhängig von den bestehenden Datenkanälen (RTSP-Video, WebSocket/Protobuf). Zu den bestehenden Datenkanälen lesen Sie bitte das Dokument BATCAM FX Übersicht.

Der ROS 2 Datenkanal arbeitet unabhängig von den bestehenden Datenkanälen.

BATCAM FX verwendet für die Datenübertragung den Nachrichtentyp FX Stream Message. In der Firmware der Kamera ist eine auf Basis von ROS 2 Humble Hawksbill gebaute Binärdatei enthalten; das Nachrichtenformat ist im folgenden öffentlichen Repository ausführlich definiert.

SMI OSS - fx-stream-msgs

Diese Nachrichten sind als ROS 2 Interface-Typen definiert und werden verwendet, um die von den Sensoren erfassten Daten zu publizieren.

Dieses Dokument behandelt die folgenden Inhalte.

Behandelt wird: Voraussetzungen (Firmware, ROS 2 Umgebung, Netzwerk), Schnellstart (Build, Abonnement prüfen), Topic-/Nachrichtenspezifikation, Action-Spezifikation, Troubleshooting
Nicht behandelt wird: Anbindung der RTSP-/WebSocket-Kanäle (BATCAM FX Übersicht), Details zur REST API (FX API-Playground), Details zum Ablauf der Änderung der ROS Domain ID (ROS Domain ID einstellen)

Voraussetzungen

Firmware-Version

Die ROS 2 bezogenen Funktionen wurden je nach Firmware-Version schrittweise hinzugefügt. Die ausführliche Änderungshistorie finden Sie in den FX Firmware-Release-Notes.

Funktion	Erstmals unterstützende Firmware	Hinweis
ROS 2 Topic-Übertragung (beamforming / image / lpoint_audio / ws_audio / prpd)	v1.0.3b (Entwicklungs-Firmware)	In der offiziellen Release-Version v1.0.3 enthalten
Einstellungs-Actions (setting_beamforming / setting_overlay)	v1.0.3c	In der offiziellen Release-Version v1.0.3 enthalten
REST API zum Abfragen und Einstellen der ROS Domain ID (`/ros/domain`)	v1.0.3c	Siehe ROS Domain ID einstellen

Die Firmware-Version der verwendeten Kamera können Sie über die REST API GET /setting/status (Abfrage der Geräteinformationen) ermitteln. Die ausführliche Spezifikation finden Sie im FX API-Playground.

ROS 2 Umgebung

Kategorie	Umgebung	Hinweis
Kamera (in der Firmware enthaltene Binärdatei)	ROS 2 Humble Hawksbill	In der Firmware enthalten, keine separate Installation erforderlich
Host-Nachrichtenpaket (fx-stream-msgs)	Verwendung von ROS 2 Humble vorausgesetzt	Nach dem Build in einer Umgebung mit Python 3.10.16 und ROS 2 Jazzy (Ubuntu 24.04) durch Tests zum Senden und Empfangen von Daten mit BATCAM FX verifiziert

💡 Hinweis: fx-stream-msgs wurde unter der Voraussetzung der Verwendung mit ROS 2 Humble erstellt und wurde durch den Build in einer Umgebung mit ROS 2 Jazzy (Ubuntu 24.04) sowie durch Tests zum Senden und Empfangen von Daten mit BATCAM FX verifiziert.

Netzwerk

Der ROS 2 Stack der Kamera verwendet eine Fast DDS Konfiguration auf Basis von UDPv4 (Stand: Release-Notes zu v1.0.3c). Kamera und Host-PC müssen im selben Netzwerk miteinander kommunizieren können.
Die Topics sind nur sichtbar, wenn die ROS_DOMAIN_ID von Kamera und Host übereinstimmt. Ab der Entwicklungs-Firmware v1.0.3b ist die Standard-ROS_DOMAIN_ID der Kamera 123; ab Firmware 1.0.3c lässt sie sich über die REST API (GET·PATCH /ros/domain) abfragen und ändern. Ausführliche Informationen finden Sie im Dokument ROS Domain ID einstellen.
Beim Abonnieren aller Topics wird, bezogen auf die Summe der fx_stream_msgs Topics, eine Bandbreite von etwa 3.6 MB/s (ohne das image Topic) benötigt. Für einen stabilen Empfang wird eine kabelgebundene Verbindung empfohlen.

Schnellstart

1. hardware_id der Kamera ermitteln

Die Topic- und Action-Namen von BATCAM FX enthalten die Hardware-ID der Kamera (z. B. /fx_{hardware_id}/beamforming). Die Hardware-ID können Sie über die REST API GET /setting/status ermitteln. Alle REST-Endpunkte erfordern eine HTTP-Basic-Authentifizierung (siehe FX API-Playground).

curl -u admin:{password} http://192.168.0.30/setting/status
# IP-Adresse und Passwort an Ihre Umgebung anpassen.

Beispielantwort:

{
  "error": 0,
  "result": {
    "hardware_id": "3287162925128",
    "sbrio_version": "1.0.14",
    "firmware_version": "v0.0.1"
  }
}

Bei der Kamera aus diesem Beispiel lautet das Topic-Präfix /fx_3287162925128. Alle Beispiele in den folgenden Schritten verwenden diesen Wert.

2. ROS_DOMAIN_ID des Hosts einstellen

Stellen Sie in der Shell des Hosts dieselbe Domain ID wie bei der Kamera ein. Den in der Kamera eingestellten Wert können Sie über GET /ros/domain (ab Firmware 1.0.3c) abfragen; ab der Entwicklungs-Firmware v1.0.3b lautet der Standardwert 123.

export ROS_DOMAIN_ID=123
# Denselben Wert wie in der Kamera einstellen.

3. fx-stream-msgs bauen

Um auf dem Host die Nachrichtentypen von fx_stream_msgs zu verwenden, laden Sie das öffentliche Repository herunter und bauen es in einem Workspace.

mkdir -p ~/fx_ws/src
cd ~/fx_ws/src
git clone https://gitlab.com/smins-oss/sound-camera/framework/protocol/fx-stream-msgs.git
cd ~/fx_ws
colcon build
source install/setup.bash

Bei jedem Öffnen eines neuen Terminals müssen Sie source ~/fx_ws/install/setup.bash erneut ausführen.

4. Topics und Actions prüfen

Prüfen Sie bei eingeschalteter und über das Netzwerk verbundener Kamera die Liste der Topics.

ros2 topic list

Erwartete Ausgabe:

/fx_3287162925128/beamforming
/fx_3287162925128/image
/fx_3287162925128/lpoint_audio
/fx_3287162925128/prpd
/fx_3287162925128/ws_audio
/parameter_events
/rosout

Auch die Liste der Actions können Sie prüfen.

ros2 action list

Erwartete Ausgabe:

/fx_3287162925128/setting_beamforming
/fx_3287162925128/setting_overlay

5. Datenempfang prüfen

Empfangen Sie testweise eine Nachricht vom PRPD Topic.

ros2 topic echo /fx_3287162925128/prpd --once

Erwartete Ausgabe (die Werte hängen von der Messsituation ab):

noise:
- -0.96
- 4.48
- -6.54
corona:
- 2.98
- 5.88
- -1.39
floating:
- -3.55
- -5.45
- 0.73
surface:
- 0.3
- -1.51
- 0.45
---

Jedes Array enthält die Logit Scores je Teilentladungstyp, die den LPoint-Kanälen CH0~CH2 entsprechen. Zur Interpretation lesen Sie bitte das Dokument AI PRPD-Klassifikator.

6. Beispiel für einen minimalen Subscriber-Node (Python)

Nachfolgend finden Sie das vollständige Dateibeispiel eines minimalen Nodes, der das Beamforming Topic abonniert und den Maximalwert der BF Map ausgibt.

fx_beamforming_listener.py

import rclpy
from rclpy.node import Node
from fx_stream_msgs.msg import Beamforming

HARDWARE_ID = '3287162925128'  # Mit dem per GET /setting/status ermittelten Wert ersetzen

class FxBeamformingListener(Node):
    def __init__(self):
        super().__init__('fx_beamforming_listener')
        self.subscription = self.create_subscription(
            Beamforming,
            f'/fx_{HARDWARE_ID}/beamforming',
            self.listener_callback,
            10)

    def listener_callback(self, msg: Beamforming):
        # bf ist die zu 1x1200 aufgefaltete 40x30 BF Map,
        # ab Firmware v1.0.2 ein dB-Wert ohne Skalenumrechnung.
        self.get_logger().info(
            f'BF max: {max(msg.bf):.1f} dB (gain={msg.gain})')

def main():
    rclpy.init()
    node = FxBeamformingListener()
    rclpy.spin(node)

if __name__ == '__main__':
    main()

Ausführung:

source ~/fx_ws/install/setup.bash
python3 fx_beamforming_listener.py

Erwartete Ausgabe (die Werte hängen von der Messsituation ab):

[INFO] [fx_beamforming_listener]: BF max: 45.2 dB (gain=100.0)
[INFO] [fx_beamforming_listener]: BF max: 45.4 dB (gain=100.0)

Topic-Referenz

BATCAM FX erzeugt auf Basis der Hardware-ID der Kamera die folgenden Topics.

Topic	Nachrichtentyp	Zyklus	Durchschnittliche Bandbreite	Größe pro Nachricht
`/fx_{hardware_id}/beamforming`	`fx_stream_msgs/msg/Beamforming`	25 Hz	~250 KB/s	9.84 KB
`/fx_{hardware_id}/image`	`sensor_msgs/msg/CompressedImage`	25 Hz (25 fps)	—	—
`/fx_{hardware_id}/lpoint_audio`	`fx_stream_msgs/msg/LPointAudio`	25 Hz	~2.5 MB/s	0.10 MB
`/fx_{hardware_id}/ws_audio`	`fx_stream_msgs/msg/WsAudio`	25 Hz	~850 KB/s	32.02 KB
`/fx_{hardware_id}/prpd`	`fx_stream_msgs/msg/Prpd`	25 Hz	~220 B/s	52 B

Mit Ausnahme von LevelTrigger werden alle Nachrichten periodisch im Abstand von 25 Hz (25 fps) publiziert. Die Summe der durchschnittlichen Bandbreite der fx_stream_msgs Topics beträgt etwa 3.6 MB/s (ohne das image Topic).

Hinweise zur Dateninterpretation

Beim gain-Wert in den Nachrichten WsAudio, LPointAudio und Beamforming wird, wenn die automatische Verstärkungsfunktion der Kamera aktiviert ist, der zuletzt eingestellte Wert oder -1 zurückgegeben.
Die Werte ws und lpoint0~2 von WsAudio und LPointAudio sind float-Arrays mit einer Länge von 8000 Samples und liegen im Float Wave Format nach IEEE 754 vor. Bezogen auf den Zyklus von 25 Hz sind das 200,000 Samples pro Sekunde, was der Mikrofon-Abtastrate der Kamera (200 kHz) entspricht.
Ab Firmware v1.0.2 ist bei der Nachricht Beamforming der Wert von bf ein dB-Wert, der keine Skalenumrechnung erfordert.

WsAudio.msg

Typ	Name	Beschreibung
float64	`gain`	Mikrofon-Verstärkungswert zum Zeitpunkt des Empfangs. Bei aktivierter automatischer Verstärkung (autogain) der zuletzt eingestellte Wert oder `-1`
float32[]	`ws`	Audiosignal mit einer Länge von 8000 Samples (IEEE 754 Float Wave Format)

LPointAudio.msg

Typ	Name	Beschreibung
float64	`gain`	Mikrofon-Verstärkungswert zum Zeitpunkt des Empfangs. Bei aktivierter automatischer Verstärkung (autogain) der zuletzt eingestellte Wert oder `-1`
float32[]	`lpoint0`	An der Position Listening Point 0 beamgeformtes Audiosignal, float-Array mit 8000 Samples (IEEE 754 Float Wave Format)
float32[]	`lpoint1`	Audiosignal an der Position Listening Point 1 (gleiches Format)
float32[]	`lpoint2`	Audiosignal an der Position Listening Point 2 (gleiches Format)

Das Koordinatensystem der Listening Points und die Einschränkungen bei der Einstellung sind im Dokument Listening-Point-Koordinaten beschrieben.

Beamforming.msg

Typ	Name	Beschreibung
float64	`gain`	Mikrofon-Verstärkungswert zum Zeitpunkt des Empfangs. Bei aktivierter automatischer Verstärkung (autogain) der zuletzt eingestellte Wert oder `-1`
float64[]	`bf`	Array, in dem die 40×30 BF Map zu 1×1200 aufgefaltet ist. Ab Firmware v1.0.2 ein dB-Wert, der keine Skalenumrechnung erfordert (siehe Aufbau und Koordinatensystem der BF Map)
float64[]	`level`	—
int32[]	`param1`	—
int32[]	`param2`	—
int32[]	`theta`	—
int32[]	`pos_x`	—
int32[]	`pos_y`	—
int32[]	`v_pos_x`	—
int32[]	`v_pos_y`	—

Prpd.msg

Jedes Feld ist ein Array der Länge 3, das den LPoint-Kanälen CH0~CH2 entspricht; die Werte sind nicht normalisierte Logit Scores je Teilentladungstyp. Die Interpretation mithilfe von argmax und softmax sowie Beispielcode finden Sie im Dokument AI PRPD-Klassifikator.

Typ	Name	Beschreibung
float32[3]	`noise`	Logit Score für Noise (Geräusch ohne Entladung) je Kanal
float32[3]	`corona`	Logit Score der Corona-Entladung je Kanal
float32[3]	`floating`	Logit Score der Floating-Entladung je Kanal
float32[3]	`surface`	Logit Score der Surface-Entladung je Kanal

LevelTrigger.msg ( künftig nicht verwendet )

Der Nachrichtentyp ist zwar definiert, wird künftig jedoch nicht verwendet und ist in der obigen Topic-Liste nicht enthalten.

Typ	Name	Beschreibung
float64	`decibel`	Pegelwert (dB)

Action-Referenz

BATCAM FX erzeugt auf Basis der Hardware-ID der Kamera die folgenden Actions (ab Firmware v1.0.3c).

Action	Action-Typ	Verwendungszweck
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	Einstellung der Beamforming-Parameter
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	Einstellung der Parameter zur Erzeugung des Overlay-Bildes und des Source-Modus

Ausführliche Beispiele für die Einstellung über Actions finden Sie im Dokument Beamforming- und Overlay-Einstellung über ROS-Actions (Beta). Dieselben Einstellungen sind auch über die REST API möglich (FX API-Playground).

BeamformingSetting.action

Goal, Result und Progress bestehen jeweils aus einem einzigen Feld des Nachrichtentyps BeamformingSetting, nämlich setting.

Abschnitt	Typ	Name
Goal	BeamformingSetting	`setting`
Result	BeamformingSetting	`setting`
Progress	BeamformingSetting	`setting`

BeamformingSetting.msg — Die Minimal-, Maximal- und Referenzwerte der einzelnen Felder finden Sie im Dokument Beamforming-Parameter.

Typ	Name	Beschreibung	Bereich (Einheit/Schritt)
bool	`autogain`	Ob die automatische Mikrofonverstärkung verwendet wird. Die Kamera bestimmt den Gain je nach Lautstärke automatisch	True / False
float64	`gain`	Mikrofon-Verstärkungswert. Wird nur angewendet, wenn `autogain` False ist	1 ~ 1000 (nur 1, 10, 100, 1000 zulässig)
float64	`x_cal`	Korrektur der Abweichung der x-Koordinate zwischen Kamerabild und Overlay-Bild	0 ~ 1 (Schritt 0.01)
float64	`y_cal`	Korrektur der Abweichung der y-Koordinate zwischen Kamerabild und Overlay-Bild	0 ~ 1 (Schritt 0.01)
float64	`distance`	Entfernung zur zu messenden Geräuschquelle. Mit der angegebenen Entfernung wird ein präziseres Beamforming versucht	1 ~ 10 (Schritt 1)
float64	`high_cut`	Höchste anzuzeigende Frequenz (Tiefpassfilter). Töne oberhalb dieses Wertes werden herausgefiltert	über low_cut ~ 100,000 Hz (Schritt 100)
float64	`low_cut`	Niedrigste anzuzeigende Frequenz (Hochpassfilter). Töne unterhalb dieses Wertes werden herausgefiltert	1,000 Hz ~ unter high_cut (Schritt 100)
int32	`l_point_0`	Index von Listening Point 0 (40×30 Raster). Alle drei müssen angegeben werden	0 ~ 1199
int32	`l_point_1`	Index von Listening Point 1	0 ~ 1199
int32	`l_point_2`	Index von Listening Point 2	0 ~ 1199

Koordinatenbezogene Einschränkungen wie der Mindestabstand zwischen den Listening Points sind im Dokument Listening-Point-Koordinaten beschrieben. In der REST API werden dieselben Werte über das Feld index_l (drei durch Komma getrennte Werte) übertragen.

Terminal-Beispiel:

ros2 action send_goal /fx_3287162925128/setting_beamforming fx_stream_msgs/action/BeamformingSetting \
"{
setting: {
autogain: false,
gain: 1,
x_cal: 0.0,
y_cal: 0.0,
distance: 5.0,
high_cut: 60000.0,
low_cut: 25000.0,
l_point_0: 580,
l_point_1: 20,
l_point_2: 290
}
}"

OverlaySetting.action

Goal, Result und Progress bestehen jeweils aus einem einzigen Feld des Nachrichtentyps OverlaySetting, nämlich setting.

Abschnitt	Typ	Name
Goal	OverlaySetting	`setting`
Result	OverlaySetting	`setting`
Progress	OverlaySetting	`setting`

OverlaySetting.msg — Die Minimal-, Maximal- und Referenzwerte der einzelnen Felder finden Sie im Dokument Overlay-Parameter.

Typ	Name	Beschreibung	Bereich (Einheit/Schritt)
bool	`enable_overlay`	Ob das Overlay-Bild ausgegeben wird. Bei True wird das Overlay in den über RTSP und ROS übertragenen Bildern angezeigt	True / False
bool	`enable_source_mode`	Modus zur Quellenerkennung. Nur nutzbar, wenn das Overlay eingeschaltet ist	True / False
int32	`number_of_sources`	Anzahl der gleichzeitig zu verfolgenden Quellen (empfohlen: höchstens 3)	1 ~ 5 (Schritt 1)
int32	`average`	Anzahl der Beamforming-Maps, über die gemittelt wird. Wird bei aktivem Modus zur Quellenerkennung nicht angewendet	0 ~ 10 (Schritt 1)
float64	`threshold`	Mindestintensitätswert, ab dem etwas als Quelle gewertet wird. Wird bei aktivem Modus zur Quellenerkennung nicht angewendet	0 ~ 120 (Schritt 1)
float64	`range`	Größe des Overlay-Bildes für eine Quelle. Wird bei aktivem Modus zur Quellenerkennung nicht angewendet	0 ~ 10 (Schritt 0.1)

Terminal-Beispiel:

ros2 action send_goal /fx_3287162925128/setting_overlay fx_stream_msgs/action/OverlaySetting \
"{
setting: {
enable_overlay: true,
enable_source_mode: true,
number_of_sources: 3,
range: 5.0,
threshold: 15.0,
average: 1
}
}"

Fehlerbehebung (Troubleshooting)

Wenn die Topics nicht in der Liste erscheinen:
- Prüfen Sie, ob die ROS_DOMAIN_ID des Hosts mit der Einstellung der Kamera übereinstimmt. Ab der Entwicklungs-Firmware v1.0.3b ist der Standardwert der Kamera 123; den aktuellen Wert können Sie über GET /ros/domain (ab Firmware 1.0.3c) abfragen. (ROS Domain ID einstellen)
- Prüfen Sie, ob Kamera und Host im selben Netzwerk kommunizieren können. Der ROS 2 Stack der Kamera verwendet eine Fast DDS Konfiguration auf Basis von UDPv4.
- Prüfen Sie über GET /setting/status, ob die Firmware eine Version ist, die die ROS 2 Übertragung unterstützt (Topic-Übertragung ab der Entwicklungs-Firmware v1.0.3b, enthalten in der offiziellen Release-Version v1.0.3).
Wenn die Fehlermeldung erscheint, dass der Nachrichtentyp fx_stream_msgs nicht gefunden werden kann:
- Prüfen Sie, ob Sie das Paket fx-stream-msgs gebaut und im aktuellen Terminal source ~/fx_ws/install/setup.bash ausgeführt haben.
- Mit dem Befehl ros2 interface show fx_stream_msgs/msg/Beamforming können Sie prüfen, ob der Typ erkannt wird.
- fx-stream-msgs setzt die Verwendung von ROS 2 Humble voraus und wurde durch Build- sowie Sende- und Empfangstests in einer Umgebung mit ROS 2 Jazzy (Ubuntu 24.04) verifiziert.
Wenn der gain-Wert als -1 empfangen wird:
- Das ist das normale Verhalten, wenn die automatische Verstärkung (autogain) der Kamera aktiviert ist. Wenn Sie einen festen gain-Wert verwenden möchten, setzen Sie autogain auf False und geben Sie anschließend den gain an (Beamforming-Parameter).
Wenn der Empfang verzögert wird oder abbricht:
- Beim Abonnieren aller Topics wird, bezogen auf die Summe der fx_stream_msgs Topics, eine Bandbreite von etwa 3.6 MB/s (ohne das image Topic) benötigt. Es wird empfohlen, eine kabelgebundene Verbindung zu verwenden und nur die benötigten Topics zu abonnieren.
Wenn die Verbindung zur Kamera unmittelbar nach der Änderung der ROS Domain ID abbricht:
- Während die Einstellung über PATCH /ros/domain übernommen wird, wird die Verbindung zur Kamera kurzzeitig unterbrochen. Stellen Sie die Verbindung nach der Übernahme erneut her.

Zugehörige Dokumente

ROS Domain ID einstellen — Vorgehen zum Abfragen und Ändern der Domain ID (REST API sowie manuelle Einstellung in älteren Versionen)
Beamforming- und Overlay-Einstellung über ROS-Actions (Beta) — Ausführliche Beispiele zur Verwendung der Actions
Beamforming-Parameter — Bereiche und Referenzwerte der Beamforming-Einstellwerte
Overlay-Parameter — Bereiche und Referenzwerte der Overlay-Einstellwerte
Listening-Point-Koordinaten — Aufbau der BF Map und Indexsystem der LPoints
AI PRPD-Klassifikator — Interpretation der Prpd-Nachricht und Beispielcode
FX Firmware-Release-Notes — Änderungshistorie der ROS-Funktionen nach Version
FX API-Playground — REST-API-Referenz (/setting/status, /ros/domain usw.)
SMI OSS - fx-stream-msgs — Definition der Nachrichten- und Action-Typen (öffentliches Repository)