Skip to main content

MQTT — Add a New Event Kind

The device speaks MQTT for admin commands (fired from the web dashboard) and status reports. Every command is an envelope shaped like {"cmd": "data", "kind": "<kind>", "data": {…}}.

Sending an MQTT command from the backend​

The web admin fires commands via the BFF endpoint POST /device/{id}/send-message?listen=true, which relays over MQTT. Web-side client wrapper (in the autonomous.ai frontend repo) is StandToEarnApi.sendDeviceMessage.

Example payload:

{ "cmd": "data", "kind": "device.soft_reset", "data": {} }

Receiving on the device — add a new handler​

Adding a new MQTT command is three edits inside os/services/:

  1. Declare the kind constant in os/services/domain/device.go:

    const (
        KindDeviceRename    = "device.rename"
        KindDeviceSoftReset = "device.soft_reset"   // ← your new one
        // …
    )

  2. Write the handler — one file under os/services/server/device/delivery/mqtt/. See device_soft_reset_handler.go and device_rename_handler.go for reference patterns (envelope unmarshalling, ack via publishDataResult, goroutine-off-callback for long work).

  3. Wire it into the dispatcher — one case in the switch in os/services/server/device/delivery/mqtt/handler.go dispatchData():

    case domain.KindDeviceSoftReset:
        return h.handleDeviceSoftReset(env)

Rebuild os-server (see Building + Shipping Code) and the new command is live.

The full MQTT protocol reference (topics, envelope shape, privacy vs inline delivery, ack model) lives in the autonomous-os repo docs.