Embedded C SDK Tutorial: How To Commission Your Device and Process Command Requests

Yonomi-cSDK-Tutorial-2019.jpg

The ThinCloud Embedded C SDK is a header-only library that includes a set of utilities to help embedded devices connect and communicate with ThinCloud. This is especially useful for devices that require a low footprint in disk, memory, and power.

The SDK is based on the AWS IoT Embedded C SDK and depends on json-c to marshal and unmarshal JSON payloads.

This tutorial will show you how to connect to ThinCloud, commission your device, and process command requests using this SDK. The full example and details is available on the SDK’s page. Please note: for this tutorial, we have assumed that you have defined a device type with us and that you have certificates to connect to ThinCloud. Before you continue, please make sure you have created an instance with the Yonomi team. You can contact us here to get started.

Connect your device to the cloud

First configure a MQTT client instance to connect to a ThinCloud MQTT endpoint using your root CA and client public and private key.

Yonomi-CSDK-Tutorial-1.png

With a valid MQTT client initialized and connected, you can start sending and receive messages from ThinCloud.

Commission Your Device

We now make a commissioning request. Commissioning registers your device to ThinCloud and assigns a device ID unique to this device. Note that all MQTT requests to ThinCloud follow the JSON-RPC spec.

Note that a device needs to commissioning once during its lifetime or until it resets. Your device will need to keep track of its commissioning status. The device could persist its device ID and check if the device has it on start. In this example we will keep a status flag and the device ID in memory.

Now we define some important values:

  • A unique RPC request ID.

  • A device type.

  • A physical ID.

The physical ID should be unique between devices such as a MAC address.

Syonomi-csdk-tutorial-2.png

Using these values, we subscribe to a commissioning response topic. We will be defining the commissioning callback handler later.

yonomi-csdk-tutorial-3.png

Next we define an event loop that can process incoming client events and most importantly call aws_iot_mqtt_yield periodically. The yield function waits on the MQTT client to process subscribe messages and dispatch them to their handlers. More information about the yield function is here.

Within the loop we check if we have sent a commissioning request before and if not we send it now.

yonomi-csdk-tutorial-4.png

Handle Commissioning Response

Now we define the commissioning callback handler. The client executes this handler when it receives a message on the commissioning response topic we had subscribe to.

Here we unmarshal the commissioning response to extract a device ID. ThinCloud requires this device ID to identify a particular device in consecutive requests. As mentioned before, we want to persist this device ID. In this example, we persist it in memory.

yonomi-csdk-tutorial-6.png

Next we subscribe to device’s command request topic using the newly acquired device ID. ThinCloud will make command requests initiated by clients to this topic.

yonomi-csdk-tutorial-7.png

Handle Command Requests

We now define the command callback handler.

We identify command requests by a method and a command ID which is the same as the RPC request ID. Here we check that we support a method, do some work and then send a response back with the same command ID. ThinCloud requires command ID in the response otherwise the command is not acknowledged in the cloud.

In this example, we support a method called ping and send a pong response.

yonomi-csdk-tutorial-7.png

Conclusion

This article covered the basics of the ThinCloud Embedded C SDK. It should give you enough information to be able to connect to ThinCloud, commission your device, and start sending and receiving messages. To further explore other capabilities of ThinCloud, see the MQTT API documentation.

 
 
IMG_4051.jpg

About the Author

Jorge Martinez Hernandez is a Backend Engineer at Yonomi. A wizard with embedded IoT solutions, he works on core functionality, feature development, and device management on the Yonomi ThinCloud team. Jorge likes working with well designed, tested and expressive code. Outside of work, he enjoys learning new languages - he is currently learning french - and spending time with his family in Manor, TX.