POSTS

Getting Started with Amazon FreeRTOS and the Espressif ESP32-DevKitC

AWS Documentation and Drift

AWS already provides a getting started guide in the Amazon FreeRTOS documentation. But, when I was following it trying to get the demos to work I was unsuccessful. After a bit of investigation it became clear that the documentation was out of date. Following submission of feedback to AWS the documentation was promptly updated with up to date information.

Now, the Amazon FreeRTOS is a very active project and is changing continously. So, it is likely that the documentation may yet again drift from the GitHub code. In an attempt to ensure that these instructions continue to work I’ll be specific about version numbers and git commits used.

General requirements

  • Python 2.7.10+ (not Python 3)
  • AWS CLI
  • boto3 - pip install boto3 --user

Set up AWS account

Either sign up for an AWS account or use your existing one. Set up a new IAM user with these policies attached.

  • AmazonFreeRTOSFullAccess
  • AWSIoTFullAccess

You’ll need this user’s Access Key and Secret Key. So, make note of those.

Configure AWS CLI with user

Run aws configure and enter your user’s credentials information along with your preferred AWS Region.

Install Espressif Toolchain

DO NOT set up the environment variable $IDF_PATH

Install CMake

WARNING: Don’t assume you have a current version of CMake installed. Version 3.13 or later is required. I wasted a lot of time because I assumed I had the latest version installed on my Linux and Mac machines. I was wrong! My Ubuntu 18.04 system had version 3.4. I ended up installing Version 3.14.5.

Get CMake 3.14.5 from official GitHub releases

Get Serial Connection working

Linux

On my Linux machine I didn’t have to do anything. The device /dev/ttyUSB0 was automatically created and available. Note that the number for your device may be different.

Mac OS X

On my Macbook Pro running macOS Mojave version 10.14.5 (18F132) I had to download and install drivers from Silicon Labs website.

A reboot was required for it to start working properly.

Clone Amazon FreeRTOS GitHub Repository

At this point you should have a directory at ~/esp with the Espressif Toolchain. You’ll now clone the amazon-freertos GitHub repository and switch to the commit which I used and have verified as working with these instructions.

cd ~/esp
git clone https://github.com/aws/amazon-freertos.git
cd amazon-freertos
git checkout -b alikhalil.tech b76006df130102971b5f3575b7a85356c5439394

Set up configuration options

Update the file ~/esp/amazon-freertos/tools/aws_config_quick_start/configure.json to reflect your own configuration parameters. Most of the parameters are self explanatory. But, for wifi_security you need to provide one of the valid values.

  • eWiFiSecurityOpen (Open, no security)
  • eWiFiSecurityWEP (WEP security)
  • eWiFiSecurityWPA (WPA security)
  • eWiFiSecurityWPA2 (WPA2 security)

~/esp/amazon-freertos/tools/aws_config_quick_start/configure.json

{
    "afr_source_dir":"../..",
    "thing_name":"my_esp32_thing",
    "wifi_ssid":"my_ssid_name",
    "wifi_password":"my_ssid_password",
    "wifi_security":"one_of_valid_values"
}

Now, execute the SetupAWS.py script to do the following.

  • Creates an IoT thing, certificate, and policy
  • Attaches the 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.h header file
cd ~/esp/amazon-freertos/tools/aws_config_quick_start
python SetupAWS.py setup

Demos available and how to switch between them

At the time of writing this blog article there is no mention of how to switch between the demos. This information I found by reviewing the code. I hope this is helpful to some.

The list of demos and its selection can be found in the file vendors/espressif/boards/esp32/aws_demos/config_files/aws_demo_config.h.

/* To run a particular demo you need to define one of these. 
   Only one demo can be configured at a time
            CONFIG_MQTT_DEMO_ENABLED
            CONFIG_SHADOW_DEMO_ENABLED
            CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED
            CONFIG_TCP_ECHO_CLIENT_DEMO_ENABLED
            CONFIG_DEFENDER_DEMO_ENABLED
            CONFIG_OTA_UPDATE_DEMO_ENABLED
            CONFIG_BLE_GATT_SERVER_DEMO_ENABLED
            
    These defines are used in iot_demo_runner.h for demo selection */

#define CONFIG_MQTT_DEMO_ENABLED

To switch between the demos just define that specific demo. Just make sure only one is defined at a time. For example, if you want to run the Shadow demo then you’ll replace

#define CONFIG_MQTT_DEMO_ENABLED

with

#define CONFIG_SHADOW_DEMO_ENABLED

Build and load the demo

At this point you’ll have your environment set up, ESP32 board connected, and demo selected.

You’ll have to be in the ~/esp/amazon-freertos/ directory to execute the following commands.

cd ~/esp/amazon-freertos/
cmake -DVENDOR=espressif -DBOARD=esp32_devkitc -DCOMPILER=xtensa-esp32 -S . -B build
cmake --build build --parallel 8
./vendors/espressif/esp-idf/tools/idf.py erase_flash flash monitor -p /dev/ttyUSB0 -B build

I used --parallel 8 because I had 8 cpus available on the PC and I wanted to speed up the process. Feel free to remove that switch.

References

comments powered by Disqus