Aller au contenu
SMI Developer Center

Présentation de BATCAM FX

Présentation du développement BATCAM FX

1. Introduction

BATCAM FX est une caméra acoustique temps réel de SM Instruments. Elle fournit conjointement une image optique d’une résolution de 1600×1200 et une carte de formation de voies (BF) de 40×30, ce qui permet de visualiser sur l’image la position d’où provient le son.

Ce document constitue le point de départ du développement d’une intégration avec BATCAM FX. Il présente d’un seul coup d’œil les interfaces fournies par l’appareil et décrit le flux de données ainsi que la méthode de connexion de la composition d’image en superposition, la tâche d’intégration la plus représentative. Les sujets détaillés tels que le contrôle des paramètres, l’intégration ROS 2 ou la mise à jour du micrologiciel renvoient chacun vers leur document dédié. Pour la structure globale du centre développeur et la documentation des autres produits (BATCAM FX2, FX Viewer), reportez-vous à Prise en main du centre développeur.

2. Aperçu des interfaces fournies

InterfaceUsageDocument associé
RTSPRéception du flux vidéo brut de la caméra. À partir du micrologiciel 1.0.3, l’appareil peut également fournir en RTSP l’image en superposition qu’il compose lui-même.Paramètres de superposition
WebSocket + ProtobufDiffusion en temps réel de la formation de voies (BF Map), de l’audio et des résultats de classification des décharges partielles par IA (PRPD)Ce document, Exemple Python Protobuf
REST APIGestion des comptes, configuration de l’appareil (réseau, micrologiciel, redémarrage, informations sur l’appareil), déclenchement d’événements, paramètres de formation de voies et de superposition, ROS Domain IDPlayground de l’API BATCAM FX
ROS 2Réception de données et configuration basées sur les topics/actions (pris en charge à partir du micrologiciel de développement v1.0.3b)Intégration ROS
Mise à jour du micrologicielInstallation du micrologiciel via la page web ou le shell (SSH)Mise à jour web, Mise à jour par shell

La spécification complète des points de terminaison de l’API REST est consultable dans le Playground de l’API, où vous pouvez également effectuer les appels directement depuis le navigateur. Pour le format des messages transmis par WebSocket, reportez-vous au schéma fx-stream-protocol et au document Exemple Python Protobuf.

3. Flux de données de la composition d’image en superposition

Les données de BATCAM FX sont transmises sous la forme de données vidéo brutes de la caméra via RTSP et de données encodées avec le protocole Protobuf via WebSocket. Si vous souhaitez obtenir directement l’image en superposition, composez l’image selon l’ordre ci-dessous.

