Espressif Systems is a multinational, fabless semiconductor company established in 2008, with headquarters in Shanghai and offices in Greater China, India, and Europe. For the last decade, they have been focused on producing connected microcontrollers and System-on-Modules (SoMs) for the emerging mobile and Internet of Things (IoT) markets.

Espressif has worked diligently to connect a number of their popular IoT SoMs to Amazon Web Services (AWS) IoT services. Here, we’ll discuss how to start running Amazon FreeRTOS on ESP32 in order to connect to AWS IoT Core.

In this post, I will guide you through the steps to:

Set up the ESP-IDF development environment for Amazon FreeRTOS

Establish a connection between the ESP32 Development Board and your computer

We assume that Xtensa toolchain, ESP-IDF, and amazon-freertos code will be installed in esp directory in the user’s home: ~/esp. You will need to add ~/esp/xtensa-esp32-elf/bin to your $PATH

Hardware Setup

While there are a number of ESP32 Development Boards available on the market, in this post we’ll use the one developed by Espressif: ESP32-DevKitC V4

Please make sure that drivers for the board are installed. When installing the driver for Silicon Labs CP2104 on Mac OS High Sierra, you may need to restart installation after whitelisting the installation package in System Preferences > Security & Privacy.

On Windows the driver would enumerate the port as COMx:

On Mac OS it would be:

$ ls /dev/tty.S*
/dev/tty.SLAB_USBtoUART

And on Linux:

$ ls /dev/ttyUSB*
/dev/ttyUSB0

Build Instructions for Amazon FreeRTOS with ESP32 Support

To get started, follow the ESP-IDF Getting Started Guide for your platform to set up the toolchain (Xtensa GCC compiler) for your OS. Please stop at the “Get ESP-IDF” section.

1. Clone amazon-freertos repository:

$ cd ~/esp
$ git clone https://github.com/aws/amazon-freertos

2. There is no need to set an explicit IDF_PATH; it will be picked up from amazon-freertos itself.

We recommend to unset if already set:

$ unset IDF_PATH

3. Set your serial port and baud rate:

$ make menuconfig

Please note that for ESP32-DevKitC, the serial port will be COMx on Windows, /dev/tty.SLAB_USBtoUART on Mac OS, and /dev/ttyUSB0 on Linux.

As an example, it can be like the one below, where afrtest is the AWS IoT Thing name, myAP is our wireless network SSID ESP32 development board will be connecting to, codehappy.2018 is the password for our wireless network, and eWiFiSecurityWPA2 is the security technology we use with our access point.

Other possible values for security technology are: (eWiFiSecurityOpen, eWiFiSecurityWEP, eWiFiSecurityWPA). Please avoid using anything except WPA2, as it is one of the easiest attack vectors on your wireless network.

When running on Windows using the mingw32 environment, install the AWS CLI using the following command: easy_install awscli

7. Install the boto3 Python module using the following command:

On Windows in the mingw32 environment: easy_install boto3

On MacOS or Linux: pip install boto3

8. Once you have boto3, navigate to the directory: ~/esp/amazon-freertos/demos/common/tools/aws_config_quick_start

Run the following command:

$ python SetupAWS.py setup

This script creates an IoT thing, certificate, and IoT policy. It will attach the IoT policy to the certificate and the certificate to the IoT thing. It will also populate the file aws_clientcredential.h with your AWS IoT endpoint, WiFi SSID, and credentials.

Finally, it will format your certificate and private key and write them to the header file: aws_clientcredential_keys.h

9. Build and upload demo project.

Go to the directory: amazon-freertos/demos/espressif/esp32_devkitc_esp_wrover_kit/make