MQTT IoT Devices

RosFit is not limited to ROS 2 robots. Any device that speaks MQTT can connect to the platform, send telemetry, receive commands, and participate in device shadow synchronization. This makes RosFit a unified fleet management layer for mixed deployments of robots and IoT sensors.

Topic convention

Every device in RosFit communicates over a structured MQTT topic hierarchy. Adhering to this convention ensures that telemetry is persisted, commands are routed, and the dashboard renders device data correctly.

rosfit/{device_id}/telemetry          # Device → Cloud: sensor readings, state
rosfit/{device_id}/command            # Cloud → Device: action requests
rosfit/{device_id}/status             # Device → Cloud: online/offline heartbeat
rosfit/{device_id}/shadow/reported    # Device → Cloud: current device state
rosfit/{device_id}/shadow/desired     # Cloud → Device: desired configuration
rosfit/{device_id}/ota                # Cloud → Device: firmware update instructions
rosfit/{device_id}/log                # Device → Cloud: structured log messages

Topic suffix	Direction	QoS	Retained	Purpose
`/telemetry`	Device → Cloud	0 or 1	No	High-frequency sensor data
`/command`	Cloud → Device	1	No	Action requests with acknowledgement
`/status`	Device → Cloud	1	Yes	Last-will heartbeat (`online`/`offline`)
`/shadow/reported`	Device → Cloud	1	Yes	Current device state snapshot
`/shadow/desired`	Cloud → Device	1	Yes	Desired configuration delta
`/ota`	Cloud → Device	1	No	Firmware URL + checksum
`/log`	Device → Cloud	0	No	Debug, info, warning, error logs

The device_id is assigned when you register a device through the API or dashboard. Use it consistently across all topics.

Telemetry schema

Telemetry payloads are JSON objects with a flat or shallow-nested structure. RosFit's message handler parses the JSON, extracts numeric fields for time-series storage, and makes all fields available in the dashboard.

Example: greenhouse sensor

{
  "temperature": 24.5,
  "humidity": 62.3,
  "soil_moisture": 48.1,
  "light_level": 8720,
  "battery_voltage": 3.72,
  "timestamp": "2026-03-30T10:15:00Z"
}

Schema rules

Rule	Description
Top-level keys are field names	Each key becomes a column in TimescaleDB and a selectable metric in the dashboard
Numeric values are indexed	Integers and floats are stored in the hypertable for charting and alerting
String values are stored as metadata	Useful for status enums (`"state": "charging"`)
`timestamp` is optional	If omitted, the server uses the MQTT message receive time
Nested objects are flattened	`{"position": {"x": 1.0, "y": 2.0}}` becomes `position.x` and `position.y`
Arrays are stored as JSON	Not indexed individually, but available in raw queries

Command schema

Commands are JSON objects sent from the cloud to a device. Each command has a command name, an optional data payload, and a unique request_id for tracking acknowledgement.

Example: set valve position

{
  "request_id": "cmd_7f3a2b",
  "command": "set_valve",
  "data": {
    "pin": 25,
    "open": true
  },
  "timeout_ms": 5000
}

Acknowledgement

Devices should publish a response to the telemetry topic (or a dedicated /command/ack sub-topic) to confirm execution:

{
  "request_id": "cmd_7f3a2b",
  "status": "completed",
  "result": {
    "pin": 25,
    "state": "open"
  },
  "executed_at": "2026-03-30T10:15:01Z"
}

The dashboard shows command status in real time: pending → delivered → completed or failed.

Custom device types

By default, RosFit treats every MQTT device as a generic sensor. To unlock device-specific dashboard views, alerts, and validation, define a custom device type in devices.yaml.

device_types:
  greenhouse_controller:
    display_name: "Greenhouse Controller"
    icon: "leaf"
    telemetry:
      - field: temperature
        unit: "°C"
        range: [-10, 60]
        alert_above: 40
        alert_below: 5
      - field: humidity
        unit: "%"
        range: [0, 100]
      - field: soil_moisture
        unit: "%"
        range: [0, 100]
        alert_below: 20
      - field: light_level
        unit: "lux"
        range: [0, 100000]
    commands:
      - name: set_valve
        description: "Open or close an irrigation valve"
        parameters:
          - name: pin
            type: integer
            required: true
          - name: open
            type: boolean
            required: true
      - name: set_shade
        description: "Adjust shade cover percentage"
        parameters:
          - name: percentage
            type: number
            min: 0
            max: 100
    status_fields:
      - field: battery_voltage
        warn_below: 3.3
        critical_below: 3.0
      - field: wifi_rssi
        warn_below: -70
        critical_below: -85

curl -X POST http://localhost:8000/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "greenhouse-north-01",
    "type": "greenhouse_controller",
    "tags": ["greenhouse", "north-wing"]
  }'

The dashboard will automatically render type-specific widgets: temperature gauges with alert thresholds, soil moisture charts, and command buttons for valve control.

Supported categories

RosFit's MQTT integration supports any device that can publish JSON over MQTT. Below are categories with tested device examples and common telemetry fields.

Smart agriculture

Device type	Examples	Telemetry fields
Soil sensors	Dragino LSE01, SenseCAP S2100	`soil_moisture`, `soil_temperature`, `soil_ec`
Climate sensors	BME280, SHT31, Davis Vantage	`temperature`, `humidity`, `pressure`, `wind_speed`
Irrigation actuators	ESP32 + relay boards, Netafim	`valve_state`, `flow_rate`, `total_volume`
Crop monitoring	ESP32-CAM, Seeed reCamera	`image_url`, `ndvi_estimate`, `growth_stage`

Smart building

Device type	Examples	Telemetry fields
HVAC controllers	Modbus → MQTT gateways, Shelly	`temperature`, `setpoint`, `fan_speed`, `mode`
Occupancy sensors	PIR, mmWave (LD2410), BLE beacons	`occupancy_count`, `zone`, `last_motion_at`
Lighting controllers	DALI → MQTT, Shelly Dimmer	`brightness`, `color_temp`, `power_watts`
Energy meters	Shelly EM, INA219	`voltage`, `current`, `power`, `energy_kwh`

Industrial IoT

Device type	Examples	Telemetry fields
PLC gateways	Siemens S7 → MQTT, Modbus TCP	`register_values`, `digital_inputs`, `alarms`
Vibration sensors	ESP32 + ADXL345, Bosch CISS	`vibration_rms`, `peak_acceleration`, `fft_dominant_freq`
Motor controllers	VFDs with MQTT, ODrive	`rpm`, `torque`, `temperature`, `fault_code`
Environmental	ESP32 + MQ series, PMS5003	`pm25`, `pm10`, `co2`, `voc`, `noise_db`

Vision and edge AI

Device type	Examples	Telemetry fields
ESP32-CAM	AI Thinker, XIAO ESP32S3 Sense	`image_url`, `detection_count`, `inference_ms`
TFLite edge	Coral Dev Board, RPi + Coral USB	`object_class`, `confidence`, `bbox`, `fps`
Intel RealSense	D435, D455, L515	`depth_map_url`, `pointcloud_topic`, `rgb_url`
Luxonis OAK-D	OAK-D, OAK-D Lite, OAK-1	`detection_results`, `spatial_coordinates`, `tracking_id`

All devices in these categories follow the same rosfit/{device_id}/telemetry topic convention and can be managed, monitored, and controlled from a single RosFit dashboard alongside your ROS 2 robots.