Zum Inhalt springen
SMI Developer Center

BATCAM FX Übersicht

BATCAM FX Entwicklungsübersicht

1. Einführung

BATCAM FX ist eine Echtzeit-Akustikkamera von SM Instruments. Sie liefert ein optisches Bild mit einer Auflösung von 1600×1200 zusammen mit einer 40×30-Beamforming-Map (BF-Map), sodass sich die Position der Schallentstehung über dem Bild visualisieren lässt.

Dieses Dokument ist der Ausgangspunkt für die Entwicklung einer BATCAM FX-Anbindung. Es stellt die vom Gerät bereitgestellten Schnittstellen im Überblick vor und erläutert den Datenfluss sowie das Verbindungsverfahren der typischsten Integrationsaufgabe, der Overlay-Bildkomposition. Detailthemen wie Parametersteuerung, ROS 2-Integration und Firmware-Update sind mit dem jeweiligen ausführlichen Dokument verlinkt. Den Gesamtaufbau des Developer Centers sowie die Dokumente zu den anderen Produkten (BATCAM FX2, FX Viewer) finden Sie unter Erste Schritte im Developer Center.

2. Die bereitgestellten Schnittstellen im Überblick

SchnittstelleVerwendungszweckZugehöriges Dokument
RTSPEmpfang des originalen Videostreams der Kamera. Ab Firmware 1.0.3 kann das Gerät auch ein von ihm selbst zusammengesetztes Overlay-Bild über RTSP bereitstellen.Overlay-Parameter
WebSocket + ProtobufEchtzeit-Streaming von Beamforming (BF Map), Audio und den Ergebnissen der KI-Teilentladungsklassifikation (PRPD)Dieses Dokument, Python-Protobuf-Beispiel
REST APIKontoverwaltung, Geräteeinstellungen (Netzwerk, Firmware, Neustart, Geräteinformationen), Ereignis-Trigger, Beamforming- und Overlay-Parameter, ROS Domain IDBATCAM FX API-Playground
ROS 2Datenempfang und Konfiguration über Topics/Actions (unterstützt ab der Entwicklungs-Firmware v1.0.3b)ROS Integration
Firmware-UpdateFirmware-Installation über die Webseite oder die Shell (SSH)Web-Update, Shell-Update

Die vollständige Endpunkt-Spezifikation der REST API finden Sie im API-Playground, wo Sie die Aufrufe auch direkt im Browser ausführen können. Das Format der über WebSocket übertragenen Nachrichten entnehmen Sie dem fx-stream-protocol-Schema sowie dem Dokument Python-Protobuf-Beispiel.

3. Datenfluss der Overlay-Bildkomposition

Die Daten von BATCAM FX werden als originale Videodaten der Kamera über RTSP und als mit dem Protobuf-Protokoll kodierte Daten über WebSocket gesendet. Wenn Sie das überlagerte Bild selbst erzeugen möchten, setzen Sie das Bild in der folgenden Reihenfolge zusammen.

