FX ROS 系统集成概述

概述

BATCAM FX 自 v1.0.3b 开发固件版本起支持基于 ROS 2 的数据发送，该功能已包含在正式发布固件 v1.0.3 中。通过本文档，您可以在主机 PC 的 ROS 2 节点中订阅 BATCAM FX 发布的 ROS 2 话题（波束成形图、音频、图像、PRPD 分类结果），并通过 ROS 2 动作控制波束成形与叠加图层设置。

ROS 2 数据通道与现有数据通道（RTSP 图像、WebSocket/Protobuf）相互独立地运行。关于现有数据通道，请参考 BATCAM FX 概述 文档。

BATCAM FX 使用 FX Stream Message 类型进行数据发送。相机的固件中包含基于 ROS 2 Humble Hawksbill 构建的二进制文件，消息格式在以下公开仓库中有详细定义。

• SMI OSS - fx-stream-msgs

这些消息以 ROS 2 接口类型定义，用于发布从传感器采集的数据。

本文档涵盖的内容如下。

• 涵盖内容：前提条件（固件、ROS 2 环境、网络）、快速开始（构建、订阅确认）、话题/消息规范、动作规范、故障排查

• 不涵盖内容：RTSP/WebSocket 通道对接（BATCAM FX 概述）、REST API 详情（FX API 演练场）、ROS Domain ID 变更步骤详情（ROS Domain ID 设置）

前提条件

固件版本

ROS 2 相关功能随固件版本逐步添加。详细的变更历史请参考 FX 固件发布说明。

功能	最初支持的固件	备注
ROS 2 话题发送 (beamforming / image / lpoint_audio / ws_audio / prpd)	v1.0.3b（开发固件）	已包含在正式发布版 v1.0.3 中
设置动作 (setting_beamforming / setting_overlay)	v1.0.3c	已包含在正式发布版 v1.0.3 中
ROS Domain ID 查询与设置 REST API (/ros/domain)	v1.0.3c	参考 ROS Domain ID 设置

所使用相机的固件版本可通过 REST API GET /setting/status（设备信息查询）确认。详细规范请参考 FX API 演练场。

ROS 2 环境

分类	环境	备注
相机（固件内置二进制文件）	ROS 2 Humble Hawksbill	已包含在固件中，无需单独安装
主机消息包 (fx-stream-msgs)	以使用 ROS 2 Humble 为前提	已在 Python 3.10.16、ROS 2 Jazzy (Ubuntu 24.04) 环境下构建，并通过与 BATCAM FX 的数据收发测试完成验证

💡 参考： fx-stream-msgs 以在 ROS 2 Humble 中使用为前提编写，并已通过在 ROS 2 Jazzy (Ubuntu 24.04) 环境下的构建以及与 BATCAM FX 之间的数据收发测试完成验证。

网络

• 相机的 ROS 2 栈使用基于 UDPv4 的 Fast DDS 配置（依据 v1.0.3c 发布说明）。相机与主机 PC 必须处于同一网络并能够相互通信。

• 只有相机与主机的 ROS_DOMAIN_ID 一致时才能看到话题。自 v1.0.3b 开发固件起，相机的默认 ROS_DOMAIN_ID 为 123，在固件 1.0.3c 及以上版本中可通过 REST API（GET、PATCH /ros/domain）查询与变更。详细内容请参考 ROS Domain ID 设置 文档。

• 订阅全部话题时，按 fx_stream_msgs 话题合计约需 3.6 MB/s（不含 image 话题）的带宽。为保证稳定接收，建议使用有线连接。

快速开始

1. 确认相机 hardware_id

BATCAM FX 的话题与动作名称中包含相机的硬件 ID（例如：/fx_{hardware_id}/beamforming）。硬件 ID 可通过 REST API GET /setting/status 确认。所有 REST 端点均需要 HTTP Basic 认证（参考 FX API 演练场）。

curl -u admin:{password} http://192.168.0.30/setting/status
# 请根据您的使用环境修改 IP 地址和密码后再使用。

响应示例：

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

若为该示例中的相机，则话题前缀为 /fx_3287162925128。以下各步骤的示例均使用该值。

2. 设置主机 ROS_DOMAIN_ID

在主机 shell 中设置与相机相同的域 ID。相机上所设置的值可通过 GET /ros/domain（固件 1.0.3c 及以上）确认，自 v1.0.3b 开发固件起默认值为 123。

export ROS_DOMAIN_ID=123
# 指定为与相机上设置的值相同的值。

3. 构建 fx-stream-msgs

若要在主机上使用 fx_stream_msgs 消息类型，请获取公开仓库并在工作空间中构建。

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

每次打开新终端时，都必须重新执行 source ~/fx_ws/install/setup.bash。

4. 确认话题与动作

在相机已开启并通过网络连接的状态下确认话题列表。

ros2 topic list

预期输出：

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

也可以确认动作列表。

ros2 action list

预期输出：

/fx_3287162925128/setting_beamforming
/fx_3287162925128/setting_overlay

5. 确认数据接收

