Présentation de l'intégration système ROS du FX

Vue d’ensemble

Le BATCAM FX prend en charge la transmission de données basée sur ROS 2 à partir de la version de firmware de développement v1.0.3b, et cette fonction est incluse dans le firmware de version officielle v1.0.3. Ce document vous permet de souscrire, depuis un nœud ROS 2 du PC hôte, aux topics ROS 2 publiés par le BATCAM FX (carte de beamforming, audio, vidéo, résultats de classification PRPD) et de contrôler les réglages de beamforming et d’overlay au moyen d’actions ROS 2.

Le canal de données ROS 2 fonctionne indépendamment des canaux de données existants (vidéo RTSP, WebSocket/Protobuf). Concernant les canaux de données existants, veuillez consulter le document Présentation de BATCAM FX.

Le canal de données ROS 2 fonctionne indépendamment des canaux de données existants.

Le BATCAM FX utilise le type FX Stream Message pour la transmission des données. La caméra intègre dans son firmware un binaire compilé sur la base de ROS 2 Humble Hawksbill, et le format des messages est défini en détail dans le dépôt public suivant.

SMI OSS - fx-stream-msgs

Ces messages sont définis en tant que types d’interface ROS 2 et sont utilisés pour publier les données collectées par les capteurs.

Ce document couvre les points suivants.

Ce qui est couvert : les prérequis (firmware, environnement ROS 2, réseau), le démarrage rapide (compilation, vérification de la souscription), la spécification des topics et des messages, la spécification des actions, le dépannage
Ce qui n’est pas couvert : l’intégration des canaux RTSP/WebSocket (Présentation de BATCAM FX), le détail de l’API REST (Playground de l’API FX), le détail de la procédure de modification du ROS Domain ID (Configuration du ROS Domain ID)

Prérequis

Version du firmware

Les fonctions liées à ROS 2 ont été ajoutées progressivement selon les versions de firmware. Pour l’historique détaillé des modifications, veuillez consulter les Notes de version du firmware FX.

Fonction	Première version de firmware prise en charge	Remarques
Transmission des topics ROS 2 (beamforming / image / lpoint_audio / ws_audio / prpd)	v1.0.3b (firmware de développement)	Inclus dans la version officielle v1.0.3
Actions de configuration (setting_beamforming / setting_overlay)	v1.0.3c	Inclus dans la version officielle v1.0.3
API REST de consultation et de configuration du ROS Domain ID (`/ros/domain`)	v1.0.3c	Voir Configuration du ROS Domain ID

La version du firmware de la caméra utilisée peut être vérifiée avec l’API REST GET /setting/status (consultation des informations de l’appareil). Pour la spécification détaillée, consultez le Playground de l’API FX.

Environnement ROS 2

Catégorie	Environnement	Remarques
Caméra (binaire intégré au firmware)	ROS 2 Humble Hawksbill	Inclus dans le firmware, aucune installation distincte n’est nécessaire
Paquet de messages de l’hôte (fx-stream-msgs)	Utilisation de ROS 2 Humble présupposée	Validé, après compilation dans un environnement Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04), par des tests d’émission et de réception de données avec le BATCAM FX

💡 Remarque : fx-stream-msgs a été conçu en présupposant une utilisation avec ROS 2 Humble, et il a été validé par une compilation dans un environnement ROS 2 Jazzy (Ubuntu 24.04) ainsi que par des tests d’émission et de réception de données avec le BATCAM FX.

Réseau

La pile ROS 2 de la caméra utilise une configuration Fast DDS basée sur UDPv4 (selon les notes de version v1.0.3c). La caméra et le PC hôte doivent pouvoir communiquer entre eux sur le même réseau.
Les topics ne sont visibles que si le ROS_DOMAIN_ID de la caméra et celui de l’hôte concordent. À partir du firmware de développement v1.0.3b, le ROS_DOMAIN_ID par défaut de la caméra est 123, et à partir du firmware 1.0.3c, il peut être consulté et modifié via l’API REST (GET · PATCH /ros/domain). Pour plus de détails, consultez le document Configuration du ROS Domain ID.
La souscription à l’ensemble des topics requiert une bande passante d’environ 3.6 MB/s au total pour les topics fx_stream_msgs (topic image exclu). Une connexion filaire est recommandée pour une réception stable.

Démarrage rapide

1. Vérification du hardware_id de la caméra

Les noms des topics et des actions du BATCAM FX contiennent l’identifiant matériel de la caméra (par exemple : /fx_{hardware_id}/beamforming). L’identifiant matériel peut être obtenu avec l’API REST GET /setting/status. Tous les points de terminaison REST requièrent une authentification HTTP Basic (voir le Playground de l’API FX).

curl -u admin:{password} http://192.168.0.30/setting/status
# Modifiez l'adresse IP et le mot de passe selon votre environnement.

Exemple de réponse :

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

Pour la caméra de cet exemple, le préfixe des topics est donc /fx_3287162925128. Tous les exemples des étapes ci-dessous utilisent cette valeur.

2. Configuration du ROS_DOMAIN_ID de l’hôte

Dans le shell de l’hôte, définissez le même identifiant de domaine que celui de la caméra. La valeur configurée sur la caméra peut être consultée avec GET /ros/domain (firmware 1.0.3c ou ultérieur) ; à partir du firmware de développement v1.0.3b, la valeur par défaut est 123.

export ROS_DOMAIN_ID=123
# Indiquez la même valeur que celle configurée sur la caméra.

3. Compilation de fx-stream-msgs

Pour utiliser les types de messages fx_stream_msgs sur l’hôte, récupérez le dépôt public et compilez-le dans un espace de travail.

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

Vous devez exécuter à nouveau source ~/fx_ws/install/setup.bash à chaque ouverture d’un nouveau terminal.

4. Vérification des topics et des actions

La caméra étant sous tension et connectée au réseau, vérifiez la liste des topics.

ros2 topic list

Sortie attendue :

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

Vous pouvez également vérifier la liste des actions.

ros2 action list

Sortie attendue :

/fx_3287162925128/setting_beamforming
/fx_3287162925128/setting_overlay

5. Vérification de la réception des données

Essayez de recevoir un message du topic PRPD.

ros2 topic echo /fx_3287162925128/prpd --once

Sortie attendue (les valeurs varient selon les conditions de mesure) :

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
---

Chaque tableau contient le logit score par type de décharge partielle, correspondant aux canaux LPoint CH0 à CH2. Pour la méthode d’interprétation, consultez le document Classificateur PRPD par IA.

6. Exemple de nœud d’abonnement minimal (Python)

Voici l’exemple de fichier complet d’un nœud minimal qui souscrit au topic Beamforming et affiche la valeur maximale de la BF Map.

fx_beamforming_listener.py

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

HARDWARE_ID = '3287162925128'  # remplacer par la valeur relevée via GET /setting/status

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 est la BF Map 40x30 aplatie en un tableau 1x1200 ;
        # à partir du firmware v1.0.2, ce sont des valeurs en dB sans conversion d'échelle.
        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()

Exécution :

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

Sortie attendue (les valeurs varient selon les conditions de mesure) :

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

Référence des topics

Le BATCAM FX crée les topics suivants sur la base de l’identifiant matériel de la caméra.

