Installed Amazon FreeRTOS on ESP32 DevKitC and tried the sample program.

• English
• 日本語

Amazon FreeRTOS

The April 2021 issue of Interface magazine(Japanese Magazine) included an introduction to Amazon x microcontroller FreeRTOS, so I gave it a try.

FreeRTOS (Real Time Operating System) was acquired by Amazon in 2017 and is being developed as “Amazon FreeRTOS”.

• A lightweight and simple RTOS (Real Time Operating System)
• Suitable for processes that perform tasks within a certain time frame that require real-time performance
• Easy to connect to AWS IoT Core (supports IoT)
• MIT license is easy to use for products.
• It is not mandatory to release your own modified source code.
• The original FreeRTOS had a MIT license, which made it a little difficult to use for commercial purposes.
• Security features are provided (encrypted by connecting to AWS using a public key system).

I installed Amazon FreeRTOS and the sample program on ESP32 DevKitC (ESP-wroom-32) according to the instructions in the magazine, connected to AWS IoT Core, and tried to publish a message, so I’ll write this article as a reminder.

Outline drawing

• Download the appropriate sample program (including FreeRTOS) from the AWS FreeRTOS Device Software page
• Configure the AWS IoT Core
• Compile in the ESP-IDF environment on your PC
• Write to ESP32 DevkitC
• Program to publish (send) messages to IoT Core at intervals of several seconds

Environment

In this case, the environment we tried was as follows.

Equipment needed

I bought a module with ESP-WROOM-32 on it.

• Tensilica LX6 Dual Core CPU Processor
• 520 KB SRAM
• Wi-Fi 802.11 b/g/n, Bluetooth 4.2
• SPI / SDIO / I2C / UART Interface
• 30 pins (15 pins x 2)
• Micro USB Type-B (power supply, data transfer)
• Button x 2 (EN+BOOT)
• LED indicator x 2

procedure

The procedure is as follows.

• Download FreeRTOS from the AWS console and configure AWS IoT Core
• Download credentials
• Install ESP-IDF tools on your computer
• Set environment variables
• Setting up the CMake environment
• Modify the source code, build, and compile
• Write to ESP32-DevKitC (Flush)

Download FreeRTOS

Login to the AWS (Amazon Web Services) console and navigate to the AWS IoT Core page from the list of services.

Select “Software” from the menu at the bottom left.

“FreeRTOS Device Software”, click the “Configure Downloads” button.

Scroll down to “Connect to AWS IoT – ESP32-DevKitC ESP32-DevKitC” and click on “Quick Connect”.

Note
There is a similarly named “Connect to AWS Greengrass – ESP32-DevKitC”.

Scroll down to the bottom of the screen for instructions.

1. Download FreeRTOS for your device
2. Register your device
3. Download your credentials
4. Configure FreeRTOS on your device
5. Test your device

Review the steps and click the “Get Started” button.

• select a FreeRTOS version to use: 202012.00 Latest
• Hardware platform: ESP32-DevKitC

and click “Show More Details”.

As of May 2021, the latest version was 202012.00.

In the Libraries, click “Add another library”.

Click “OTA Updates” to add it to the library for download.

OTA (Over-The-Air) is a function that updates software wirelessly and is used when you want to update the program of an IoT device remotely.

In this article, we will not describe the OTA demo.

We have confirmed that ESP32-DevKitC gets the latest file when the update binary file is stored in Amazon s3, and automatically updates to the latest software over the air.

Make sure that OTA Updates has been added to the installation library and scroll down.

Make sure that the “coreMQTT Demos” Enable demo is selected.

After this, multiple demo projects will be downloaded to your computer, and here you can specify which demo project you want to compile and run.

In this case, I have enabled the MQTT demo project, but you can change the project to be compiled by modifying the description in aws_demo_config.h even after downloading.

• Name required: ConnecttoAWSIoT-ESP32-DevKitC-test-en
• Description (optional): Get started with the libraries required to securely connect to AWS IoT.test-en

and click the “Create and download” button.

“Create” means that you need to create things, certificates, and create policies in AWS IoT Core, but it will create them automatically behind the scenes.

If you have already created things, certificates, and policies manually, you can just “download” them.

Save the freertos-xxxxx.zip file (about 60MB) in an your PC folder and extract it.

folder structure

I unzipped it under D:\GoogleDriveD\M2B\