尝试从 PRPD 话题接收 1 条消息。

ros2 topic echo /fx_3287162925128/prpd --once

预期输出（数值因测量情况而异）：

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

各数组是与 LPoint 通道 CH0~CH2 相对应的、按局部放电类型划分的 logit score。解释方法请参考 AI PRPD 分类器 文档。

6. 最小订阅节点示例 (Python)

以下是订阅 Beamforming 话题并输出 BF Map 最大值的最小节点的完整文件示例。

fx_beamforming_listener.py

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

HARDWARE_ID = '3287162925128'  # 修改为通过 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 是将 40x30 的 BF Map 展开为 1x1200 的数组，
        # 在 v1.0.2 及以上固件中为无需比例换算的 dB 值。
        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()

运行：

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

预期输出（数值因测量情况而异）：

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

话题参考

BATCAM FX 以相机的硬件 ID 为基准生成以下话题。

话题	消息类型	周期	平均带宽	每条消息大小
/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

除 LevelTrigger 之外的所有消息均以 25 Hz (25 fps) 的间隔周期性发布。fx_stream_msgs 话题的平均带宽合计约为 3.6 MB/s（不含 image 话题）。

数据解释注意事项

• WsAudio、LPointAudio、Beamforming 消息中包含的 gain 值，在相机的自动增益功能启用的情况下，将返回最后一次设置的值或 -1。

• WsAudio、LPointAudio 的 ws、lpoint0~2 值是长度为 8000 个采样的 float 数组，由 IEEE 754 格式的 Float Wave Format 构成。按 25 Hz 周期计算为每秒 200,000 个采样，对应相机的麦克风采样率（200 kHz）。

• 自 v1.0.2 固件起，Beamforming 消息的 bf 值为无需比例换算的 dB 值。

WsAudio.msg

类型	名称	说明
float64	gain	接收时刻的麦克风增益值。自动增益 (autogain) 启用时为最后设置的值或 -1
float32[]	ws	长度为 8000 个采样的音频信号 (IEEE 754 Float Wave Format)

LPointAudio.msg

类型	名称	说明
float64	gain	接收时刻的麦克风增益值。自动增益 (autogain) 启用时为最后设置的值或 -1
float32[]	lpoint0	在 Listening Point 0 位置经波束成形的音频信号，8000 个采样的 float 数组 (IEEE 754 Float Wave Format)
float32[]	lpoint1	Listening Point 1 位置的音频信号（格式相同）
float32[]	lpoint2	Listening Point 2 位置的音频信号（格式相同）

关于 Listening Point 的坐标体系与设置约束，请参考 Listening Point 坐标 文档。

Beamforming.msg

类型	名称	说明
float64	gain	接收时刻的麦克风增益值。自动增益 (autogain) 启用时为最后设置的值或 -1
float64[]	bf	将 40×30 的 BF Map 展开为 1×1200 的数组。自 v1.0.2 固件起为无需比例换算的 dB 值（参考 BF Map 结构与坐标系）
float64[]	level	—
int32[]	param1	—
int32[]	param2	—
int32[]	theta	—
int32[]	pos_x	—
int32[]	pos_y	—
int32[]	v_pos_x	—
int32[]	v_pos_y	—

Prpd.msg

各字段是与 LPoint 通道 CH0~CH2 相对应的长度为 3 的数组，其值为按局部放电类型划分的未归一化 logit score。使用 argmax、softmax 的解释方法与示例代码请参考 AI PRPD 分类器 文档。

类型	名称	说明
float32[3]	noise	各通道的 Noise（非放电噪声）logit score
float32[3]	corona	各通道的 Corona 放电 logit score
float32[3]	floating	各通道的 Floating 放电 logit score
float32[3]	surface	各通道的 Surface 放电 logit score

LevelTrigger.msg（预定不使用）

虽已定义为消息类型，但预定不使用，且未包含在上述话题列表中。

类型	名称	说明
float64	decibel	电平值 (dB)

动作参考

BATCAM FX 以相机的硬件 ID 为基准生成以下动作（固件 v1.0.3c 及以上）。

动作	动作类型	用途
/fx_{hardware_id}/setting_beamforming	fx_stream_msgs/action/BeamformingSetting	波束成形参数设置
/fx_{hardware_id}/setting_overlay	fx_stream_msgs/action/OverlaySetting	叠加图层图像生成参数及源模式设置

使用动作进行设置的详细示例请参考 使用 ROS 动作进行 Beamforming 与 Overlay 设置（测试版） 文档。相同的设置也可以通过 REST API 完成（FX API 演练场）。

BeamformingSetting.action

Goal、Result、Progress 均由 BeamformingSetting 消息类型的单个 setting 字段构成。

区段	类型	名称
Goal	BeamformingSetting	setting
Result	BeamformingSetting	setting
Progress	BeamformingSetting	setting

BeamformingSetting.msg — 各字段的最小/最大/基准值请参考 Beamforming 参数 文档。

