The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Getting Started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT

This tutorial provides instructions for getting started with the Espressif ESP32-DevKitC and the ESP-WROVER-KIT. If you don't have an Espressif ESP32-DevKitC, you can purchase one from our partner on the AWS Partner Device Catalog. If you don't have an Espressif ESP32-WROVER-KIT, you can purchase one from our partner on the AWS Partner Device Catalog. Both devices are supported on Amazon FreeRTOS. For more information about these boards, see ESP32-DevKitC or ESP-WROVER-KIT on the Espressif website.

Note

Currently, the Amazon FreeRTOS port for ESP32-WROVER-KIT and ESP DevKitC does not support the following features:

Lightweight IP.
Symmetric multiprocessing (SMP).

Overview

This tutorial contains instructions for the following getting started steps:

Connecting your board to a host machine.
Installing software on the host machine for developing and debugging embedded applications for your microcontroller board.
Cross compiling an Amazon FreeRTOS demo application to a binary image.
Loading the application binary image to your board, and then running the application.
Interacting with the application running on your board across a serial connection, for monitoring and debugging purposes.

Prerequisites

Before you get started with Amazon FreeRTOS on your Espressif board, you need to set up your AWS account and permissions.

To create an AWS account, see Create and Activate an AWS Account.

To add an IAM user to your AWS account, see IAM User Guide. To grant your IAM user account access to AWS IoT and Amazon FreeRTOS, attach the following IAM policies to your IAM user account:

AmazonFreeRTOSFullAccess
AWSIoTFullAccess

To attach the AmazonFreeRTOSFullAccess policy to your IAM user

Browse to the IAM console, and from the navigation pane, choose Users.
Enter your user name in the search text box, and then choose it from the list.
Choose Add permissions.
Choose Attach existing policies directly.
In the search box, enter AmazonFreeRTOSFullAccess, choose it from the list, and then choose Next: Review.
Choose Add permissions.

To attach the AWSIoTFullAccess policy to your IAM user

Browse to the IAM console, and from the navigation pane, choose Users.
Enter your user name in the search text box, and then choose it from the list.
Choose Add permissions.
Choose Attach existing policies directly.
In the search box, enter AWSIoTFullAccess, choose it from the list, and then choose Next: Review.
Choose Add permissions.

For more information about IAM and user accounts, see IAM User Guide.

For more information about policies, see IAM Permissions and Policies.

Set Up the Espressif Hardware

See the ESP32-DevKitC Getting Started Guide for information about setting up the ESP32-DevKitC development board hardware.

See the ESP-WROVER-KIT Getting Started Guide for information about setting up the ESP-WROVER-KIT development board hardware.

Note

Do not proceed to the Get Started section of the Espressif guides. Instead, follow the steps below.

Set Up Your Development Environment

To communicate with your board, you need to download and install a toolchain.

Setting Up the Toolchain

To set up the toolchain, follow the instructions for your host machine's operating system:

Note

When you reach the "Get ESP-IDF" instructions under Next Steps, stop and return to the instructions on this page.   If you previously followed the "Get ESP-IDF" instructions and installed ESP-IDF, make sure that you clear the  IDF_PATH environment variable from your system before continuing.

Note

Version 3.1.3 of the ESP-IDF (the version used by Amazon FreeRTOS) does not support the latest version of the ESP32 compiler. You must use the compiler that is compatible with version 3.1.3 of the ESP-IDF (see the links above). To check the version of your compiler, run "xtensa-esp32-elf-gcc --version".

Install CMake

The CMake build system is required to build the Amazon FreeRTOS demo and test applications for this device. Amazon FreeRTOS supports versions 3.13 and later.

You can download the latest version of CMake from CMake.org. Both source and binary distributions are available.

For more details about using CMake with Amazon FreeRTOS, see Using CMake with Amazon FreeRTOS.

Establish a Serial Connection

To establish a serial connection between your host machine and the ESP32-DevKitC, you must install CP210x USB to UART Bridge VCP drivers. You can download these drivers from Silicon Labs.

