Beamforming Parameters

Overview

On BATCAM FX, you can configure the frequency filter, amplification, and Listening Point (LPoint) settings for the signal delivered from the microphones. This document explains the meaning and range of each beamforming parameter, and how to read and write the values through two interfaces: REST API and ROS 2.

This document applies to BATCAM FX. For beamforming settings on BATCAM FX2, see the Device Manager - Beamforming document.

Interface	Method	Path / Interface Name	Notes
REST API	HTTP `GET` / `PATCH`	`/beamforming/setting`	Requires HTTP Basic authentication. `PATCH` uses `multipart/form-data` format. You can try it directly under the beamforming tag in the API Playground.
ROS 2	Action	`/fx_{hardware_id}/setting_beamforming` ( `fx_stream_msgs/action/BeamformingSetting` )	Beta feature available from the v1.0.3b development firmware. See ROS Firmware BF/Overlay Settings (Beta).

Prerequisites

The BATCAM FX device serves the REST API directly. The base URL has the form http://{device_ip}; the examples below assume the device IP is 192.168.0.30.
All REST endpoints require HTTP Basic authentication. BATCAM FX comes with two preconfigured accounts: admin, user. Always change the factory default passwords before use.
Configuring via ROS 2 Action requires development firmware v1.0.3b or later and the fx-stream-msgs message package. For the message and action definitions, see the ROS Integration document.

Parameter Reference

REST PATCH request field names and ranges are listed below. The step is the smallest increment a value can change by; parameters with an explicit allowed-value list accept only those values.

Parameter	REST Field	Type	Unit	Min	Max	Step / Allowed Values
LowCut	`low_cut`	integer	Hz	1000	Less than HighCut	Step 100
HighCut	`high_cut`	integer	Hz	Greater than LowCut	100000	Step 100
Gain	`gain`	number	-	1	1000	Allowed values: `1`, `10`, `100`, `1000` only
Auto Gain	`autogain`	boolean	-	-	-	`true` / `false`
Distance	`distance`	number	-	1	10	Step 1
Image Calibration X	`x_cal`	number	-	0	1	Step 0.01
Image Calibration Y	`y_cal`	number	-	0	1	Step 0.01
Listening Point Index	`index_l`	string	-	0 (per index)	599 (per index)	Three comma-separated 40×15 compressed indexes required

Frequency Range - LowCut / HighCut ( `low_cut`, `high_cut` )

Sets the frequency filter. LowCut is a high-pass filter; HighCut is a low-pass filter.

LowCut: the lowest frequency to display in the frequency range. Sounds below this frequency are filtered out.
HighCut: the highest frequency to display in the frequency range. Sounds above this frequency are filtered out.

The two values must always satisfy low_cut < high_cut.

Gain / Auto Gain ( `gain`, `autogain` )

Gain is the amplification value of the microphones. It is not used while Auto Gain is enabled.

Auto Gain toggles automatic microphone amplification. The camera automatically determines the Gain based on the sound level.

To change Gain directly, first set autogain to false. When Auto Gain is enabled, the gain value included in ROS 2 and stream messages ( WsAudio, LPointAudio, Beamforming ) returns the last configured value or -1.

Distance ( `distance` )

Specifies the distance to the noise source being measured. The camera attempts more precise beamforming at the specified distance.

Image Calibration ( `x_cal`, `y_cal` )

If the position of the overlaid beamforming image does not match the actual camera image, use these values to adjust the position.

x_cal: corrects the x-coordinate offset between the camera image and the visualized overlay image.
y_cal: corrects the y-coordinate offset between the camera image and the visualized overlay image.

Listening Point Index ( `index_l` )

Sets the indexes of the Listening Points (LPoint) on the camera. The BF Map of BATCAM FX divides the camera image (1600x1200) into a 40x30 grid (one-dimensional indexes 0~1199); a Listening Point specifies a position on this grid by index.

However, API requests must send indexes converted (compressed) into the 40×15 layout with the vertical resolution halved. The compressed index range is 0~599.

Value format: send three comma-separated compressed indexes (each 0~599) as a single string. Example: 20,510,579

You must specify all three indexes; REST GET responses return them as an integer array (e.g. [20, 510, 579]).

⚠️ BF Map indexes use a coordinate system where the bottom-right is 0 and the top-left is 1199. For the 40×30 ↔ 40×15 compression/restoration formulas and per-language example code, see the Listening Point Coordinates document.

