FX ROS Firmware BF/Overlay Parameter Setting (Beta)

⚠️ Beta: Dieses Dokument behandelt Beta-Funktionen; Oberfläche und Inhalt können sich durch Firmware-Updates ändern. Die Änderungen der einzelnen Versionen finden Sie in den Firmware-Release-Notes.

Überblick

Bei BATCAM FX lassen sich die Beamforming- und Overlay-Einstellungen über die Action-Schnittstelle von ROS 2 ändern. Dieses Dokument beschreibt die Namen und Felder der beiden Einstellungs-Actions sowie den Aufruf über das Terminal (CLI) und aus Python-Code.

Die von den einzelnen Actions behandelten Werte verwenden dasselbe Werteschema wie die REST API (/beamforming/setting, /beamforming/overlay). Die Spezifikation der REST API finden Sie im API Playground (FX).

Die Definition und das Format der Nachrichtentypen entnehmen Sie bitte dem Dokument ROS Integration oder dem Repository SMI OSS - fx-stream-msgs.

Voraussetzungen

Firmware-Version: Die Einstellungs-Actions (setting action) dieses Dokuments werden ab der FX-Firmware v1.0.3c (2025.05.27) unterstützt. Die ROS-2-basierte Datenübertragung selbst wird ab der Entwicklungs-Firmware v1.0.3b unterstützt. Weitere Einzelheiten finden Sie in den Firmware-Release-Notes.
ROS-2-Umgebung: Die ROS-2-Funktionen von BATCAM FX basieren auf ROS 2 Humble Hawksbill. Das Paket fx-stream-msgs setzt die Verwendung unter ROS 2 Humble voraus und wurde in einer Umgebung mit Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04) gebaut und verifiziert.
fx_stream_msgs-Paket: Die Definitionen der Action-Typen werden im Repository fx-stream-msgs bereitgestellt. Sie müssen das Paket im Workspace der Umgebung, in der Sie die Befehle ausführen, bauen und sourcen, um die Typen der nachfolgenden Beispiele verwenden zu können.
Netzwerk und ROS_DOMAIN_ID: Sie müssen sich im selben Netzwerk wie die Kamera befinden und dieselbe ROS_DOMAIN_ID wie die Kamera verwenden. Wie Sie die Domain ID der Kamera einstellen, finden Sie im Dokument ROS Domain ID.

Action-Namen und hardware_id

BATCAM FX erzeugt auf Basis der Hardware-ID der Kamera die folgenden zwei Einstellungs-Actions.

Action-Name	Action-Typ	Einstellungsziel
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	Beamforming-Parameter
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	Overlay-Parameter

{hardware_id} können Sie am Action-Namen ablesen, wenn Sie im selben ROS-2-Netzwerk wie die Kamera ros2 action list ausführen.

ros2 action list

# Beispielausgabe
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

Die Beispiele in diesem Dokument beziehen sich auf eine Kamera mit der hardware_id 276730383020104.

Das Goal jeder Action besteht aus einem einzigen Feld setting, in dem sämtliche Einstellungswerte übertragen werden. Felder, die im Goal nicht angegeben werden, werden mit dem Standardwert ihres Typs (0, False) gesendet; es wird daher empfohlen, alle Felder auszufüllen. Im Result werden die angewendeten Einstellungswerte in derselben setting-Struktur wie im Goal zurückgegeben; in der Action-Spezifikation ist außerdem ein Progress-Element (Feedback) mit derselben Struktur definiert.

Beamforming-Einstellungen

/fx_{hardware_id}/setting_beamforming

Legt die Werte der Beamforming-Parameter fest. Es wird dasselbe Werteschema wie bei den REST-API-Endpunkten GET/PATCH /beamforming/setting verwendet; lediglich die Notation des Listening Point unterscheidet sich. In REST werden drei durch Kommas getrennte Werte in einem einzigen Feld index_l übertragen, in ROS sind sie dagegen auf die drei Felder l_point_0 ~ l_point_2 aufgeteilt.

Feldübersicht

