Aller au contenu
SMI Developer Center

Paramètres de beamforming

Vue d’ensemble

Sur le BATCAM FX, vous pouvez définir le filtre de fréquence, l’amplification et les Listening Points (LPoint) du signal transmis par les microphones. Ce document présente la signification et la plage de chaque paramètre de beamforming, ainsi que la manière de lire et d’écrire ces valeurs via deux interfaces : l’API REST et ROS 2.

Ce document porte sur le BATCAM FX. Pour la configuration du beamforming du BATCAM FX2, veuillez consulter le document Device Manager - Beamforming.

InterfaceMéthodeChemin / nom de l’interfaceRemarques
REST APIHTTP GET / PATCH/beamforming/settingAuthentification HTTP Basic requise. PATCH utilise le format multipart/form-data. Vous pouvez l’exécuter directement depuis le tag beamforming de l’API Playground.
ROS 2Action/fx_{hardware_id}/setting_beamforming ( fx_stream_msgs/action/BeamformingSetting )Fonction bêta prise en charge à partir du firmware de développement v1.0.3b. Voir Configuration BF/Overlay du firmware ROS (bêta).

Prérequis

  • L’appareil BATCAM FX expose directement l’API REST. L’URL de base suit le format http://{device_ip} ; dans les exemples ci-dessous, l’adresse IP de l’appareil est supposée être 192.168.0.30.

  • Tous les points de terminaison REST nécessitent une authentification HTTP Basic. Le BATCAM FX est préconfiguré avec deux comptes, admin et user ; veillez à modifier les mots de passe par défaut d’usine avant utilisation.

  • Pour effectuer la configuration via une Action ROS 2, un firmware de développement v1.0.3b ou supérieur ainsi que le paquet de messages fx-stream-msgs sont nécessaires. Pour les définitions des messages et des actions, veuillez consulter le document ROS Integration.

Référence des paramètres

Les noms de champs et les plages indiqués correspondent à la requête REST PATCH. Le pas est l’unité minimale selon laquelle la valeur peut varier ; pour les paramètres dont les valeurs autorisées sont fixées, seules ces valeurs peuvent être utilisées.

ParamètreChamp RESTTypeUnitéMinimum (Min)Maximum (Max)Pas / valeurs autorisées
LowCutlow_cutintegerHz1000Inférieur à HighCutPas de 100
HighCuthigh_cutintegerHzSupérieur à LowCut100000Pas de 100
Gaingainnumber-11000Valeurs autorisées : seuls 1, 10, 100 et 1000 peuvent être utilisés
Auto Gainautogainboolean---true / false
Distancedistancenumber-110Pas de 1
Image Calibration Xx_calnumber-01Pas de 0.01
Image Calibration Yy_calnumber-01Pas de 0.01
Listening Point Indexindex_lstring-0 (par index)599 (par index)3 index compressés 40×15 séparés par des virgules obligatoires

Frequency Range - LowCut / HighCut ( low_cut, high_cut )

Définit le filtre de fréquence. LowCut est un filtre passe-haut, HighCut un filtre passe-bas.

  • LowCut : fréquence minimale à afficher dans la plage de fréquences. Les sons situés en dessous de cette fréquence sont éliminés par le filtre.

  • HighCut : fréquence maximale à afficher dans la plage de fréquences. Les sons situés au-dessus de cette fréquence sont éliminés par le filtre.

Les deux valeurs doivent toujours satisfaire la relation low_cut < high_cut.

Gain / Auto Gain ( gain, autogain )

Gain est la valeur d’amplification du microphone. Elle n’est pas utilisée lorsque Auto Gain est activé.

Auto Gain indique si l’amplification automatique du microphone est utilisée. La caméra détermine automatiquement le Gain en fonction du niveau sonore.

Pour modifier directement le Gain, vous devez d’abord définir autogain sur false. Lorsque Auto Gain est activé, la valeur gain contenue dans les messages ROS 2 et de flux ( WsAudio, LPointAudio, Beamforming ) renvoie la dernière valeur définie ou -1.

Distance ( distance )

Spécifie la distance jusqu’à la source de bruit à mesurer. Le beamforming est effectué de manière un peu plus précise à la distance spécifiée.

Image Calibration ( x_cal, y_cal )

Si la position de l’image de beamforming superposée ne coïncide pas avec celle de l’image réelle de la caméra, ces valeurs permettent d’ajuster la position.

  • x_cal : corrige l’écart de coordonnée x entre l’image de la caméra et l’image d’overlay affichée.

  • y_cal : corrige l’écart de coordonnée y entre l’image de la caméra et l’image d’overlay affichée.

Listening Point Index ( index_l )

Définit l’index du Listening Point (LPoint) à configurer sur la caméra. La BF Map du BATCAM FX est une structure qui divise l’image de la caméra (1600x1200) en une grille 40x30 (index unidimensionnel de 0 à 1199) ; le Listening Point désigne une position sur cette grille au moyen d’un index.

Toutefois, lors des requêtes API, vous devez transmettre un index converti (compressé) au format 40×15, dont la résolution verticale est réduite de moitié. La plage des index compressés est de 0 à 599.

Format de la valeur : transmettez trois index compressés (chacun de 0 à 599) séparés par des virgules, sous la forme d’une seule chaîne de caractères. Exemple : 20,510,579