To establish a serial connection between your host machine and the ESP32-WROVER-KIT, you must install some FTDI virtual COM port drivers. You can download these drivers from FTDI.

For more information, see Establish Serial Connection with ESP32. After you establish a serial connection, make a note of the serial port for your board's connection. You need it when you build the demo.

Download and Configure Amazon FreeRTOS

After your environment is set up, you can download Amazon FreeRTOS from GitHub, or from the Amazon FreeRTOS console.

Configure the Amazon FreeRTOS Demo Applications

If you are running macOS or Linux, open a terminal prompt. If you are running Windows, open mingw32.exe.
To verify that you have Python 2.7.10 or later installed, run python --version. The version installed is displayed. If you do not have Python 2.7.10 or later installed, you can install it from the Python website.
You need the AWS CLI to run AWS IoT commands. If you are running Windows, use the easy_install awscli to install the AWS CLI in the mingw32 environment.

If you are running macOS or Linux, see Installing the AWS Command Line Interface.
Run aws configure and configure the AWS CLI with your AWS access key ID, secret access key, and default region name. For more information, see Configuring the AWS CLI.
Use the following command to install the AWS SDK for Python (boto3):
- On Windows, in the mingw32 environment, run easy_install boto3.
- On macOS or Linux, run pip install tornado nose --user and then run pip install boto3 --user.

Amazon FreeRTOS includes the SetupAWS.py script to make it easier to set up your Espressif board to connect to AWS IoT. To configure the the script, open <amazon-freertos>/tools/aws_config_quick_start/configure.json and set the following attributes:

afr_source_dir

The complete path to the amazon-freertos directory on your computer. Make sure that you use forward slashes to specify this path.

thing_name

The name that you want to assign to the AWS IoT thing that represents your board.

wifi_ssid

The SSID of your Wi-Fi network.

wifi_password

The password for your Wi-Fi network.

wifi_security

The security type for your Wi-Fi network.

Valid security types are:

eWiFiSecurityOpen (Open, no security)
eWiFiSecurityWEP (WEP security)
eWiFiSecurityWPA (WPA security)
eWiFiSecurityWPA2 (WPA2 security)

To run the configuration script

If you are running macOS or Linux, open a terminal prompt. If you are running Windows, open mingw32.exe.
Go to the <amazon-freertos>/tools/aws_config_quick_start directory and run python SetupAWS.py setup.

The script does the following:

Creates an IoT thing, certificate, and policy
Attaches the IoT policy to the certificate and the certificate to the AWS IoT thing
Populates the aws_clientcredential.h file with your AWS IoT endpoint, Wi-Fi SSID, and credentials
Formats your certificate and private key and writes them to the aws_clientcredential.h header file

For more information about SetupAWS.py, see the README.md in the <amazon-freertos>/tools/aws_config_quick_start directory.

Build, Flash, and Run the Amazon FreeRTOS Demo Project

You can use CMake to generate the build files, Make to build the application binary, and Espressif's IDF utility to flash your board.

Build Amazon FreeRTOS

(If you are using Windows, please see the next section.)

Use CMake to generate the build files, and then use Make to build the application.

To generate the demo application's build files with CMake

Change directories to the root of your Amazon FreeRTOS download directory.
Use the following command to generate the build files:
```
cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -S . -B your-build-directory
```
Note

If you want to build the application for debugging, add the -DCMAKE_BUILD_TYPE=Debug flag to this command.

If you want to generate the test application build files, add the -DAFR_ENABLE_TESTS=1 flag.

To build the application with Make

Change directories to the build directory.
Use the following command to build the application with Make:
```
make all -j4
```
Note

You must generate the build files with the cmake command every time you switch between the aws_demos project and the aws_tests project.

Build Amazon FreeRTOS On Windows

