Yoto Developers
MQTT Documentation

MQTT Documentation

The MQTT topics that you can use to interact with your Yoto players.

Set volume

Direction: Client → Device

Topic

/device/{deviceId}/command/volume/set

Set the player’s volume level.

Payload

{
  "type": "object",
  "properties": {
    "volume": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100,
      "description": "Target volume level."
    }
  },
  "required": [
    "volume"
  ]
}

Set ambient LED color

Direction: Client → Device

Topic

/device/{deviceId}/command/ambients/set

Control the player’s RGB ambient LEDs.

Payload

{
  "type": "object",
  "properties": {
    "r": {
      "type": "integer",
      "minimum": 0,
      "maximum": 255
    },
    "g": {
      "type": "integer",
      "minimum": 0,
      "maximum": 255
    },
    "b": {
      "type": "integer",
      "minimum": 0,
      "maximum": 255
    }
  },
  "required": [
    "r",
    "g",
    "b"
  ]
}

Set sleep timer

Direction: Client → Device

Topic

/device/{deviceId}/command/sleep-timer/set

Set the player’s sleep timer.

Payload

{
  "type": "object",
  "properties": {
    "seconds": {
      "type": "integer",
      "minimum": 0,
      "description": "Sleep timer duration in seconds. 0 disables the timer."
    }
  },
  "required": [
    "seconds"
  ]
}

Reboot

Direction: Client → Device

Topic

/device/{deviceId}/command/reboot

Trigger a system reboot.

Start card playback

Direction: Client → Device

Topic

/device/{deviceId}/command/card/start

Start playback of a card, optionally targeting a chapter/track/position.

Payload

{
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "description": "URI of the card to play."
    },
    "chapterKey": {
      "type": "string",
      "description": "Chapter to start playback from."
    },
    "trackKey": {
      "type": "string",
      "description": "Track to start playback from."
    },
    "secondsIn": {
      "type": "integer",
      "description": "Position in seconds to start playback from."
    },
    "cutOff": {
      "type": "integer",
      "description": "Playback cutoff position in seconds."
    },
    "anyButtonStop": {
      "type": "boolean",
      "description": "Whether any button press stops playback."
    }
  },
  "required": [
    "uri"
  ]
}

Stop card playback

Direction: Client → Device

Topic

/device/{deviceId}/command/card/stop

Stop playback of the current card.

Pause card playback

Direction: Client → Device

Topic

/device/{deviceId}/command/card/pause

Pause playback of the current card.

Resume card playback

Direction: Client → Device

Topic

/device/{deviceId}/command/card/resume

Resume playback of the current card.

Enable Bluetooth

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/on

Enable Bluetooth in source or sink mode. Warning: entering sink mode disables MQTT command handling entirely until the user physically holds the left button for approximately 3 seconds to exit.

Payload

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "Bluetooth action to perform, e.g. selecting source or sink mode."
    },
    "mode": {
      "type": "boolean",
      "description": "Bluetooth mode flag."
    },
    "rssi": {
      "type": "integer",
      "description": "Minimum signal strength (RSSI) used when scanning/connecting in source mode."
    },
    "name": {
      "type": "string",
      "description": "Name of the target Bluetooth device, used in source mode."
    },
    "mac": {
      "type": "string",
      "description": "MAC address of the target Bluetooth device, used in source mode."
    }
  }
}

Disable Bluetooth

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/off

Delete Bluetooth bond

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/delete-bond

Delete bonded Bluetooth devices.

Connect Bluetooth

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/connect

Connect to a bonded Bluetooth device.

Disconnect Bluetooth

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/disconnect

Disconnect the active Bluetooth connection.

Get Bluetooth state

Direction: Client → Device

Topic

/device/{deviceId}/command/bluetooth/state

Check the Bluetooth driver status.

Preview display icon

Direction: Client → Device

Topic

/device/{deviceId}/command/display/preview

Preview an icon on the player’s display.

Payload

