跳转到内容
SMI Developer Center

FX ROS 固件 BF/Overlay 参数设置（测试版）

⚠️ 测试版： 本文档介绍的是测试版功能，其接口和内容可能会随固件更新而变更。各版本的变更内容请参阅固件发布说明。

概述

BATCAM FX 可通过 ROS 2 的 Action 接口更改波束成形（Beamforming）和叠加（Overlay）设置。本文档介绍这两个设置 Action 的名称与字段，以及在终端（CLI）和 Python 代码中的调用方法。

各 Action 所处理的值与 REST API（/beamforming/setting、/beamforming/overlay）使用相同的取值体系。REST API 规格可在 API Playground (FX) 中确认。

消息类型的定义及格式请参阅 ROS Integration 文档或 SMI OSS - fx-stream-msgs 代码仓库。

前提条件

  • 固件版本：本文档中的设置 Action（setting action）自 FX 固件 v1.0.3c（2025.05.27）起开始支持。基于 ROS 2 的数据发送本身自 v1.0.3b 开发固件起开始支持。详细内容请参阅固件发布说明。

  • ROS 2 环境：BATCAM FX 的 ROS 2 功能基于 ROS 2 Humble Hawksbill。fx-stream-msgs 包以在 ROS 2 Humble 中使用为前提，并已在 Python 3.10.16、ROS 2 Jazzy (Ubuntu 24.04) 环境中完成构建与验证。

  • fx_stream_msgs 包：Action 类型定义由 fx-stream-msgs 代码仓库提供。必须在执行命令的环境的工作空间中构建并 source 该包，才能使用下述示例中的类型。

  • 网络及 ROS_DOMAIN_ID：必须处于与相机相同的网络中，并使用与相机相同的 ROS_DOMAIN_ID。相机的 Domain ID 设置方法请参阅 ROS Domain ID 文档。

Action 名称与 hardware_id

BATCAM FX 会以相机的硬件 ID 为基准，创建以下两个设置 Action。

Action 名称Action 类型设置对象
/fx_{hardware_id}/setting_beamformingfx_stream_msgs/action/BeamformingSetting波束成形参数
/fx_{hardware_id}/setting_overlayfx_stream_msgs/action/OverlaySetting叠加参数

在与相机相同的 ROS 2 网络中执行 ros2 action list，即可从 Action 名称中确认 {hardware_id}。

Terminal window
ros2 action list


# 输出示例
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

本文档的示例以 hardware_id 为 276730383020104 的相机为基准编写。

各 Action 的 Goal 由 setting 一个字段构成，其中包含全部设置值并进行发送。Goal 中未指定的字段将以类型默认值（0、False）发送，因此建议填写所有字段后再发送。Result 中会以与 Goal 相同的 setting 结构返回已应用的设置值；Action 规格中还定义了相同结构的 Progress（反馈）项。

Beamforming 设置

/fx_{hardware_id}/setting_beamforming

设置波束成形参数的值。使用与 REST API 的 GET/PATCH /beamforming/setting 端点相同的取值体系，仅 Listening Point 的表示方式不同。在 REST 中通过 index_l 一个字段发送以逗号分隔的 3 个值，而在 ROS 中则分为 l_point_0 ~ l_point_2 三个字段。

字段摘要

字段类型单位范围步长 / 允许值说明
autogainbool-False / TrueBoolean是否使用麦克风自动增益。为 True 期间不会使用 gain 值。
gainfloat64-1 ~ 1000仅可使用允许值 1、10、100、1000麦克风增益值。如需更改，必须先将 autogain 设置为 False。
x_calfloat64-0 ~ 1步长 0.01相机图像与叠加图像的 x 坐标误差校正。
y_calfloat64-0 ~ 1步长 0.01相机图像与叠加图像的 y 坐标误差校正。
distancefloat64-1 ~ 10步长 1到待测噪声源的距离。
high_cutfloat64Hz大于 low_cut ~ 100,000步长 100要显示的最高频率。作为低通滤波器，高于该值的声音将被滤除。
low_cutfloat64Hz1,000 ~ 小于 high_cut步长 100要显示的最低频率。作为高通滤波器，低于该值的声音将被滤除。
l_point_0 ~ l_point_2int32-0 ~ 1199步长 1Listening Point 索引。必须全部指定 3 个。坐标体系请参阅 Listening Point 坐标 文档。

各参数的详细说明及最小值/最大值/基准值请参阅 Beamforming Parameters 文档。

