Skip to content

Latest commit

 

History

History
270 lines (182 loc) · 13.6 KB

readme.md

File metadata and controls

270 lines (182 loc) · 13.6 KB
Raw
page_type description languages products
sample
Connecting ESPRESSIF ESP32-Azure IoT Kit to Azure IoT Central using the Azure SDK for C Arduino library
c
azure-iot
azure-iot-pnp
azure-iot-central

Getting started with the ESPRESSIF ESP32-Azure IoT Kit and Azure IoT Central with Azure SDK for C Arduino library

Total completion time: 30 minutes

In this tutorial you use the Azure SDK for C to connect the ESPRESSIF ESP32-Azure IoT Kit (hereafter, the ESP32 DevKit) to Azure IoT Central. The article is part of the series IoT Device Development. The series introduces device developers to the Azure SDK for C, and shows how to connect several device evaluation kits to Azure IoT.

You will complete the following tasks:

  • Install the Azure SDK for C library on Arduino
  • Build the image and flash it onto the ESP32 DevKit
  • Use Azure IoT Central to create cloud components, view properties, view device telemetry, and call direct commands

The following was run on Windows 11, with Arduino IDE 2.1.0 and ESP32 board library version 2.0.9.

Prerequisites

  • 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.

  • Hardware

Create the cloud components

Create the IoT Central Application

There are several ways to connect devices to Azure IoT. In this section, you learn how to connect a device by using Azure IoT Central. IoT Central is an IoT application platform that reduces the cost and complexity of creating and managing IoT solutions.

To create a new application:

  1. From Azure IoT Central portal, select My apps on the side navigation menu.

  2. Select + New application.

  3. Select Custom apps.

  4. Add Application Name and a URL.

  5. Choose the pricing plan of your preference.

    IoT Central create an application

  6. Select Create.

  7. After IoT Central provisions the application, it redirects you automatically to the new application dashboard.

    Note: If you have an existing IoT Central application, you can use it to complete the steps in this article rather than create a new application.

Create a new device

In this section, you use the IoT Central application dashboard to create a new device. You will use the connection information for the newly created device to securely connect your physical device in a later section.

To create a device:

  1. From the application dashboard, select Devices on the side navigation menu.

  2. Select + New to bring up the Create a new device window.

  3. Leave Device template as Unassigned.

  4. Fill in the desired Device name and Device ID.

    IoT Central create a device

  5. Select the Create button.

  6. The newly created device will appear in the All devices list. Select on the device name to show details.

  7. Select Connect in the top right menu bar to display the connection information used to configure the device in the next section.

    IoT Central create a device

    The information provided above will create a device with Symmetric Key authentication. If you prefer, you can also use X.509 certificates. In order to do that:

    • In the Authentication type box, select individual enrollment

    • In the Authentication method box, select Certificates (X.509)

    • Click on the blue folder icon for both primary and secondary and select your device Certificate.

      If needed, 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.

  8. Note the connection values for the following connection string parameters displayed in Connect dialog. You'll use these values during the following configuration step:

  • ID scope
  • Device ID
  • Primary key (only if you choose Symmetric Key authentication)

Setup and Run Instructions

  1. Run the Arduino IDE.

  2. 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.

  3. Install ESPRESSIF ESP32 Sensors library for Arduino

    • On the Arduino IDE, go to menu Sketch, Include Library, Manage Libraries....
    • Search for and install Espressif ESP32 Azure IoT Kit Sensors (by Ewerton Scaboro da Silva).

  4. Open the ESPRESSIF ESP32 DevKit sample.

    • On the Arduino IDE, go to menu File, Examples, Azure SDK for C.
    • Click on Azure_IoT_Central_ESP32_AzureIoTKit to open the sample.

  5. Configure the 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 Device Provisioning Scope ID to DPS_ID_SCOPE
    • 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 private key to IOT_CONFIG_DEVICE_CERT_PRIVATE_KEY
    • If using Symmetric Key:
      • Add your device key to IOT_CONFIG_DEVICE_KEY

  6. Connect the ESP32 Azure IoT Kit microcontroller to your USB port.

  7. On the Arduino IDE, select the board and port.

    • Go to menu Tools, Board and select ESP32 Wrover Module.
    • Go to menu Tools, Port and select the port to which the microcontroller is connected.

  8. Upload the sketch.

    • Go to menu Sketch and click on Upload.

  9. 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:

      ...
