跳转到内容
SMI Developer Center

波束成形参数

概述

在 BATCAM FX 中，可以设置麦克风传入信号的频率滤波、增益以及 Listening Point（LPoint）等参数。本文档介绍各波束成形参数的含义和取值范围，以及通过 REST API 和 ROS 2 两种接口读写这些值的方法。

本文档以 BATCAM FX 为准。BATCAM FX2 的波束成形设置请参阅 Device Manager - Beamforming 文档。

接口方式路径 / 接口名备注
REST APIHTTP GET / PATCH/beamforming/setting需要 HTTP Basic 认证。PATCH 使用 multipart/form-data 格式。可在 API 演练场 的 beamforming 标签中直接执行。
ROS 2Action/fx_{hardware_id}/setting_beamforming ( fx_stream_msgs/action/BeamformingSetting )自 v1.0.3b 开发固件起支持的 Beta 功能。请参阅 ROS 固件 BF/Overlay 设置（Beta）。

前提条件

  • BATCAM FX 设备直接提供 REST API 服务。基础 URL 的格式为 http://{device_ip}，以下示例中假定设备 IP 为 192.168.0.30。

  • 所有 REST 端点均需要 HTTP Basic 认证。BATCAM FX 默认预设了 admin、user 两个账户，出厂默认密码务必修改后再使用。

  • 若要通过 ROS 2 Action 进行设置，需要 v1.0.3b 或更高版本的开发固件以及 fx-stream-msgs 消息包。消息与 Action 的定义请参阅 ROS Integration 文档。

参数参考

以下是以 REST PATCH 请求为准的字段名和取值范围。步长是取值可变化的最小单位；对于规定了允许值的参数，只能使用这些值。

参数REST 字段类型单位最小值（Min）最大值（Max）步长 / 允许值
LowCutlow_cutintegerHz1000小于 HighCut步长 100
HighCuthigh_cutintegerHz大于 LowCut100000步长 100
Gaingainnumber-11000允许值：仅可使用 1、10、100、1000
Auto Gainautogainboolean---true / false
Distancedistancenumber-110步长 1
Image Calibration Xx_calnumber-01步长 0.01
Image Calibration Yy_calnumber-01步长 0.01
Listening Point Indexindex_lstring-0（按索引）599（按索引）必须为逗号分隔的 3 个 40×15 压缩索引

Frequency Range - LowCut / HighCut ( low_cut, high_cut )

用于设置频率滤波器。LowCut 为高通滤波器，HighCut 为低通滤波器。

  • LowCut：在频率范围内要显示的最低频率。低于该频率的声音将被滤除。

  • HighCut：在频率范围内要显示的最高频率。高于该频率的声音将被滤除。

两个值必须始终满足 low_cut < high_cut 的关系。

Gain / Auto Gain ( gain, autogain )

Gain 是麦克风的增益值。在启用 Auto Gain 的状态下不会被使用。

Auto Gain 表示是否使用麦克风的自动增益。相机会根据声音大小自动确定 Gain。

若要直接修改 Gain，必须先将 autogain 设置为 false 后再使用。启用 Auto Gain 时，ROS 2 及流消息( WsAudio、LPointAudio、Beamforming )中包含的 gain 值将返回最后设置的值或 -1。

Distance ( distance )

指定到待测噪声源的距离。系统会按照指定的距离尝试进行更精细的波束成形。

Image Calibration ( x_cal, y_cal )

当叠加的波束成形图像位置与实际相机图像的位置不一致时，可以使用该值来调整位置。

  • x_cal：修正相机图像与可视化叠加图像之间的 x 坐标偏差。

  • y_cal：修正相机图像与可视化叠加图像之间的 y 坐标偏差。

Listening Point Index ( index_l )

设置要在相机上配置的 Listening Point（LPoint）索引。BATCAM FX 的 BF Map 是将相机图像（1600x1200）划分为 40x30 网格的结构（一维索引 0~1199），Listening Point 通过索引指定该网格上的位置。

