This tutorial shows you how to get started with the Espressif ESP32-S2 SoC and ESP32-S2-Saola-1 development boards.
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 using a serial connection.
Before you get started with FreeRTOS on your Espressif board, you must set up your AWS account and permissions.
To create an account, see Create and Activate an AWS Account.
To add an AWS Identity and Access Management (IAM) user to your account, see Adding a user in the IAM User Guide. To grant your IAM user permission to AWS IoT and FreeRTOS, attach the following IAM managed policies to your IAM users:
AmazonFreeRTOSFullAccess
– Allows full access to all of your IAM user's FreeRTOS resources (freertos:*
).AWSIoTFullAccess
– Allows full access to all of your IAM user's AWS IoT resources (iot:*
).
To attach the AmazonFreeRTOSFullAccess
policy to your IAM user
-
Navigate to the IAM console.
-
In 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
-
Navigate to the IAM console.
-
In 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, see the IAM User Guide.
For more information about policies, see Permissions and policies in IAM.
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-S2 development board hardware, see the ESP32-S2-Saola-1 Getting Started Guide. Important
When you reach the Get Started section of the Espressif guides, stop, and then return to the instructions on this page. -
Download Amazon FreeRTOS
You can download Amazon FreeRTOS from either:
-
(For instructions, see the README.md file.)
-
(Select the correct Configuration and Hardware Platform that matches your device, for example "Connect to AWS IoT - ESP32-DevKitC".)
-
-
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
-
Download ESP-IDF's Universal Online Installer for Windows.
-
Run the Universal Online Installer.
-
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
. -
Complete the installation.
macOS
-
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. -
Open a command line window.
-
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
-
Add the ESP-IDF toolchain tools to your terminal's path with the following command.
source vendors/espressif/esp-idf/export.sh
Linux
-
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. -
Open a command line window.
-
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
-
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.
-
To establish a serial connection between your host machine and the ESP32-DevKitC, install the CP210x USB to UART Bridge VCP drivers. You can download these drivers from Silicon Labs.
-
Follow the steps to Establish a 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 to flash the demo.
-
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
.)
-
If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" app (if you included this option when you installed the ESP-IDF toolchain), or the "Command Prompt" app otherwise.
-
To verify that you have Python3 installed, run the following:
python --version
The version installed is displayed. If you don't have Python 3.0.1 or later installed, you can install it from the Python website.
-
You need the AWS Command Line Interface (CLI) to run AWS IoT commands. If you're running Windows, use the
easy_install awscli
command to install the AWS CLI in the "Command" or "ESP-IDF 4.x CMD" app.If you're running macOS or Linux, see Installing the AWS CLI.
-
Run
aws configure
and configure the AWS CLI with your AWS access key ID, secret access key, and default AWS Region. For more information, see Configuring the AWS CLI.
-
Use the following command to install the AWS SDK for Python (boto3):
-
On Windows, in the "Command" or "ESP-IDF 4.x CMD" app, run
easy_install boto3
-
On macOS or Linux, run
pip install tornado nose --user
and then run
pip install boto3 --user
-
FreeRTOS includes the SetupAWS.py
script to make it easier to set up your Espressif board to connect to AWS IoT.
To run the configuration script
-
To configure the script, open
freertos/tools/aws_config_quick_start/configure.json
and set the following attributes:
afr_source_dir
The complete path to thefreertos
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. The following are valid security types:eWiFiSecurityOpen
(Open, no security)eWiFiSecurityWEP
(WEP security)eWiFiSecurityWPA
(WPA security)eWiFiSecurityWPA2
(WPA2 security)
-
If you're running macOS or Linux, open a terminal prompt. If you're running Windows, open the "ESP-IDF 4.x CMD" or "Command" app.
-
Navigate to the
freertos/tools/aws_config_quick_start
directory and runpython SetupAWS.py setup
The script does the following:
- Creates an AWS IoT thing, certificate, and policy.
- Attaches the AWS 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_keys.h
header file. Note
The certificate is hardcoded for demonstration purposes only. Production-level applications should store these files in a secure location.
For more information about
SetupAWS.py
, see theREADME.md
in thefreertos/tools/aws_config_quick_start
directory.
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.
When the demo project successfully runs on your device you see "Hello World!" sent multiple times to the topic that you subscribed to.
You can use Espressif's IDF utility to generate the build files, build the application binary, and flash your board.
Use the idf.py
script to build the project 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
To build and flash the project
-
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=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 build
You should see output like this following example.
Executing action: all (aliases: build) Running cmake in directory /path/to/hello_world/build Executing "cmake -G Ninja -DPYTHON_DEPS_CHECKED=1 -DESP_PLATFORM=1 -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -DCCACHE_ENABLE=0 /path/to/hello_world"... -- The C compiler identification is GNU 8.4.0 -- The CXX compiler identification is GNU 8.4.0 -- The ASM compiler identification is GNU ... (more lines of build system output) [1628/1628] Generating binary image from built executable esptool.py v3.0 Generated /path/to/hello_world/build/aws_demos.bin Project build complete. To flash, run this command: esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x16000 build/ota_data_initial.bin 0x20000 build/aws_demos.bin or run 'idf.py -p (PORT) flash'
If there are no errors, the build generates 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
```
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=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0
-
With Ninja
cmake -DVENDOR=espressif -DBOARD=esp32s2_saola_1 -DCOMPILER=xtensa-esp32s2 -S . -B ./YOUR_BUILD_DIRECTORY -DAFR_ENABLE_ALL_MODULES=1 -DAFR_ENABLE_TESTS=0 -GNinja
-
-
Build the project.
-
With Unix Makefiles
make -C ./YOUR_BUILD_DIRECTORY -j8
-
With Ninja
ninja -C ./YOUR_BUILD_DIRECTORY -j8
-
-
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
-
For more information about using and troubleshooting Espressif ESP32 boards, see the following topics: