Beamforming-Parameter

Überblick

Bei BATCAM FX können Sie für das vom Mikrofon übertragene Signal den Frequenzfilter, die Verstärkung, die Listening-Point-Einstellungen (LPoint) und Weiteres festlegen. Dieses Dokument erläutert die Bedeutung und den Wertebereich der einzelnen Beamforming-Parameter sowie das Lesen und Schreiben der Werte über die beiden Schnittstellen REST API und ROS 2.

Dieses Dokument bezieht sich auf BATCAM FX. Für die Beamforming-Einstellungen von BATCAM FX2 lesen Sie bitte das Dokument Device Manager - Beamforming.

Schnittstelle	Methode	Pfad / Schnittstellenname	Hinweise
REST API	HTTP `GET` / `PATCH`	`/beamforming/setting`	HTTP-Basic-Authentifizierung erforderlich. `PATCH` verwendet das Format `multipart/form-data`. Im Tag beamforming des API-Playgrounds können Sie die Aufrufe direkt ausführen.
ROS 2	Action	`/fx_{hardware_id}/setting_beamforming` ( `fx_stream_msgs/action/BeamformingSetting` )	Beta-Funktion, die ab der Entwicklungs-Firmware v1.0.3b unterstützt wird. Siehe ROS-Firmware BF/Overlay-Einstellungen (Beta).

Voraussetzungen

Das BATCAM FX-Gerät stellt die REST API selbst bereit. Die Basis-URL hat das Format http://{device_ip}; in den folgenden Beispielen wird als Geräte-IP 192.168.0.30 angenommen.
Alle REST-Endpunkte erfordern eine HTTP-Basic-Authentifizierung. In BATCAM FX sind standardmäßig die beiden Konten admin und user vorkonfiguriert; ändern Sie das werkseitige Standardpasswort unbedingt vor der Verwendung.
Für die Konfiguration über eine ROS 2 Action werden eine Entwicklungs-Firmware ab v1.0.3b und das Nachrichtenpaket fx-stream-msgs benötigt. Die Nachrichten- und Action-Definitionen finden Sie im Dokument ROS Integration.

Parameterreferenz

Feldnamen und Wertebereiche bezogen auf die REST-PATCH-Anfrage. Der Schritt ist die kleinste Einheit, um die sich ein Wert ändern kann; bei Parametern mit festgelegten zulässigen Werten dürfen nur diese Werte verwendet werden.

Parameter	REST-Feld	Typ	Einheit	Minimum (Min)	Maximum (Max)	Schritt / zulässige Werte
LowCut	`low_cut`	integer	Hz	1000	kleiner als HighCut	Schritt 100
HighCut	`high_cut`	integer	Hz	größer als LowCut	100000	Schritt 100
Gain	`gain`	number	-	1	1000	Nur die zulässigen Werte `1`, `10`, `100`, `1000` verwendbar
Auto Gain	`autogain`	boolean	-	-	-	`true` / `false`
Distance	`distance`	number	-	1	10	Schritt 1
Image Calibration X	`x_cal`	number	-	0	1	Schritt 0.01
Image Calibration Y	`y_cal`	number	-	0	1	Schritt 0.01
Listening Point Index	`index_l`	string	-	0 (je Index)	599 (je Index)	Drei kommagetrennte komprimierte 40×15-Indizes erforderlich

Frequency Range - LowCut / HighCut ( `low_cut`, `high_cut` )

Legt den Frequenzfilter fest. LowCut ist ein Hochpassfilter, HighCut ein Tiefpassfilter.

LowCut: Die niedrigste im Frequenzbereich anzuzeigende Frequenz. Geräusche unterhalb dieser Frequenz werden vom Filter herausgefiltert.
HighCut: Die höchste im Frequenzbereich anzuzeigende Frequenz. Geräusche oberhalb dieser Frequenz werden vom Filter herausgefiltert.

Die beiden Werte müssen stets die Beziehung low_cut < high_cut erfüllen.

Gain / Auto Gain ( `gain`, `autogain` )

Gain ist der Verstärkungswert des Mikrofons. Bei aktiviertem Auto Gain wird er nicht verwendet.

Auto Gain legt fest, ob die automatische Verstärkung des Mikrofons verwendet wird. Die Kamera bestimmt den Gain je nach Lautstärke automatisch.