但在发送 API 请求时，必须传送将纵向分辨率减半后转换（压缩）为 40×15 形式的索引。压缩索引的范围为 0~599。

取值格式：将逗号分隔的 3 个压缩索引（各为 0~599）作为一个字符串发送。例）20,510,579

必须指定全部 3 个索引；在 REST GET 响应中以整数数组（例如 [20, 510, 579]）的形式返回。

⚠️ BF Map 索引使用右下角为 0、左上角为 1199 的坐标系。40×30 ↔ 40×15 的压缩/还原公式以及各语言的示例代码，请参阅 Listening Point 坐标文档。

REST 与 ROS 2 的字段名差异

两个接口的参数本身相同，但 Listening Point 的表示方式不同。

参数REST ( 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 个逗号分隔的字符串）l_point_0、l_point_1、l_point_2（3 个 int32）

设置示例

查询当前设置（REST）

GET /beamforming/setting 返回保存在 BATCAM FX 内实时处理器中的波束成形设置值。

Terminal window
curl -u admin:<password> http://192.168.0.30/beamforming/setting

预期输出 ( error 为 0 表示成功 )：

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

修改设置（REST）

⚠️ 部分设置不会生效，因此必须发送全部值。 若只想修改部分值，请先通过 GET 获取当前设置，然后将修改后的全部值通过 PATCH 发送。

PATCH /beamforming/setting 以 multipart/form-data 格式接收全部字段。

Terminal window
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"

预期输出 ( 应用后的设置值将原样返回 )：

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

完整的请求/响应结构可在 API 演练场 的 beamforming 标签中查看。

修改设置（ROS 2 Action）

在 ROS 2 中，通过 fx_stream_msgs/action/BeamformingSetting Action 设置相同的参数。默认提供的格式与 REST API 上提供的格式相同。

Terminal window
❯ 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
}
}"

Action 的 Goal / Result / Progress 均由一个 BeamformingSetting 类型的 setting 字段构成。详细规范请参阅 ROS Integration 文档。

限制与错误响应

  • 发送全部值：PATCH /beamforming/setting 不支持部分更新。必须始终一并发送全部字段。

  • 频率范围：low_cut 必须小于 high_cut。

  • Gain 允许值：gain 只能使用 1、10、100、1000，且仅在 autogain 为 false 时生效。

  • Listening Point：index_l 必须完整指定逗号分隔的 3 个 40×15 压缩索引（各为 0~599），且两个 Listening Point 之间在横向和纵向上各需要至少 ±2 格以上的间隔。详细限制和转换公式请参阅 Listening Point 坐标文档。

所有 REST 响应均使用通用的信封结构。error 为 0 表示成功，非 0 表示错误；发生错误时，result.message 中可能包含详细消息。

状态码响应示例原因
400{ "error": 1, "result": { "message": "lpoint parameter error" } }请求无效（例如 index_l 参数错误）
401-HTTP Basic 认证失败

故障排查 (Troubleshooting)

  • 发生 401 错误时：

    • 请确认 HTTP Basic 认证凭据。BATCAM FX 默认预设了 admin、user 两个账户。

  • 发生 400 错误( lpoint parameter error )时：

    • 请确认 index_l 是否由逗号分隔的 3 个索引组成。

    • 请确认各索引是否处于 40×15 压缩索引范围（0599）内。不得将 BF Map 原始索引（01199）未经转换直接发送。转换公式请参阅 Listening Point 坐标文档。

    • 请确认是否违反了 Listening Point 之间的最小间隔（横向·纵向 ±2 格）限制。

  • 仅发送了部分字段而设置未生效时：

    • 部分设置不会生效。请通过 GET 获取当前设置后，重新发送全部值。

  • Gain 设置未生效时：

    • 在 autogain 为 true 的状态下，gain 值不会被使用。请将 autogain 设置为 false 后再进行修改。

  • 流消息的 gain 值显示为 -1 时：

    • 这是启用自动增益（Auto Gain）时的正常行为。此时流消息的 gain 会返回最后设置的值或 -1。

相关文档