Skip to content
SMI Developer Center

ROS Domain ID Setup

BATCAM FX ROS Domain ID Configuration

1. Overview

BATCAM FX publishes sensor data on ROS 2 Humble, and only nodes that use the same ROS_DOMAIN_ID can discover and communicate with each other. Change this setting to keep multiple ROS 2 systems on the same network isolated from each other, or to match BATCAM FX to the Domain ID already used in your environment.

2. Choose a Method: Check Your Firmware Version

The configuration method depends on the firmware version. Check the firmware version of your device first.

Firmware versionConfiguration methodNotes
1.0.3c or laterREST API (Section 3, recommended)Officially supported
Below 1.0.3cManually edit the systemd service file (Section 4)Unofficial method — read the cautions first

Check the firmware version with the device status API (GET /setting/status), in the firmware_version field of the response.

Terminal window
curl -u admin:<password> "http://192.168.0.30/setting/status"
# Replace 192.168.0.30 with the actual IP address of your BATCAM FX.

Example response:

{
  "error": 0,
  "result": {
    "hardware_id": "3287162925128",
    "sbrio_version": "1.0.14",
    "firmware_version": "v1.0.3c"
  }
}

💡 Note: All BATCAM FX REST APIs require HTTP Basic authentication. The device ships with two preconfigured accounts, admin and user. Change the factory default passwords before use. For firmware update instructions, see BATCAM FX Web Software Update or BATCAM FX Shell Software Update.

Starting with firmware 1.0.3c, BATCAM FX supports setting the ROS Domain ID via the REST API. For the detailed request/response schema and live testing, see the BATCAM FX API Reference, under the ros tag.

MethodPathDescriptionRequest body
GET/ros/domainGet the currently configured ROS Domain IDNone
PATCH/ros/domainChange the ROS Domain IDmultipart/form-data

PATCH /ros/domain request fields:

FieldTypeRequiredDescription
domain_idintegerRequiredROS Domain ID to set

Get the current value

Terminal window
curl -u admin:<password> "http://192.168.0.30/ros/domain"

Example response:

{
  "error": 0,
  "result": {
    "domain_id": 123
  }
}

Change the value

Terminal window
curl -u admin:<password> -X PATCH "http://192.168.0.30/ros/domain" -F "domain_id=113"

Example response:

{
  "error": 0,
  "result": {
    "domain_id": 113
  }
}

⚠️ Caution: The connection to the camera drops briefly while the setting is applied. Losing the connection right after the change is normal behavior.

4. Manual Configuration on Older Firmware (Below 1.0.3c, Unofficial)

If your environment uses a ROS_DOMAIN_ID other than 0, this is the currently unofficially supported way to configure it.

BATCAM FX firmware below 1.0.3c provides no option to add a DOMAIN_ID to the ROS 2 stack running inside the device. You therefore need to edit the service file of beamforming-camerad, the daemon that creates and publishes the ROS 2 nodes and topics.

⚠️ Caution: This service is configured with Restart=always and StartLimitAction=reboot, so a wrong edit to the service file can make beamforming-camerad restart repeatedly until the camera reboots. Keep a copy of the original file before editing, and follow the format of the example below exactly. After a firmware update, we also recommend verifying that the setting is still in place.

Prerequisites

  • You must be able to reach BATCAM FX over SSH. Replace 192.168.50.11 in the examples below with the actual IP address of your BATCAM FX.

Steps

  1. Log in to BATCAM FX via SSH

  2. Open the service file (vi, nano, etc.)

  3. Add an Environment line to the Service section

  4. Reload the daemon and service files

  5. Restart beamforming-camerad or the camera

Detailed steps

Log in to BATCAM FX via SSH.

Terminal window
ssh root@192.168.50.11
# Change the IP address to match your environment.

Open the service file with the command below. Use whichever editor you prefer, such as vi or nano.

Terminal window
nano /lib/systemd/system/beamforming-camerad.service
# or
vi /lib/systemd/system/beamforming-camerad.service

Add the Environment value inside the Service section, as shown in the code block below. Replace 113 in the example with the ROS_DOMAIN_ID value for your environment.

[Unit]
Description=Batcam FX Camera daemon
Wants=multi-user.target
After=systemd-networkd.service dbus-org.neard.service network.target nvargus-daemon.service setup-account.service


[Service]
## Lines to add — set ROS_DOMAIN_ID to match your environment.
Environment=ROS_DOMAIN_ID=113
##
ExecStart=/bin/bash -c 'source /opt/ros/humble/local_setup.sh && systemctl restart nvargus-daemon && /opt/ros/humble/bin/beamforming-camerad'
Restart=always
StartLimitAction=reboot
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=infinity
ExecStartPre=/bin/sleep 15
# RuntimeMaxSec=86400


[Install]
WantedBy=multi-user.target

⚠️ Caution: systemd unit files do not support end-of-line comments. If the Environment=ROS_DOMAIN_ID=113 line is followed by a # comment on the same line, the comment is parsed as part of the value and the setting will not work — always put comments on a separate line.

Reload the systemd daemon with the command below.

Terminal window
systemctl daemon-reload

Restart beamforming-camerad or reboot the camera.

Terminal window
systemctl restart beamforming-camerad
# or
reboot

5. Verify the Configuration

You can verify that the setting has been applied in two ways.

Verify via REST API (firmware 1.0.3c or later)

GET /ros/domain should return a domain_id that matches the value you set. (See the query example in Section 3.)

Verify with ROS 2 topics on the host PC

In the ROS 2 environment on your host PC, set the same ROS_DOMAIN_ID as the device, then check that the BATCAM FX topics appear in the topic list.

Terminal window
export ROS_DOMAIN_ID=113   # Set to the same value configured on the device
ros2 topic list

When the setting is applied correctly, topics based on the camera hardware ID appear in the list, as shown below.

Terminal window
/fx_276730383020104/beamforming
/fx_276730383020104/image
/fx_276730383020104/lpoint_audio
/fx_276730383020104/prpd
/fx_276730383020104/ws_audio

The hardware ID in the topic names (hardware_id) is available from the device status API (GET /setting/status). For per-topic message specifications, see FX ROS System Integration Overview.

6. Troubleshooting

  • Device topics do not appear on the host:

    • Check that the host and the device use the same ROS_DOMAIN_ID. You can read the device value via GET /ros/domain (firmware 1.0.3c or later) or from the Environment line in the service file.

    • The default ROS DOMAIN_ID of the device is 123. If the device has not been changed, run export ROS_DOMAIN_ID=123 on the host and check again.

  • REST API calls fail with 401:

    • Check that the HTTP Basic authentication credentials (the admin or user account) are correct.

  • The camera disconnects right after a PATCH:

    • A brief disconnect while the setting is applied is normal behavior. Reconnect after a moment and verify the value with GET /ros/domain.

  • The service restarts repeatedly or the camera reboots after a manual edit:

    • Environment=ROS_DOMAIN_ID=<value>: check this line for an end-of-line comment or a typo, fix it, and run systemctl daemon-reload again.