Connection Methods

RosFit supports multiple ways to connect devices to the cloud, from the primary MQTT bridge to WebSocket rosbridge, direct DDS peering, and micro-ROS for resource-constrained MCUs. Choose the method that best fits your hardware, network topology, and latency requirements.

Comparison

ROS 2 Bridge

The ROS 2 Bridge uses rosbridge_suite to expose the local ROS 2 graph over a WebSocket. The RosFit dashboard and other web clients can connect directly to subscribe to topics and call services.

How it works

1. rosbridge_server runs on the robot and opens a WebSocket on port 9090.
2. Clients connect over ws:// (or wss:// with TLS) and send JSON-RPC messages to subscribe to topics, advertise publishers, or call services.
3. The bridge translates between the WebSocket JSON protocol and the native ROS 2 DDS layer.

When to use it

• Local development — You are on the same network as the robot and need quick, low-latency access to ROS 2 topics from a browser.
• Prototyping — You want to visualize topics in a web UI before setting up the full MQTT pipeline.
• Complementary access — Run rosbridge alongside the MQTT bridge for local debugging while production traffic flows through MQTT.

Limitations

• Not designed for WAN or multi-site deployments (no built-in NAT traversal).
• No message persistence or offline buffering.
• Scaling beyond a handful of clients requires additional infrastructure.

MQTT Bridge

The MQTT Bridge is the primary and recommended connection method for production deployments. It runs as a lightweight Python process on the robot, built on rclpy and paho-mqtt.

When to use MQTT instead of rosbridge

• Multi-site fleets — Robots are distributed across buildings, cities, or countries. MQTT works natively over the internet with NAT traversal.
• Cloud-first architecture — You need persistent telemetry storage, device shadows, and OTA — features that require cloud-side message routing.
• Behind NAT / firewalls — MQTT uses a single outbound TCP connection from the robot, which works through most firewalls without port forwarding.
• Offline resilience — The MQTT client queues messages locally when the connection drops and flushes them when it reconnects.

Topic mapping configuration

The bridge reads a YAML file that maps ROS 2 topics to MQTT topics. Each entry defines the direction, QoS, and optional message transform.

device_id: bot-01

mqtt:
  host: emqx.rosfit.cloud
  port: 8883
  tls: true
  token: mqtt_tok_a1b2c3d4e5f6

bridges:
  - ros_topic: /odom
    mqtt_topic: rosfit/bot-01/telemetry/odom
    direction: ros_to_mqtt
    qos: 1
    throttle_hz: 10

  - ros_topic: /cmd_vel
    mqtt_topic: rosfit/bot-01/cmd/cmd_vel
    direction: mqtt_to_ros
    qos: 1

  - ros_topic: /scan
    mqtt_topic: rosfit/bot-01/telemetry/scan
    direction: ros_to_mqtt
    qos: 0
    throttle_hz: 5

  - ros_topic: /battery_state
    mqtt_topic: rosfit/bot-01/telemetry/custom/battery
    direction: ros_to_mqtt
    qos: 1
    throttle_hz: 0.2

  - ros_topic: /camera/image_compressed
    mqtt_topic: rosfit/bot-01/blob/image
    direction: ros_to_mqtt
    qos: 0
    throttle_hz: 2
    max_payload_kb: 256

micro-ROS

For resource-constrained microcontrollers (ESP32, STM32, Arduino Portenta), RosFit integrates with the micro-ROS ecosystem.

Data path

┌──────────────┐    XRCE-DDS     ┌────────────────┐    DDS     ┌───────────┐    MQTT
│  ESP32 /     │ ──────────────▶ │  micro-ROS     │ ────────▶  │  RosFit   │ ────────▶  Cloud
│  STM32       │   serial/UDP    │  Agent         │   ROS 2    │  Bridge   │
│  (micro-ROS) │ ◀────────────── │  (on gateway)  │ ◀────────  │           │ ◀────────
└──────────────┘                 └────────────────┘            └───────────┘

1. The MCU runs a micro-ROS application that publishes and subscribes to ROS 2 topics using the XRCE-DDS protocol over serial (UART/USB) or UDP.
2. A micro-ROS Agent runs on a gateway device (Raspberry Pi, Jetson, or any Linux host) and translates XRCE-DDS to standard DDS.
3. The micro-ROS topics appear as native ROS 2 topics on the gateway's ROS 2 graph.
4. The RosFit Bridge (also running on the gateway) picks up these topics and forwards them to the cloud over MQTT.

When to use it

• Your sensors or actuators run on bare-metal MCUs without a full Linux/ROS 2 stack.
• You need sub-millisecond deterministic control on the MCU while still reporting telemetry to the cloud.
• You are building a mixed fleet of full robots and lightweight sensor nodes.

QoS mapping

ROS 2 and MQTT have different quality-of-service models. The RosFit Bridge maps between them automatically.

Override in bridge config

You can override the automatic mapping per topic in the bridge YAML:

bridges:
  - ros_topic: /critical_alert
    mqtt_topic: rosfit/bot-01/telemetry/custom/critical_alert
    direction: ros_to_mqtt
    qos: 2  # Force exactly-once even if ROS 2 QoS is RELIABLE

MQTT QoS quick reference