Get Started with Microsoft Azure IoT Starter Kit - ESP32-DevKitC ("Core Board")

This sample was tested with Espressif's ESP32-DevKitC ("Core Board"), but many other kits would work as well.

Don't have a kit yet? Click here

This sample was modified from this one.

Step 1 - Download the ESP32 SDK

Clone the Espressif IoT Development Framework repository with the following command:

git clone --recursive

Step 2 - Set up the ESP32 toolchain

Follow the instructions for setting up the ESP32 toolchain found here.

Step 3 - Set IDF_PATH

Set the IDF_PATH environment variable to point to the location of the esp-idf directory that you cloned in Step 1.

If you're using MSYS on Windows, a good place to set the IDF_PATH variable is in the ~\msys32\home\user\.bashrc file that gets created the first time you run msys2_shell.cmd.

Step 4 - Install the Azure IoT C SDK

Create an azure-iot directory in the ESP32 SDK's components directory:
mkdir $IDF_PATH/components/azure-iot

Clone the Azure IoT C SDK into the azure-iot directory as sdk:
cd $IDF_PATH/components/azure-iot
git clone --recursive sdk

Copy the file for ESP32 into the azure-iot directory:
cp sdk/c-utility/build_all/esp32/sdk/ .

Step 5 - Create your new project

Create a directory for your new project and make that directory current:
mkdir <myproject>
cd <myproject>

Copy the project structure:
cp -a $IDF_PATH/components/azure-iot/sdk/c-utility/build_all/esp32/proj/. .

Copy the sample files:
cp $IDF_PATH/components/azure-iot/sdk/iothub_client/samples/iothub_client_sample_mqtt/iothub_client_sample_mqtt.* main

Step 6 - Set your device's connection string

Create and IoT Hub and an associated device identity as shown here. Then open the main/iothub_client_sample_mqtt.c file in the main directory of your project and find the line near the top that reads

static const char* connectionString = "";

and set the value of the connectionString variable to the be the connection string of the device identity that you created.

Step 7- Configure the make process

Using the toolchain you installed in Step 2 (MSYS, for example), navigate to the location of the sample code you downloaded in Step 4 and run the following command:

make menuconfig

This command will bring up a configuration dialog.

  1. Under "Serial flasher config --->Default serial port" set the serial port ID to that of your ESP32 device. (On Windows you can find the serial port ID under Computer Management.)

  2. Under "Example Configuration --->" enter your WiFi router SSID and password.

  3. Save the configuration and exit the dialog.

Step 8 - Run the make process

Build the sample with the simple command:


This will produce a iothub_client_sample_mqtt.bin file, a partitions_singleapp.bin file, a bootloader/bootloader.bin file, plus associated maps.

Step 9 - Flash the ESP32 device

Make sure the ESP32 device is plugged in and run the command:

make flash

This will flash the project onto the ESP32 device. Alternate methods of flashing the device can be found here

Step 10 - Monitor the device output

The sample program sends status output to the device's serial port at a default 115200 baud. You monitor this output by connecting to the serial port with any terminal program such as Putty.


This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact with any additional questions or comments.