Device shadow

Device shadow is a JSON object that is associated with a device. It lives on a cloud and keeps device state and custom metadata. Device shadow is always available via MQTT and REST API, regardless whether an associated device is online or offline. Device shadow JSON object has the following structure:

  • state.desired - this is the state you want your device to have
  • state.reported - this is the state your device actually has
  • - automatically generated difference between desired and reported
  • tags - arbitrary metadata invisible to the device but visible to the cloud user
  "state": {
    "desired": {
       "switched_on": true   // State you want your device to have
                             // Should be changed by the cloud user
    "reported": {
       "switched_on": false, // State your device actually has
       "ram": 12473          // Should be changed by a device
    "delta": {
      "switched_on": false  // Difference between desired and reported
                            // ONLY FOR KEYS THAT ARE PRESENT IN DESIRED 
                            //  Automatically generated on each change
  "tags": {
    "answer": 42  // Arbitrary cloud metadata

The structure of the state.desired, state.reported and tags sub-objects is arbitrary - create whatever structure you wish.

Shadow-specific MQTT topics

  • DEVICE_ID/shadow/update - publish to this topic to update the shadow. Example message:
     {"state": {"reported": {"temperature": 22.3}}}`
  • DEVICE_ID/shadow/delta - subscribe to this topic to receive deltas. Example message:
     {"state":{"switched_on": true}, "version": 257, "timestamp": 123}`
  • DEVICE_ID/shadow - subscribe to this topic to get shadow values on DEVICE_ID/shadow/get requests. Example message:
     {"state":{"reported":{"foo":"bar"}}, "tags":{}, "version": 1, "timestamp": 123}`
  • DEVICE_ID/shadow/get - publish an empty message to this topic to trigger shadow report

Idiomatic device shadow usage

  • When a device is connected to the mDash,
    • Subscribe to the shadow delta topic DEVICE_ID/shadow/delta
    • Report current state by sending a message {"state": {"reported":{...}}} to a DEVICE_ID/shadow/update topic
  • When a message is received on a delta topic, handle it and then report current state like on a previous step

Automatic device shadow values

mDash creates and maintains several shadow values automatically:

  • - a boolean value, showing device online state
  • state.reported.ota - an object that contains device information, specifically, a result of the Sys.GetInfo RPC call


  "state": {
    "reported": {
      "online": true,                   // created automatically
      "ota": {                          // created automatically
        "app": "my-product",            // created automatically
        "arch": "esp32",                // created automatically
        "fw_id": "20190613-141510",     // created automatically
        "fw_version": "1.0.28-idf",     // created automatically
        "ram_free": 45172,              // created automatically
        "reboot_reason": "power-on"     // created automatically
  "tags": {
    "labels": "prod devkit"
  "version": 3331,
  "timestamp": 1560498134

How to delete shadow keys

In order to create new keys, simply send a shadow update with a new key and its value. In order to delete a key, send a shadow update where a key is set to null:

{"state": {"reported": {"my_key": null}}}