├─d:
│  │      
│  ├─GoogleDriveD
│  │  │
│  │  ├──M2B
│  │  │  │
│  │  │  ├──build　・・・　Create an empty one (for storing build files)
│  │  │  │
│  │  │  ├──FreeRTOS ・・・ Unzip it here.
│  │  │  │  │
│  │  │  │  ├──demos　・・・Demo Applications
│  │  │  │  │
│  │  │  │  ├──device
│  │  │  │  │
│  │  │  │  ├──freertos_kernel　・・・ Kernel of FreeRTOS
│  │  │  │  │
│  │  │  │  ├──libraries　・・・　Libraries
│  │  │  │  │
│  │  │  │  ├──tests
│  │  │  │  │
│  │  │  │  ├──tools　・・・　Tools (Conversion tools for authentication files,etc)
│  │  │  │  │
│  │  │  │  ├──vendors　・・・ ESP-IDF
│  │  │  │  │

Registering a Device

Moves to the screen for entering the device name.

• Name: ESP-WROOM-32-Test-en

and click the “Next” button.

Click the “Download and continue” button to create and download the credentials.

Also, AWS IoT Core things and policies will be created automatically.

Credential files

Credentials.zip will be created, save it and extract it.

・aws_clientcredential.h
・aws_clientcredential_keys.h
・ESP-WROOM-32-Test-en.cert.pem
・ESP-WROOM-32-Test-en.private.key
・ESP-WROOM-32-Test-en.public.key

The above five files will be extracted.

In the AWS console, you will see “Configure FreeRTOS on your device”, so follow the instructions and modify the files you just extracted to suit your environment.

I will mainly configure the Wi-Fi Credentials and AWS Credentials.

The next step in the AWS console is to test (receive MQTT messages), and before that, set up the ESP-IDF environment on the PC side.

The AWS console in the browser can be left as it is, or you can exit it once here (the test screen can be called up later).

Set up Wi-Fi Credentials

Set the Wi-Fi credentials in the aws_clientcredential.h file that you downloaded and extracted earlier.

The following three points need to be changed.

• clientcredentialWIFI_SSID: Specify the SSID.
• clientcredentialWIFI_PASSWORD: Specify the password.
• clientcredentialWIFI_SECURITY: Specify the encryption (security) method.*

* The following three types of encryption can be specified.

1. eWiFiSecurityOpen
2. eWiFiSecurityWEP
3. eWiFiSecurityWPA

Set up AWS credentials

• aws_clientcredential.h
• aws_clientcredential_keys.h

to d:\GoogleDriveD\M2B\FreeRTOS\demos\include\~.

There is already a file with the same name, so I renamed it and backed it up just in case.

The contents of the aws_clientcredential_keys.h file are as follows.

The information for the private key (ESP-WROOM-32-Test.private.key) to connect to the AWS IoT Core is set.

The line ends with \n”\, which is a convention for writing key information in C language code.

A tool to convert the original key format into the above format is included below.

D:\GoogleDriveD\M2B\FreeRTOS\tools\certificate_configuration\CertificateConfigurator.html

ESP-IDF Tools

Download the ESP-IDF tools (Ver 3.3) from this page.

As of May 2021, the latest version of FreeRTOS for ESP32-DevKitC (202012.00) recommended Ver 3.3 instead of Ver 4.2.

I think it will eventually support ESP-IDF Ver 4.2.

Scroll down to download https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe (ESP-IDF Ver 3.3 version).

Run the downloaded esp-idf-tools-setup-1.2.exe and you will be prompted to accept the license, select “I accept the agreement” and click the “Next” button.

Select the installation location (default is C:\Program Files\Espressif\ESP-IDF Tools) and click the “Next” button.

Select “Custom Installation” and click the “Next” button.

• Add Tools to Path：For all users
• Download and Run CMake 3.11.1 Installer：Uncheck the box.
• Download and Run Python 2.7.14 installer and install Python dependencies：Uncheck the box.

I clicked the “Next” button.

CMAKE is unchecked because we will install the latest version separately.

I also unchecked Python because I already have Ver 3.7 installed, but you can check the box according to your environment.

Click the “Install” button.

Installed successfully.

Setting Environment Variables

Set IDF_PATH as a Windows environment variable.

From the Start menu, search for “Environment Variables” and select “Edit the system environment variables”.

“Advanced” tab, click the “Environment Variables” button.

Click the “New” button in the “System variables” field.

If you only want to use ESP-IDF with this user, you can select User variables.

• Variable name: IDF_PATH
• Variable value: Set the following value

D:\GoogleDriveD\M2B\FreeRTOS\vendors\espressif\esp-idf

Enter the above text and click the “OK” button.

IDF_PATH has been added.

Then, select the system variables Path and click the “Edit” button.

A list of already configured Path will be displayed, click the “New” button.

The bottom line will be added, so add the following Path, and click the “OK” button.

D:\GoogleDriveD\M2B\FreeRTOS\vendors\espressif\esp-idf\tools

Click the “OK” button on the previous screen to finish setting the environment variables.

CMake

Download

Next, download the CMake installer from this page to set up the CMake compilation environment.

Scroll down to the bottom.

Download “cmake-3.21.0-rc1-windows-x86_64.msi”

Install

