This application shows you how to connect your Wio Terminal from Seeed 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 application 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.
- Supported device attestation methods
- Update the Wi-Fi Firmware
- Configure directly connect to Azure IoT Hub
- Configure use provisioning to connect to Azure IoT Hub
- Running the application
- Testing the application
- A few words on the Azure SDK for Embedded C and how it's been ported to Wio Terminal
The following table summarizes supported device attestation/authentication methods :
| Service | Enrollment | Authentication | Support status |
|---|---|---|---|
| Azure IoT Hub | - | Symmetric Key | Need recompile |
| Azure IoT Hub | - | X.509 Self-Signed | Not Supported |
| Azure IoT Hub | - | X.509 CA-Signed | Not Supported |
| Azure IoT DPS | Group | Symmetric Key | Supported |
| Azure IoT DPS | Group | CA Certificate | Not Supported |
| Azure IoT DPS | Group | Intermediate Certificate | Not Supported |
| Azure IoT DPS | Individual | Symmetric Key | Supported |
| Azure IoT DPS | Individual | X.509 | Not Supported |
| Azure IoT DPS | Individual | TPM | Not Supported |
Please follow instruction at Wio Terminal's network overview page to update the firmware.
You must use the version of Wi-Fi firmware specified in Azure IoT Firmware. See the release page.
If you use provisioning service, skip this section.
- Create an Azure IoT Hub. See here. Do "Create an IoT hub" section only.
- Select IoT devices page in your Azure IoT Hub on Azure portal.
- Select +New.
- Input Device ID and click Save button.
- Open
include/config.hin text editor. - Comment out
#define USE_CLI. - Modify [wifi ssid] to your Wi-Fi SSID.
- Modify [wifi password] to your Wi-Fi password.
- Modify [Azure IoT Hub host name] to hostname of your Azure IoT Hub.
- Modify [device id] to the Device ID of the device.
- Modify [symmetric key] to primary key or secondary key of the device.
If you DON'T use provisioning service, skip this section.
- Create an Azure IoT Hub. See here. Do "Create an IoT hub" section only.
- Create an Azure IoT Hub DPS. See here. Do "Create a new IoT Hub Device Provisioning Service" section only.
- Link Azure IoT Hub and Azure IoT Hub DPS. See here. Do "Link the IoT hub and your Device Provisioning Service" section only.
- Select Manage enrollments page in your Azure IoT Hub DPS on Azure portal.
- Select +Add individual enrollment.
- Change X.509 at Mechanism to Symmetric Key.
- Input Registration ID.
- Input IoT Hub Device ID.
- Click Save button.
- Open
include/config.hin text editor. - Comment out
#define USE_CLI. - Uncomment
#define USE_DPS. - Modify [wifi ssid] to your Wi-Fi SSID.
- Modify [wifi password] to your Wi-Fi password.
- Modify [id scope] to hostname of your Azure IoT Hub DPS.
- Modify [registration id] to the Registration ID of the indivisual enrollment.
- Modify [symmetric key] to primary key or secondary key of the individual enrollment.
Use the PlatformIO IDE (VS Code extension) or the PlatformIO command-line interface to deploy the application to your Wio Terminal.
Once running, the application will connect to IoT Hub and:
- send telemetry—the acceleration values from the 3-axis acceleration 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.
To check that telemetry data is correctly sent, you will want to subscribe to the telemetry feed of your device. Since this code leverages IoT Plug and Play, Azure IoT Explorer will provide you with extra information regarding the data model for your acceleration 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 application 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 application uses the
PubSubClientMQTT library from Nick O'Leary. - And of course, one has to implement their own application logic. For this application, this meant using the Wio Terminal's acceleration sensor 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
👤 Seeed K.K.
- Website: https://www.seeed.co.jp/
- Twitter: @SeeedJP
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Give a ⭐️ if this project helped you!
Copyright © 2020 Benjamin Cabé.
Copyright © 2020 Seeed K.K.
This project is MIT licensed.
This README was generated with ❤️ by readme-md-generator