On Windows, you must specify a build generator for CMake, otherwise CMake defaults to Visual Studio. Espressif officially recommends the Ninja build system because it works on Windows, Linux and MacOS. You must run CMake commands in a native Windows environment like cmd or powershell. Running CMake commands in a virtual Linux environment, like MSYS2 or WSL, is not supported.

Use CMake to generate the build files, and then use Make to build the application.

To generate the demo application's build files with CMake

Change directories to the root of your Amazon FreeRTOS download directory.
Use the following command to generate the build files:
```
cmake -DVENDOR=espressif -DBOARD=esp32_wrover_kit -DCOMPILER=xtensa-esp32 -GNinja -S . -B your-build-directory
```
Note

If you want to build the application for debugging, add the -DCMAKE_BUILD_TYPE=Debug flag to this command.

If you want to generate the test application build files, add the -DAFR_ENABLE_TESTS=1 flag.

To build the application

Change directories to the build directory.
Invoke Ninja to build the application:
```
ninja
```
Or, use the generic CMake interface to build the application:
```
cmake --build your-build-directory
```
Note

You must generate the build files with the cmake command every time you switch between the aws_demos project and the aws_tests project.

Flash and Run Amazon FreeRTOS

Use Espressif's IDF utility (<amazon-freertos>/vendors/espressif/esp-idf/tools/idf.py) to flash your board, run the application, and see logs.

To erase the board's flash, go to the <amazon-freertos> directory and use the following command:


./vendors/espressif/esp-idf/tools/idf.py erase_flash -B build

To flash the application binary to your board, use make:


make flash

You can also use the IDF script to flash your board:


./vendors/espressif/esp-idf/tools/idf.py flash -B build

To monitor:


./vendors/espressif/esp-idf/tools/idf.py monitor -p /dev/ttyUSB1 -B build

Note

You can combine these commands. For example:


./vendors/espressif/esp-idf/tools/idf.py erase_flash flash monitor -p /dev/ttyUSB1 -B build

Monitoring MQTT Messages on the Cloud

You can use the MQTT client in the AWS IoT console to monitor the messages that your device sends to the AWS Cloud.

To subscribe to the MQTT topic with the AWS IoT MQTT client

Sign in to the AWS IoT console.
In the navigation pane, choose Test to open the MQTT client.
In Subscription topic, enter iotdemo/#, and then choose Subscribe to topic.

Run the Bluetooth Low-Energy Demos

Amazon FreeRTOS supports Bluetooth Low Energy connectivity.

To run the Amazon FreeRTOS demo project across Bluetooth Low Energy, you need to run the Amazon FreeRTOS Bluetooth Low Energy Mobile SDK Demo Application on an iOS or Android mobile device.

To set up the the Amazon FreeRTOS Bluetooth Low Energy Mobile SDK demo application

Follow the instructions in Mobile SDKs for Amazon FreeRTOS Bluetooth Devices to download and install the SDK for your mobile platform on your host computer.
Follow the instructions in Amazon FreeRTOS Bluetooth Low Energy Mobile SDK Demo Application to set up the demo mobile application on your mobile device.

For instructions about how to run the MQTT over Bluetooth Low Energy demo on your board, see the MQTT over Bluetooth Low Energy Demo Application.

For instructions about how to run the Wi-Fi provisioning demo on your board, see the Wi-Fi Provisioning Demo Application.

Troubleshooting