Feld	Typ	Einheit	Bereich	Schritt / zulässige Werte	Beschreibung
`autogain`	bool	-	False / True	Boolean	Gibt an, ob die automatische Mikrofonverstärkung verwendet wird. Solange True gesetzt ist, wird der Wert `gain` nicht verwendet.
`gain`	float64	-	1 ~ 1000	Nur die zulässigen Werte `1`, `10`, `100`, `1000` verwendbar	Wert der Mikrofonverstärkung. Zum Ändern müssen Sie zuerst `autogain` auf False setzen.
`x_cal`	float64	-	0 ~ 1	Schritt 0.01	Korrektur der Abweichung der x-Koordinate zwischen Kamerabild und Overlay-Bild.
`y_cal`	float64	-	0 ~ 1	Schritt 0.01	Korrektur der Abweichung der y-Koordinate zwischen Kamerabild und Overlay-Bild.
`distance`	float64	-	1 ~ 10	Schritt 1	Abstand zur zu messenden Geräuschquelle.
`high_cut`	float64	Hz	über low_cut ~ 100,000	Schritt 100	Maximale anzuzeigende Frequenz. Ein Tiefpassfilter: Geräusche oberhalb dieses Wertes werden herausgefiltert.
`low_cut`	float64	Hz	1,000 ~ unter high_cut	Schritt 100	Niedrigste anzuzeigende Frequenz. Ein Hochpassfilter: Geräusche unterhalb dieses Wertes werden herausgefiltert.
`l_point_0` ~ `l_point_2`	int32	-	0 ~ 1199	Schritt 1	Index des Listening Point. Es müssen alle drei angegeben werden. Das Koordinatensystem finden Sie im Dokument Listening-Point-Koordinaten.

Ausführliche Beschreibungen sowie Minimal-/Maximal-/Referenzwerte der einzelnen Parameter entnehmen Sie bitte dem Dokument Beamforming Parameters.

Terminal-Beispiel

ros2 action send_goal /fx_276730383020104/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
}
}"

Bei Erfolg erfolgt die Ausgabe im folgenden Ablauf und der Status endet mit SUCCEEDED.

Waiting for an action server to become available...
Sending goal:
...
Goal accepted with ID: ...
Result:
setting: ...
Goal finished with status: SUCCEEDED

Im setting des Result werden die auf der Kamera angewendeten Einstellungswerte in derselben Struktur wie im Goal zurückgegeben.

Übernahme prüfen

Mit GET /beamforming/setting der REST API können Sie die aktuell gespeicherten Beamforming-Einstellungswerte abfragen. Die Spezifikation finden Sie im API Playground (FX).
Wenn Sie in ROS das Topic /fx_{hardware_id}/beamforming abonnieren, können Sie in den Echtzeit-Beamforming-Daten unter anderem den Wert gain prüfen. Bei aktivierter automatischer Verstärkung wird als publizierter gain-Wert der zuletzt eingestellte Wert oder -1 zurückgegeben.

Overlay-Einstellungen

/fx_{hardware_id}/setting_overlay

Legt die Parameter für die Erzeugung des Overlay-Bildes im Full-View-Modus sowie den Quellenerkennungsmodus fest. Die Overlay-Funktion wird ab BATCAM FX Firmware-Version 1.0.3 unterstützt und verwendet dieselbe Feldstruktur wie die REST-API-Endpunkte GET/PATCH /beamforming/overlay.

Feldübersicht

Feld	Typ	Einheit	Bereich	Schritt / zulässige Werte	Beschreibung
`enable_overlay`	bool	-	False / True	Boolean	Gibt an, ob das Overlay-Bild ausgegeben wird. Bei der Einstellung True wird das Overlay in den über RTSP und ROS übertragenen Bildern angezeigt.
`enable_source_mode`	bool	-	False / True	Boolean	Gibt an, ob der Quellenerkennungsmodus verwendet wird. Er funktioniert nur, wenn das Overlay eingeschaltet ist; je nach Wert von `number_of_sources` wird der Einzel- oder der Mehrquellenmodus aktiviert.
`number_of_sources`	int32	-	1 ~ 5	Schritt 1	Anzahl der gleichzeitig zu verfolgenden Quellen. Es können maximal 5 angegeben werden, empfohlen werden jedoch höchstens 3.
`average`	int32	-	0 ~ 10	Schritt 1	Anzahl der Beamforming-Maps, über die gemittelt wird. Je höher der Wert, desto weicher wird das Ergebnis. Bei aktivem Quellenerkennungsmodus wird der Wert nicht angewendet.
`threshold`	float64	-	0 ~ 120	Schritt 1	Mindestintensität, ab der etwas als Quelle gewertet wird. Bei höheren Werten werden nur stärkere Quellen angezeigt. Bei aktivem Quellenerkennungsmodus wird der Wert nicht angewendet.
`range`	float64	-	0 ~ 10	Schritt 0.1	Größe des Overlay-Bildes für eine Quelle. Je höher der Wert, desto größer wird das Overlay. Bei aktivem Quellenerkennungsmodus wird der Wert nicht angewendet.

Ausführliche Beschreibungen sowie Minimal-/Maximal-/Referenzwerte der einzelnen Parameter entnehmen Sie bitte dem Dokument Overlay Parameters.

Terminal-Beispiel

ros2 action send_goal /fx_276730383020104/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
}
}"

Der Ablauf des Ausführungsergebnisses entspricht dem der Beamforming-Einstellungen. Bei Erfolg endet die Action mit dem Status SUCCEEDED, und im setting des Result werden die angewendeten Overlay-Einstellungswerte zurückgegeben.

