FX ROS システム統合の概要

概要

BATCAM FX は v1.0.3b 開発ファームウェアバージョンから ROS 2 ベースのデータ送信をサポートしており、この機能は正式リリースファームウェア v1.0.3 に含まれています。本ドキュメントを通じて、BATCAM FX がパブリッシュする ROS 2 トピック（ビームフォーミングマップ、オーディオ、映像、PRPD 分類結果）をホスト PC の ROS 2 ノードで購読し、ROS 2 アクションでビームフォーミング・オーバーレイ設定を制御できます。

ROS 2 データチャンネルは、既存のデータチャンネル（RTSP 映像、WebSocket/Protobuf）とは独立して動作します。既存のデータチャンネルについては BATCAM FX 概要ドキュメントをご参照ください。

ROS 2 データチャンネルは既存のデータチャンネルとは独立して動作します。

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

ホストのシェルで、カメラと同じドメイン 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 フィールド 1 つで構成されます。

区分	タイプ	名前
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 フィールド 1 つで構成されます。

区分	タイプ	名前
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）