Topic	Type de message	Fréquence	Bande passante moyenne	Taille par message
`/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

À l’exception de LevelTrigger, tous les messages sont publiés périodiquement à un intervalle de 25 Hz (25 fps). La somme des bandes passantes moyennes des topics fx_stream_msgs est d’environ 3.6 MB/s (topic image exclu).

Précautions relatives à l’interprétation des données

La valeur de gain contenue dans les messages WsAudio, LPointAudio et Beamforming renvoie la dernière valeur configurée ou -1 lorsque la fonction d’amplification automatique de la caméra est activée.
Les valeurs ws et lpoint0 à lpoint2 de WsAudio et LPointAudio sont des tableaux de float d’une longueur de 8000 échantillons, constitués selon le Float Wave Format au format IEEE 754. Sur la base d’une période de 25 Hz, cela représente 200,000 échantillons par seconde, ce qui correspond à la fréquence d’échantillonnage des microphones de la caméra (200 kHz).
À partir du firmware v1.0.2, dans le message Beamforming, la valeur de bf est une valeur en dB ne nécessitant aucune conversion d’échelle.

WsAudio.msg

Type	Nom	Description
float64	`gain`	Valeur d’amplification du microphone au moment de la réception. Lorsque l’amplification automatique (autogain) est active, dernière valeur configurée ou `-1`
float32[]	`ws`	Signal audio d’une longueur de 8000 échantillons (IEEE 754 Float Wave Format)

LPointAudio.msg

Type	Nom	Description
float64	`gain`	Valeur d’amplification du microphone au moment de la réception. Lorsque l’amplification automatique (autogain) est active, dernière valeur configurée ou `-1`
float32[]	`lpoint0`	Signal audio traité par beamforming à la position Listening Point 0, tableau de float de 8000 échantillons (IEEE 754 Float Wave Format)
float32[]	`lpoint1`	Signal audio à la position Listening Point 1 (format identique)
float32[]	`lpoint2`	Signal audio à la position Listening Point 2 (format identique)

Pour le système de coordonnées des Listening Points et les contraintes de configuration, consultez le document Coordonnées des Listening Points.

Beamforming.msg

Type	Nom	Description
float64	`gain`	Valeur d’amplification du microphone au moment de la réception. Lorsque l’amplification automatique (autogain) est active, dernière valeur configurée ou `-1`
float64[]	`bf`	Tableau obtenu en aplatissant la BF Map 40×30 en 1×1200. À partir du firmware v1.0.2, valeur en dB ne nécessitant aucune conversion d’échelle (voir Structure de la BF Map et système de coordonnées)
float64[]	`level`	—
int32[]	`param1`	—
int32[]	`param2`	—
int32[]	`theta`	—
int32[]	`pos_x`	—
int32[]	`pos_y`	—
int32[]	`v_pos_x`	—
int32[]	`v_pos_y`	—

Prpd.msg

Chaque champ est un tableau de longueur 3 correspondant aux canaux LPoint CH0 à CH2, et les valeurs sont des logit scores non normalisés par type de décharge partielle. Pour la méthode d’interprétation à l’aide d’argmax et de softmax ainsi que pour un exemple de code, consultez le document Classificateur PRPD par IA.

Type	Nom	Description
float32[3]	`noise`	Logit score de Noise (bruit sans décharge) par canal
float32[3]	`corona`	Logit score de décharge Corona par canal
float32[3]	`floating`	Logit score de décharge Floating par canal
float32[3]	`surface`	Logit score de décharge Surface par canal

LevelTrigger.msg ( utilisation non prévue )

Ce type de message est défini, mais son utilisation n’est pas prévue et il ne figure pas dans la liste des topics ci-dessus.

Type	Nom	Description
float64	`decibel`	Valeur de niveau (dB)

Référence des actions

Le BATCAM FX crée les actions suivantes sur la base de l’identifiant matériel de la caméra (firmware v1.0.3c ou ultérieur).

Action	Type d’action	Usage
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	Configuration des paramètres de beamforming
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	Configuration des paramètres de génération de l’image d’overlay et du mode source

Pour des exemples détaillés de configuration au moyen des actions, consultez le document Configuration du beamforming et de l’overlay au moyen d’actions ROS (bêta). Les mêmes réglages sont également possibles via l’API REST (Playground de l’API FX).

BeamformingSetting.action

Goal, Result et Progress sont tous constitués d’un unique champ du type de message BeamformingSetting, nommé setting.

Section	Type	Nom
Goal	BeamformingSetting	`setting`
Result	BeamformingSetting	`setting`
Progress	BeamformingSetting	`setting`

BeamformingSetting.msg — Pour les valeurs minimales, maximales et de référence de chaque champ, consultez le document Paramètres de beamforming.

Type	Nom	Description	Plage (unité/pas)
bool	`autogain`	Utilisation ou non de l’amplification automatique du microphone. La caméra détermine automatiquement le Gain en fonction du niveau sonore	True / False
float64	`gain`	Valeur d’amplification du microphone. Appliquée uniquement lorsque `autogain` est False	1 ~ 1000 (seules les valeurs 1, 10, 100 et 1000 sont autorisées)
float64	`x_cal`	Correction de l’écart de coordonnée x entre l’image de la caméra et l’image d’overlay	0 ~ 1 (pas 0.01)
float64	`y_cal`	Correction de l’écart de coordonnée y entre l’image de la caméra et l’image d’overlay	0 ~ 1 (pas 0.01)
float64	`distance`	Distance jusqu’à la source de bruit à mesurer. Un beamforming plus précis est tenté à la distance spécifiée	1 ~ 10 (pas 1)
float64	`high_cut`	Fréquence maximale à afficher (filtre passe-bas). Les sons situés au-dessus de cette valeur sont filtrés	supérieur à low_cut ~ 100,000 Hz (pas 100)
float64	`low_cut`	Fréquence minimale à afficher (filtre passe-haut). Les sons situés en dessous de cette valeur sont filtrés	1,000 Hz ~ inférieur à high_cut (pas 100)
int32	`l_point_0`	Index du Listening Point 0 (grille 40×30). Les trois doivent être spécifiés	0 ~ 1199
int32	`l_point_1`	Index du Listening Point 1	0 ~ 1199
int32	`l_point_2`	Index du Listening Point 2	0 ~ 1199

Pour les contraintes liées aux coordonnées, telles que la distance minimale entre les Listening Points, consultez le document Coordonnées des Listening Points. Dans l’API REST, les mêmes valeurs sont transmises dans le champ index_l (trois valeurs séparées par des virgules).

Exemple en terminal :

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 et Progress sont tous constitués d’un unique champ du type de message OverlaySetting, nommé setting.

Section	Type	Nom
Goal	OverlaySetting	`setting`
Result	OverlaySetting	`setting`
Progress	OverlaySetting	`setting`

OverlaySetting.msg — Pour les valeurs minimales, maximales et de référence de chaque champ, consultez le document Paramètres Overlay.

Type	Nom	Description	Plage (unité/pas)
bool	`enable_overlay`	Affichage ou non de l’image d’overlay. Si True, l’overlay est affiché sur les images transmises via RTSP et ROS	True / False
bool	`enable_source_mode`	Mode de détection de source. Utilisable uniquement si l’overlay est activé	True / False
int32	`number_of_sources`	Nombre de sources à suivre simultanément (3 au maximum recommandé)	1 ~ 5 (pas 1)
int32	`average`	Nombre de cartes de beamforming sur lesquelles appliquer la moyenne. Non appliqué lorsque le mode de détection de source est actif	0 ~ 10 (pas 1)
float64	`threshold`	Valeur d’intensité minimale à partir de laquelle un élément est considéré comme une source. Non appliqué lorsque le mode de détection de source est actif	0 ~ 120 (pas 1)
float64	`range`	Taille de l’image d’overlay pour la source. Non appliqué lorsque le mode de détection de source est actif	0 ~ 10 (pas 0.1)

Exemple en terminal :

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

Résolution des problèmes (Troubleshooting)

Lorsque les topics n’apparaissent pas dans la liste :
- Vérifiez que le ROS_DOMAIN_ID de l’hôte correspond à la configuration de la caméra. À partir du firmware de développement v1.0.3b, la valeur par défaut de la caméra est 123, et la valeur actuelle peut être consultée avec GET /ros/domain (firmware 1.0.3c ou ultérieur). (Configuration du ROS Domain ID)
- Vérifiez que la caméra et l’hôte peuvent communiquer sur le même réseau. La pile ROS 2 de la caméra utilise une configuration Fast DDS basée sur UDPv4.
- Vérifiez avec GET /setting/status que le firmware est bien une version prenant en charge la transmission ROS 2 (la transmission des topics est disponible à partir du firmware de développement v1.0.3b et incluse dans la version officielle v1.0.3).
Lorsqu’une erreur indique que le type de message fx_stream_msgs est introuvable :
- Vérifiez que le paquet fx-stream-msgs a été compilé et que source ~/fx_ws/install/setup.bash a été exécuté dans le terminal courant.
- La commande ros2 interface show fx_stream_msgs/msg/Beamforming permet de vérifier que le type est bien reconnu.
- fx-stream-msgs présuppose l’utilisation de ROS 2 Humble et a été validé par une compilation ainsi que par des tests d’émission et de réception dans un environnement ROS 2 Jazzy (Ubuntu 24.04).
Lorsque la valeur de gain reçue est -1 :
- Il s’agit du fonctionnement normal lorsque la fonction d’amplification automatique (autogain) de la caméra est activée. Pour utiliser une valeur de gain fixe, réglez autogain sur False puis spécifiez le gain (Paramètres de beamforming).
Lorsque la réception est retardée ou interrompue :
- La souscription à l’ensemble des topics requiert une bande passante d’environ 3.6 MB/s au total pour les topics fx_stream_msgs (topic image exclu). Il est recommandé d’utiliser une connexion filaire et de ne souscrire qu’aux topics nécessaires.
Lorsque la connexion à la caméra est perdue juste après la modification du ROS Domain ID :
- La connexion avec la caméra est brièvement interrompue pendant l’application du réglage PATCH /ros/domain. Reconnectez-vous une fois le réglage appliqué.

Documents associés

Configuration du ROS Domain ID — Méthode de consultation et de modification de l’identifiant de domaine (API REST et configuration manuelle pour les versions antérieures)
Configuration du beamforming et de l’overlay au moyen d’actions ROS (bêta) — Exemples détaillés d’utilisation des actions
Paramètres de beamforming — Plages et valeurs de référence des réglages de beamforming
Paramètres Overlay — Plages et valeurs de référence des réglages d’overlay
Coordonnées des Listening Points — Structure de la BF Map et système d’index des LPoint
Classificateur PRPD par IA — Méthode d’interprétation des messages Prpd et exemple de code
Notes de version du firmware FX — Historique des modifications des fonctions ROS par version
Playground de l’API FX — Référence de l’API REST (/setting/status, /ros/domain, etc.)
SMI OSS - fx-stream-msgs — Définition des types de messages et d’actions (dépôt public)