终端示例

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

成功时将按如下流程输出，并以 SUCCEEDED 状态结束。

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

Result 的 setting 中会以与 Goal 相同的结构返回已应用到相机的设置值。

应用确认

  • 可通过 REST API 的 GET /beamforming/setting 查询当前保存的波束成形设置值。规格请参阅 API Playground (FX)。

  • 在 ROS 中订阅 /fx_{hardware_id}/beamforming 话题后，可从实时波束成形数据中确认 gain 值等。启用自动增益时，所发布的 gain 值将返回最后设置的值或 -1。

Overlay 设置

/fx_{hardware_id}/setting_overlay

设置 Full View 模式的叠加图像生成参数以及声源探测模式。叠加功能自 BATCAM FX 固件 1.0.3 版本以上开始支持，并使用与 REST API 的 GET/PATCH /beamforming/overlay 端点相同的字段构成。

字段摘要

字段类型单位范围步长 / 允许值说明
enable_overlaybool-False / TrueBoolean是否输出叠加图像。设置为 True 时，通过 RTSP 及 ROS 传输的图像上会显示叠加。
enable_source_modebool-False / TrueBoolean是否使用声源探测模式。需在叠加处于开启状态时才会运行，并根据 number_of_sources 的值启用单声源或多声源模式。
number_of_sourcesint32-1 ~ 5步长 1同时追踪的声源数量。最多可指定 5 个，但建议不超过 3 个。
averageint32-0 ~ 10步长 1用于取平均值的波束成形图数量。值越高结果越平滑。启用声源探测模式时不生效。
thresholdfloat64-0 ~ 120步长 1判定为声源的最小强度值。值越高则仅显示强度更大的声源。启用声源探测模式时不生效。
rangefloat64-0 ~ 10步长 0.1针对声源的叠加图像大小。值越高叠加越大。启用声源探测模式时不生效。

各参数的详细说明及最小值/最大值/基准值请参阅 Overlay Parameters 文档。

终端示例

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

执行结果的流程与 Beamforming 设置相同。成功时以 SUCCEEDED 状态结束，并在 Result 的 setting 中返回已应用的叠加设置值。

应用确认

  • 可通过 REST API 的 GET /beamforming/overlay 查询当前的叠加设置值。规格请参阅 API Playground (FX)。

  • 将 enable_overlay 设置为 True 后，通过 RTSP 及 ROS 传输的图像上会显示叠加，因此可在视频流中直接确认。

在代码中调用（Python）

在实际集成时，多数情况下是在代码中调用 Action，而非使用终端 CLI。以下是使用 rclpy 调用 Beamforming 设置 Action 的完整示例。Overlay 设置也只需更改 Action 名称、类型（OverlaySetting）和字段，即可以相同结构进行调用。

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


from fx_stream_msgs.action import BeamformingSetting


HARDWARE_ID = '276730383020104'  # 更改为通过 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'已应用的设置: {result.setting}')


    node.destroy_node()
    rclpy.shutdown()


if __name__ == '__main__':
    main()

问题排查（Troubleshooting）

  • Action 未出现在 ros2 action list 中时：

    • 确认相机的固件是否为 v1.0.3c 以上。（固件发布说明）

    • 确认执行环境的 ROS_DOMAIN_ID 是否与相机相同。（ROS Domain ID）

    • 确认是否已连接到与相机相同的网络。

  • 出现找不到 fx_stream_msgs 类型的错误时：

    • 确认构建了 fx-stream-msgs 包的工作空间是否已在当前 shell 中完成 source。

  • gain 的更改未生效时：

    • autogain 为 True 期间不会使用 gain 值。请先将 autogain 设置为 False。

    • 固件 v1.0.3（2025.10.04）版本中包含移除 Gain 设置及停用 Auto Gain 的变更。所使用固件版本的行为请查看固件发布说明。

  • 声源探测模式无法运行时：

    • enable_source_mode 仅在 enable_overlay 为 True 时才会运行。

  • average / threshold / range 的更改未生效时：

    • 这三个值在声源探测模式（enable_source_mode）启用期间不会生效。

  • Listening Point 设置失败时：

    • l_point_0 ~ l_point_2 必须在 0 ~ 1199 范围内全部指定 3 个。坐标体系请参阅 Listening Point 坐标 文档。

    • 在使用相同取值体系的 REST API 中，对于错误的 L Point 参数会返回 lpoint parameter error。

相关文档