Device twin
AWS
Receive device twin notifications
Devices can receive notifications to the following topic when applications update the desired properties.
| Type | Description |
|---|---|
| Subscription Topic | $iothub/twin/PATCH/properties/desired/# |
| Response Topic | $iothub/twin/PATCH/properties/desired/?$version={version} |
| Payload | { "key": "value", "key1": "value", "$version": {version}} |
| version | Version of the desired property. |
Get device twin
Devices can get the device twin document including desired and reported properties.
| Operation | Topic | Payload |
|---|---|---|
| Subscription Topic | $iothub/twin/res/# | N/A |
| Request | $iothub/twin/GET/?$rid={request id} | Empty |
| Response | $iothub/twin/res/{status}/?$rid={request id} | { "desired": { "desiredkey1": "desiredvalue1", "desiredkey2": "desiredvalue2", "$version": {desiredPropVersionNumber} }, "reported": { "reportedKey": "reportedValue" "$version": {reportedPropVersionNumber} }} |
Update device twin
Devices can update or delete the reported properties. Properties set to null will be removed.
| Operation | Topic | Payload |
|---|---|---|
| Subscription Topic | $iothub/twin/res/# | N/A |
| Request | $iothub/twin/PATCH/properties/reported/?$rid={request id} | { “Key”:”Value”, “Key1”:”Value1”} |
| Response | $iothub/twin/res/{status}/?$rid={request id}&$version={versionNumber} | Empty |
-
request id : Used to synchronize request and response. RequestId set in the request will be returned in the response.
-
versionNumber: Version Number of the Device Twin
-
status: Status of the Request.
Possible Status Codes are
- 204 Success (no content is returned)
- 400 Bad Request. Malformed JSON
- 429 Too many requests
- 500 Server errors
Device twin limitations
- Maximum size limit on each of the values for reported/desired properties is 32 KB. The size excludes the read-only elements like $version and $metadata/$lastUpdated.
- Keys: All keys in JSON objects are UTF-8 encoded, case-sensitive, and up-to 1 KB in length.
- Values: All values in JSON objects can be of the following JSON types: boolean, number, string, object and arrays
- Integers can have a minimum value of -4503599627370496 and a maximum value of 4503599627370495.
- String values are UTF-8 encoded and can have a maximum length of 4 KB.
- Depth: The maximum depth of JSON objects in desired properties and reported properties is 10.