If you are running macOS and the operating system does not recognize your ESP-WROVER-KIT, make sure you do not have the D2XX drivers installed. To uninstall them, follow the instructions in the FTDI Drivers Installation Guide for macOS X.
The monitor utility provided by ESP-IDF (and invoked using make monitor) helps you decode addresses. For this reason, it can help you get some meaningful backtraces in the event the application crashes. For more information, see Automatically Decoding Addresses on the Espressif website.
It is also possible to enable GDBstub for communication with gdb without requiring any special JTAG hardware. For more information, see Launch GDB for GDBStub on the Espressif website.
For information about setting up an OpenOCD-based environment if JTAG hardware-based debugging is required, see JTAG Debugging on the Espressif website.
If pyserial cannot be installed using pip on macOS, download it from the pyserial website.
If the board resets continuously, try erasing the flash by entering the following command on the terminal:
```
make erase_flash
```
If you see errors when you run idf_monitor.py, use Python 2.7.
Required libraries from ESP-IDF are included in Amazon FreeRTOS, so there is no need to download them externally. If the IDF_PATH environment variable is set, we recommend that you clear it before you build Amazon FreeRTOS.
On Windows, it can take 3-4 minutes for the project to build. You can use the -j4 switch on the make command to reduce the build time:
```
make flash monitor -j4
```
If your device has trouble connecting to AWS IoT, open the aws_clientcredential.h file, and verify that the configuration variables are properly defined in the file. clientcredentialMQTT_BROKER_ENDPOINT[] should look like <1234567890123>-ats.iot.<us-east-1>.amazonaws.com.

For general troubleshooting information about Getting Started with Amazon FreeRTOS, see Troubleshooting Getting Started.

Debugging Code on Espressif ESP32-DevKitC and ESP-WROVER-KIT

You need a JTAG to USB cable. We use a USB to MPSSE cable (for example, the FTDI C232HM-DDHSL-0).

ESP-DevKitC JTAG Setup

For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32 DevkitC:

C232HM-DDHSL-0 Wire Color	ESP32 GPIO Pin	JTAG Signal Name
Brown (pin 5)	IO14	TMS
Yellow (pin 3)	IO12	TDI
Black (pin 10)	GND	GND
Orange (pin 2)	IO13	TCK
Green (pin 4)	IO15	TDO

ESP-WROVER-KIT JTAG Setup

For the FTDI C232HM-DDHSL-0 cable, these are the connections to the ESP32-WROVER-KIT:

C232HM-DDHSL-0 Wire Color	ESP32 GPIO Pin	JTAG Signal Name
Brown (pin 5)	IO14	TMS
Yellow (pin 3)	IO12	TDI
Orange (pin 2)	IO13	TCK
Green (pin 4)	IO15	TDO

These tables were developed from the FTDI C232HM-DDHSL-0 datasheet. For more information, see C232HM MPSSE Cable Connection and Mechanical Details in the datasheet.

To enable JTAG on the ESP-WROVER-KIT, place jumpers on the TMS, TDO, TDI, TCK, and S_TDI pins as shown here:

Debugging on Windows

To set up for debugging on Windows

Connect the USB side of the FTDI C232HM-DDHSL-0 to your computer and the other side as described in Debugging Code on Espressif ESP32-DevKitC and ESP-WROVER-KIT. The FTDI C232HM-DDHSL-0 device should appear in Device Manager under Universal Serial Bus Controllers.
Under the list of universal serial bus devices, right-click the C232HM-DDHSL-0 device, and choose Properties.

Note

The device might be listed as USB Serial Port.

In the properties window, choose the Details tab to see the properties of the device. If the device is not listed, install the Windows driver for FTDI C232HM-DDHSL-0.
On the Details tab, choose Property, and then choose Hardware IDs. You should see something like this in the Value field:
```
FTDIBUS\COMPORT&VID_0403&PID_6014
```
In this example, the vendor ID is 0403 and the product ID is 6014.

Verify these IDs match the IDs in projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg. The IDs are specified in a line that begins with ftdi_vid_pid followed by a vendor ID and a product ID:
```
ftdi_vid_pid 0x0403 0x6014
```
Download OpenOCD for Windows.
Unzip the file to C:\ and add C:\openocd-esp32\bin to your system path.
OpenOCD requires libusb, which is not installed by default on Windows.