{
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "description": "URI of the icon to preview."
    },
    "timeout": {
      "type": "integer",
      "description": "Duration in seconds to show the preview before reverting."
    },
    "animated": {
      "type": "integer",
      "description": "Whether the icon is animated."
    }
  },
  "required": [
    "uri",
    "timeout",
    "animated"
  ]
}

Request events report

Direction: Client → Device

Topic

/device/{deviceId}/command/events/request

Trigger the device to publish a current events report.

Events report

Direction: Device → Client

Topic

/device/{deviceId}/data/events

Real-time playback and interaction event data.

Payload

{
  "type": "object",
  "properties": {
    "cardId": {
      "type": "string"
    },
    "chapterTitle": {
      "type": "string"
    },
    "chapterKey": {
      "type": "string"
    },
    "trackTitle": {
      "type": "string"
    },
    "trackKey": {
      "type": "string"
    },
    "position": {
      "type": "integer",
      "description": "Playback position in seconds."
    },
    "trackLength": {
      "type": "integer",
      "description": "Track length in seconds."
    },
    "playbackStatus": {
      "type": "string",
      "enum": [
        "playing",
        "paused",
        "stopped"
      ]
    },
    "volume": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "sleepTimerActive": {
      "type": "boolean"
    },
    "sleepTimerSeconds": {
      "type": "integer"
    },
    "source": {
      "type": "string",
      "enum": [
        "card",
        "remote",
        "button",
        "bt",
        "none"
      ]
    },
    "eventUtc": {
      "type": "integer",
      "description": "Unix timestamp of the event."
    }
  }
}

Request status report

Direction: Client → Device

Topic

/device/{deviceId}/command/status/request

Trigger the device to publish a current status report.

Status report

Direction: Device → Client

Topic

/device/{deviceId}/data/status

Device status, environment, and configuration.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "statusVersion": {
          "type": "integer",
          "description": "Version identifier for the status message format."
        },
        "fwVersion": {
          "type": "string",
          "description": "Player firmware version."
        },
        "productType": {
          "type": "string"
        },
        "batteryLevel": {
          "type": "integer"
        },
        "charging": {
          "type": "boolean"
        },
        "freeDisk": {
          "type": "integer",
          "description": "Free disk space in KB."
        },
        "als": {
          "type": "integer",
          "description": "Ambient light sensor reading."
        },
        "activeCard": {
          "type": "string"
        },
        "cardInserted": {
          "type": "boolean"
        },
        "playingStatus": {
          "type": "string"
        },
        "headphones": {
          "type": "boolean"
        },
        "bluetoothHp": {
          "type": "boolean",
          "description": "Whether Bluetooth headphones are connected."
        },
        "volume": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "userVolume": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "timeFormat": {
          "type": "string",
          "enum": [
            "12",
            "24"
          ]
        },
        "nightlightMode": {
          "type": "string"
        },
        "day": {
          "type": "boolean"
        }
      },
      "required": [
        "statusVersion"
      ]
    }
  }
}

Receive Response

Direction: Device → Client

Topic

/device/{deviceId}/response

Volume command response

Acknowledges a volume/set command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "volume": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "volume",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Ambients command response

Acknowledges an ambients/set command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "ambients": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "ambients",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Sleep timer command response

Acknowledges a sleep-timer/set command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "sleep-timer": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "sleep-timer",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Reboot command response

Acknowledges a reboot command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "reboot": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "reboot",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Card command response

Acknowledges a card/start, card/stop, card/pause, or card/resume command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "card": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "card",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Bluetooth command response

Acknowledges any bluetooth/* command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "bluetooth": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "bluetooth",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Display command response

Acknowledges a display/preview command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "display": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "display",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Events command response

Acknowledges an events/request command.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "events": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "events",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Status command response

Acknowledges a status/request command. Note the inner “status” key is the generic response resource name, which for this command happens to match the outer “status” wrapper used by every response message.

Payload

{
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "OK",
            "FAIL"
          ]
        },
        "req_body": {
          "type": "string",
          "description": "Stringified JSON of the original request payload."
        }
      },
      "required": [
        "status",
        "req_body"
      ]
    }
  },
  "required": [
    "status"
  ]
}