This sample application shows you how to connect your Wio Terminal from Seeed Studio to Azure IoT Hub. It is built on top of the Azure SDK for Embedded C, a small footprint, easy-to-port library for communicating with Azure services.
As the Wio Terminal is one of PlatformIO's (many!) supported platforms, the sample is conveniently made available as a PlatformIO project. This means that you don't have to worry about installing the multiple Arduino libraries the Wio Terminal requires for Wi-Fi & TLS, and you don't need to manually install any other third-party library either! All dependencies are automatically fetched from Github by the PlatformIO Library Manager.
- Running the sample
- Testing the sample
- A few words on the Azure SDK for Embedded C and how it's been ported to Wio Terminal
In order to run the sample, update the macro declarations in config.h with your Wi-Fi SSID and password, as well as IoT Hub credentials (IoT hostname, device ID, and device key).
// Wifi
#define IOT_CONFIG_WIFI_SSID "SSID"
#define IOT_CONFIG_WIFI_PASSWORD "PWD"
// Azure IoT
#define IOT_CONFIG_IOTHUB_FQDN "[your Azure IoT host name].azure-devices.net"
#define IOT_CONFIG_DEVICE_ID "Device ID"
#define IOT_CONFIG_DEVICE_KEY "Device Key"Use the PlatformIO IDE (VS Code extension) or the PlatformIO command-line interface to deploy the application to your Wio Terminal.
Once running, the sample will connect to IoT Hub and:
- send telemetry—the acceleration values from the IMU sensor—every 2 second.
- listen to a
ringBuzzercommand that, when triggered from the Cloud will... ring the buzzer! The duration is provided as a command parameter.
You can use the Azure IoT Explorer to test that your Wio Terminal is properly connected to Azure IoT Hub, i.e that it is regularly sending telemetry data, and responding to commands.
Since the IoT Plug and Play model ID used in this sample does not correspond to any official/certified model, you will have to manually instruct Azure IoT Explorer about a local folder where the actual model corresponding to model ID dtmi:seeed:wioterminal;1 resides.
You can either manually download wioterminal.json or clone this repository, and then add the corresponding local folder in the "IoT Plug and Play Settings" of your Azure IoT Explorer. You'll find more information on configuring Azure IoT Explorer here.
Note, as at September 2020, IoT Plug and Play is currently available on IoT hubs created in the Central US, North Europe, and East Japan regions. IoT Plug and Play support is not included in basic-tier IoT hubs.
To check that telemetry data is correctly sent, you will want to subscribe to the telemetry feed of your device. Since this code sample leverages IoT Plug and Play, Azure IoT Explorer will provide you with extra information regarding the data model for your IMU sensor data (e.g the unit of measurement being "g") if you enable the "Show modeled events" option.
In order to send the ringBuzzer command, head over to the "Commands" section of the IoT Plug and Play default component of your device, enter a duration, and send the command.
Note: As of today, the Azure SDK for Embedded C is still being actively developed, therefore, it hasn't been officially released as an Arduino or PlatformIO library. To make it easier for you to get started, the Azure IoT client libraries have been included in the lib/azure-sdk-for-c folder. You can synchronize them with the latest version from the Embedded C SDK github repository by running the lib/download_aziot_embedded_c_lib.sh script.
You can read more on the Azure IoT client library here, but in a nutshell, here's what had to be done to get the Wio Terminal connected:
- As this sample uses symmetric keys to authenticate, a security token needs to be generated.
- Since the generated token has an expiration date (typically set to a few hours in the future), we need to know the current date and time. We use an NTP library to get the current time from a time server.
- The token includes an HMAC-SHA256 signature string that needs to be base64-encoded. Luckily, the recommended WiFi+TLS stack of the Wio Terminal already includes Mbed TLS, making it relatively simple to compute HMAC signatures (ex.
mbedtls_md_hmac_starts) and perform base64 encoding (ex.mbedtls_base64_encode).
- The Azure IoT client libraries help with crafting MQTT topics that follow the Azure IoT conventions, but you still need to provide your own MQTT library. In fact, that is a major difference with the historical Azure IoT C SDK, for which the MQTT implementation was baked into it. Since it is widely supported and just worked out-of-the-box, this sample uses the
PubSubClientMQTT library from Nick O'Leary. - And of course, one has to implement their own application logic. For this sample application, this meant using the Wio Terminal's IMU driver to get acceleration data every 2 seconds, or hooking up the
ringBuzzercommand to actual embedded code that rings the buzzer.
👤 Benjamin Cabé
- Website: https://blog.benjamin-cabe.com
- Twitter: @kartben
- Github: @kartben
- LinkedIn: @benjamincabe
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Give a ⭐️ if this project helped you!
Copyright © 2020 Benjamin Cabé.
This project is MIT licensed.
This README was generated with ❤️ by readme-md-generator