Réglage des paramètres BF/Overlay du firmware ROS FX (bêta)

⚠️ Bêta : ce document traite de fonctionnalités en bêta ; son interface et son contenu peuvent changer au fil des mises à jour du firmware. Pour les modifications propres à chaque version, consultez les Notes de version du firmware.

Présentation

BATCAM FX permet de modifier les réglages de formation de voies (Beamforming) et de superposition (Overlay) via l’interface Action de ROS 2. Ce document présente le nom et les champs des deux actions de réglage, ainsi que la manière de les appeler depuis le terminal (CLI) et depuis du code Python.

Les valeurs traitées par chaque action utilisent le même système de valeurs que l’API REST (/beamforming/setting, /beamforming/overlay). La spécification de l’API REST est consultable dans API Playground (FX).

Pour la définition et le format des types de messages, veuillez consulter le document ROS Integration ou le dépôt SMI OSS - fx-stream-msgs.

Prérequis

Version du firmware : les actions de réglage (setting action) décrites dans ce document sont prises en charge à partir du firmware FX v1.0.3c (2025.05.27). La transmission de données basée sur ROS 2 est quant à elle prise en charge à partir du firmware de développement v1.0.3b. Pour plus de détails, consultez les Notes de version du firmware.
Environnement ROS 2 : les fonctionnalités ROS 2 de BATCAM FX reposent sur ROS 2 Humble Hawksbill. Le paquet fx-stream-msgs présuppose une utilisation sous ROS 2 Humble ; il a été compilé et validé dans un environnement Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04).
Paquet fx_stream_msgs : les définitions des types d’action sont fournies dans le dépôt fx-stream-msgs. Vous devez compiler et sourcer ce paquet dans l’espace de travail de l’environnement où les commandes seront exécutées pour pouvoir utiliser les types des exemples ci-dessous.
Réseau et ROS_DOMAIN_ID : vous devez vous trouver sur le même réseau que la caméra et utiliser le même ROS_DOMAIN_ID que celle-ci. Pour la méthode de configuration du Domain ID de la caméra, consultez le document ROS Domain ID.

Nom des actions et hardware_id

BATCAM FX crée les deux actions de réglage suivantes en se basant sur l’ID matériel de la caméra.

Nom de l’action	Type d’action	Cible du réglage
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	Paramètres de beamforming
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	Paramètres d’overlay

{hardware_id} peut être relevé dans le nom des actions en exécutant ros2 action list depuis le même réseau ROS 2 que la caméra.

ros2 action list

# Exemple de sortie
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

Les exemples de ce document sont rédigés sur la base d’une caméra dont le hardware_id est 276730383020104.

Le Goal de chaque action se compose d’un unique champ setting, dans lequel l’ensemble des valeurs de réglage est transmis. Les champs non spécifiés dans le Goal sont envoyés avec la valeur par défaut de leur type (0, False) ; il est donc recommandé de renseigner tous les champs. Le Result renvoie les valeurs de réglage appliquées dans la même structure setting que le Goal, et la spécification de l’action définit également un élément Progress (feedback) de structure identique.

Réglage du Beamforming

/fx_{hardware_id}/setting_beamforming

Définit les valeurs des paramètres de beamforming. Cette action utilise le même système de valeurs que le point de terminaison GET/PATCH /beamforming/setting de l’API REST ; seule la notation du Listening Point diffère. En REST, trois valeurs séparées par des virgules sont transmises dans un unique champ index_l, alors qu’en ROS elles sont réparties sur trois champs, de l_point_0 à l_point_2.

Résumé des champs

