Skip to content

Latest commit

 

History

History
371 lines (261 loc) · 16.8 KB

readme.md

File metadata and controls

371 lines (261 loc) · 16.8 KB
page_type description languages products
sample
Connecting Arduino Portenta H7 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 Arduino Portenta H7 and Azure IoT Central with Azure SDK for C Arduino library

Total completion time: 30 minutes

Introduction

In this tutorial you will use the Azure SDK for C to connect the Arduino Portenta H7 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.

What is Covered

You will complete the following tasks:

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

The following was run on Windows 10 and WSL1 Ubuntu Desktop 20.04 environments, with Arduino IDE 1.8.19 and Arduino Arduino Nano RP2040 Connect with headers.

Prerequisites

IoT Central and Device Setup

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. Go to Azure IoT Central portal.

  2. On the left side menu, select 'My apps'.

  3. Select '+ New application'.

  4. In the 'Custom app' box, select 'Create app'.

  5. Create a custom Application name and a URL.

  6. Under 'Pricing plan', select 'Free' to activate a 7-day trial.

    IoT Central create an application

  7. Select 'Create'.

  8. 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 will use the IoT Central application dashboard to create a new logical device.

To create a device:

  1. On the left side menu, under 'Connect', select 'Devices'.

  2. Select '+ New'. A 'Create a new device' window will appear.

  3. Fill in the desired 'Device name' and 'Device ID'.

  4. Leave Device template as 'Unassigned'.

    IoT Central create a device

  5. Select 'Create'. The newly created device will appear in the 'All devices' list.

  6. Under 'Device name', select your newly created device name.

  7. In the top menu bar, select 'Connect'. A 'Device connection groups' window will appear.

    IoT Central create a device

  8. We will need the following information from this window:

    • ID scope
    • Device ID
    • Primary key

Arduino IDE Setup

  1. Open the Arduino IDE.

  2. Install the Azure SDK for Embedded C library.

    • Navigate to Tools > Manage Libraries.
    • Search for the 'azure-sdk-for-c' library.
    • Install the latest version.

  3. Install Arduino Mbed OS Portenta Boards support in the Arduino IDE. Full instructions can be found here.

    • Navigate to Tools > Board > Boards Manager.

    • Search for 'Portenta' and install the Arduino Mbed OS Portenta Boards core.

    • Install the latest version.

      Note: This process may take several minutes.

  4. Nagivate to Tools > Board > Arduino Mbed OS Portenta Boards and select 'Arduino Portenta H7 (M7 core)'.

  5. In Tools > Flash split, set the flash split to be '2MB M7 + M4 in SDRAM'.

  6. If this is your first time using the Portenta, follow these instructions to update the WiFi firmware on the Portenta.

  7. Install additional libraries for the Portenta Embedded C SDK sample.

    • This process is more involved than typical because we are using the NTP Client Generic library which has circular dependencies so we must do a special install to only grab the what we need.

    • There are two ways to do this:

      1. Download the NTP Client Generic library manually from its repository, or
      2. Use the Arduino CLI.

    • This tutorial will use the CLI approach because it is faster and easier to describe.

    • Using the Arduino CLI, type and run the following command to install the NTP Client :

      arduino-cli lib install --no-deps NTPClient_Generic

    • Since we're already in the Arduino CLI, let's install remaining libraries (can also install these from Library Manager):

      arduino-cli lib install "Azure SDK for C" ArduinoBearSSL Time ArduinoMqttClient ArduinoECCX08

  8. You may need to restart the Arduino IDE for changes to show up.

Run the Sample

  1. Open the Arduino Portenta H7 sample.

    • In the Arduino IDE, navigate to File > Examples > Azure SDK For C
    • Select Azure_IoT_Central_Arduino_Portenta_H7 to open the sample.

  2. Navigate to the 'iot_configs.h' file

  3. In the 'iot_configs.h' file, fill in your credentials.

    • Add in your WiFi SSID and password.
    • Paste your ID Scope for the IOT_CONFIG_DPS_ID_SCOPE variable.
    • Paste your Device ID for the IOT_CONFIG_DEVICE_ID variable.
    • Finally, paste your Primary Key for the IOT_CONFIG_DEVICE_KEY variable.

  4. Connect the Arduino Portenta H7 to your USB port.

  5. On the Arduino IDE, select the port.

    • Navigate to Tools > Port.
    • Select the port to which the Portenta H7 is connected.

  6. Upload the sketch.

    • Navigate to Sketch > Upload.

      Note: This process may take several minutes.

      Expected output of the upload: 

      Sketch uses 431236 bytes (21%) of program storage space. Maximum is 1966080 bytes.
Global variables use 95208 bytes (18%) of dynamic memory, leaving 428416 bytes for local variables. Maximum is 523624 bytes.
dfu-util 0.10-dev

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

Opening DFU capable USB device...
Device ID 2341:035b
Device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Interface #0 ...
Determining device status...
DFU state(2) = dfuIDLE, status(0) = No error condition is present
DFU mode device DFU version 011a
Device returned transfer size 4096
DfuSe interface name: "Internal Flash   "
Downloading element to address = 0x08040000, size = 435916
Erase   	[=========================] 100%       435916 bytes
Erase    done.
Download	[=========================] 100%       435916 bytes
Download done.
File downloaded successfully
Transitioning to dfuMANIFEST state

  7. While the sketch is uploading, open the Serial Monitor to monitor the MCU (microcontroller) locally via the Serial Port.

    • Navigate to 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:

      2106-02-06 23:32:04 [INFO] Connecting to WIFI wifi_ssid <ssid>
...
2106-02-06 23:32:44 [INFO] WiFi connected, IP address: 604051168
2106-02-06 23:32:44 [INFO] Setting time using SNTP

