Overview Prerequisites Get started Additional information

Getting started with the Espressif ESP32-WROOM-32SE

Important

This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

Note

To explore how to integrate FreeRTOS modular libraries and demos within your own Espressif IDF project, see our featured reference integration for ESP32-C3 platform.
Currently, the FreeRTOS port for ESP32-WROOM-32SE doesn't support the symmetric multiprocessing (SMP) feature.

This tutorial shows you how to get started with the Espressif ESP32-WROOM-32SE. To purchase one from our partner on the AWS Partner Device catalog, see ESP32-WROOM-32SE.

Overview

This tutorial guides you through the following steps:

Connect your board to a host machine.
Install software on your host machine to develop and debug embedded applications for your microcontroller board.
Cross compile a FreeRTOS demo application to a binary image.
Load the application binary image to your board, and then run the application.
Monitor and debug the running application by using a serial connection.

Prerequisites

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

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

Open https://portal.aws.amazon.com/billing/signup.
Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to an administrative user, and use only the root user to perform tasks that require root user access.

AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to https://aws.amazon.com/ and choosing My Account.

Create an administrative user

After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks.

Secure your AWS account root user

Sign in to the AWS Management Console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

For help signing in by using root user, see Signing in as the root user in the AWS Sign-In User Guide.
Turn on multi-factor authentication (MFA) for your root user.

For instructions, see Enable a virtual MFA device for your AWS account root user (console) in the IAM User Guide.

Create an administrative user

Enable IAM Identity Center.

For instructions, see Enabling AWS IAM Identity Center in the AWS IAM Identity Center User Guide.
In IAM Identity Center, grant administrative access to an administrative user.

For a tutorial about using the IAM Identity Center directory as your identity source, see Configure user access with the default IAM Identity Center directory in the AWS IAM Identity Center User Guide.

Sign in as the administrative user

To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user.

For help signing in using an IAM Identity Center user, see Signing in to the AWS access portal in the AWS Sign-In User Guide.

To provide access, add permissions to your users, groups, or roles:

Users and groups in AWS IAM Identity Center:

Create a permission set. Follow the instructions in Create a permission set in the AWS IAM Identity Center User Guide.
Users managed in IAM through an identity provider:

Create a role for identity federation. Follow the instructions in Creating a role for a third-party identity provider (federation) in the IAM User Guide.
IAM users:
- Create a role that your user can assume. Follow the instructions in Creating a role for an IAM user in the IAM User Guide.
- (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in Adding permissions to a user (console) in the IAM User Guide.

Get started

Note

The Linux commands in this tutorial require that you use the Bash shell.

Set up the Espressif hardware.

For information about setting up the ESP32-WROOM-32SE development board hardware, see the ESP32-DevKitC V4 Getting Started Guide.

Important
When you reach the Installation Step by Step section of the guide, follow till you complete Step 4 (Set up the environment variables). Stop after you complete Step 4 and follow the remaining steps here.
Download Amazon FreeRTOS from GitHub. (For instructions, see the README.md file.)
Set up your development environment.

To communicate with your board, you must install a toolchain. Espressif provides the ESP-IDF to develop software for their boards. Since the ESP-IDF has its own version of the FreeRTOS Kernel integrated as a component, Amazon FreeRTOS includes a custom version of the ESP-IDF v4.2 that has the FreeRTOS Kernel removed. This fixes problems with duplicate files when you compile. To use the custom version of the ESP-IDF v4.2 included with Amazon FreeRTOS, follow the instructions below for your host machine's operating system.

Windows
1. Download ESP-IDF's Universal Online Installer for Windows.
2. Run the Universal Online Installer.
3. When you get to the step Download or use ESP-IDF, select Use an existing ESP-IDF directory and set Choose existing ESP-IDF directory to freertos/vendors/espressif/esp-idf.
4. Complete the installation.
macOS
1. Follow the instructions in the Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for macOS.
  
  Important
  When you reach the "Get ESP-IDF" instructions under Next Steps, stop, and then return to the instructions on this page.
2. Open a command line window.
3. Navigate to the FreeRTOS download directory, and then run the following script to download and install the espressif toolchain for your platform.
```
vendors/espressif/esp-idf/install.sh
```
4. Add the ESP-IDF toolchain tools to your terminal's path with the following command.
```
source vendors/espressif/esp-idf/export.sh
```
Linux
1. Follow the instructions in the Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for Linux.
  
  Important
  When you reach the "Get ESP-IDF" instructions under Next Steps, stop, and then return to the instructions on this page.
2. Open a command line window.
3. Navigate to the FreeRTOS download directory, and then run the following script to download and install the Espressif toolchain for your platform.
```
vendors/espressif/esp-idf/install.sh
```
4. Add the ESP-IDF toolchain tools to your terminal's path with the following command.
```
source vendors/espressif/esp-idf/export.sh
```
Establish a serial connection.
1. To establish a serial connection between your host machine and the ESP32-WROOM-32SE, install the CP210x USB to UART Bridge VCP drivers. You can download these drivers from Silicon Labs.
2. Follow the steps to Establish a Serial Connection with ESP32.
3. After you establish a serial connection, make a note of the serial port for your board's connection. You need it to flash the demo.

Configure the FreeRTOS demo applications

For this tutorial, the FreeRTOS configuration file is located at freertos/vendors/espressif/boards/board-name/aws_demos/config_files/FreeRTOSConfig.h. (For example, if AFR_BOARD espressif.esp32_devkitc is chosen, the configuration file is located at freertos/vendors/espressif/boards/esp32/aws_demos/config_files/FreeRTOSConfig.h.)

Important

The ATECC608A device has a one-time initialization that is locked onto the device the first time a project is run (during the call to C_InitToken). However, the FreeRTOS demo project and test project have different configurations. If the device is locked during the demo project configurations, not all tests in the test project will succeed.

Configure the FreeRTOS Demo Project by following the steps in Configuring the FreeRTOS demos. When you get to the last step To format your AWS IoT credentials, stop, and perform the following steps.
Microchip has provided several scripting tools to help with the setup of the ATECC608A parts. Navigate to the freertos/vendors/microchip/example_trust_chain_tool directory, and open the README.md file.
To provision your device, follow the instructions in the README.md file. The steps include the following:
1. Create and register a certificate authority with AWS.
2. Generate your keys on the ATECC608A and export the public key and device serial number.
3. Generate a certificate for the device and register that certificate with AWS.
Load the CA certificate and device certificate onto the device by following the instructions for Developer-mode key provisioning.

Monitoring MQTT messages on the AWS Cloud

Before you run the FreeRTOS demo project, you can set up 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, then choose MQTT Test Client.
In Subscription topic, enter your-thing-name/example/topic and then choose Subscribe to topic.

Build, flash, and run the FreeRTOS demo project using the idf.py script

You can use Espressif's IDF utility (idf.py) to generate the build files, build the application binary, and flash the binaries onto your device.

Note

Some setups might require that you use the port option "-p port-name" with idf.py to specify the correct port, as in the following example.


idf.py -p /dev/cu.usbserial-00101301B flash

Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)

