Updated August 24, 2021

While building our latest IoT product, our development team found that documentation for FreeRTOS was dated and often flat-out wrong. To help others as they make their way through this process, we decided to document and release our findings as a FreeRTOS tutorial for developers. Here is how to get started with ESP32 on Linux.

Initial Observations

One can set up and install AWS FreeRTOS on numerous microcontrollers. For most of these steps, you will need either a Linux, Mac, or Windows computer.

• Ideally a Linux environment would work best with setup and work. Mac’s also work well with setup and flashing the boards
• Windows requires additional setup and might require more troubleshooting depending on experience.

Finding Documentation

AWS offers different documentation for different boards. Select from this list of microcontrollers depending on what you bought. In the context of this example, we are using this architecture of the ESP32 so we will be following the ESP32-DevKitC guide. We will also be using Ubuntu 20.04 to set up and flash the ESP32. Either a full installation or a VM will work. Ubuntu iso download here. Virtual Box Download here (if using VM).

Ubuntu Prerequisites

Virtual Box setup

• Click new. Give name of choosing to the VM, set Type to Linux, and version to Ubuntu (64-bit) and click next
• Set Memory (RAM) size to whatever fits. I recommend to ~4 Gigabytes of RAM and click next
• Select Create a virtual hard disk now and click next
• Select VDI and click next
• Select Fixed size and click next
• Set disk size for your virtual machine. I recommend around 25GB and click create. (wait until completion might take a while)

Select your virtual machine and click settings

• Go to storage and next to Controller: IDE click the blue cd icon with a green plus sign
• Click add and navigate to the place where you downloaded the Ubuntu ISO

In settings click the USB tab

• In the right side click the usb icon with a green plus sign
• Add anything with Silicon Labs USB to Uart Bridge controllers, or anything with Cygnal Integrated products CP210x Uart bridge. If you don't see these options you many need to download drivers for your platform here

Once USB and storage settings are set up, start the virtual machine

• Select language and click install Ubuntu
• Click Normal Installation and select Download updates while installing Ubuntu
• Select Erase disk and install Ubuntu and click install now

For all Ubuntu distributions

• sudo apt install gcc g++ cmake putty unzip curl
• sudo apt update
• sudo apt upgrade

If you are on a virtual machine (Virtual Box), at the top of the window click Devices

• For shared clipboard set to bidirectional
• For drag and drop set to bidirectional

Finally click Insert guest additions CD Image

• Once done installing in terminal input reboot
• These steps are not mandatory. They just make working inside the virtual box easier

AWS Prerequisites

• Have access to AWS services

Go to the Identity and Access Management (IAM) and grant your IAM user permission to use AWS IoT and FreeRTOS services.

Attach the following Policies to IAM user:

• AmazonFreeRTOSFullAccess
• AwsIoTFullAccess

Adding Policies

IAM Console

AmazonFreeRTOSFullAccess

• In the navigation pane, choose Users
• Input your username in search box, and select your name
• Choose Add permissions
• Choose Attach existing policies directly
• Search AmazonFreeRTOSFullAccess and select it from the list. Then choose Next: Review
• Choose Add permissions

AWSIoTFullAccess

• In the navigation pane, choose Users
• Input your username in search box, and select your name
• Choose Add permissions
• Choose Attach existing policies directly
• Search AWSIoTFullAccess and select it from the list. Then choose Next: Review
• Choose Add permissions

Setting up ESP32

Depending on the platform (Linux, Mac, Windows) select the following documentation and install the needed modules/ software.

• Windows
• Mac
• Linux

If you haven’t downloaded a FreeRTOS configuration go to the FreeRTOS console. Here you can download a pre-configured FreeRTOS that has some prebuilt modules depending on the services you might want to use and depending on chip architecture.

Under My configurations, you can make your own FreeRTOS version that can include (or exclude) certain libraries.

For our ESP32 in search bar enter ESP32 download the row that has configuration Connect to AWS Greengrass with hardware platform ESP32-DevKitC

Once downloaded unzip and make note where the extract folder is (we will be using the command line in this directory)

• Rename the folder with a name with no special characters, if you don’t rename the folder and it still has special characters it may mess with cmake

In command line/ Terminal. Navigate to the extracted freeRTOS file.

Navigate to vendors/espressif/esp-idf/

• Enter ls -al and check to see if the execute command is enabled (+x) for both install.sh and export.sh

If not (or you aren’t sure) enter the command:

• chmod +x install.sh export.sh
• This will enable the scripts to be run.

Now navigate back to the freeRTOS directory and run the following commands

• source vendors/espressif/esp-idf/install.sh

source vendors/espressif/esp-idf/export.sh

• Everytime you restart terminal, you need to run export.sh or else flashing and building won’t work.

If you are using Windows or Mac you also need to install the drivers for this platforms from silicon labs check here

• Don't do this if you are working within a linux virtual machine

At this point try to establish a serial connection with your ESP32

• To figure out for your machine check here

For linux use ls /dev/tty*

• You should see /dev/ttyUSBX (X is usually a number)
• In a new terminal enter sudo putty (make sure your esp32 is connected to your computer.
• For connection type select serial. For serial line input the port you found in the previous step. For speed input 115200
• If everything works you should see a black terminal
• If this is the case press the buttons on your ESP32 to restart the board, this will cause some text to print to the screen
• You won’t be able to connect to the ESP32 unless you use sudo putty. To change this enter sudo usermod -a -G dialout $USER and then reboot the machine/VM
• After rebooting don’t forget to rerun source vendor/espressif/esp-idf/export.sh from the FreeRTOS directory

Flashing ESP32

• First in terminal/command line check the version of python using python3 --version. Make sure you have python 3.0.1 or higher installed

If you haven't installed aws cli follow the doc here for your system here

For Ubuntu run the following

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"

• Careful not to download this in freeRTOS directory
• unzip awscliv2.zip
• sudo ./aws/install

Enter aws configure and enter your account information public key, private key, region, format. For format you could leave it empty or set it to json

• This would be helpful if you want to use IoT Core directly from the ESP32 without using Greengrass. Check the documentation here and scroll down to the Download and configure FreeRTOS section
• Enter pip install tornado nose
• Enter pip install boto3
• Make sure you are inside the FreeRTOS directory and enter source vendors/espressif/esp-idf/export.sh

Navigate to vendors/espressif/esp-idf/tools there should be a file called idf.py

• Execute chmod +x idf.py  This will enable us to run the script

Then in the FreeRTOS directory execute the following:

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

idf.py erase_flash flash monitor

• Each one of these can be run individually the first wipes the esp32, the second flashes binaries on it, and the third launches a terminal to see what the esp32 is printing
• If everything works fine you will see a bunch of lines and addresses being printed.

Next Up: FreeRTOS Tutorial #3: Creating a Hello World Application