Getting started with the Espressif ESP32-S2

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. 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 a user, and use only the root user to perform tasks that require root user access.

Secure your AWS account root user

1. 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.

2. 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 a user with administrative access

1. Enable IAM Identity Center.

   For instructions, see Enabling AWS IAM Identity Center in the AWS IAM Identity Center User Guide.

2. In IAM Identity Center, grant administrative access to a 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 user with administrative access

• 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.

Assign access to additional users

1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions.

   For instructions, see Create a permission set in the AWS IAM Identity Center User Guide.

2. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see Add groups in the AWS IAM Identity Center User Guide.

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.

   Important

   When you reach the Get Started section of the Espressif guides, stop, and then return to the instructions on this page.

2. Download Amazon FreeRTOS from GitHub. (For instructions, see the README.md file.)

3. 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

4. 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.

   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.

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.

2. 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.

3. 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.

4. 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.

5. 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

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 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)

2. 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.

3. Navigate to the freertos/tools/aws_config_quick_start directory and run

   python 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 the README.md in the freertos/tools/aws_config_quick_start directory.

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

1. Sign in to the AWS IoT console.

2. In the navigation pane, choose Test, then choose MQTT Test Client.

3. In Subscription topic, enter your-thing-name/example/topic, and then choose Subscribe to topic.

To build and flash the project

1. Navigate to the root of your FreeRTOS download directory.

2. 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

3. 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.

4. Erase your development board's flash memory with the following command.

   idf.py erase_flash

5. Use the idf.py script to flash the application binary to your board.

   idf.py flash

6. 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

To build and flash the project

1. In a command line window, navigate to the root of your FreeRTOS download directory.

2. 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

3. 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

4. Build the project.

   • With Unix Makefiles

     make -C ./YOUR_BUILD_DIRECTORY -j8

   • With Ninja

     ninja -C ./YOUR_BUILD_DIRECTORY -j8

5. 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