Navigate to the root of your FreeRTOS download directory.
In a command line window, enter the following command to add the ESP-IDF tools to your terminal's PATH:
Windows ("Command" app)
```
vendors\espressif\esp-idf\export.bat
```
Windows ("ESP-IDF 4.x CMD" app)

(This has already been done when you opened the app.)

Linux / macOS
```
source vendors/espressif/esp-idf/export.sh
```

Configure cmake in the build directory and build the firmware image with the following command.


idf.py -DVENDOR=espressif -DBOARD=esp32_ecc608a_devkitc -DCOMPILER=xtensa-esp32 build

You should see output like this following example.


   Running cmake in directory /path/to/hello_world/build
   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
   Warn about uninitialized values.
   -- Found Git: /usr/bin/git (found version "2.17.0")
   -- Building empty aws_iot component due to configuration
   -- Component names: ...
   -- Component paths: ...

   ... (more lines of build system output)

   [527/527] Generating hello-world.bin
   esptool.py v2.3.1

   Project build complete. To flash, run this command:
   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
   or run 'idf.py -p PORT flash'

If there are no errors, the build will generate the firmware binary .bin files.

Erase your development board's flash memory with the following command.
```
idf.py erase_flash
```
Use the idf.py script to flash the application binary to your board.
```
idf.py flash
```
Monitor the output from your board's serial port with the following command.
```
idf.py monitor
```
Note
- You can combine these commands as in the following example.
  
  idf.py erase_flash flash monitor
- For certain host machine setups, you must specify the port when you flash the board as in the following example.
  
  idf.py erase_flash flash monitor -p /dev/ttyUSB1

Build and Flash FreeRTOS with CMake

Besides using the idf.py script provided by the IDF SDK to build and run your code, you can also build the project with CMake. Currently it supports Unix Makefile and the Ninja build system.

To build and flash the project

In a command line window, navigate to the root of your FreeRTOS download directory.
Run the following script to add the ESP-IDF tools to your shell's PATH.
Windows
```
vendors\espressif\esp-idf\export.bat
```
Linux / macOS
```
source vendors/espressif/esp-idf/export.sh
```

Enter the following command to generate the build files.

With Unix Makefiles


cmake -DVENDOR=espressif -DBOARD=esp32_plus_ecc608a_devkitc -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0

With Ninja


cmake -DVENDOR=espressif -DBOARD=esp32_plus_ecc608a_devkitc -DCOMPILER=xtensa-esp32 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja

Erase the flash and then flash the board.

With Unix Makefiles


make -C ./YOUR_BUILD_DIRECTORY erase_flash


make -C ./YOUR_BUILD_DIRECTORY flash

With Ninja


ninja -C ./YOUR_BUILD_DIRECTORY erase_flash


ninja -C ./YOUR_BUILD_DIRECTORY flash

Additional information

For more information about using and troubleshooting Espressif ESP32 boards, see the following topics:

Warning Javascript is disabled or is unavailable in your browser.

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

Document Conventions

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

Getting started with the Espressif ESP32-S2

Getting started with the Espressif ESP32-WROOM-32SE

Important

Note

Overview

Prerequisites

Sign up for an AWS account

To sign up for an AWS account

Create an administrative user

Secure your AWS account root user

Create an administrative user

Sign in as the administrative user

Get started

Note

Important

Important

Important

Configure the FreeRTOS demo applications

Important

Monitoring MQTT messages on the AWS Cloud

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

Build, flash, and run the FreeRTOS demo project using the idf.py script

Note

Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)

Note

Build and Flash FreeRTOS with CMake

To build and flash the project

Additional information