类型	名称	说明	范围（单位/步长）
bool	autogain	是否使用麦克风自动增益。相机根据声音大小自动确定 Gain	True / False
float64	gain	麦克风增益值。仅在 autogain 为 False 时适用	1 ~ 1000（仅允许 1、10、100、1000）
float64	x_cal	相机图像与叠加图层图像的 x 坐标误差校正	0 ~ 1（步长 0.01）
float64	y_cal	相机图像与叠加图层图像的 y 坐标误差校正	0 ~ 1（步长 0.01）
float64	distance	到待测噪声源的距离。以指定的距离尝试更精确的波束成形	1 ~ 10（步长 1）
float64	high_cut	要显示的最高频率（低通滤波器）。高于该值的声音将被滤除	大于 low_cut ~ 100,000 Hz（步长 100）
float64	low_cut	要显示的最低频率（高通滤波器）。低于该值的声音将被滤除	1,000 Hz ~ 小于 high_cut（步长 100）
int32	l_point_0	Listening Point 0 的索引（40×30 网格）。3 个均需指定	0 ~ 1199
int32	l_point_1	Listening Point 1 的索引	0 ~ 1199
int32	l_point_2	Listening Point 2 的索引	0 ~ 1199

Listening Point 之间的最小距离限制等坐标相关约束，请参考 Listening Point 坐标 文档。在 REST API 中，相同的值通过 index_l 字段（以逗号分隔的 3 个值）发送。

终端示例：

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、Progress 均由 OverlaySetting 消息类型的单个 setting 字段构成。

区段	类型	名称
Goal	OverlaySetting	setting
Result	OverlaySetting	setting
Progress	OverlaySetting	setting

OverlaySetting.msg — 各字段的最小/最大/基准值请参考 Overlay 参数 文档。

类型	名称	说明	范围（单位/步长）
bool	enable_overlay	是否输出叠加图层图像。为 True 时，在通过 RTSP 及 ROS 传输的图像上显示叠加图层	True / False
bool	enable_source_mode	源探测模式。需在叠加图层已开启的状态下才能使用	True / False
int32	number_of_sources	同时追踪的源数量（建议 3 个以下）	1 ~ 5（步长 1）
int32	average	应用平均值的波束成形图数量。源探测模式启用时不适用	0 ~ 10（步长 1）
float64	threshold	判定为源的最小强度值。源探测模式启用时不适用	0 ~ 120（步长 1）
float64	range	针对源的叠加图层图像大小。源探测模式启用时不适用	0 ~ 10（步长 0.1）

终端示例：

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

故障排查 (Troubleshooting)

• 话题未出现在列表中时：

  • 确认主机的 ROS_DOMAIN_ID 是否与相机的设置一致。自 v1.0.3b 开发固件起，相机的默认值为 123，当前值可通过 GET /ros/domain（固件 1.0.3c 及以上）确认。（ROS Domain ID 设置）

  • 确认相机与主机是否能在同一网络中通信。相机的 ROS 2 栈使用基于 UDPv4 的 Fast DDS 配置。

  • 通过 GET /setting/status 确认固件是否为支持 ROS 2 发送的版本（话题发送自 v1.0.3b 开发固件起提供，已包含在正式发布版 v1.0.3 中）。

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

  • 确认是否已构建 fx-stream-msgs 包，并在当前终端中执行了 source ~/fx_ws/install/setup.bash。

  • 可通过 ros2 interface show fx_stream_msgs/msg/Beamforming 命令确认类型是否已被识别。

  • fx-stream-msgs 以使用 ROS 2 Humble 为前提，并已通过在 ROS 2 Jazzy (Ubuntu 24.04) 环境下的构建与收发测试完成验证。

• 接收到的 gain 值为 -1 时：

  • 这是相机的自动增益 (autogain) 功能启用时的正常行为。若要使用固定的 gain 值，请将 autogain 设置为 False 后再指定 gain（Beamforming 参数）。

• 接收出现延迟或中断时：

  • 订阅全部话题时，按 fx_stream_msgs 话题合计约需 3.6 MB/s（不含 image 话题）的带宽。建议使用有线连接，并仅订阅所需的话题。

• 变更 ROS Domain ID 后相机连接立即中断时：

  • 在 PATCH /ros/domain 设置生效期间，与相机的连接会暂时中断。生效后请重新连接。

相关文档

• ROS Domain ID 设置 — 域 ID 的查询与变更方法（REST API 及旧版本的手动设置）

• 使用 ROS 动作进行 Beamforming 与 Overlay 设置（测试版） — 动作使用的详细示例

• Beamforming 参数 — 波束成形设置值的范围与基准

• Overlay 参数 — 叠加图层设置值的范围与基准

• Listening Point 坐标 — BF Map 结构与 LPoint 索引体系

• AI PRPD 分类器 — Prpd 消息的解释方法与示例代码

• FX 固件发布说明 — 各版本 ROS 功能的变更历史

• FX API 演练场 — REST API 参考（/setting/status、/ros/domain 等）

• SMI OSS - fx-stream-msgs — 消息与动作类型定义（公开仓库）