Bridge Configuration

The RosFit bridge is configured through a single YAML file — rosfit-bridge.yaml. This file defines the device identity, MQTT connection, topic mappings, service bridges, shadow behavior, OTA settings, and logging.

Overview

The configuration is divided into six top-level sections:

Section	Purpose
`rosfit`	Device identity and version
`connection`	MQTT broker address, transport, TLS, and authentication
`bridge`	ROS 2 ↔ MQTT topic and service mappings
`shadow`	Device shadow reporting behavior
`ota`	Over-the-air update settings
`logging`	Log level, file output, and rotation

The bridge reads this file at startup. Changes require a restart unless you send a reload_config command via MQTT.

Full example

# rosfit-bridge.yaml — complete configuration example

rosfit:
  device_id: bot-01
  version: "1.0"

connection:
  provider: self-hosted          # "self-hosted" or "rosfit-cloud"
  host: emqx.rosfit.local
  port: 8883
  transport: tcp                 # "tcp" or "websocket"
  tls:
    enabled: true
    ca_cert: /etc/rosfit/certs/ca.crt
    client_cert: /etc/rosfit/certs/bot-01.crt
    client_key: /etc/rosfit/certs/bot-01.key
    verify_hostname: true
  auth:
    method: token                # "token", "certificate", or "username"
    token: mqtt_tok_a1b2c3d4

bridge:
  publish:
    - ros_topic: /odom
      mqtt_suffix: telemetry/odom
      msg_type: nav_msgs/Odometry
      qos: 1
      throttle_hz: 10
    - ros_topic: /battery_state
      mqtt_suffix: telemetry/battery
      msg_type: sensor_msgs/BatteryState
      qos: 1
      throttle_hz: 1
    - ros_topic: /scan
      mqtt_suffix: telemetry/scan
      msg_type: sensor_msgs/LaserScan
      qos: 0
      throttle_hz: 5
    - ros_topic: /diagnostics
      mqtt_suffix: telemetry/diagnostics
      msg_type: diagnostic_msgs/DiagnosticArray
      qos: 1
      throttle_hz: 0.2
    - ros_topic: /camera/image_compressed
      mqtt_suffix: telemetry/camera
      msg_type: sensor_msgs/CompressedImage
      qos: 0
      throttle_hz: 2

  subscribe:
    - mqtt_suffix: cmd/cmd_vel
      ros_topic: /cmd_vel
      msg_type: geometry_msgs/Twist
      qos: 1
    - mqtt_suffix: cmd/navigate
      ros_topic: /navigate_to_pose
      msg_type: geometry_msgs/PoseStamped
      qos: 1
    - mqtt_suffix: cmd/set_param
      ros_topic: /rosfit/set_param
      msg_type: std_msgs/String
      qos: 1

  services:
    - ros_service: /set_parameters
      mqtt_request: cmd/set_parameters/request
      mqtt_response: cmd/set_parameters/response
      srv_type: rcl_interfaces/SetParameters
      timeout_sec: 10
    - ros_service: /get_parameters
      mqtt_request: cmd/get_parameters/request
      mqtt_response: cmd/get_parameters/response
      srv_type: rcl_interfaces/GetParameters
      timeout_sec: 5

shadow:
  enabled: true
  report_on_change: true
  report_interval_sec: 30
  watched_params:
    - max_speed
    - camera_resolution
    - led_color
    - navigation_mode
    - firmware_version

ota:
  enabled: true
  download_dir: /tmp/rosfit/ota
  scripts:
    pre_update: /opt/rosfit/scripts/pre_update.sh
    install: /opt/rosfit/scripts/install.sh
    post_update: /opt/rosfit/scripts/post_update.sh
    rollback: /opt/rosfit/scripts/rollback.sh
  auto_rollback: true
  max_download_retries: 3
  verify_checksum: true

logging:
  level: info                    # debug, info, warn, error
  file: /var/log/rosfit/bridge.log
  max_size_mb: 50
  rotate_count: 5

rosfit

The rosfit section identifies the device and configuration version.

Field	Type	Required	Description
`device_id`	string	yes	Unique device identifier, must match the registered device ID
`version`	string	no	Configuration schema version (default `"1.0"`)