Champ	Type	Unité	Plage	Pas / valeurs autorisées	Description
`autogain`	bool	-	False / True	Boolean	Utilisation ou non de l’amplification automatique du microphone. Tant que la valeur est True, la valeur `gain` n’est pas utilisée.
`gain`	float64	-	1 ~ 1000	Seules les valeurs autorisées `1`, `10`, `100`, `1000` sont utilisables	Valeur d’amplification du microphone. Pour la modifier, vous devez d’abord régler `autogain` sur False.
`x_cal`	float64	-	0 ~ 1	Pas 0.01	Correction de l’écart de coordonnée x entre l’image de la caméra et l’image d’overlay.
`y_cal`	float64	-	0 ~ 1	Pas 0.01	Correction de l’écart de coordonnée y entre l’image de la caméra et l’image d’overlay.
`distance`	float64	-	1 ~ 10	Pas 1	Distance jusqu’à la source de bruit à mesurer.
`high_cut`	float64	Hz	supérieur à low_cut ~ 100,000	Pas 100	Fréquence maximale à afficher. Il s’agit d’un filtre passe-bas : les sons situés au-dessus de cette valeur sont filtrés.
`low_cut`	float64	Hz	1,000 ~ inférieur à high_cut	Pas 100	Fréquence minimale à afficher. Il s’agit d’un filtre passe-haut : les sons situés en dessous de cette valeur sont filtrés.
`l_point_0` ~ `l_point_2`	int32	-	0 ~ 1199	Pas 1	Index du Listening Point. Les trois doivent être spécifiés. Pour le système de coordonnées, consultez le document Coordonnées du Listening Point.

Pour la description détaillée de chaque paramètre ainsi que les valeurs minimale, maximale et de référence, veuillez consulter le document Beamforming Parameters.

Exemple dans le terminal

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

En cas de succès, la sortie se déroule comme suit et l’état se termine sur SUCCEEDED.

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

Le champ setting du Result renvoie les valeurs de réglage appliquées à la caméra, dans la même structure que le Goal.

Vérification de la prise en compte

La commande GET /beamforming/setting de l’API REST permet de consulter les valeurs de réglage de beamforming actuellement enregistrées. Pour la spécification, consultez API Playground (FX).
En vous abonnant au topic /fx_{hardware_id}/beamforming dans ROS, vous pouvez vérifier notamment la valeur gain dans les données de beamforming en temps réel. Lorsque l’amplification automatique est activée, la valeur gain publiée correspond à la dernière valeur définie ou à -1.

Réglage de l’Overlay

/fx_{hardware_id}/setting_overlay

Définit les paramètres de génération de l’image d’overlay du mode Full View ainsi que le mode de détection de source. La fonction d’overlay est prise en charge à partir de la version 1.0.3 du firmware BATCAM FX et utilise la même composition de champs que le point de terminaison GET/PATCH /beamforming/overlay de l’API REST.

Résumé des champs

Champ	Type	Unité	Plage	Pas / valeurs autorisées	Description
`enable_overlay`	bool	-	False / True	Boolean	Sortie ou non de l’image d’overlay. Lorsque la valeur est True, l’overlay est affiché sur les images transmises via RTSP et ROS.
`enable_source_mode`	bool	-	False / True	Boolean	Utilisation ou non du mode de détection de source. Il ne fonctionne que si l’overlay est activé et, selon la valeur de `number_of_sources`, le mode source unique ou le mode multi-sources est activé.
`number_of_sources`	int32	-	1 ~ 5	Pas 1	Nombre de sources à suivre simultanément. Il est possible d’en spécifier jusqu’à 5, mais il est recommandé de ne pas dépasser 3.
`average`	int32	-	0 ~ 10	Pas 1	Nombre de cartes de beamforming sur lesquelles appliquer la moyenne. Plus la valeur est élevée, plus le résultat est lissé. Ce paramètre ne s’applique pas lorsque le mode de détection de source est actif.
`threshold`	float64	-	0 ~ 120	Pas 1	Valeur d’intensité minimale à partir de laquelle un élément est considéré comme une source. Plus la valeur est élevée, plus seules les sources fortes sont affichées. Ce paramètre ne s’applique pas lorsque le mode de détection de source est actif.
`range`	float64	-	0 ~ 10	Pas 0.1	Taille de l’image d’overlay appliquée à une source. Plus la valeur est élevée, plus l’overlay est grand. Ce paramètre ne s’applique pas lorsque le mode de détection de source est actif.