Les trois index doivent impérativement être tous spécifiés ; dans la réponse REST GET, ils sont renvoyés sous forme de tableau d’entiers (par exemple [20, 510, 579]).

⚠️ Les index de la BF Map utilisent un système de coordonnées dans lequel le coin inférieur droit vaut 0 et le coin supérieur gauche 1199. Pour les formules de compression/restauration 40×30 ↔ 40×15 et les exemples de code par langage, veuillez consulter le document Coordonnées des Listening Points.

Différences de noms de champs entre REST et ROS 2

Les paramètres eux-mêmes sont identiques pour les deux interfaces, mais le mode de représentation du Listening Point diffère.

ParamètreREST ( PATCH /beamforming/setting )ROS 2 ( BeamformingSetting.msg )
LowCut / HighCutlow_cut, high_cut (integer)low_cut, high_cut (float64)
Gain / Auto Gaingain (number), autogain (boolean)gain (float64), autogain (bool)
Distancedistance (number)distance (float64)
Image Calibrationx_cal, y_cal (number)x_cal, y_cal (float64)
Listening Pointindex_l (1 chaîne séparée par des virgules)l_point_0, l_point_1, l_point_2 (3 valeurs int32)

Exemples de configuration

Consulter la configuration actuelle (REST)

GET /beamforming/setting renvoie les valeurs de configuration du beamforming enregistrées dans le processeur temps réel du BATCAM FX.

Fenêtre de terminal
curl -u admin:<password> http://192.168.0.30/beamforming/setting

Sortie attendue ( si error vaut 0, l’opération a réussi ) :

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

Modifier la configuration (REST)

⚠️ Les configurations partielles ne sont pas prises en compte : vous devez transmettre l’ensemble des valeurs. Pour ne modifier que certaines valeurs, récupérez d’abord la configuration actuelle avec GET, puis transmettez l’ensemble des valeurs modifiées avec PATCH.

PATCH /beamforming/setting reçoit l’ensemble des champs au format multipart/form-data.

Fenêtre de terminal
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"

Sortie attendue ( les valeurs de configuration appliquées sont renvoyées telles quelles ) :

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

L’intégralité des schémas de requête/réponse est consultable dans le tag beamforming de l’API Playground.

Modifier la configuration (Action ROS 2)

Sous ROS 2, les mêmes paramètres se configurent au moyen de l’Action fx_stream_msgs/action/BeamformingSetting. Le format fourni par défaut est identique à celui proposé par l’API REST.

Fenêtre de 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
}
}"

Les Goal / Result / Progress de l’Action sont tous constitués d’un unique champ de type BeamformingSetting, le champ setting. Pour la spécification détaillée, veuillez consulter le document ROS Integration.

Contraintes et réponses d’erreur

  • Transmission de toutes les valeurs : PATCH /beamforming/setting ne prend pas en charge les mises à jour partielles. L’ensemble des champs doit toujours être transmis conjointement.

  • Plage de fréquences : low_cut doit être inférieur à high_cut.

  • Valeurs autorisées pour Gain : gain ne peut prendre que les valeurs 1, 10, 100 et 1000, et n’est appliqué que lorsque autogain vaut false.

  • Listening Point : index_l doit spécifier les trois index compressés 40×15 (chacun de 0 à 599) séparés par des virgules, et un écart d’au moins ±2 cases, horizontalement comme verticalement, est nécessaire entre deux Listening Points. Pour les restrictions détaillées et les formules de conversion, veuillez consulter le document Coordonnées des Listening Points.

Toutes les réponses REST utilisent une structure d’enveloppe commune. Si error vaut 0, l’opération a réussi ; si la valeur est différente de 0, il s’agit d’une erreur, et le champ result.message peut alors contenir un message détaillé.

Code de statutExemple de réponseCause
400{ "error": 1, "result": { "message": "lpoint parameter error" } }Requête incorrecte (par exemple, erreur du paramètre index_l)
401-Échec de l’authentification HTTP Basic

Résolution des problèmes (Troubleshooting)

  • Si une erreur 401 se produit :

    • Vérifiez les identifiants d’authentification HTTP Basic. Le BATCAM FX est préconfiguré avec deux comptes, admin et user.

  • Si une erreur 400 ( lpoint parameter error ) se produit :

    • Vérifiez que index_l est composé de trois index séparés par des virgules.

    • Vérifiez que chaque index se situe dans la plage des index compressés 40×15 (0 à 599). Les index d’origine de la BF Map (0 à 1199) ne doivent pas être transmis tels quels, sans conversion. Pour la formule de conversion, veuillez consulter le document Coordonnées des Listening Points.

    • Vérifiez que la contrainte d’écart minimal entre Listening Points (±2 cases horizontalement et verticalement) n’est pas enfreinte.

  • Si la configuration n’est pas prise en compte alors que seuls certains champs ont été transmis :

    • Les configurations partielles ne sont pas prises en compte. Récupérez la configuration actuelle avec GET, puis retransmettez l’ensemble des valeurs.

  • Si le réglage du Gain n’est pas pris en compte :

    • Lorsque autogain vaut true, la valeur gain n’est pas utilisée. Définissez autogain sur false, puis effectuez la modification.

  • Si la valeur gain des messages de flux apparaît à -1 :

    • Il s’agit du comportement normal lorsque l’amplification automatique (Auto Gain) est activée. Dans ce cas, le champ gain des messages de flux renvoie la dernière valeur définie ou -1.

Documents connexes