FX ROS Firmware BF/Overlay Parameter Setting (ベータ)

⚠️ ベータ: 本ドキュメントはベータ機能を扱っており、インターフェースおよび内容はファームウェアのアップデートに伴って変更される場合があります。バージョンごとの変更点はファームウェアリリースノートを参照してください。

概要

BATCAM FXは、ROS 2のActionインターフェースを介してビームフォーミング(Beamforming)およびオーバーレイ(Overlay)の設定を変更できます。本ドキュメントでは、2つの設定アクションの名前とフィールド、ターミナル(CLI)およびPythonコードからの呼び出し方法を説明します。

各アクションが扱う値は、REST API(/beamforming/setting, /beamforming/overlay)と同じ値体系を使用します。REST APIの仕様はAPI Playground (FX)で確認できます。

メッセージタイプの定義および形式は、ROS Integrationドキュメント、またはSMI OSS - fx-stream-msgsリポジトリを参照してください。

前提条件

ファームウェアバージョン: 本ドキュメントの設定アクション(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パッケージ: アクションタイプの定義はfx-stream-msgsリポジトリで提供されます。コマンドを実行する環境のワークスペースで該当パッケージをビルドしてソーシングしないと、以下の例のタイプを使用できません。
ネットワークおよびROS_DOMAIN_ID: カメラと同じネットワーク上で、カメラと同一のROS_DOMAIN_IDを使用する必要があります。カメラのDomain IDの設定方法はROS Domain IDドキュメントを参照してください。

アクション名とhardware_id

BATCAM FXは、カメラのハードウェアIDを基準に次の2つの設定アクションを生成します。

アクション名	アクションタイプ	設定対象
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	ビームフォーミングパラメータ
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	オーバーレイパラメータ

{hardware_id}は、カメラと同じROS 2ネットワークでros2 action listを実行すると、アクション名から確認できます。

ros2 action list

# 出力例
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

本ドキュメントの例は、hardware_idが276730383020104のカメラを基準に作成されています。

各アクションのGoalはsettingフィールド1つで構成され、その中に設定値全体を含めて送信します。Goalで明示しなかったフィールドはタイプの既定値(0、False)で送信されるため、すべてのフィールドを埋めて送信することを推奨します。ResultにはGoalと同じsetting構造で適用された設定値が返され、アクション仕様には同じ構造のProgress(フィードバック)項目も定義されています。

Beamforming 設定

/fx_{hardware_id}/setting_beamforming

ビームフォーミングパラメータの値を設定します。REST APIのGET/PATCH /beamforming/settingエンドポイントと同じ値体系を使用しますが、Listening Pointのみ表記が異なります。RESTではindex_lという1つのフィールドにカンマで区切った3つの値を送信しますが、ROSではl_point_0 ~ l_point_2の3つのフィールドに分かれています。

フィールド概要

フィールド	タイプ	単位	範囲	ステップ / 許容値	説明
`autogain`	bool	-	False / True	Boolean	マイクの自動増幅を使用するかどうか。Trueの間は`gain`値は使用されません。
`gain`	float64	-	1 ~ 1000	許容値`1`、`10`、`100`、`1000`のみ使用可能	マイクの増幅値。変更するには、まず`autogain`をFalseに設定する必要があります。
`x_cal`	float64	-	0 ~ 1	ステップ 0.01	カメラ映像とオーバーレイ画像のx座標の誤差補正。
`y_cal`	float64	-	0 ~ 1	ステップ 0.01	カメラ映像とオーバーレイ画像のy座標の誤差補正。
`distance`	float64	-	1 ~ 10	ステップ 1	測定する騒音源までの距離。
`high_cut`	float64	Hz	low_cut 超過 ~ 100,000	ステップ 100	表示する最大周波数。ローパスフィルターであり、この値より上の音は除去されます。
`low_cut`	float64	Hz	1,000 ~ high_cut 未満	ステップ 100	表示する最低周波数。ハイパスフィルターであり、この値より下の音は除去されます。
`l_point_0` ~ `l_point_2`	int32	-	0 ~ 1199	ステップ 1	Listening Pointのインデックス。3つすべてを指定する必要があります。座標体系はListening Point 座標ドキュメントを参照してください。

各パラメータの詳細な説明および最小/最大/基準値は、Beamforming Parametersドキュメントを参照してください。

ターミナルの例

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_overlay`	bool	-	False / True	Boolean	オーバーレイ画像を出力するかどうか。Trueに設定すると、RTSPおよびROSへ送信される画像にオーバーレイが表示されます。
`enable_source_mode`	bool	-	False / True	Boolean	ソース探知モードを使用するかどうか。オーバーレイがオンになっている必要があり、`number_of_sources`の値に応じて単一または複数ソースモードが有効になります。
`number_of_sources`	int32	-	1 ~ 5	ステップ 1	同時に追跡するソースの個数。最大5個まで指定できますが、3個までを推奨します。
`average`	int32	-	0 ~ 10	ステップ 1	平均値を適用するビームフォーミングマップの個数。高いほど結果が滑らかになります。ソース探知モードが有効な場合は適用されません。
`threshold`	float64	-	0 ~ 120	ステップ 1	ソースと判断する最小強度値。高いほどより強いソースのみが表示されます。ソース探知モードが有効な場合は適用されません。
`range`	float64	-	0 ~ 10	ステップ 0.1	ソースに対するオーバーレイ画像のサイズ。高いほどオーバーレイが大きくなります。ソース探知モードが有効な場合は適用されません。

各パラメータの詳細な説明および最小/最大/基準値は、Overlay Parametersドキュメントを参照してください。

ターミナルの例

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)

実際の統合では、ターミナルのCLIではなくコードからアクションを呼び出す場合が多くあります。以下はrclpyでBeamforming設定アクションを呼び出す全体の例です。Overlay設定も、アクション名とタイプ(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)

アクションがros2 action listに表示されない場合:
- カメラのファームウェアがv1.0.3c以上であるかを確認します。(ファームウェアリリースノート)
- 実行環境のROS_DOMAIN_IDがカメラと同一であるかを確認します。(ROS Domain ID)
- カメラと同じネットワークに接続されているかを確認します。
fx_stream_msgsタイプが見つからないというエラーが発生する場合:
- fx-stream-msgsパッケージをビルドしたワークスペースが、現在のシェルにソーシングされているかを確認します。
gainの変更が反映されない場合:
- autogainがTrueの間はgain値が使用されません。まずautogainをFalseに設定します。
- ファームウェアv1.0.3(2025.10.04)リリースには、Gain設定の削除およびAuto Gainの無効化という変更が含まれています。使用中のファームウェアバージョンの動作はファームウェアリリースノートで確認してください。
ソース探知モードが動作しない場合:
- enable_source_modeはenable_overlayがTrueの場合にのみ動作します。
average / threshold / rangeの変更が反映されない場合:
- これら3つの値は、ソース探知モード(enable_source_mode)が有効な間は適用されません。
Listening Pointの設定が失敗する場合:
- l_point_0 ~ l_point_2は0 ~ 1199の範囲で3つすべてを指定する必要があります。座標体系はListening Point 座標ドキュメントを参照してください。
- 同じ値体系を使用するREST APIでは、誤ったL Pointパラメータに対してlpoint parameter errorを返します。

FX ROS Firmware BF/Overlay Parameter Setting (ベータ)

概要

前提条件

アクション名とhardware_id

Beamforming 設定

フィールド概要

ターミナルの例

反映の確認

Overlay 設定

フィールド概要

ターミナルの例

反映の確認

コードからの呼び出し (Python)

トラブルシューティング (Troubleshooting)

関連ドキュメント