MQTT Documentation

Here is a list of the MQTT topics and commands that you can use to interact with Yoto players.

MQTT Command Topics

`/device/{id}/command/events/request`

Direction: Client → Device

Description: Triggers the device to publish a current events report to /device/{id}/data/events.

`/device/{id}/command/status/request`

Direction: Client → Device

Description: Triggers the device to publish a current status report to /device/{id}/data/status.

`/device/{id}/command/volume/set`

Direction: Client → Device

Description: Sets the player’s volume level.

Payload:

{
  "volume": <integer>
}

Field Details:

volume: Level to set [0 - 100]

`/device/{id}/command/ambients/set`

Direction: Client → Device

Description: Sets the RGB tone for the player’s ambient LEDs.

Payload:

{
  "r": <integer>,
  "g": <integer>,
  "b": <integer>
}

Field Details:

r: Red intensity [0 - 255]
g: Green intensity [0 - 255]
b: Blue intensity [0 - 255]

`/device/{id}/command/sleep-timer/set`

Direction: Client → Device

Description: Starts or restarts the sleep timer.

Payload:

{
  "seconds": <integer>
}

Field Details:

seconds: Number of seconds for the sleep timer. 0 disables the timer.

`/device/{id}/command/reboot`

Direction: Client → Device

Description: Triggers a system reboot.

`/device/{id}/command/card/start`

Direction: Client → Device

Description: Starts playback of a card with optional targeting of chapters, tracks, offsets, and playback controls.

Payload:

{
  "uri":           "<string>",
  "chapterKey":    "<string>",   // optional
  "trackKey":      "<string>",   // optional
  "secondsIn":     <integer>,  // optional
  "cutOff":        <integer>,  // optional
  "anyButtonStop": <boolean>,  // optional
}

Field Details:

uri: Card URI (e.g., https://yoto.io/<cardID>)
chapterKey: Chapter to start playback from
trackKey: Track to start playback from
secondsIn: Playback start offset (in seconds)
cutOff: Playback stop offset (in seconds)
anyButtonStop: Whether button press stops playback

`/device/{id}/command/card/stop`

Direction: Client → Device

Description: Stops playback of a card.

`/device/{id}/command/card/pause`

Direction: Client → Device

Description: Pauses playback of a card.

`/device/{id}/command/card/resume`

Direction: Client → Device

Description: Resumes playback of a card.

`/device/{id}/command/bluetooth/on`

Direction: Client → Device

Description: Turns Bluetooth on in a specified mode with optional filters.

Warning: Entering Bluetooth sink mode (mode: false) disables MQTT command handling entirely until the user physically holds the left button for approximately 3 seconds to exit the mode. There is no way to detect this state or recover from it programmatically, so callers will receive no response after entering this mode.

Payload:

{
  "action": "<string>",   // optional
  "mode":   <boolean>,   // optional
  "rssi":   <integer>,  // optional
  "name":   "<string>",   // optional
  "mac":    "<string>"    // optional
}

Field Details:

action: "on"
mode: "true" (BT audio source) BT sink is not triggered by setting the mode to false to trigger bt sink/speaker mode set mode to “bt_speaker” and do not set action mode only /bluetooth/on {“mode”:“bt_speaker”}
rssi: RSSI threshold for auto-connect
name: Target Bluetooth device name
mac: Target Bluetooth MAC (preferred over name)

`/device/{id}/command/bluetooth/off`

Direction: Client → Device

Description: Turns Bluetooth off.

`/device/{id}/command/bluetooth/delete-bond`

Direction: Client → Device

Description: Deletes all previously bonded Bluetooth devices.

`/device/{id}/command/bluetooth/connect`

Direction: Client → Device

Description: Connects to a previously bonded Bluetooth device.

`/device/{id}/command/bluetooth/disconnect`

Direction: Client → Device

Description: Disconnects the current active Bluetooth connection.

`/device/{id}/command/bluetooth/state`

Direction: Client → Device

Description: Checks if the Bluetooth driver is initialized and running.

`/device/{id}/command/display/preview`

Direction: Client → Device

Description: Previews an icon on the player display.

Payload:

{
  "uri":      "<string>",
  "timeout":  <integer>,
  "animated": <integer>
}

Field Details:

uri: Filepath to the icon asset
timeout: Display duration in seconds
animated: Whether the icon is animated (1) or static (0)

MQTT Data Topics

`/device/{id}/data/events`

Direction: Device → Client

Description: Provides real-time playback and interaction event data.

Payload:

{
  "cardId": "<string>",
  "chapterTitle": "<string>",
  "chapterKey": "<string>",
  "trackTitle": "<string>",
  "trackKey": "<string>",
  "position": <integer>,         // Current position in seconds
  "trackLength": <integer>,      // Track duration in seconds
  "playbackStatus": "<string>",  // "playing", "paused", or "stopped"
  "volume": <integer>,
  "sleepTimerActive": <boolean>,
  "sleepTimerSeconds": <integer>, // Seconds remaining on the sleep timer
  "repeatAll": <boolean>,
  "requestId": "<string>",       // Card playback request ID
  "source": "<string>",          // How audio was started: "card", "remote", "button", "bt", "none"
  "streaming": <boolean>,
  "volumeMax": <integer>,
  "playbackWait": <boolean>,
  "eventUtc": <integer>,         // Unix timestamp
  "cardUpdatedAt": "<string>"    // ISO8601 format timestamp
}

`/device/{id}/data/status`

Direction: Device → Client

Description: Provides device status information, environment details, and configuration state.

Payload:

{
  "status": {
    "statusVersion": <integer>, // Public status payload version
    "fwVersion": "<string>", // Firmware version currently running on the player
    "productType": "<string>", // Player hardware/product type
    "batteryLevel": <integer>, // Battery charge percentage
    "als": <integer>, // Ambient light sensor reading
    "freeDisk": <integer>, // Free SD card space, in KB
    "shutdownTimeout": <integer>, // Inactivity timeout before the player shuts down
    "dbatTimeout": <integer>, // Display timeout setting
    "charging": <integer>, // Whether the player is currently charging
    "activeCard": "<string>", // Card ID for the currently active card, when available
    "cardInserted": <integer>, // Inserted card type
    "playingStatus": <integer>, // Current audio playback state
    "headphones": <integer>, // Whether headphones are inserted
    "dnowBrightness": <integer>, // Current display brightness
    "dayBright": <integer>, // Configured display brightness for day mode
    "nightBright": <integer>, // Configured display brightness for night mode
    "bluetoothHp": <integer>, // Whether Bluetooth headphones are connected
    "volume": <integer>, // Current system volume
    "userVolume": <integer>, // Current user-facing volume percentage
    "timeFormat": "12" | "24", // Clock format
    "nightlightMode": "<string>", // Current nightlight mode. Only included on supported player models
    "day": <integer> // Whether the player currently considers it daytime. -1 means unknown
  }
}

Response Topic

`/device/{id}/response`

Direction: Device → Client

Description: Used by the device to confirm the result of a command. The response dynamically names the field after the command’s resource.

Payload:

{
  "status": {
    "<resource>": "OK" | "FAIL",
    "req_body": "{\"requestId\":\"<string>\"}"
  }
}

Notes:

Applies to all topics under /command/{resource}/{action}
<resource> corresponds to the resource part of the command topic (e.g., status, events, volume)
The result ("OK" or "FAIL") reflects whether the command was successfully handled
req_body is a stringified JSON from the original request, typically including "requestId"