FX ROS Firmware BF/Overlay Parameter Setting (Beta)

⚠️ Beta: This document covers beta functionality; the interface and content may change with firmware updates. For version-specific changes, see the Firmware Release Notes.

Overview

BATCAM FX lets you change Beamforming and Overlay settings through the ROS 2 Action interface. This document covers the names and fields of the two setting actions, and how to call them from the terminal (CLI) and from Python code.

The values handled by each action use the same value scheme as the REST API (/beamforming/setting, /beamforming/overlay). For the REST API specification, see API Playground (FX).

For message type definitions and formats, refer to the ROS Integration document or the SMI OSS - fx-stream-msgs repository.

Prerequisites

Firmware version: The setting actions in this document are supported from FX firmware v1.0.3c (2025.05.27). ROS 2-based data transmission itself has been supported since the v1.0.3b development firmware. For details, see the Firmware Release Notes.
ROS 2 environment: The ROS 2 features of BATCAM FX are based on ROS 2 Humble Hawksbill. The fx-stream-msgs package is intended for use with ROS 2 Humble, and has been built and verified in a Python 3.10.16, ROS 2 Jazzy (Ubuntu 24.04) environment.
fx_stream_msgs package: Action type definitions are provided in the fx-stream-msgs repository. To use the types in the examples below, build and source the package in the workspace of the environment where you run the commands.
Network and ROS_DOMAIN_ID: On the same network as the camera, use the same ROS_DOMAIN_ID as the camera. For how to set the camera’s Domain ID, see the ROS Domain ID document.

Action names and hardware_id

BATCAM FX creates the following two setting actions based on the camera’s hardware ID.

Action name	Action type	Configures
`/fx_{hardware_id}/setting_beamforming`	`fx_stream_msgs/action/BeamformingSetting`	Beamforming parameters
`/fx_{hardware_id}/setting_overlay`	`fx_stream_msgs/action/OverlaySetting`	Overlay parameters

{hardware_id} appears in the action names when you run ros2 action list on the same ROS 2 network as the camera.

ros2 action list

# Example output
/fx_276730383020104/setting_beamforming
/fx_276730383020104/setting_overlay

The examples in this document are written for a camera whose hardware_id is 276730383020104.

The Goal of each action consists of a single setting field, which carries the entire set of setting values. Fields not specified in the Goal are sent as their type defaults (0, False), so we recommend filling in every field. The Result returns the applied settings in the same setting structure as the Goal, and the action specification also defines a Progress (feedback) item with the same structure.

Beamforming settings

/fx_{hardware_id}/setting_beamforming

Sets the beamforming parameter values. It uses the same value scheme as the REST API GET/PATCH /beamforming/setting endpoints; only the Listening Point notation differs. REST sends three comma-separated values in a single index_l field, while ROS splits them into three fields, l_point_0 ~ l_point_2.

Field summary

Field	Type	Unit	Range	Step / allowed values	Description
`autogain`	bool	-	False / True	Boolean	Whether to use automatic microphone gain. While True, the `gain` value is not used.
`gain`	float64	-	1 ~ 1000	Only `1`, `10`, `100`, `1000` are allowed	Microphone gain value. To change it, first set `autogain` to False.
`x_cal`	float64	-	0 ~ 1	Step 0.01	Corrects the x-coordinate offset between the camera image and the overlay image.
`y_cal`	float64	-	0 ~ 1	Step 0.01	Corrects the y-coordinate offset between the camera image and the overlay image.
`distance`	float64	-	1 ~ 10	Step 1	Distance to the noise source to measure.
`high_cut`	float64	Hz	Above low_cut ~ 100,000	Step 100	Maximum frequency to display. A low-pass filter: sounds above this value are filtered out.
`low_cut`	float64	Hz	1,000 ~ below high_cut	Step 100	Minimum frequency to display. A high-pass filter: sounds below this value are filtered out.
`l_point_0` ~ `l_point_2`	int32	-	0 ~ 1199	Step 1	Listening Point indexes. All three must be specified. For the coordinate system, see the Listening Point Coordinates document.

For detailed descriptions and the minimum/maximum/reference values of each parameter, refer to the Beamforming Parameters document.

Terminal example

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

On success, the output proceeds as follows, and the action finishes with the SUCCEEDED status.

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

The setting in the Result returns the settings applied to the camera in the same structure as the Goal.

Verifying the changes