1970/1/1 00:00:03 [INFO] WiFi connected, IP address: 192.168.1.228
1970/1/1 00:00:03 [INFO] Setting time using SNTP
...
2022/1/18 23:53:17 [INFO] Time initialized!
2022/1/18 23:53:18 [INFO] Azure IoT client initialized (state=1)
2022/1/18 23:53:18 [INFO] MQTT client target uri set to 'mqtts://global.azure-devices-provisioning.net'
2022/1/18 23:53:18 [INFO] MQTT client connecting.
2022/1/18 23:53:19 [INFO] MQTT client connected (session_present=0).
2022/1/18 23:53:19 [INFO] MQTT client subscribing to '$dps/registrations/res/#'
2022/1/18 23:53:19 [INFO] MQTT topic subscribed (message id=48879).
2022/1/18 23:53:19 [INFO] MQTT client publishing to '$dps/registrations/PUT/iotdps-register/?$rid=1{"modelId":"dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1"}{"registrationId":"myDeviceId","payload":{"modelId":"dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1"}}'
2022/1/18 23:53:19 [INFO] MQTT message received.
2022/1/18 23:53:19 [INFO] MQTT client publishing to '$dps/registrations/GET/iotdps-get-operationstatus/?$rid=1&operationId=4.8a7f95e72373290a.f936a9b2-12ff-4b7d-8189-4c250236c141'
2022/1/18 23:53:19 [INFO] MQTT message received.
2022/1/18 23:53:22 [INFO] MQTT client publishing to '$dps/registrations/GET/iotdps-get-operationstatus/?$rid=1&operationId=4.8a7f95e72373290a.f936a9b2-12ff-4b7d-8189-4c250236c141'
2022/1/18 23:53:22 [INFO] MQTT message received.
2022/1/18 23:53:22 [INFO] MQTT client being disconnected.
2022/1/18 23:53:22 [INFO] MQTT client target uri set to 'mqtts://myProvisionedIoTHubFqdn.azure-devices.net'
2022/1/18 23:53:22 [INFO] MQTT client connecting.
2022/1/18 23:53:23 [INFO] MQTT client connected (session_present=0).
2022/1/18 23:53:23 [INFO] MQTT client subscribing to '$iothub/methods/POST/#'
2022/1/18 23:53:23 [INFO] MQTT topic subscribed (message id=556).
2022/1/18 23:53:23 [INFO] MQTT client subscribing to '$iothub/twin/res/#'
2022/1/18 23:53:23 [INFO] MQTT topic subscribed (message id=10757).
2022/1/18 23:53:23 [INFO] MQTT client subscribing to '$iothub/twin/PATCH/properties/desired/#'
2022/1/18 23:53:23 [INFO] MQTT topic subscribed (message id=15912).
2022/1/18 23:53:23 [INFO] MQTT client publishing to '$iothub/twin/PATCH/properties/reported/?$rid=0'
2022/1/18 23:53:23 [INFO] MQTT client publishing to 'devices/myDeviceId/messages/events/'
2022/1/18 23:53:23 [INFO] MQTT message received.
2022/1/18 23:53:23 [INFO] Properties update request completed (id=0, status=204)
2022/1/18 23:53:33 [INFO] MQTT client publishing to 'devices/myDeviceId/messages/events/'

Verify the device status

To view the device status in IoT Central portal:

  1. From the application dashboard, select Devices on the side navigation menu.

  2. Check the Device status of the device is updated to Provisioned.

  3. Check the Device template of the device has updated to Espressif ESP32 Azure IoT Kit.

    IoT Central device status

View telemetry

With IoT Central, you can view the flow of telemetry from your device to the cloud.

To view telemetry in IoT Central portal:

  1. From the application dashboard, select Devices on the side navigation menu.

  2. Select the device from the device list.

  3. View the telemetry as the device sends messages to the cloud in the Overview tab.

    IoT Central device telemetry

Send a command on the device

You can also use IoT Central to send a command to your device. In this section, you can call a command to toggle LEDs or write to the screen.

To write to the screen:

  1. Select the Command tab from the device page.
  2. Locate the Display Text command.
  3. In the Content textbox, enter the text to be displayed on the screen.
  4. Select Run.
  5. The screen on the device will update with the desired text.

To toggle an LED:

  1. Select the Command tab from the device page.
  2. Locate the Toggle LED 1 or Toggle LED 2 command
  3. Select Run.
  4. An LED light on the device will toggle state.

IoT Central invoke method

View device information

You can view the device information from IoT Central.

Select About tab from the device page. IoT Central device info

Clean up resources

If you no longer need the Azure resources created in this tutorial, you can delete them from the IoT Central portal. Optionally, if you continue to another tutorial in this Getting Started guide, you can keep the resources you've already created and reuse them.

To keep the Azure IoT Central sample application but remove only specific devices:

  1. Select the Devices tab for your application.
  2. Select the device from the device list.
  3. Select Delete.

To remove the entire Azure IoT Central sample application and all its devices and resources:

  1. Select Administration > Your application.
  2. Select Delete.

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 and c 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.