Run “cmake-3.20.2-windows-x86_64.msi” to launch the installer and click the “Next” button.

When the End-User License Agreement is displayed, check “I accept the terms in the License Agreement” and click the “Next” button.

Select “Add CMake to the system PATH for all users” and click the “Next” button.

Specify the Destination Folder and click the “Next” button.

Click the “Install” button.

Click the “Finish” button when the installation has been successfully completed.

Modify TOPIC

Open the following file and make some changes to the program source.

D:\GoogleDriveD\M2B\FreeRTOS\demos\coreMQTT\mqtt_demo_mutual_auth.c

• #define mqttexampleTOPIC： “/iotdemo/topic/1”
• #define mqttexampleMESSAGE：”Hello World! from ESP-WROOM-32″

Topic is a key for sorting messages in MQTT, and you can set the hierarchical structure with “/” (slash).

You can set any hierarchical structure, if you are interested in the recommended structure, please refer to the “MQTT design best practices“.

CMake

Start Power shell, go to the directory where you installed FreeRTOS, and create a build file with the following command.

d:
cd .\GoogleDriveD\M2B\FreeRTOS\
cmake -DVENDOR=espressif -DBOARD=esp32_devkitc -DCOMPILER=xtensa-esp32 -G Ninja -S . -B ..\build\

Parameters

If the cmake command is executed successfully, the following message will be displayed and the Build file will be created under the build folder.

Specifying the program to build

The sample program to be built is specified in the following file.

D:\GoogleDriveD\M2B\FreeRTOS\vendors\espressif\boards\esp32\aws_demos\config_files\aws_demo_config.h

CONFIG_CORE_MQTT_MUTUAL_AUTH_DEMO_ENABLED is specified because we enabled “coreMQTT Demos” in the AWS console demo activation described above.

If you want to build other sample programs, there is a list of projects that can be set in lines 32-47, so select one and define it with #define.

Errors in Python

I had an error at Cmake with the following error message.

“Some Python dependencies must be installed.”

In that case, use the following command to install additional modules that you need.

python -m pip install --user -r .\vendors\espressif\esp-idf\requirements.txt

Build

Compile the build file with the following command.

cmake --build ..\build\

Alternatively, you can go to the build directory and use the following command.

cd ..\build\
ninja

It will be compiled successfully and aws_demos.bin (executable file) will be created.

Write (Flush)

Connect your computer to the ESP32 DevKitC with the USB cable (Type-B).

Then use idf.py to write (flash) to the board.

.\vendors\espressif\esp-idf\tools\idf.py flash -b 115200 -B ..\build\

Parameter

A new Window will open and writing will start on the board.

When the Writing at reaches 100%, the Window will automatically close and writing will end.

To delete the file, use the following command.

.\vendors\espressif\esp-idf\tools\idf.py erase_flash -b 115200 -B ..\build\

Execution result

As soon as the writing is finished, the sample program runs and messages are sent to AWS IoT Core via MQTT protocol.

Monitoring

The following command from PowerShell was supposed to be able to monitor the program, but unfortunately, in my environment, the window opened for a moment, but closed immediately and I could not monitor it.

.\vendors\espressif\esp-idf\tools\idf.py flash monitor -p COM7 - b 115200 -B ..\build\

I gave up trying to monitor by command from PowerShell, and tried to monitor by serial connection with PuTTY.

Make the following settings via serial.

• Serial line to connect to: COM7 (depends on the environment)
• speed(baud): 115200
• Data bits: 8
• Stop bits: 1

I was able to monitor the output results of the ESP-32 DevKitC to the serial console by connecting with PuTTY.

• Topic Name：ESP-WROOM-32-GGTest/iotdemo/topic/1

I found out that it publishes (sends) at

MQTT test client

Confirm that the AWS IoT Core side is subscribing (receiving) the message.

If the AWS console is still intact, you can receive and display the test message.

If it is closed, select IoT Core from the list of services in the AWS console, go to the AWS IoT page, and then select “MQTT Test Client” from the menu.

Enter “#” (Sharp is a wildcard) in the Topic filter field and click the “Subscribe” button.

After waiting for a while, it receives a series of messages(Hello World! from ESP-WROOM-32) from ESP-32 DevKitC.

Since the received message is not in JSON format, the message “Message cannot be displayed in specified format” message is displayed, but you don’t need to worry about it.

This sample program will terminate the program after sending a few messages.

Pressing the EN (Enable) button on the ESP32 DevKitC will reset it and start the program from the beginning.

The End

In this sample program, I was able to connect to AWS IoT Core easily.

Also, when connecting to cloud services from ESP32, I felt that using Amazon FreeRTOS to connect to AWS IoT Core is a good choice because it ensures security.

I would like to try another sample project soon.

That’s the end of this article.

I hope this article will be useful to someone somewhere.