Field Name Differences Between REST and ROS 2

The parameters themselves are identical across both interfaces, but the Listening Point representation differs.

Parameter	REST ( `PATCH /beamforming/setting` )	ROS 2 ( `BeamformingSetting.msg` )
LowCut / HighCut	`low_cut`, `high_cut` (integer)	`low_cut`, `high_cut` (float64)
Gain / Auto Gain	`gain` (number), `autogain` (boolean)	`gain` (float64), `autogain` (bool)
Distance	`distance` (number)	`distance` (float64)
Image Calibration	`x_cal`, `y_cal` (number)	`x_cal`, `y_cal` (float64)
Listening Point	`index_l` (one comma-separated string)	`l_point_0`, `l_point_1`, `l_point_2` (three int32 fields)

Configuration Examples

Reading the Current Settings (REST)

GET /beamforming/setting returns the beamforming settings stored in the real-time processor inside the BATCAM FX.

curl -u admin:<password> http://192.168.0.30/beamforming/setting

Expected output ( error of 0 means success ):

{
  "error": 0,
  "result": {
    "autogain": true,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

Changing Settings (REST)

⚠️ Partial settings are not applied — you must send all values. To change only some values, first fetch the current settings with GET, then send the full modified set with PATCH.

PATCH /beamforming/setting accepts the full field set in multipart/form-data format.

curl -X PATCH http://192.168.0.30/beamforming/setting \
  -u admin:<password> \
  -F "low_cut=2000" \
  -F "high_cut=45000" \
  -F "gain=100" \
  -F "distance=1" \
  -F "x_cal=0.06" \
  -F "y_cal=0" \
  -F "index_l=20,510,579" \
  -F "autogain=false"

Expected output ( the applied settings are returned as-is ):

{
  "error": 0,
  "result": {
    "autogain": false,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

The full request/response schema is available under the beamforming tag in the API Playground.

Changing Settings (ROS 2 Action)

In ROS 2, set the same parameters with the fx_stream_msgs/action/BeamformingSetting Action. The default format is the same as the one provided by the REST API.

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

The Action’s Goal / Result / Progress all consist of a single BeamformingSetting-typed setting field. For the detailed specification, see the ROS Integration document.

Constraints and Error Responses

Send all values: PATCH /beamforming/setting does not support partial updates. Always send every field together.
Frequency range: low_cut must be less than high_cut.
Allowed Gain values: gain accepts only 1, 10, 100, 1000, and applies only when autogain is false.
Listening Point: index_l must specify all three comma-separated 40×15 compressed indexes (each 0~599), and any two Listening Points must be spaced at least ±2 cells apart both horizontally and vertically. For detailed constraints and conversion formulas, see the Listening Point Coordinates document.

All REST responses use a common envelope structure. error of 0 means success; any non-zero value is an error, in which case result.message may contain a detailed message.

Status Code	Example Response	Cause
400	`{ "error": 1, "result": { "message": "lpoint parameter error" } }`	Invalid request (e.g. `index_l` parameter error)
401	-	HTTP Basic authentication failure

Troubleshooting

If you get a 401 error:
- Check your HTTP Basic authentication credentials. BATCAM FX comes with two preconfigured accounts: admin, user.
If you get a 400 error ( lpoint parameter error ):
- index_l must consist of three comma-separated indexes.
- Make sure each index is within the 40×15 compressed index range (0~~599). Do not send raw BF Map indexes (0~~1199) without conversion. For the conversion formulas, see the Listening Point Coordinates document.
- Make sure the minimum spacing between Listening Points (±2 cells horizontally and vertically) is not violated.
If you sent only some fields and the settings were not applied:
- Partial settings are not applied. Fetch the current settings with GET, then resend all values.
If the Gain setting is not applied:
- autogain set to true means the gain value is not used. Set autogain to false before changing it.
If the gain value in stream messages shows -1:
- This is normal behavior when automatic amplification (Auto Gain) is enabled. In this case, the gain in stream messages returns the last configured value or -1.

Listening Point Coordinates - LPoint index coordinate system and compression/restoration formulas
ROS Integration - ROS 2 message and action specifications
ROS Firmware BF/Overlay Settings (Beta) - ROS 2 Action configuration example
Overlay Parameters - overlay image generation parameters
BATCAM FX API Playground - request/response schemas and live execution under the beamforming tag