Pour la description détaillée de chaque paramètre ainsi que les valeurs minimale, maximale et de référence, veuillez consulter le document Overlay Parameters.

Exemple dans le terminal

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

Le déroulement du résultat d’exécution est identique à celui du réglage du Beamforming. En cas de succès, l’exécution se termine sur l’état SUCCEEDED et le champ setting du Result renvoie les valeurs de réglage d’overlay appliquées.

Vérification de la prise en compte

La commande GET /beamforming/overlay de l’API REST permet de consulter les valeurs de réglage d’overlay actuelles. Pour la spécification, consultez API Playground (FX).
Si vous réglez enable_overlay sur True, l’overlay est affiché sur les images transmises via RTSP et ROS ; vous pouvez donc le vérifier directement dans le flux vidéo.

Appel depuis le code (Python)

Lors d’une intégration réelle, les actions sont souvent appelées depuis le code plutôt que depuis le terminal (CLI). Voici un exemple complet d’appel de l’action de réglage Beamforming avec rclpy. Le réglage Overlay peut être appelé selon la même structure, en changeant uniquement le nom et le type de l’action (OverlaySetting) ainsi que les champs.

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

from fx_stream_msgs.action import BeamformingSetting

HARDWARE_ID = '276730383020104'  # remplacer par la valeur relevée avec ros2 action list

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'Paramètres appliqués : {result.setting}')

    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

Résolution des problèmes (Troubleshooting)

L’action n’apparaît pas dans ros2 action list :
- Vérifiez que le firmware de la caméra est en v1.0.3c ou une version ultérieure. (Notes de version du firmware)
- Vérifiez que le ROS_DOMAIN_ID de l’environnement d’exécution est identique à celui de la caméra. (ROS Domain ID)
- Vérifiez que vous êtes connecté au même réseau que la caméra.
Une erreur signale que le type fx_stream_msgs est introuvable :
- Vérifiez que l’espace de travail dans lequel le paquet fx-stream-msgs a été compilé est bien sourcé dans le shell courant.
La modification de gain n’est pas prise en compte :
- Tant que autogain est True, la valeur gain n’est pas utilisée. Réglez d’abord autogain sur False.
- La version v1.0.3 (2025.10.04) du firmware inclut la suppression du réglage Gain ainsi que la désactivation de l’Auto Gain. Pour le comportement de la version de firmware que vous utilisez, consultez les Notes de version du firmware.
Le mode de détection de source ne fonctionne pas :
- enable_source_mode ne fonctionne que lorsque enable_overlay est True.
Les modifications de average / threshold / range ne sont pas prises en compte :
- Ces trois valeurs ne s’appliquent pas tant que le mode de détection de source (enable_source_mode) est activé.
Le réglage du Listening Point échoue :
- Les champs l_point_0 ~ l_point_2 doivent tous les trois être spécifiés dans la plage 0 ~ 1199. Pour le système de coordonnées, consultez le document Coordonnées du Listening Point.
- L’API REST, qui utilise le même système de valeurs, renvoie lpoint parameter error pour un paramètre L Point incorrect.

Documents associés

ROS Integration — Spécification complète des messages et des actions
ROS Domain ID — Méthode de configuration de ROS_DOMAIN_ID
Beamforming Parameters — Détail des paramètres de beamforming
Overlay Parameters — Détail des paramètres d’overlay
Coordonnées du Listening Point — Système de coordonnées des index L Point
Notes de version du firmware — Fonctionnalités prises en charge par version
API Playground (FX) — Référence de l’API REST
SMI OSS - fx-stream-msgs — Dépôt de définition des types de messages/actions