Diagramm des Datenflusses der BATCAM FX Overlay-Bildkomposition: Kombination des RTSP-Originalbildes mit den Beamforming-Daten über WebSocket/Protobuf

  1. Empfangen Sie über RTSP (rtsp://{device_ip}/raw) das Originalbild.

  2. Empfangen Sie über WebSocket die im Protobuf-Format kodierte Beamforming-Nachricht und dekodieren Sie diese in ein Array aus insgesamt 1200 Float-Werten (Float Array). Dieses Array entsteht, indem die BF Map der Struktur 40x30 zu einer Struktur 1x1200 ausgerollt wird, und wird mit einer Periode von 25Hz übertragen.

  3. Interpolieren Sie das Float Array, um das zu überlagernde Bild zu erzeugen. Die 40×30 BF Map wird passend auf das optische Bild mit 1600×1200 abgebildet.

  4. Durch die Kombination des RTSP-Videostreams mit den empfangenen Schallquellendaten können Sie in Echtzeit ein Beamforming-Overlay-Bild erzeugen.

💡 Hinweis: Ab Firmware 1.0.3 unterstützt BATCAM FX die Bereitstellung eines RTSP-Streams, in dem das Overlay-Bild bereits geräteseitig zusammengesetzt ist; damit ist auch eine Konfiguration ohne eigene Komposition möglich. Zur Einstellung lesen Sie bitte das Dokument Overlay-Parameter, zum Koordinatensystem der BF Map und zur Festlegung des Listening Point das Dokument Listening-Point-Koordinaten.

4. Verbindungsinformationen und Authentifizierung

{device_ip} in der folgenden Tabelle steht für die IP-Adresse des Geräts. Die IP-Einstellung können Sie über die REST API (/setting/ip) abfragen und ändern; die Firmware-Version des Geräts können Sie über die API zur Abfrage der Geräteinformationen (/setting/status) prüfen. Die ausführliche Spezifikation finden Sie im API-Playground.

ElementWertHinweise
RTSP-Videostreamrtsp://{device_ip}/rawBenutzerauthentifizierung erforderlich
WebSocket-Streamingws://{device_ip}/wsAngabe des SubProtocol zwingend erforderlich
WebSocket SubProtocolSubscribeJe nach Beispiel wird auch die Kleinschreibung subscribe verwendet
REST APIhttp://{device_ip}Das Gerät stellt die API direkt bereit
Firmware-Update-Seitehttp://{device_ip}/firmwaresiehe Web-Update
Firmware-Update-Logws://{device_ip}/firmware/wsEmpfang des Logs zum Update-Fortschritt
AuthentifizierungsverfahrenHTTP Basicgemeinsam für REST, RTSP und WebSocket

In BATCAM FX sind standardmäßig die beiden Konten admin und user voreingerichtet. Das Anlegen eines Kontos erfolgt über den Endpunkt /auth/create, die Abfrage der gesamten Kontenliste über /auth/all und die Abfrage, Entfernung sowie das Zurücksetzen des Passworts einzelner Konten über /auth/account.

⚠️ Achtung: Ändern Sie das werkseitige Standardpasswort unbedingt, bevor Sie das Gerät verwenden.

Aufbau des Authorization-Headers — Wenn die von Ihnen verwendete WebSocket-Bibliothek Authentifizierung unterstützt, geben Sie Username und Password an; unterstützt sie dies nicht, fügen Sie im Header der WebSocket-Verbindungsanfrage den Schlüssel Authorization hinzu und nehmen darin die mit base64 kodierte Zeichenkette {username}:{password} auf.

Authorization: Basic base64({username}:{password})


# Beispiel: bei username=admin, password=password
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Abonnement (Subscribe) starten — Nach dem Aufbau der WebSocket-Verbindung werden nicht sofort Nachrichten empfangen; Sie müssen mit dem Subscribe-Objekt aus dem vorab generierten Protobuf-Code das Abonnement für den gewünschten Datenstrom an die Kamera senden. Die Subscribe-IDs der einzelnen Streams lauten wie folgt.

Subscribe IDNachrichtInhaltSendefrequenz
0Beamforming40×30 BF Map (1×1200 Float-Array)25 Hz
1WsAudioFloat-Audio mit 8000 Samples (200 kHz × 40 ms)25 Hz
2LPointAudioDreikanalige Beamforming-Audiodaten des Listening Point25 Hz
3PrpdErgebnisse der KI-Teilentladungsklassifikation (ab Firmware v1.0.3c, siehe AI PRPD-Klassifikation)4 Hz

5. Beispielcode und Protobuf-Schema

Ein Beispiel für den Datenaustausch mittels Protobuf und WebSocket ist auf unserem GitHub (C#-Beispiel) veröffentlicht. Dieses Beispiel umfasst den gesamten oben beschriebenen Overlay-Kompositionsprozess und enthält außerdem ein GUI-Beispiel.

Das folgende Python-Beispiel zeigt den Ablauf vom Aufbau der WebSocket-Verbindung über das Senden des Abonnements bis zum Dekodieren der ersten Nachricht.

import asyncio
import base64
import websockets
import fx_protocol_pb2 as pb  # vorab generierte Datei aus fx-stream-protocol


async def stream(ip: str, user: str, password: str):
    cred = base64.b64encode(f"{user}:{password}".encode()).decode()
    headers = {
        "Authorization": f"Basic {cred}",
        "Sec-WebSocket-Protocol": "subscribe",
    }
    uri = f"ws://{ip}/ws"


    async with websockets.connect(uri, additional_headers=headers, subprotocols=["subscribe"]) as ws:
        # Abonnement für Beamforming (ID 0) starten
        sub = pb.Subscribe()
        sub.id = 0
        sub.type = pb.Subscribe.SUBSCRIBE
        await ws.send(sub.SerializeToString())


        async for raw in ws:
            event = pb.Event()
            event.ParseFromString(raw)
            if event.WhichOneof("data") == "beamforming":
                bf = event.beamforming
                print(f"bf count={len(bf.bf)} gain={bf.gain}")  # bf count=1200


asyncio.run(stream("192.168.0.30", "admin", "password"))

Die Einrichtung der Umgebung, die Erzeugung der Python-Bindings und ausführliche Beispiele je Nachrichtentyp werden im Dokument Python-Protobuf-Beispiel Schritt für Schritt erläutert.

Das zum Kodieren/Dekodieren von Protobuf erforderliche Schema und die vorab generierten Dateien finden Sie in unserem OSS GitLab (fx-stream-protocol). Dieses Dokument bezieht sich auf die vorab generierten Dateien des Tags v0.0.2; andere Versionen entnehmen Sie der Tag-Liste des Repositorys.

6. Häufige Probleme (Troubleshooting)

SymptomUrsacheLösung
Die WebSocket-Verbindung kommt nicht zustandeSubProtocol nicht angegebenGeben Sie beim Verbindungsaufbau das WebSocket-SubProtocol unbedingt als Subscribe an (Option subprotocols der Bibliothek).
Die Verbindung besteht, es werden aber keine Nachrichten empfangenAbonnement-Nachricht (Subscribe) nicht gesendetSenden Sie unmittelbar nach dem Verbindungsaufbau das Subscribe-Objekt (id, type), um das Abonnement zu starten. (C#-Referenzlink)
Die Verbindung wird mit einem Authentifizierungsfehler (401) abgelehntFehlende Authentifizierungsdaten oder falsche KontodatenÜbergeben Sie Username/Password an die Authentifizierungsfunktion der Bibliothek (C#-Referenzlink) oder bauen Sie den Authorization-Header im oben gezeigten Format selbst auf. Prüfen Sie, ob Konto und Passwort korrekt sind.

7. Nächste Schritte