Um den Gain direkt zu ändern, müssen Sie zunächst autogain auf false setzen. Bei aktiviertem Auto Gain wird als gain-Wert in ROS 2 und in den Stream-Nachrichten ( WsAudio, LPointAudio, Beamforming ) der zuletzt eingestellte Wert oder -1 zurückgegeben.

Distance ( `distance` )

Legt die Entfernung zur zu messenden Geräuschquelle fest. Mit der angegebenen Entfernung wird ein etwas genaueres Beamforming versucht.

Image Calibration ( `x_cal`, `y_cal` )

Wenn die Position des überlagerten Beamforming-Bildes nicht mit der Position des tatsächlichen Kamerabildes übereinstimmt, können Sie die Position mit diesen Werten anpassen.

x_cal: Korrigiert die Abweichung der x-Koordinate zwischen dem Kamerabild und dem visualisierten Overlay-Bild.
y_cal: Korrigiert die Abweichung der y-Koordinate zwischen dem Kamerabild und dem visualisierten Overlay-Bild.

Listening Point Index ( `index_l` )

Legt den Index des Listening Point (LPoint) fest, der an der Kamera eingestellt werden soll. Die BF Map von BATCAM FX ist eine Struktur, bei der das Kamerabild (1600x1200) in ein 40x30-Raster unterteilt ist (eindimensionaler Index 0~1199); der Listening Point gibt eine Position auf diesem Raster über einen Index an.

Bei API-Anfragen muss jedoch ein in die Form 40×15 umgerechneter (komprimierter) Index gesendet werden, bei dem die vertikale Auflösung halbiert ist. Der Bereich des komprimierten Index ist 0~599.

Wertformat: Drei durch Kommas getrennte komprimierte Indizes (je 0~599) werden als eine einzige Zeichenfolge gesendet. Beispiel: 20,510,579

Es müssen unbedingt alle drei Indizes angegeben werden; in der REST-GET-Antwort werden sie als Integer-Array (z. B. [20, 510, 579]) zurückgegeben.

⚠️ Der BF-Map-Index verwendet ein Koordinatensystem, bei dem unten rechts 0 und oben links 1199 ist. Die Formeln für die Komprimierung/Wiederherstellung zwischen 40×30 ↔ 40×15 sowie Beispielcode je Programmiersprache finden Sie im Dokument Listening-Point-Koordinaten.

Unterschiede der Feldnamen zwischen REST und ROS 2

Die Parameter selbst sind bei beiden Schnittstellen identisch, die Darstellung des Listening Point unterscheidet sich jedoch.

Parameter	REST ( `PATCH /beamforming/setting` )	ROS 2 ( `BeamformingSetting.msg` )
LowCut / HighCut	`low_cut`, `high_cut` (integer)	`low_cut`, `high_cut` (float64)
Gain / Auto Gain	`gain` (number), `autogain` (boolean)	`gain` (float64), `autogain` (bool)
Distance	`distance` (number)	`distance` (float64)
Image Calibration	`x_cal`, `y_cal` (number)	`x_cal`, `y_cal` (float64)
Listening Point	`index_l` (1 durch Kommas getrennte Zeichenfolge)	`l_point_0`, `l_point_1`, `l_point_2` (3 × int32)

Konfigurationsbeispiele

Aktuelle Einstellungen abfragen (REST)

GET /beamforming/setting gibt die im Echtzeit-Prozessor von BATCAM FX gespeicherten Beamforming-Einstellwerte zurück.

curl -u admin:<password> http://192.168.0.30/beamforming/setting

Erwartete Ausgabe ( error gleich 0 bedeutet Erfolg ):

{
  "error": 0,
  "result": {
    "autogain": true,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

Einstellungen ändern (REST)

⚠️ Eine teilweise Einstellung wird nicht übernommen, daher müssen alle Werte gesendet werden. Wenn Sie nur einzelne Werte ändern möchten, rufen Sie zunächst mit GET die aktuellen Einstellungen ab und senden Sie anschließend die vollständigen, geänderten Werte per PATCH.

PATCH /beamforming/setting nimmt alle Felder im Format multipart/form-data entgegen.

curl -X PATCH http://192.168.0.30/beamforming/setting \
  -u admin:<password> \
  -F "low_cut=2000" \
  -F "high_cut=45000" \
  -F "gain=100" \
  -F "distance=1" \
  -F "x_cal=0.06" \
  -F "y_cal=0" \
  -F "index_l=20,510,579" \
  -F "autogain=false"

Erwartete Ausgabe ( die übernommenen Einstellwerte werden unverändert zurückgegeben ):

{
  "error": 0,
  "result": {
    "autogain": false,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

Das vollständige Anfrage-/Antwortschema finden Sie im Tag beamforming des API-Playgrounds.

Einstellungen ändern (ROS 2 Action)

In ROS 2 werden dieselben Parameter über die Action fx_stream_msgs/action/BeamformingSetting eingestellt. Das standardmäßig bereitgestellte Format entspricht dem Format der REST API.

❯ 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
}
}"

Goal / Result / Progress der Action bestehen jeweils aus einem einzigen BeamformingSetting-Feld setting. Die ausführliche Spezifikation finden Sie im Dokument ROS Integration.

Einschränkungen und Fehlerantworten

Senden aller Werte: PATCH /beamforming/setting unterstützt keine Teilaktualisierung. Es müssen stets alle Felder gemeinsam gesendet werden.
Frequenzbereich: low_cut muss kleiner als high_cut sein.
Zulässige Gain-Werte: Für gain können nur 1, 10, 100, 1000 verwendet werden, und der Wert wird nur übernommen, wenn autogain auf false steht.
Listening Point: Für index_l müssen alle drei durch Kommas getrennten komprimierten 40×15-Indizes (je 0~599) angegeben werden, und zwischen zwei Listening Points ist horizontal und vertikal jeweils ein Abstand von mindestens ±2 Zellen erforderlich. Die genauen Einschränkungen und die Umrechnungsformel finden Sie im Dokument Listening-Point-Koordinaten.

Alle REST-Antworten verwenden eine gemeinsame Envelope-Struktur. error gleich 0 bedeutet Erfolg, ein Wert ungleich 0 bedeutet einen Fehler; im Fehlerfall kann result.message eine ausführliche Meldung enthalten.

Statuscode	Antwortbeispiel	Ursache
400	`{ "error": 1, "result": { "message": "lpoint parameter error" } }`	Ungültige Anfrage (z. B. Fehler beim Parameter `index_l`)
401	-	HTTP-Basic-Authentifizierung fehlgeschlagen

Fehlerbehebung (Troubleshooting)

Wenn ein 401-Fehler auftritt:
- Prüfen Sie die Anmeldedaten der HTTP-Basic-Authentifizierung. In BATCAM FX sind standardmäßig die beiden Konten admin und user vorkonfiguriert.
Wenn ein 400-Fehler ( lpoint parameter error ) auftritt:
- Prüfen Sie, ob index_l aus drei durch Kommas getrennten Indizes besteht.
- Prüfen Sie, ob jeder Index im Bereich des komprimierten 40×15-Index (0~~599) liegt. Der ursprüngliche BF-Map-Index (0~~1199) darf nicht ohne Umrechnung unverändert gesendet werden. Die Umrechnungsformel finden Sie im Dokument Listening-Point-Koordinaten.
- Prüfen Sie, ob die Beschränkung des Mindestabstands zwischen Listening Points (horizontal und vertikal ±2 Zellen) nicht verletzt wurde.
Wenn nur einzelne Felder gesendet wurden und die Einstellung nicht übernommen wird:
- Eine teilweise Einstellung wird nicht übernommen. Rufen Sie mit GET die aktuellen Einstellungen ab und senden Sie anschließend alle Werte erneut.
Wenn die Gain-Einstellung nicht übernommen wird:
- Wenn autogain auf true steht, wird der Wert gain nicht verwendet. Setzen Sie autogain auf false und ändern Sie den Wert anschließend.
Wenn der gain-Wert der Stream-Nachricht als -1 angezeigt wird:
- Dies ist das normale Verhalten bei aktivierter automatischer Verstärkung (Auto Gain). In diesem Fall wird als gain der Stream-Nachricht der zuletzt eingestellte Wert oder -1 zurückgegeben.