Übernahme prüfen

Mit GET /beamforming/overlay der REST API können Sie die aktuellen Overlay-Einstellungswerte abfragen. Die Spezifikation finden Sie im API Playground (FX).
Wenn Sie enable_overlay auf True setzen, wird das Overlay in den über RTSP und ROS übertragenen Bildern angezeigt, sodass Sie es direkt im Videostream prüfen können.

Aufruf aus dem Code (Python)

Bei der tatsächlichen Integration werden Actions häufig aus dem Code statt über das Terminal-CLI aufgerufen. Nachfolgend finden Sie ein vollständiges Beispiel, das die Beamforming-Einstellungs-Action mit rclpy aufruft. Auch die Overlay-Einstellungen lassen sich mit derselben Struktur aufrufen, indem Sie lediglich den Action-Namen, den Typ (OverlaySetting) und die Felder ändern.

import rclpy
from rclpy.action import ActionClient
from rclpy.node import Node

from fx_stream_msgs.action import BeamformingSetting

HARDWARE_ID = '276730383020104'  # Durch den mit ros2 action list ermittelten Wert ersetzen

class BeamformingSettingClient(Node):
    def __init__(self):
        super().__init__('beamforming_setting_client')
        self._client = ActionClient(
            self,
            BeamformingSetting,
            f'/fx_{HARDWARE_ID}/setting_beamforming',
        )

    def send_goal(self):
        goal = BeamformingSetting.Goal()
        goal.setting.autogain = False
        goal.setting.gain = 1.0
        goal.setting.x_cal = 0.0
        goal.setting.y_cal = 0.0
        goal.setting.distance = 5.0
        goal.setting.high_cut = 60000.0
        goal.setting.low_cut = 25000.0
        goal.setting.l_point_0 = 580
        goal.setting.l_point_1 = 20
        goal.setting.l_point_2 = 290

        self._client.wait_for_server()
        return self._client.send_goal_async(goal)

def main():
    rclpy.init()
    node = BeamformingSettingClient()

    goal_future = node.send_goal()
    rclpy.spin_until_future_complete(node, goal_future)
    goal_handle = goal_future.result()

    if not goal_handle.accepted:
        node.get_logger().error('Goal rejected')
    else:
        result_future = goal_handle.get_result_async()
        rclpy.spin_until_future_complete(node, result_future)
        result = result_future.result().result
        node.get_logger().info(f'Angewendete Einstellungen: {result.setting}')

    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

Fehlerbehebung (Troubleshooting)

Die Actions erscheinen nicht in ros2 action list:
- Prüfen Sie, ob die Firmware der Kamera v1.0.3c oder höher ist. (Firmware-Release-Notes)
- Prüfen Sie, ob die ROS_DOMAIN_ID der Ausführungsumgebung mit der der Kamera übereinstimmt. (ROS Domain ID)
- Prüfen Sie, ob Sie mit demselben Netzwerk wie die Kamera verbunden sind.
Es tritt ein Fehler auf, dass der Typ fx_stream_msgs nicht gefunden werden kann:
- Prüfen Sie, ob der Workspace, in dem das Paket fx-stream-msgs gebaut wurde, in der aktuellen Shell gesourct ist.
Änderungen an gain werden nicht übernommen:
- Solange autogain True ist, wird der Wert gain nicht verwendet. Setzen Sie zuerst autogain auf False.
- Das Release der Firmware v1.0.3 (2025.10.04) enthält die Entfernung der Gain-Einstellung sowie die Deaktivierung von Auto Gain. Das Verhalten der von Ihnen verwendeten Firmware-Version finden Sie in den Firmware-Release-Notes.
Der Quellenerkennungsmodus funktioniert nicht:
- enable_source_mode funktioniert nur, wenn enable_overlay True ist.
Änderungen an average / threshold / range werden nicht übernommen:
- Diese drei Werte werden nicht angewendet, solange der Quellenerkennungsmodus (enable_source_mode) aktiviert ist.
Die Einstellung des Listening Point schlägt fehl:
- l_point_0 ~ l_point_2 müssen alle drei im Bereich 0 ~ 1199 angegeben werden. Das Koordinatensystem finden Sie im Dokument Listening-Point-Koordinaten.
- Die REST API, die dasselbe Werteschema verwendet, gibt bei fehlerhaften L-Point-Parametern lpoint parameter error zurück.

FX ROS Firmware BF/Overlay Parameter Setting (Beta)

Überblick

Voraussetzungen

Action-Namen und hardware_id

Beamforming-Einstellungen

Feldübersicht

Terminal-Beispiel

Übernahme prüfen

Overlay-Einstellungen

Feldübersicht

Terminal-Beispiel

Übernahme prüfen

Aufruf aus dem Code (Python)

Fehlerbehebung (Troubleshooting)

Verwandte Dokumente