To install libusb
1. Download zadig.exe.
2. Run zadig.exe. From the Options menu, choose List All Devices.
3. From the drop-down menu, choose C232HM-DDHSL-0.
4. In the target driver field, to the right of the green arrow, choose WinUSB.
5. From the drop-down box under the target driver field, choose the arrow, and then choose Install Driver. Choose Replace Driver.
Open a command prompt, navigate to projects/espressif/esp32/make/aws_demos and run:
```
openocd.exe -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg
```
Leave this command prompt open.
Open a new command prompt, navigate to your msys32 directory, and run mingw32.exe. In the mingw32 terminal, navigate to projects/espressif/esp32/make/aws_demos and run make flash monitor.
Open another mingw32 terminal, navigate to projects/espressif/esp32/make/aws_demos and wait until the demo starts running on your board. When it does, run xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf. The program should stop in the main function.

Note

The ESP32 supports a maximum of two break points.

Debugging on macOS

Download the FTDI driver for macOS.
Download OpenOCD.
Extract the downloaded .tar file and set the path in .bash_profile to <OCD_INSTALL_DIR>/openocd-esp32/bin.
Use the following command to install libusb on macOS:
```
brew install libusb
```
Use the following command to unload the serial port driver:
```
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
```
If you are running a macOS version later than 10.9, use the following command to unload the Apple FTDI driver:
```
sudo kextunload -b com.apple.driver.AppleUSBFTDI
```
Use the following command to get the product ID and vendor ID of the FTDI cable. It lists the attached USB devices:
```
system_profiler SPUSBDataType
```
The output from system_profiler should look like this:
```
DEVICE:
							
Product ID: product-ID
Vendor ID: vendor-ID (Future Technology Devices International Limited)
```
Open projects/espressif/esp32/make/aws_demos/esp32_devkitj_v1.cfg. The vendor ID and product ID for your device are specified in a line that begins with ftdi_vid_pid. Change the IDs to match the IDs from the system_profiler output in the previous step.
Open a terminal window, navigate to projects/espressif/esp32/make/aws_demos, and use the following command to run OpenOCD:
```
openocd -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg
```
Open a new terminal, and use the following command to load the FTDI serial port driver:
```
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
```
Navigate to projects/espressif/esp32/make/aws_demos, and run the following command:
```
make flash monitor
```
Open another new terminal, navigate to projects/espressif/esp32/make/aws_demos, and run the following command:
```
xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf
```
The program should stop at main().

Debugging on Linux

Download OpenOCD. Extract the tarball and follow the installation instructions in the readme file.
Use the following command to install libusb on Linux:
```
sudo apt-get install libusb-1.0
```
Open a terminal and enter ls -l /dev/ttyUSB* to list all USB devices connected to your computer. This helps you check if the board’s USB ports are recognized by the operating system. You should see output like this:
```
$ls -l /dev/ttyUSB*
crw-rw----	1	root	dialout	188,	0	Jul	10	19:04	/dev/ttyUSB0
crw-rw----	1	root	dialout	188,	1	Jul	10	19:04	/dev/ttyUSB1
```
Sign off and then sign in and cycle the power to the board to make the changes take effect. In a terminal prompt, list the USB devices. Make sure the group owner has changed from dialout to plugdev:
```
$ls -l /dev/ttyUSB*
crw-rw----	1	root	plugdev	188,	0	Jul	10	19:04	/dev/ttyUSB0
crw-rw----	1	root	plugdev	188,	1	Jul	10	19:04	/dev/ttyUSB1
```
The /dev/ttyUSBn interface with the lower number is used for JTAG communication. The other interface is routed to the ESP32’s serial port (UART) and is used for uploading code to the ESP32’s flash memory.
In a terminal window, navigate to projects/espressif/esp32/make/aws_demos, and use the following command to run OpenOCD:
```
openocd -f esp32_devkitj_v1.cfg -f esp-wroom-32.cfg
```
Open another terminal, navigate to projects/espressif/esp32/make/aws_demos, and run the following command:
```
make flash monitor
```
Open another terminal, navigate to projects/espressif/esp32/make/aws_demos, and run the following command:
```
xtensa-esp32-elf-gdb -x gdbinit build/aws_demos.elf
```
The program should stop in main().

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »