# Getting started with the Espressif ESP32-S2
**Important**
This reference integration is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).
**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](https://www.freertos.org/featured-freertos-iot-integration-targeting-an-espressif-esp32-c3-risc-v-mcu/).
This tutorial shows you how to get started with the Espressif ESP32-S2 SoC and [ESP32-S2-Saola-1](https://devices.amazonaws.com/detail/a3G0h00000AkFngEAF/ESP32-S2-Saola-1) development boards.
## Overview
This tutorial guides you through the following steps:
1. Connect your board to a host machine.
1. Install software on your host machine to develop and debug embedded applications for your microcontroller board.
1. Cross-compile a FreeRTOS demo application to a binary image.
1. Load the application binary image to your board, and then run the application.
1. Monitor and debug the running application using a serial connection.
## Prerequisites
Before you get started with FreeRTOS on your Espressif board, you must set up your Amazon account and permissions.
### Sign up for an Amazon Web Services account
If you do not have an Amazon Web Services account, use the following procedure to create one.
**To sign up for Amazon Web Services**
1. Open [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choose **Sign Up**.
1. Follow the on-screen instructions.
Amazon 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 [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choosing **My Account**.
### Secure IAM users
After you sign up for an Amazon Web Services account, safeguard your administrative user by turning on multi-factor authentication (MFA). For instructions, see [Enable a virtual MFA device for an IAM user (console)](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-iam-user) in the *IAM User Guide*.
To give other users access to your Amazon Web Services account resources, create IAM users. To secure your IAM users, turn on MFA and only give the IAM users the permissions needed to perform their tasks.
For more information about creating and securing IAM users, see the following topics in the *IAM User Guide*:
+ [Creating an IAM user in your Amazon Web Services account](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_create.html)
+ [Access management for Amazon resources](https://docs.amazonaws.cn/IAM/latest/UserGuide/access.html)
+ [Example IAM identity-based policies](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_examples.html)
To provide access, add permissions to your users, groups, or roles:
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-user.html) 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)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
## Get started
**Note**
The Linux commands in this tutorial require that you use the Bash shell.
1. **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](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html).
**Important**
When you reach the **Get Started** section of the Espressif guides, stop, and then return to the instructions on this page.
1. Download Amazon FreeRTOS from [GitHub](https://github.com/aws/amazon-freertos). (For instructions, see the [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) file.)
1. **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](https://dl.espressif.com/dl/esp-idf/?idf=4.2) for Windows.
1. Run the **Universal Online Installer**.
1. 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`.
1. Complete the installation.
**macOS**
1. Follow the instructions in the [ Standard Setup of Toolchain prerequisites (ESP-IDF v4.2) for macOS](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/get-started/macos-setup.html).
**Important**
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.
1. Open a command line window.
1. 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
```
1. 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](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32s2/get-started/linux-setup.html).
**Important**
When you reach the "Get ESP-IDF" instructions under **Next Steps**, stop, and then return to the instructions on this page.
1. Open a command line window.
1. 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
```
1. Add the ESP-IDF toolchain tools to your terminal's path with the following command.
```
source vendors/espressif/esp-idf/export.sh
```
1. **Establish a serial connection.**
1. 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](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).
1. Follow the steps to [ Establish a Serial Connection with ESP32](https://docs.espressif.com/projects/esp-idf/en/release-v4.2/esp32/get-started/establish-serial-connection.html).
1. 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`.)
1. 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.
1. 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](https://www.python.org/downloads/) website.
1. You need the Amazon Command Line Interface (CLI) to run Amazon IoT commands. If you're running Windows, use the `easy_install awscli` command to install the Amazon CLI in the "Command" or "ESP-IDF 4.x CMD" app.
If you're running macOS or Linux, see [Installing the Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/installing.html).
1. Run
```
aws configure
```
and configure the Amazon CLI with your Amazon access key ID, secret access key, and default Amazon Region. For more information, see [Configuring the Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-getting-started.html).
1. Use the following command to install the Amazon 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 Amazon IoT.
**To run the configuration script**
1. 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 the `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 Amazon 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)
1. 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.
1. Navigate to the `freertos/tools/aws_config_quick_start` directory and run
```
python SetupAWS.py setup
```
The script does the following:
+ Creates an Amazon IoT thing, certificate, and policy.
+ Attaches the Amazon IoT policy to the certificate and the certificate to the Amazon IoT thing.
+ Populates the `aws_clientcredential.h` file with your Amazon 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 the `README.md` in the `freertos/tools/aws_config_quick_start` directory.
### Monitoring MQTT messages on the Amazon Cloud
Before you run the FreeRTOS demo project, you can set up the MQTT client in the Amazon IoT console to monitor the messages that your device sends to the Amazon Cloud.
**To subscribe to the MQTT topic with the Amazon IoT MQTT client**
1. Sign in to the [Amazon IoT console](https://console.aws.amazon.com/iotv2/).
1. In the navigation pane, choose **Test**, then choose **MQTT Test Client**.
1. 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\$1" sent multiple times to the topic that you subscribed to.
### Build, flash, and run the FreeRTOS demo project using the idf.py script
You can use Espressif's IDF utility to generate the build files, build the application binary, and flash your board.
#### Build and flash FreeRTOS on Windows, Linux, and macOS (ESP-IDF v4.2)
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**
1. Navigate to the root of your FreeRTOS download directory.
1. 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
```
1. 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.
1. Erase your development board's flash memory with the following command.
```
idf.py erase_flash
```
1. Use the `idf.py` script to flash the application binary to your board.
```
idf.py flash
```
1. 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**
1. In a command line window, navigate to the root of your FreeRTOS download directory.
1. 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
```
1. 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
```
1. Build the project.
+ With Unix Makefiles
```
make -C ./YOUR_BUILD_DIRECTORY -j8
```
+ With Ninja
```
ninja -C ./YOUR_BUILD_DIRECTORY -j8
```
1. 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:
+ [Using FreeRTOS in your own CMake project for ESP32](getting_started_espressif.md#getting_started_espressif_cmake_project)
+ [Troubleshooting](getting_started_espressif.md#getting_started_espressif_troubleshooting)
+ [Debugging](getting_started_espressif.md#getting_started_espressif_debugging)