RPI-Pico-Arduino-AzSDK: Device Twin Prop PATCH


Azure SDK for C Arduino ESP2866 sample comes with Telemetry and Cloud to Device Messaging. It does not include Device Twins so lets implement Patch updates.

Scenario

  • Device starts
  • Device requests Twin document of Desired Properties
    • Hub sends Twin Document
    • Device acknowledges it
    • Device sets the desired properties it can
    • Device reports properties
  • Hub changes one or more deired properties through an app or utility
    • Hub publishes that to the device
    • Device receives and acknowledges
    • Device updates properties
    • Device reports updated properties

Device Setup

  • As per previous post

Log of Device being updated by Hub through a PATCH

Starting with the IsRunning as false; the Telemetry is not running, whilst in Azure IoT Explorer change the IsRunning property to true. The following is logged automatically on the device with explicit action there:

================================================================================
Got IoT Hub Doc-Message-Method-Response
================================================================================
Got Topic: $iothub/twin/PATCH/properties/desired
  Got Payload
{"IsRunning":true,"TelemetryFrequencyMilliseconds":10000,"LEDIsOn":false,"$version":6}
{
  "IsRunning": true,
  "TelemetryFrequencyMilliseconds": 10000,
  "LEDIsOn": false,
  "$version": 6
}\\\\\\\\\\\\\\\\\\\\\\\
Patched Twin Properties to device.
\\\\\\\\\\\\\\\\\\\\\\\

================================================================================
Reporting Device Properties to Hub:
================================================================================
 - Reported
================================================================================
 - END Callback
================================================================================

47210 RPI Pico (Arduino) Sending telemetry . . . devices/PicoDev7/messages/events/StatC
{"LightIntensity":7,"msgCount":0}
OK

The device log for a Twin PATCH

Note that Telemetry is now started.

THe complete topic for the document reception is:

 Topic: $iothub/twin/PATCH/properties/desired/?$version=6

So the property Patch has been made. IsRunningis now true.

The payload for above is

{"IsRunning":true,"TelemetryFrequencyMilliseconds":10000,"LEDIsOn":false,"$version":6}

So rather than the complete Twin document only the desired properties as a Json document are sent. All of then in this case.

Only the changed properties are then reported individually back to the hub from the device. This is programmatic choice. a refresh in Az Explorer shows that the IsRunning property was updated:

{
	...
    ...
	},
	"modelId": "",
	"version": 34,
	"properties": {
		"desired": {
			"IsRunning": true,
			"TelemetryFrequencyMilliseconds": 10000,
			"LEDIsOn": false,
			"$metadata": {
            ...
				}
			},
			"$version": 6
		},
		"reported": {
			"IsRunning": true,
			"TelemetryFrequencyMilliseconds": 10000,
			"LEDIsOn": false,
			"$metadata": {
             ...
			},
			"$version": 28
		}
	},
    ...}
}

Report back log (same for each property)

The complete topic for these acknowledgements from the hub to the device are of the format:

Topic: $iothub/twin/res/204/?$rid=reported_prop&$version=3

So is ack for reported properties, was OK with no payload (204) and is version 3 of properties. :)

Azure IoT Explorer View

You can view the Device Twin document in Az IoT Explorer.

{
	"deviceId": "PicoDev7",
	"etag": "AAAAAAAAAAU=",
	"deviceEtag": "MzgxNjU2MDcx",
	"status": "enabled",
	"statusUpdateTime": "0001-01-01T00:00:00Z",
	"connectionState": "Connected",
	"lastActivityTime": "0001-01-01T00:00:00Z",
	"cloudToDeviceMessageCount": 0,
	"authenticationType": "sas",
	"x509Thumbprint": {
		"primaryThumbprint": null,
		"secondaryThumbprint": null
	},
	"modelId": "",
	"version": 24,
	"properties": {
		"desired": {
			"IsRunning": false,
			"TelemetryFrequencyMilliseconds": 10000,
			"LEDIsOn": false,
			"$metadata": {
				...
				}
			},
			"$version": 5
		},
		"reported": {
			"IsRunning": true,
			"TelemetryFrequencyMilliseconds": 5000,
			"LEDIsOn": true,
			"$metadata": {
          ,,,
				}
			},
			"$version": 13
		}
	},
	"capabilities": {
		"iotEdge": false
	}
}

Azure IoT Explorer view of the Device Twin Document
The metadata has been removed.

Note that when a property is changed that controls an aspect of hardware, any relevant hardware is called. For example if LEDIsOn is changed then the state of the LED is changed.

VS Code (Azure IoT Hub extension)

You can also right-click on a Device in VS Code and **Edit Device Twin” document. It then gets the document from the Hub. You can chnge a property and then right-click on the document there to send the Patch to the device. The device log is as for the Az explorer.

Console App.

There is a Console app, TwiningDesiredProperties for programmtically setting device properties.

The app Patches the frequency (actuallly period) with a similar log to as above. It requires a refresh in Az IoT Explorer, but the property change was made by the app to the twin and implemented on the device.

The app demonstrates how to set tags and desired properties:

    var twin = await registryManager.GetTwinAsync(s_DeviceName);
    await registryManager.UpdateTwinAsync(twin.DeviceId, patchOff, twin.ETag);

patchOff is Json string for a tag to add to the Twin and for Desired Properties to set:

    @"{
        tags: {
            location: {
                region: 'AU',
                plant: 'Melb'
            }
        },
        properties: {
                desired: {
                IsRunning : false,
                TelemetryFrequencyMilliseconds: 6000
            }
        }
    }";

The app also demonstrates how to select devices through a query.

    var query = registryManager.CreateQuery(
        "SELECT * FROM devices WHERE tags.location.plant = 'Melb'", 100);
    var twinsMelb = await query.GetNextAsTwinAsync();

App output is:

Telemetry Off
Devices in Melb: PicoDev7
Devices in Melb and not running Telemetry: PicoDev7
Devices in Melb and  running Telemetry:
Telemetry On
Devices in Melb: PicoDev7
Devices in Melb and not running Telemetry:
Devices in Melb and  running Telemetry: PicoDev7

When queries are made, they are done with the Twin, not the device. There is no log on the device with respect to the query. Also tag metainformation remains with the Twin; Is not sent to the device.

 TopicSubtopic
   
 This Category Links 
Category:Pico W AzSDK Index:Pico W AzSDK
  Next: > RPI-Pico-Arduino-AzSDK
<  Prev:   RPI-Pico-Arduino-AzSDK