Skip to content
SMI Developer Center

Overlay Parameters and Configuration

Overview

Starting with firmware version 1.0.3, BATCAM FX can composite the overlay image on the device itself and serve it over the RTSP stream. When the overlay is enabled, the beamforming overlay appears on images delivered via RTSP and ROS 2. This document describes the properties of the parameters used for overlay compositing and how to configure them.

This feature is available only on firmware 1.0.3 or later. To composite the raw RTSP video and beamforming data directly outside the device (on the client), see the BATCAM FX Overview document.

Prerequisites

  • Firmware 1.0.3 or later: check the current firmware version with the GET /setting/status response’s result.firmware_version value. If your version is older, update by following the Web Software Update or Shell Software Update document. See the Firmware Release Notes for changes in each version.

  • REST API credentials: all REST endpoints require HTTP Basic authentication. BATCAM FX ships with two preconfigured accounts, admin and user. Always change the factory default passwords before use.

  • ROS 2 environment (when configuring via ROS 2): for the device’s ROS 2 interface setup, see the ROS Integration document; for ROS Domain ID configuration, see the ROS Domain ID document.

Configuration Interfaces

Overlay parameters can be configured in two ways: via the REST API or a ROS 2 Action.

InterfaceMethodName / PathNotes
REST APIGET / PATCH/beamforming/overlayHTTP Basic authentication · PATCH request body is multipart/form-data · see the FX API Reference for the full specification
ROS 2Action/fx_{hardware_id}/setting_overlayAction type fx_stream_msgs/action/OverlaySetting — the Goal’s setting field is an OverlaySetting message

  • PATCH /beamforming/overlay does not support partial updates. Even when changing only some of the values, you must send all 6 fields as form-data.

  • The ROS 2 message and action definitions are available in the ROS Integration document or the SMI OSS - fx-stream-msgs repository.

Parameter Reference

The field names below are shared between the REST API form-data keys and the fields of the ROS 2 OverlaySetting message.

Field nameTypeRangeStepNotes
enable_overlayBooleantrue / false—Whether the overlay is rendered · prerequisite for all other settings
enable_source_modeBooleantrue / false—Works only while the overlay is enabled
number_of_sourcesInteger1 ~ 51Unit: number of sources · at most 3 recommended · used in source find mode
averageInteger0 ~ 101Unit: number of beamforming (BF) maps · not applied while source find mode is active
thresholdFloat0 ~ 1201BF visualization threshold · not applied while source find mode is active
rangeFloat0 ~ 100.1BF visualization range · not applied while source find mode is active

Parameter Dependencies

  • enable_overlay is the prerequisite for all overlay behavior. While the overlay is off (false), no overlay image is rendered and source find mode does not operate.

  • enable_source_mode (source find mode), when turned on, runs single- or multi-source mode according to the number_of_sources value; while it is on, the average, threshold, and range values are not applied.

  • enable_source_mode, when turned off, applies the average, threshold, and range values to overlay image generation.

Parameter Details

Enable Overlay (field name: enable_overlay)

Controls whether the overlay image is rendered. true shows the overlay on images delivered via RTSP and ROS 2.

Enable Source find mode (field name: enable_source_mode)

Controls source find mode. Source find mode works only while the overlay is enabled (enable_overlay=true). true activates single- or multi-source mode according to the number_of_sources value. See the Number of sources section below for the number of sources you can configure.

Number of sources (field name: number_of_sources)

Specifies the number of sources to track simultaneously. Used in source find mode (enable_source_mode=true). Up to 5 sources can be specified, but we recommend no more than 3.

Beamforming Averaging (field name: average)

Specifies the number of beamforming (BF) maps to average. Sets how strongly averaging is applied to reduce noise in the overlay image. Higher values produce smoother results.

Not applied while source find mode (enable_source_mode) is active.

Beamforming Threshold (field name: threshold)

Specifies the minimum intensity for a signal to be treated as a source in the overlay image. Higher values display only stronger sources.

Not applied while source find mode (enable_source_mode) is active.

Beamforming Image Range (field name: range)

Specifies the rendered image size of each source in the overlay image. Higher values enlarge the overlay drawn for each source.

Not applied while source find mode (enable_source_mode) is active.

Configuration Examples

REST API (curl)

Query the current overlay settings. Replace the device IP (192.168.0.30) and the account credentials to match your environment.

Terminal window
curl -u 'admin:<password>' http://192.168.0.30/beamforming/overlay

Expected response — every response uses the common envelope structure; an error of 0 means success.

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 1,
    "threshold": 15.0,
    "range": 5.0
  }
}

Change the settings. Since partial updates are not supported, send all 6 fields as form-data, using the query result above as the baseline.

Terminal window
curl -u 'admin:<password>' -X PATCH http://192.168.0.30/beamforming/overlay \
  -F 'enable_overlay=true' \
  -F 'enable_source_mode=true' \
  -F 'number_of_sources=3' \
  -F 'average=3' \
  -F 'threshold=30' \
  -F 'range=5'

Expected response — the full set of applied settings is returned.

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 3,
    "threshold": 30.0,
    "range": 5.0
  }
}

The full request/response schema is documented in the FX API Reference under the /beamforming/overlay entry.

ROS 2 (CLI)

In a ROS 2 environment, you can send the same settings via the /fx_{hardware_id}/setting_overlay action.

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

fx_276730383020104 is an example hardware ID. Find your actual hardware ID in the GET /setting/status response’s result.hardware_id value. For details on configuring via ROS 2 Actions, see the ROS Firmware BF/Overlay Settings (Beta) document.

Verify the Result

  • RTSP: open the device video stream in your RTSP client and check whether the overlay is displayed.

  • ROS 2: check the overlay on images published to the /fx_{hardware_id}/image topic (sensor_msgs/msg/CompressedImage).

  • Settings: call GET /beamforming/overlay again to fetch the currently applied values and confirm your changes.

Troubleshooting

  • The overlay does not appear in the stream:

    • GET /beamforming/overlay — check that enable_overlay is true.

    • This feature is not available on firmware below 1.0.3. In the GET /setting/status response, check result.firmware_version and, if needed, update the firmware.

  • average / threshold / range changes are not applied: enable_source_mode set to true means these three values are not applied. Turn source find mode off and check again.

  • Source find mode does not work: Source find mode works only while the overlay is enabled. Check that enable_overlay is true.

  • PATCH request fails with 400 (error: 1): Partial updates are not supported. Make sure you sent all 6 fields as form-data and that each value is within its allowed range.

  • 401 is returned: The HTTP Basic authentication credentials are missing or incorrect. Check the account information.