2022-06-16 13:04:50 [INFO] Time initialized!
2022-06-16 13:04:50 [INFO] Azure IoT client initialized (state=2)
2022-06-16 13:04:50 [INFO] MQTT Client ID: <device id>
2022-06-16 13:04:50 [INFO] MQTT Username: <id scope>/registrations/<device id>/api-version=2019-03-31
2022-06-16 13:04:50 [INFO] MQTT Password: ***
2022-06-16 13:04:50 [INFO] MQTT client address: global.azure-devices-provisioning.net
2022-06-16 13:04:50 [INFO] MQTT client port: 8883
2022-06-16 13:04:52 [INFO] MQTT client connected.
2022-06-16 13:04:53 [INFO] MQTT client subscribing to '$dps/registrations/res/#'
2022-06-16 13:04:53 [INFO] MQTT topic subscribed
2022-06-16 13:04:54 [INFO] MQTT client publishing to '$dps/registrations/PUT/iotdps-register/?$rid=1'
2022-06-16 13:04:55 [INFO] MQTT message received.
2022-06-16 13:04:55 [INFO] MQTT client publishing to '$dps/registrations/GET/iotdps-get-operationstatus/?$rid=1&operationId=4.36e237c8db462f45.1209aff3-9c58-4c56-b070-0fd4359286d1'
2022-06-16 13:04:56 [INFO] MQTT message received.
2022-06-16 13:04:58 [INFO] MQTT client publishing to '$dps/registrations/GET/iotdps-get-operationstatus/?$rid=1&operationId=4.36e237c8db462f45.1209aff3-9c58-4c56-b070-0fd4359286d1'
2022-06-16 13:04:59 [INFO] MQTT message received.
2022-06-16 13:05:00 [INFO] MQTT client being disconnected.
2022-06-16 13:05:00 [INFO] MQTT Client ID: <device id>
2022-06-16 13:05:00 [INFO] MQTT Username: <provisioned iot hub fqdn>.azure-devices.net/<device id>/?api-version=2020-09-30&DeviceClientType=c%2F1.3.1(ard;portentaH7)&model-id=dtmi%3Aazureiot%3Adevkit%3Afreertos%3AEsp32AzureIotKit%3B1
2022-06-16 13:05:00 [INFO] MQTT Password: ***
2022-06-16 13:05:00 [INFO] MQTT client address: <provisioned iot hub fqdn>.azure-devices.net
2022-06-16 13:05:00 [INFO] MQTT client port: 8883
2022-06-16 13:05:02 [INFO] MQTT client connected.
2022-06-16 13:05:02 [INFO] MQTT client subscribing to '$iothub/methods/POST/#'
2022-06-16 13:05:03 [INFO] MQTT topic subscribed
2022-06-16 13:05:03 [INFO] MQTT client subscribing to '$iothub/twin/res/#'
2022-06-16 13:05:03 [INFO] MQTT topic subscribed
2022-06-16 13:05:04 [INFO] MQTT client subscribing to '$iothub/twin/PATCH/properties/desired/#'
2022-06-16 13:05:04 [INFO] MQTT topic subscribed
2022-06-16 13:05:04 [INFO] MQTT client publishing to '$iothub/twin/PATCH/properties/reported/?$rid=0'
2022-06-16 13:05:04 [INFO] MQTT client publishing to 'devices/<device id>/messages/events/'
2022-06-16 13:05:04 [INFO] MQTT message received.
2022-06-16 13:05:04 [INFO] Properties update request completed (id=0, status=204)
2022-06-16 13:05:14 [INFO] MQTT client publishing to 'devices/<device id>/messages/events/'

View your device data from IoT Central

With IoT Central, you can view the device status and information, observe telemetry, and send commands.

  1. Go to your IoT Central application portal.
  2. Select your application.
  3. On the left side menu, under 'Connect', select 'Devices'.

Verify the device status

To view the device status in IoT Central portal:

  1. Find your device in the devices list.

  2. Confirm the 'Device status' of the device is updated to 'Provisioned'.

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

    Note: The 'Espressif ESP32 Azure IoT Kit' device template is used in this Arduino Portenta H7 sample for simplicity. It is a published template available from IoT Central. For more information on creating a custom device template, view these instructions.

    IoT Central device status

View device information

To view the device information in IoT Central portal:

  1. Click on your device's name in the device list.

  2. Select the 'About' tab.

    IoT Central device info

View telemetry

To view telemetry in IoT Central portal:

  1. Click on your device's name in the device list.

  2. Select the 'Overview' tab.

  3. View the telemetry as the device sends messages to the cloud.

    IoT Central device telemetry

Send a command

To send a command to the device:

  1. Select the 'Commands' tab.

  2. Locate the 'Display Text' box.

  3. In the 'Content' textbox, enter the text to be displayed on the screen.

  4. Select 'Run'.

  5. Because this is a simulated screen, the text will print to the log.

    2022-06-16 13:31:50 [INFO] OLED display: <text>

To toggle an LED:

  1. Select the 'Commands' tab.

  2. Locate the 'Toggle LED 1' or 'Toggle LED 2' box.

  3. Select 'Run'.

  4. Because these are simulated LEDs, the following will print to the log.

    2022-06-16 13:31:46 [INFO] LED <#> state: <ON/OFF>

IoT Central invoke method

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. On the left side menu, under 'Connect', select 'Devices'.
  2. Hover over your device's name and click on the circle that appears to the left. The circle will turn blue.
  3. Select 'Delete'. A box will appear to confirm deletion.
  4. Select 'Delete' again.

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

  1. On the left side menu, under 'Settings', select 'Application'.
  2. Select the 'Management' tab.
  3. Scroll to the bottom of the page.
  4. Select 'Delete'. A box will appear to confirm deletion.
  5. Select 'Delete' again.

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.