The REST API GET /beamforming/setting endpoint returns the currently stored beamforming settings. For the specification, see API Playground (FX).
In ROS, subscribing to the /fx_{hardware_id}/beamforming topic lets you check values such as gain in the real-time beamforming data. While automatic gain is enabled, the published gain value is either the last configured value or -1.

Overlay settings

/fx_{hardware_id}/setting_overlay

Sets the overlay image generation parameters and the source detection mode for Full View mode. The overlay feature is supported on BATCAM FX firmware version 1.0.3 and later, and uses the same field layout as the REST API GET/PATCH /beamforming/overlay endpoints.

Field summary

Field	Type	Unit	Range	Step / allowed values	Description
`enable_overlay`	bool	-	False / True	Boolean	Whether to output the overlay image. When set to True, the overlay is shown on images delivered over RTSP and ROS.
`enable_source_mode`	bool	-	False / True	Boolean	Whether to use source detection mode. It works only while the overlay is enabled; the `number_of_sources` value determines whether single- or multi-source mode is activated.
`number_of_sources`	int32	-	1 ~ 5	Step 1	Number of sources to track simultaneously. Up to 5 can be specified, but 3 or fewer is recommended.
`average`	int32	-	0 ~ 10	Step 1	Number of beamforming maps to average. Higher values produce smoother results. Not applied while source detection mode is active.
`threshold`	float64	-	0 ~ 120	Step 1	Minimum intensity to be considered a source. Higher values show only stronger sources. Not applied while source detection mode is active.
`range`	float64	-	0 ~ 10	Step 0.1	Overlay image size for a source. Higher values make the overlay larger. Not applied while source detection mode is active.

For detailed descriptions and the minimum/maximum/reference values of each parameter, refer to the Overlay Parameters document.

Terminal example

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

The execution flow is the same as for the Beamforming settings. On success, the action finishes with the SUCCEEDED status, and the setting in the Result returns the applied overlay settings.

Verifying the changes

The REST API GET /beamforming/overlay endpoint returns the current overlay settings. For the specification, see API Playground (FX).
enable_overlay set to True shows the overlay on images delivered over RTSP and ROS, so you can verify it directly in the video stream.

Calling from code (Python)

In real integrations, actions are often called from code rather than through the terminal CLI. Below is a complete example that calls the Beamforming setting action with rclpy. The Overlay settings can be called with the same structure by changing only the action name, the type (OverlaySetting), and the fields.

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

from fx_stream_msgs.action import BeamformingSetting

HARDWARE_ID = '276730383020104'  # Replace with the value found via 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'Applied settings: {result.setting}')

    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

Troubleshooting

The actions do not appear in ros2 action list:
- Check that the camera firmware is v1.0.3c or later. (Firmware Release Notes)
- Check that the ROS_DOMAIN_ID of your environment matches the camera’s. (ROS Domain ID)
- Check that you are connected to the same network as the camera.
fx_stream_msgs types cannot be found:
- fx-stream-msgs package: check that the workspace where it was built is sourced in the current shell.
gain changes are not applied:
- autogain must be False for gain to take effect; while it is True, the value is ignored. First set autogain to False.
- The firmware v1.0.3 (2025.10.04) release includes the removal of the Gain setting and the disabling of Auto Gain. Check the behavior of your firmware version in the Firmware Release Notes.
Source detection mode does not work:
- enable_source_mode works only while enable_overlay is True.
average / threshold / range changes are not applied:
- These three values are not applied while source detection mode (enable_source_mode) is active.
Listening Point settings fail:
- l_point_0 ~ l_point_2 must all be specified within the 0 ~ 1199 range. For the coordinate system, see the Listening Point Coordinates document.
- The REST API, which uses the same value scheme, returns lpoint parameter error for invalid L Point parameters.

ROS Integration — full message and action specifications
ROS Domain ID — how to set ROS_DOMAIN_ID
Beamforming Parameters — beamforming parameter details
Overlay Parameters — overlay parameter details
Listening Point Coordinates — L Point index coordinate system
Firmware Release Notes — features supported per version
API Playground (FX) — REST API reference
SMI OSS - fx-stream-msgs — message/action type definition repository

FX ROS Firmware BF/Overlay Parameter Setting (Beta)

Overview

Prerequisites

Action names and hardware_id

Beamforming settings

Field summary

Terminal example

Verifying the changes

Overlay settings

Field summary

Terminal example

Verifying the changes

Calling from code (Python)

Troubleshooting

Related documents