28acdc59b6 | ||
---|---|---|
.. | ||
AzIoTSasToken.cpp | ||
AzIoTSasToken.h | ||
Azure_IoT_Hub_ESP32.ino | ||
SerialLogger.cpp | ||
SerialLogger.h | ||
iot_configs.h | ||
readme.md |
readme.md
page_type | description | languages | products | |||||
---|---|---|---|---|---|---|---|---|
sample | Connecting an ESP32 device to Azure IoT using the Azure SDK for Embedded C |
|
|
Before you proceed
This sample is based on the Azure IoT SDK for C, uses a bare metal (no RTOS) approach and has support for Arduino IDE.
There is a different sample for the ESP32 with the Azure IoT middleware for FreeRTOS (requires FreeRTOS to work).
If this is what you’re looking for please visit this GitHub repo.
How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Espressif ESP32
- How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Espressif ESP32
- Introduction
- What is Covered
- Prerequisites
- Setup and Run Instructions
- Troubleshooting
- Contributing
- License
Introduction
This is a "to-the-point" guide outlining how to run an Azure SDK for Embedded C IoT Hub telemetry sample on an ESP32 microcontroller. The command line examples are tailored to Debian/Ubuntu environments.
What is Covered
- Configuration instructions for the Arduino IDE to compile a sample using the Azure SDK for Embedded C.
- Configuration, build, and run instructions for the IoT Hub telemetry sample.
The following was run on Windows 11, with Arduino IDE 2.1.0 and ESP32 board library version 2.0.9.
Prerequisites
-
Have an Azure account created.
-
Have an Azure IoT Hub created.
-
Have a logical device created in your Azure IoT Hub: using authentication type "Symmetric Key" or "X.509 self-signed".
- Symmetric Key: follow this guidance to create a device.In this case, the device keys are used to automatically generate a SAS token for authentication.
- X.509 self-signed cert: Instructions on how to create an X.509 cert for tests can be found here (Step 1). Please note that you might need to install some of the prerequisites like OpenSSL.
-
Have the latest Arduino IDE installed.
-
Have the ESP32 board support installed on Arduino IDE.
- ESP32 boards are not natively supported by Arduino IDE, so you need to add them manually.
- Follow the instructions in the official ESP32 repository.
- If your ESP32 board is not recognized and a COM port is not mapped by your computer, try installing the serial port drivers recommended by ESPRESSIF.
-
Have one of the following interfaces to your Azure IoT Hub set up:
-
Azure Command Line Interface (Azure CLI) utility installed, along with the Azure IoT CLI extension.
On Windows:
Download and install: https://aka.ms/installazurecliwindows
PS C:\>az extension add --name azure-iot
On Linux:
$ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash $ az extension add --name azure-iot
A list of all the Azure IoT CLI extension commands can be found here.
-
The most recent version of Azure IoT Explorer installed. More instruction on its usage can be found here.
NOTE: This guide demonstrates use of the Azure CLI and does NOT demonstrate use of Azure IoT Explorer.
-
Setup and Run Instructions
-
Run the Arduino IDE.
-
Install the Azure SDK for Embedded C library.
- On the Arduino IDE, go to menu
Sketch
,Include Library
,Manage Libraries...
. - Search for and install
azure-sdk-for-c
.
- On the Arduino IDE, go to menu
-
Open the ESPRESSIF ESP32 sample.
- On the Arduino IDE, go to menu
File
,Examples
,azure-sdk-for-c
. - Click on
az_esp32
to open the sample.
- On the Arduino IDE, go to menu
-
Configure the ESPRESSIF ESP32 sample.
Enter your Azure IoT Hub and device information into the sample's
iot_configs.h
:- Add your Wi-Fi SSID to
IOT_CONFIG_WIFI_SSID
- Add your Wi-Fi password to
IOT_CONFIG_WIFI_PASSWORD
- Add you IoTHub Name to
IOT_CONFIG_IOTHUB_FQDN
- Add your Device ID to
IOT_CONFIG_DEVICE_ID
- If using X.509 Cert:
- Uncomment the
#define IOT_CONFIG_USE_X509_CERT
- Add your cert to
IOT_CONFIG_USE_X509_CERT
- Add your cert PK to
IOT_CONFIG_DEVICE_CERT_PRIVATE_KEY
- Uncomment the
- If using Symmetric Key:
- Add your device key to
IOT_CONFIG_DEVICE_KEY
- Add your device key to
- Add your Wi-Fi SSID to
-
Connect the ESP32 microcontroller to your USB port.
-
On the Arduino IDE, select the board and port.
- Go to menu
Tools
,Board
and selectESP32
. - Go to menu
Tools
,Port
and select the port to which the microcontroller is connected.
- Go to menu
-
Upload the sketch.
-
Go to menu
Sketch
and click onUpload
.Expected output of the upload:
Executable segment sizes: IROM : 361788 - code in flash (default or ICACHE_FLASH_ATTR) IRAM : 26972 / 32768 - code in IRAM (ICACHE_RAM_ATTR, ISRs...) DATA : 1360 ) - initialized variables (global, static) in RAM/HEAP RODATA : 2152 ) / 81920 - constants (global, static) in RAM/HEAP BSS : 26528 ) - zeroed variables (global, static) in RAM/HEAP Sketch uses 392272 bytes (37%) of program storage space. Maximum is 1044464 bytes. Global variables use 30040 bytes (36%) of dynamic memory, leaving 51880 bytes for local variables. Maximum is 81920 bytes. /home/user/.arduino15/packages/esp8266/tools/python3/3.7.2-post1/python3 /home/user/.arduino15/packages/esp8266/hardware/esp8266/2.7.1/tools/upload.py --chip esp8266 --port /dev/ttyUSB0 --baud 230400 --before default_reset --after hard_reset write_flash 0x0 /tmp/arduino_build_826987/azure_iot_hub_telemetry.ino.bin esptool.py v2.8 Serial port /dev/ttyUSB0 Connecting.... Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: dc:4f:22:5e:a7:09 Uploading stub... Running stub... Stub running... Changing baud rate to 230400 Changed. Configuring flash size... Auto-detected Flash size: 4MB Compressed 396432 bytes to 292339... Writing at 0x00000000... (5 %) Writing at 0x00004000... (11 %) Writing at 0x00008000... (16 %) Writing at 0x0000c000... (22 %) Writing at 0x00010000... (27 %) Writing at 0x00014000... (33 %) Writing at 0x00018000... (38 %) Writing at 0x0001c000... (44 %) Writing at 0x00020000... (50 %) Writing at 0x00024000... (55 %) Writing at 0x00028000... (61 %) Writing at 0x0002c000... (66 %) Writing at 0x00030000... (72 %) Writing at 0x00034000... (77 %) Writing at 0x00038000... (83 %) Writing at 0x0003c000... (88 %) Writing at 0x00040000... (94 %) Writing at 0x00044000... (100 %) Wrote 396432 bytes (292339 compressed) at 0x00000000 in 13.0 seconds (effective 243.4 kbit/s)... Hash of data verified. Leaving... Hard resetting via RTS pin...
-
-
Monitor the MCU (microcontroller) locally via the Serial Port.
-
Go to menu
Tools
,Serial Monitor
.If you perform this step right away after uploading the sketch, the serial monitor will show an output similar to the following upon success:
Connecting to WIFI SSID buckaroo .......................WiFi connected, IP address: 192.168.1.123 Setting time using SNTP..............................done! Current time: Thu May 28 02:55:05 2020 Client ID: mydeviceid Username: myiothub.azure-devices.net/mydeviceid/?api-version=2018-06-30&DeviceClientType=c%2F1.0.0 SharedAccessSignature sr=myiothub.azure-devices.net%2Fdevices%2Fmydeviceid&sig=placeholder-password&se=1590620105 MQTT connecting ... connected.
-
-
Monitor the telemetry messages sent to the Azure IoT Hub using the connection string for the policy name
iothubowner
found under "Shared access policies" on your IoT Hub in the Azure portal.$ az iot hub monitor-events --login <your Azure IoT Hub owner connection string in quotes> --device-id <your device id>
Expected telemetry output:
Starting event monitor, filtering on device: mydeviceid, use ctrl-c to stop... { "event": { "origin": "mydeviceid", "payload": "payload" } } { "event": { "origin": "mydeviceid", "payload": "payload" } } { "event": { "origin": "mydeviceid", "payload": "payload" } } { "event": { "origin": "mydeviceid", "payload": "payload" } } { "event": { "origin": "mydeviceid", "payload": "payload" } } { "event": { "origin": "mydeviceid", "payload": "payload" } } ^CStopping event monitor...
Certificates - Important to know
The Azure IoT service certificates presented during TLS negotiation shall be always validated, on the device, using the appropriate trusted root CA certificate(s).
The Azure SDK for C Arduino library automatically installs the root certificate used in the United States regions, and adds it to the Arduino sketch project when the library is included.
For other regions (and private cloud environments), please use the appropriate root CA certificate.
Additional Information
For important information and additional guidance about certificates, please refer to this blog post from the security team.
Troubleshooting
- The error policy for the Embedded C SDK client library is documented here.
- File an issue via Github Issues.
- Check previous questions or ask new ones on StackOverflow using the
azure
andc
tags.
Contributing
This project welcomes contributions and suggestions. Find more contributing details here.
License
Azure SDK for Embedded C is licensed under the MIT license.