Tutorial: Connect an ESPRESSIF ESP32-Azure IoT Kit to IoT Hub
In this tutorial, you use the Azure IoT middleware for FreeRTOS to connect the ESPRESSIF ESP32-Azure IoT Kit (from now on, the ESP32 DevKit) to Azure IoT.
You complete the following tasks:
- Install a set of embedded development tools for programming an ESP32 DevKit
- Build an image and flash it onto the ESP32 DevKit
- Use Azure CLI to create and manage an Azure IoT hub that the ESP32 DevKit connects to
- Use Azure IoT Explorer to register a device with your IoT hub, view device properties, view device telemetry, and call direct commands on the device
Prerequisites
- A PC running Windows 10 or Windows 11
- Git for cloning the repository
- Hardware
- ESPRESSIF ESP32-Azure IoT Kit
- USB 2.0 A male to Micro USB male cable
- Wi-Fi 2.4 GHz
- An active Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
Prepare the development environment
Install the tools
To set up your development environment, first you install the ESPRESSIF ESP-IDF build environment. The installer includes all the tools required to clone, build, flash, and monitor your device.
To install the ESP-IDF tools:
- Download and launch the ESP-IDF v5.0 Offline-installer.
- When the installer lists components to install, select all components and complete the installation.
Clone the repo
Clone the following repo to download all sample device code, setup scripts, and SDK documentation. If you previously cloned this repo, you don't need to do it again.
To clone the repo, run the following command:
git clone --recursive https://github.com/Azure-Samples/iot-middleware-freertos-samples.git
For Windows 10 and 11, make sure long paths are enabled.
To enable long paths, see Enable long paths in Windows 10.
In git, run the following command in a terminal with administrator permissions:
git config --system core.longpaths true
Create the cloud components
Create an IoT hub
You can use Azure CLI to create an IoT hub that handles events and messaging for your device.
To create an IoT hub:
Launch your CLI app. To run the CLI commands in the rest of this quickstart, copy the command syntax, paste it into your CLI app, edit variable values, and press Enter.
- If you're using Cloud Shell, right-click the link for Cloud Shell, and select the option to open in a new tab.
- If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.
Run az extension add to install or upgrade the azure-iot extension to the current version.
az extension add --upgrade --name azure-iot
Run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the centralus region.
Note
You can optionally set an alternate
location
. To see available locations, run az account list-locations.az group create --name MyResourceGroup --location centralus
Run the az iot hub create command to create an IoT hub. It might take a few minutes to create an IoT hub.
YourIotHubName. Replace this placeholder in the code with the name you chose for your IoT hub. An IoT hub name must be globally unique in Azure. This placeholder is used in the rest of this quickstart to represent your unique IoT hub name.
The
--sku F1
parameter creates the IoT hub in the Free tier. Free tier hubs have a limited feature set and are used for proof of concept applications. For more information on IoT Hub tiers, features, and pricing, see Azure IoT Hub pricing.az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2
After the IoT hub is created, view the JSON output in the console, and copy the
hostName
value to use in a later step. ThehostName
value looks like the following example:{Your IoT hub name}.azure-devices.net
Configure IoT Explorer
In the rest of this quickstart, you use IoT Explorer to register a device to your IoT hub, to view the device properties and telemetry, and to send commands to your device. In this section, you configure IoT Explorer to connect to the IoT hub you created, and to read plug and play models from the public model repository.
To add a connection to your IoT hub:
Install Azure IoT Explorer. This tool is a cross-platform utility to monitor and manage Azure IoT resources.
In your CLI app, run the az iot hub connection-string show command to get the connection string for your IoT hub.
az iot hub connection-string show --hub-name {YourIoTHubName}
Copy the connection string without the surrounding quotation characters.
In Azure IoT Explorer, select IoT hubs on the left menu.
Select + Add connection.
Paste the connection string into the Connection string box.
Select Save.
If the connection succeeds, IoT Explorer switches to the Devices view.
To add the public model repository:
In IoT Explorer, select Home to return to the home view.
On the left menu, select IoT Plug and Play Settings.
Confirm that there's an existing Public Repository entry with an endpoint of
https://devicemodels.azure.com
.Note
If there's not an entry the public repository, select +Add, select Public repository from the drop-down menu, specify the
https://devicemodels.azure.com
endpoint value, and then select Save.The completed entry for the public repository looks like the following screenshot:
Register a device
In this section, you create a new device instance and register it with the IoT hub you created. You use the connection information for the newly registered device to securely connect your physical device in a later section.
To register a device:
From the home view in IoT Explorer, select IoT hubs.
The connection you previously added should appear. Select View devices in this hub below the connection properties.
Select + New and enter a device ID for your device; for example,
mydevice
. Leave all other properties the same.Select Create.
Use the copy buttons to copy the Device ID and Primary key fields.
Before continuing to the next section, save each of the following values retrieved from earlier steps, to a safe location. You use these values in the next section to configure your device.
hostName
deviceId
primaryKey
Prepare the device
To connect the ESP32 DevKit to Azure, you modify configuration settings, build the image, and flash the image to the device.
Set up the environment
To launch the ESP-IDF environment:
Select Windows Start, find ESP-IDF 5.0 CMD, and run it.
In ESP-IDF 5.0 CMD, navigate to the iot-middleware-freertos-samples directory that you cloned previously.
Navigate to the ESP32-Azure IoT Kit project directory demos\projects\ESPRESSIF\aziotkit.
Run the following command to launch the configuration menu:
idf.py menuconfig
Add configuration
To add wireless network configuration:
In ESP-IDF 5.0 CMD, select Azure IoT middleware for FreeRTOS Sample Configuration --->, and press Enter.
Set the following configuration settings using your local wireless network credentials.
Setting Value WiFi SSID {Your Wi-Fi SSID} WiFi Password {Your Wi-Fi password} Select Esc to return to the previous menu.
To add configuration to connect to Azure IoT Hub:
Select Azure IoT middleware for FreeRTOS Main Task Configuration --->, and press Enter.
Set the following Azure IoT configuration settings to the values that you saved after you created Azure resources.
Setting Value Azure IoT Hub FQDN {Your host name} Azure IoT Device ID {Your Device ID} Azure IoT Device Symmetric Key {Your primary key} Note
In the setting Azure IoT Authentication Method, confirm that the default value of Symmetric Key is selected.
Select Esc to return to the previous menu.
To save the configuration:
- Select Shift+S to open the save options. This menu lets you save the configuration to a file named skconfig in the current .\aziotkit directory.
- Select Enter to save the configuration.
- Select Enter to dismiss the acknowledgment message.
- Select Q to quit the configuration menu.
Build and flash the image
In this section, you use the ESP-IDF tools to build, flash, and monitor the ESP32 DevKit as it connects to Azure IoT.
Note
In the following commands in this section, use a short build output path near your root directory. Specify the build path after the -B
parameter in each command that requires it. The short path helps to avoid a current issue in the ESPRESSIF ESP-IDF tools that can cause errors with long build path names. The following commands use a local path C:\espbuild as an example.
To build the image:
In ESP-IDF 5.0 CMD, from the iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit directory, run the following command to build the image.
idf.py --no-ccache -B "C:\espbuild" build
After the build completes, confirm that the binary image file was created in the build path that you specified previously.
C:\espbuild\azure_iot_freertos_esp32.bin
To flash the image:
On the ESP32 DevKit, locate the Micro USB port, which is highlighted in the following image:
Connect the Micro USB cable to the Micro USB port on the ESP32 DevKit, and then connect it to your computer.
Open Windows Device Manager, and view Ports to find out which COM port the ESP32 DevKit is connected to.
In ESP-IDF 5.0 CMD, run the following command, replacing the <Your-COM-port> placeholder and brackets with the correct COM port from the previous step. For example, replace the placeholder with
COM3
.idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash
Confirm that the output completes with the following text for a successful flash:
Hash of data verified Leaving... Hard resetting via RTS pin... Done
To confirm that the device connects to Azure IoT Central:
In ESP-IDF 5.0 CMD, run the following command to start the monitoring tool. As you did in a previous command, replace the <Your-COM-port> placeholder, and brackets with the COM port that the device is connected to.
idf.py -B "C:\espbuild" -p <Your-COM-port> monitor
Check for repeating blocks of output similar to the following example. This output confirms that the device connects to Azure IoT and sends telemetry.
I (50807) AZ IOT: Successfully sent telemetry message I (50807) AZ IOT: Attempt to receive publish message from IoT Hub. I (51057) MQTT: Packet received. ReceivedBytes=2. I (51057) MQTT: Ack packet deserialized with result: MQTTSuccess. I (51057) MQTT: State record updated. New state=MQTTPublishDone. I (51067) AZ IOT: Puback received for packet id: 0x00000008 I (53067) AZ IOT: Keeping Connection Idle...
View device properties
You can use Azure IoT Explorer to view and manage the properties of your devices. In the following sections, you use the Plug and Play capabilities that are visible in IoT Explorer to manage and interact with the ESP32 DevKit. These capabilities rely on the device model published for the ESP32 DevKit in the public model repository. You configured IoT Explorer to search this repository for device models earlier in this tutorial. In many cases, you can perform the same action without using plug and play by selecting IoT Explorer menu options. However, using plug and play often provides an enhanced experience. IoT Explorer can read the device model specified by a plug and play device and present information specific to that device.
To access IoT Plug and Play components for the device in IoT Explorer:
From the home view in IoT Explorer, select IoT hubs, then select View devices in this hub.
Select your device.
Select IoT Plug and Play components.
Select Default component. IoT Explorer displays the IoT Plug and Play components that are implemented on your device.
On the Interface tab, view the JSON content in the device model Description. The JSON contains configuration details for each of the IoT Plug and Play components in the device model.
Each tab in IoT Explorer corresponds to one of the IoT Plug and Play components in the device model.
Tab Type Name Description Interface Interface Espressif ESP32 Azure IoT Kit
Example device model for the ESP32 DevKit Properties (writable) Property telemetryFrequencySecs
The interval that the device sends telemetry Commands Command ToggleLed1
Turn the LED on or off Commands Command ToggleLed2
Turn the LED on or off Commands Command DisplayText
Displays sent text on the device screen
To view and edit device properties using Azure IoT Explorer:
Select the Properties (writable) tab. It displays the interval that telemetry is sent.
Change the
telemetryFrequencySecs
value to 5, and then select Update desired value. Your device now uses this interval to send telemetry.IoT Explorer responds with a notification.
To use Azure CLI to view device properties:
Run the az iot hub device-twin show command.
az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}
Inspect the properties for your device in the console output.
Tip
You can also use Azure IoT Explorer to view device properties. In the left navigation select Device twin.
View telemetry
With Azure IoT Explorer, you can view the flow of telemetry from your device to the cloud. Optionally, you can do the same task using Azure CLI.
To view telemetry in Azure IoT Explorer:
From the IoT Plug and Play components (Default Component) pane for your device in IoT Explorer, select the Telemetry tab. Confirm that Use built-in event hub is set to Yes.
Select Start.
View the telemetry as the device sends messages to the cloud.
Select the Show modeled events checkbox to view the events in the data format specified by the device model.
Select Stop to end receiving events.
To use Azure CLI to view device telemetry:
Run the az iot hub monitor-events command. Use the names that you created previously in Azure IoT for your device and IoT hub.
az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}
View the JSON output in the console.
{ "event": { "origin": "mydevice", "module": "", "interface": "dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1", "component": "", "payload": "{\"temperature\":28.6,\"humidity\":25.1,\"light\":116.66,\"pressure\":-33.69,\"altitude\":8764.9,\"magnetometerX\":1627,\"magnetometerY\":28373,\"magnetometerZ\":4232,\"pitch\":6,\"roll\":0,\"accelerometerX\":-1,\"accelerometerY\":0,\"accelerometerZ\":9}" } }
Select CTRL+C to end monitoring.
Call a direct method on the device
You can also use Azure IoT Explorer to call a direct method that you implemented on your device. Direct methods have a name, and can optionally have a JSON payload, configurable connection, and method timeout. In this section, you call a method that turns an LED on or off. Optionally, you can do the same task using Azure CLI.
To call a method in Azure IoT Explorer:
From the IoT Plug and Play components (Default Component) pane for your device in IoT Explorer, select the Commands tab.
For the ToggleLed1 command, select Send command. The LED on the ESP32 DevKit toggles on or off. You should also see a notification in IoT Explorer.
For the DisplayText command, enter some text in the content field.
Select Send command. The text displays on the ESP32 DevKit screen.
To use Azure CLI to call a method:
Run the az iot hub invoke-device-method command, and specify the method name and payload. For this method, setting
method-payload
totrue
means the LED toggles to the opposite of its current state.az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}
The CLI console shows the status of your method call on the device, where
200
indicates success.{ "payload": {}, "status": 200 }
Check your device to confirm the LED state.
Troubleshoot and debug
If you experience issues building the device code, flashing the device, or connecting, see Troubleshooting.
For debugging the application, see Debugging with Visual Studio Code.
Clean up resources
If you no longer need the Azure resources created in this quickstart, you can use the Azure CLI to delete the resource group and all of its resources.
Important
Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you do not accidentally delete the wrong resource group or resources.
To delete a resource group by name:
Run the az group delete command. This command removes the resource group, the IoT Hub, and the device registration you created.
az group delete --name MyResourceGroup
Run the az group list command to confirm the resource group is deleted.
az group list
Next steps
In this tutorial, you built a custom image that contains the Azure IoT middleware for FreeRTOS sample code, and then you flashed the image to the ESP32 DevKit device. You connected the ESP32 DevKit to Azure IoT Hub, and carried out tasks such as viewing telemetry and calling methods on the device.
As a next step, explore the following article to learn more about embedded development options.
Phản hồi
https://aka.ms/ContentUserFeedback.
Sắp ra mắt: Trong năm 2024, chúng tôi sẽ dần gỡ bỏ Sự cố với GitHub dưới dạng cơ chế phản hồi cho nội dung và thay thế bằng hệ thống phản hồi mới. Để biết thêm thông tin, hãy xem:Gửi và xem ý kiến phản hồi dành cho