Diagramme du flux de données de la composition d'image en superposition de BATCAM FX : combinaison de l'image brute RTSP et des données de formation de voies WebSocket/Protobuf

  1. Recevez l’image brute depuis RTSP (rtsp://{device_ip}/raw).

  2. Recevez via WebSocket le message Beamforming encodé au format Protobuf, puis décodez-le pour le convertir en un tableau (Float Array) composé de 1200 valeurs Float au total. Ce tableau correspond à la BF Map de structure 40x30 aplatie en une structure 1x1200, et il est transmis à une cadence de 25Hz.

  3. Interpolez le Float Array afin de générer l’image à superposer. La BF Map 40×30 est mappée sur l’image optique 1600×1200.

  4. En combinant le flux vidéo RTSP et les données sonores reçues, vous pouvez générer en temps réel une image en superposition de Beamforming.

💡 Remarque : À partir du micrologiciel 1.0.3, BATCAM FX prend en charge la fourniture d’un flux RTSP dont l’image en superposition est composée par l’appareil lui-même ; une configuration sans composition manuelle est donc également possible. Pour la méthode de configuration, reportez-vous au document Paramètres de superposition et, pour le système de coordonnées de la BF Map et la désignation du Listening Point, au document Coordonnées du Listening Point.

4. Informations de connexion et authentification

Dans le tableau ci-dessous, {device_ip} désigne l’adresse IP de l’appareil. La configuration IP peut être consultée et modifiée via l’API REST (/setting/ip), et la version du micrologiciel de l’appareil peut être vérifiée via l’API de consultation des informations de l’appareil (/setting/status). Pour la spécification détaillée, reportez-vous au Playground de l’API.

ÉlémentValeurRemarque
Flux vidéo RTSPrtsp://{device_ip}/rawAuthentification utilisateur requise
Diffusion WebSocketws://{device_ip}/wsSpécification du SubProtocol obligatoire
WebSocket SubProtocolSubscribeSelon les exemples, la notation en minuscules subscribe est également utilisée
REST APIhttp://{device_ip}L’appareil expose directement l’API
Page de mise à jour du micrologicielhttp://{device_ip}/firmwareVoir Mise à jour web
Journal de mise à jour du micrologicielws://{device_ip}/firmware/wsRéception du journal de progression de la mise à jour
Méthode d’authentificationHTTP BasicCommune à REST, RTSP et WebSocket

BATCAM FX est livré avec deux comptes préconfigurés par défaut : admin et user. La création d’un compte s’effectue via le point de terminaison /auth/create, la consultation de la liste complète des comptes via /auth/all, et la consultation, la suppression ou la réinitialisation du mot de passe d’un compte individuel via /auth/account.

⚠️ Attention : Veillez à modifier le mot de passe par défaut d’usine avant toute utilisation.

Composition de l’en-tête Authorization — Si la bibliothèque WebSocket que vous utilisez prend en charge l’authentification, fournissez le Username et le Password ; si elle ne la prend pas en charge, ajoutez la clé Authorization à l’en-tête de la requête de connexion WebSocket et incluez-y la chaîne {username}:{password} encodée en base64.

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


# ex. : pour username=admin, password=password
Authorization: Basic YWRtaW46cGFzc3dvcmQ=

Démarrage de l’abonnement (Subscribe) — Les messages ne sont pas reçus immédiatement après l’établissement de la connexion WebSocket : vous devez envoyer à la caméra un abonnement au flux de données souhaité à l’aide de l’objet Subscribe fourni par le code Protobuf pré-généré. Les Subscribe ID par flux sont les suivants.

Subscribe IDMessageContenuFréquence de transmission
0BeamformingBF Map 40×30 (tableau Float 1×1200)25 Hz
1WsAudioAudio Float de 8000 échantillons (200 kHz × 40 ms)25 Hz
2LPointAudioAudio de formation de voies 3 canaux du Listening Point25 Hz
3PrpdRésultat de classification des décharges partielles par IA (micrologiciel v1.0.3c ou ultérieur, voir Classification PRPD par IA)4 Hz

5. Exemples de code et schéma Protobuf

Un exemple d’échange de données à l’aide de Protobuf et de WebSocket est publié sur notre GitHub (exemple C#). Cet exemple couvre l’intégralité du processus de composition en superposition décrit ci-dessus et comprend également un exemple d’interface graphique (GUI).

L’exemple Python suivant illustre le déroulement, de la connexion WebSocket à l’envoi de l’abonnement puis au décodage du premier message.

import asyncio
import base64
import websockets
import fx_protocol_pb2 as pb  # fichier pré-généré de 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:
        # Démarrer l'abonnement Beamforming (ID 0)
        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"))

La configuration de l’environnement, la génération des bindings Python et les exemples détaillés par type de message sont présentés étape par étape dans le document Exemple Python Protobuf.

Le schéma et les fichiers pré-générés nécessaires à l’encodage/décodage de Protobuf sont disponibles sur notre GitLab OSS (fx-stream-protocol). Ce document se fonde sur les fichiers pré-générés du tag v0.0.2 ; pour les autres versions, consultez la liste des tags du dépôt.

6. Problèmes fréquents (Troubleshooting)

SymptômeCauseSolution
La connexion WebSocket ne s’établit pasSubProtocol non spécifiéLors de la connexion, spécifiez impérativement le SubProtocol WebSocket sur Subscribe (option subprotocols de la bibliothèque).
La connexion s’établit mais aucun message n’est reçuMessage d’abonnement (Subscribe) non envoyéImmédiatement après la connexion, envoyez l’objet Subscribe (id, type) pour démarrer l’abonnement. (Lien de référence C#)
La connexion est refusée avec une erreur d’authentification (401)Informations d’authentification manquantes ou identifiants de compte incorrectsFournissez le Username/Password à la fonction d’authentification de la bibliothèque (Lien de référence C#), ou composez directement l’en-tête Authorization selon le format ci-dessus. Vérifiez que le compte et le mot de passe sont corrects.

7. Étapes suivantes