Skip to content

Device Shadow

This document provides a detailed guide for implementing Device Shadow functionality with the Numio platform. For basic MQTT communication setup, please refer to the MQTT documentation.

1. Introduction

Device Shadow is a JSON document that stores and retrieves current state information for a device. It provides a reliable way to keep devices in sync with their desired state, even when they’re offline.

2. Device Shadow Basics

2.1. Message Format

Device Shadow uses JSON messages with two key sections:

  • reported (data currently sent by the device)
  • desired (data expected from the device)

Example JSON Structure:

{
  "state": {
    "reported": {
      "status": "Operational"
    }
  }
}

2.2. MQTT Topics

Publishing State Data to Device Shadow

The device publishes data to:

$aws/things/{thingName}/shadow/update

Example Python code for sending data:

import json
import paho.mqtt.client as mqtt


THING_NAME = "your-assigned-thing-name"
BROKER_URL = "your-assigned-endpoint.amazonaws.com"
PORT = 8883
CERT_PATH = "certificate.pem.crt"
KEY_PATH = "private.pem.key"
CA_PATH = "AmazonRootCA1.pem"


client = mqtt.Client()
client.tls_set(CA_PATH, certfile=CERT_PATH, keyfile=KEY_PATH)
client.connect(BROKER_URL, PORT)


payload = {
  "state": {
    "reported": {
      "status": "Operational"
    }
  }
}


client.publish(f"$aws/things/{THING_NAME}/shadow/update", json.dumps(payload))


client.loop_stop()
client.disconnect()

Subscribing to Device Shadow Updates

The device can subscribe to changes in the desired values:

$aws/things/{thingName}/shadow/update/delta

Upon receiving a message, the device should update its reported section accordingly.

3. Troubleshooting

3.1. Device not receiving delta updates

Symptoms:

  • Device does not respond to changes in the desired section
  • No messages received on topic $aws/things/{thingName}/shadow/update/delta

Possible Causes:

  • Device is not subscribed to the delta topic
  • No changes have been made to the desired section
  • Incorrect thingName used in the topic

Recommended Actions:

  • Confirm subscription to the correct delta topic
  • Use AWS Console or CLI to update the desired state
  • Monitor messages using:
Terminal window
mosquitto_sub -h your-endpoint.amazonaws.com -p 8883 --cafile AmazonRootCA1.pem --cert cert.pem --key private.key -t "$aws/things/{thingName}/shadow/update/delta"

3.2. No response after publishing state

Symptoms:

  • Device publishes to shadow/update but no confirmation or acknowledgment is received

Possible Causes:

  • MQTT client disconnected too early
  • Payload is invalid JSON or does not match expected format
  • Topic name contains typos or wrong thingName

Recommended Actions:

  • Enable loop_start() or wait before disconnecting
  • Validate payload with a JSON linter
  • Use the following topic and verify the full path:
$aws/things/{thingName}/shadow/update

4. Conclusion

This document outlines how to implement Device Shadow functionality with the Numio platform. Device Shadow provides a reliable way to keep devices in sync with their desired state and maintain a persistent record of device state information.