RPI-Pico-Arduino-AzSDK: About SDK Implementation


A bit or “reverse engineering” aka hacking … Whilst other samples in the Azure SDK for C Arduino implemnted more complex features of the Azure Embedded SDK for C, the ESP2866 sample only implemented basic Telemetry and basic CD Messaging. Therefore the basic port of that sample to the RPi Pico W was similarly limited. Lets expand upon this. The objective of this context it to implement as much of the complete SDK Hub<–>Device interaction as is possible.

Elements of an IoT Hub System

  • Azure IoT Hub, in the cloud
  • Actual device collecting data using sensors
  • Device sends telemetry to hub
  • Hub accepts data
    • Hub sends acknowedgement
    • Device recieves acknowledgement
  • Device may include properties in the telemetry
    • Hub is able to decipher this
  • Hub sends Cloud to Device (CD) messages
    • Device receives them and may or may not take action
    • Default is no acknowledgment from device to hub. May also be
      • Full
      • Only on error
      • Only on success
  • Hub sends Direct Method with or without payload
    • If recognised by device and any required parameters
      • Action the method
      • Postive acknowledgement
    • Else Negative acknowledgement
  • Device requests Twin document of Desired Properties
    • Hub sends Twin Document
    • Device acknowledges it
    • Device sets the desired properties it can
  • Hub sends an update of a Desired property as a Patch
    • Device receives it and acknowledges it
    • Devices sets it if it can.
  • Hub requests the current property/ies on the device
    • Device acknowledges the request by sending it/them.
  • Device Deployment
    • Deployment of the OS, apps and data from the hub to a device. Reboot of the device.
    • Not part of this context

The SDK Software

A device starts by initaiting networking (WiFi) and then MQTT on top of that. As indicated previously with the Telemetry, the device then subscribes to various topics. As per the SDK documentation there are 4 subscriptions possible:

  • messages
    • “devices/+/messages/devicebound/#”
  • methods
    • “$iothub/methods/POST/#”
  • twin patch
    • “$iothub/twin/PATCH/properties/desired/#”
  • twin response
    • “$iothub/twin/res/#”

With the SDK there is one Callback method that is assigned to the MQTT Client on the device. This receives all of the correspondence from the hub and must interpret that based upon the topic supplied. The function prototype for the Callback is:

void receivedCallback(char* topic, byte* payload, unsigned int length)

Note that there is only one Callback for a device.

The decipher of the topic is as follows:

Topic starts with Topic type
“$iothub/methods/” Direct Method
“$iothub/twin/” Twin …
“$iothub/twin/res/” Twin GET document response
“$iothub/twin/PATCH/properties” Twin Property Patch
“devices/PicoDev2023/messages/devicebound” CD Message

The topic has other metainformation appended. The call may or may not have a payload. The length parameter is the string length of the payload. The topic does not come with a length. I found I had to santise it a bit by ignoring anything after the first byte 0 in the the char array.

An example of a full topic is:

 $iothub/twin/res/200/?$rid=get_twin

This means that its a reponsse to a request from the device to the hub for the Device Twin document with that documentation of the Desired Properties as a Json document as the payload. The 200 means the request and delivery were successful.

Another example is:

 $iothub/twin/res/204/?$rid=reported_prop&$version=2

This means that a property on the device was successfully reported to the hub. The 204 also means it was successful but there is no payload. Its just an acknowledgement.

There is some “outlining” of the device logs such that as a received message is drilled into deeper and deeper logs are given and extra tab for each level. This outlining is defined as macros in az_local_msglevels.h and is enabled if _USEOUTLINING_ is defined there. Top level regions of logs to be so outlined begin with and end with

PRINT_BEGIN
{
  logged content
}
PRINT_END

Sub regions are nested and begin and end with (where n is the level)

PRINT_BEGIN_SUB_n
{
  logged content
}
PRINT_END_SUB_n

Instead of Serial.print etc there are SERIALPRINT macros to tab this content.

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