rosfit:
  device_id: bot-01
  version: "1.0"

connection

Defines how the bridge connects to the MQTT broker.

Field	Type	Default	Description
`provider`	string	`self-hosted`	`self-hosted` for your own broker, `rosfit-cloud` for managed service
`host`	string	`localhost`	Broker hostname or IP
`port`	integer	`1883`	Broker port (`1883` plain, `8883` TLS)
`transport`	string	`tcp`	Transport protocol (`tcp` or `websocket`)
`tls.enabled`	boolean	`false`	Enable TLS encryption
`tls.ca_cert`	string	—	Path to CA certificate file
`tls.client_cert`	string	—	Path to client certificate (for mTLS)
`tls.client_key`	string	—	Path to client private key (for mTLS)
`tls.verify_hostname`	boolean	`true`	Verify the broker's hostname against the certificate
`auth.method`	string	`token`	Authentication method: `token`, `certificate`, or `username`
`auth.token`	string	—	MQTT access token (used with `token` method)
`auth.username`	string	—	MQTT username (used with `username` method)
`auth.password`	string	—	MQTT password (used with `username` method)

bridge

Maps ROS 2 topics to MQTT and vice versa. The bridge automatically prefixes all MQTT topics with rosfit/{device_id}/.

publish (ROS 2 → MQTT)

Each entry maps a local ROS 2 topic to an MQTT suffix.

Field	Type	Required	Description
`ros_topic`	string	yes	ROS 2 topic to subscribe to
`mqtt_suffix`	string	yes	MQTT topic suffix (prepended with `rosfit/{device_id}/`)
`msg_type`	string	yes	ROS 2 message type (e.g. `sensor_msgs/LaserScan`)
`qos`	integer	no	MQTT QoS level: `0`, `1`, or `2` (default `1`)
`throttle_hz`	number	no	Maximum publish rate in Hz (default unlimited)

subscribe (MQTT → ROS 2)

Each entry maps an MQTT suffix to a local ROS 2 topic.

Field	Type	Required	Description
`mqtt_suffix`	string	yes	MQTT topic suffix to subscribe to
`ros_topic`	string	yes	ROS 2 topic to publish on
`msg_type`	string	yes	ROS 2 message type
`qos`	integer	no	MQTT QoS level (default `1`)

services (ROS 2 service ↔ MQTT request/response)

Bridge ROS 2 services over MQTT using a request/response pattern.

Field	Type	Required	Description
`ros_service`	string	yes	ROS 2 service name
`mqtt_request`	string	yes	MQTT suffix for the request topic
`mqtt_response`	string	yes	MQTT suffix for the response topic
`srv_type`	string	yes	ROS 2 service type
`timeout_sec`	number	no	Service call timeout (default `10`)

shadow

Configures the AWS IoT-style device shadow behavior.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable shadow state reporting
`report_on_change`	boolean	`true`	Report immediately when a watched parameter changes
`report_interval_sec`	number	`30`	Periodic reporting interval in seconds
`watched_params`	array	`[]`	List of parameter names to include in the reported shadow state

The bridge publishes shadow updates to rosfit/{device_id}/shadow/reported and listens for desired state changes on rosfit/{device_id}/shadow/desired.

ota

Configures over-the-air firmware update behavior.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable OTA update support
`download_dir`	string	`/tmp/rosfit/ota`	Directory for downloaded firmware files
`scripts.pre_update`	string	—	Script to run before applying the update
`scripts.install`	string	—	Script to run to apply the firmware
`scripts.post_update`	string	—	Script to run after successful update
`scripts.rollback`	string	—	Script to run on rollback
`auto_rollback`	boolean	`true`	Automatically roll back if the post-update health check fails
`max_download_retries`	number	`3`	Number of download retry attempts
`verify_checksum`	boolean	`true`	Verify firmware SHA256 checksum

logging

Field	Type	Default	Description
`level`	string	`info`	Minimum log level (`debug`, `info`, `warn`, `error`)
`file`	string	—	Path to log file (logs to stdout if omitted)
`max_size_mb`	number	`50`	Maximum log file size before rotation
`rotate_count`	number	`5`	Number of rotated log files to keep

Environment variables reference