March 14, 2020     3min read

Easy AWS IoT with ESP-IDF


Get the code for this post!

t04glovern/esp-idf-aws-iot

When working on IoT projects its common that you will need to bake in libraries that allow you to interface with features on your embedded device. Espressif manufacture the commonly used ESP32/8266 devices and it's within their best interests to make it as easy as possible to start building on their platform. To accommodate they maintain the Espressif IoT Development Framework (ESP-IDF) which bundles all these libraries for you making it really easy to get started with projects.

In this post we are exploring how to use the Espressif IoT Development Framework (ESP-IDF) with PlatformIO to make developing projects for AWS IoT even easier.

Prerequisites

Before getting started on this post it will help if you have most of the following:

ESP32 Device

ESP32 FireBeetle device from https://core-electronics.com.au/
ESP32 FireBeetle device from https://core-electronics.com.au/

I recommend having an ESP32 device to work with. I personally use the FireBeetle ESP32 micro however any mainstream device should be fine. Some of these alternatives are:

NOTE: There are many boards available out there, most of which should work however note that your experiences may vary.

PlatformIO

PlatformIO is a very well established tool chain for developing on embedded devices. It serves itself as an IDE extension for popular editors like VSCode and enables developers to write the same code and deploy it to different architectures seamlessly.

PlatformIO Logo
PlatformIO Logo

In this post we will be making use of the PlatformIO Core CLI. To install this follow the guide at PlatformIO Core or install it via pip using the following command

pip install -U platformio

You can also achieve everything through the fantastic plugin for VSCode. If you have VSCode installed already simply install the PlatformIO Core plugin

PlatformIO VSCode plugin
PlatformIO VSCode plugin

Sample Project

The final requirement is the sample project available at t04glovern/esp-idf-aws-iot on GitHub. You can clone it down by running the following commands

https://github.com/t04glovern/esp-idf-aws-iot.git
cd esp-idf-aws-iot

We'll go over the individual details shortly, however feel free to check the README and jump ahead.

AWS IoT Device

Create a new AWS IoT device by following the excellent guide on the AWS IoT documentation page. By the end of the short guide you should have the following:

  • Three certificates (used in the next steps)
  • One IoT thing with a policy attached
    • When creating the policy, if asked for a topic use test_topic/esp32

Create New Project

When working with PlatformIO all project details can be provided in one simple platformio.ini file. Along with this are a couple generally used files such as:

  • src - Directory with C/C++ code
  • .gitignore - Defines what shouldn't be checked into Git
  • .pio - Ignored directory where compiled source gets stored
  • .vscode - VSCode configuration for your project

PlatformIO project files
PlatformIO project files

platformio.ini

The platformio.ini file is the heart of your ESP-IDF and any other IoT projects you are working on. It defines details such as the platform, framework, what embedded board you are building for and other adhoc things.

Check out the one we're using for this project below

[env:esp32dev]
platform = espressif32
framework = espidf
board = esp32dev
monitor_speed = 115200
build_flags =
  -DCONFIG_WIFI_SSID=\"wifissid\"
  -DCONFIG_WIFI_PASSWORD=\"wifipass\"
  -DCONFIG_AWS_IOT_TOPIC=\"test_topic/esp32\"

board_build.embed_txtfiles =
  src/private.pem.key
  src/certificate.pem.crt
  src/aws-root-ca.pem

Your Task: Define the WiFi SSID and Password you want your IoT device to use to connect to the internet. Update these fields with your own WiFi details

Certificates

Did you take note of the embed_txtfiles field? This is where we define where the certificates live that need to be loaded onto our board and used to communicate with AWS IoT.

  • src/aws-root-ca.pem - This certificate should contain the AWS CA (or your own private CA certificate). You can obtain this certificate from the Amazon trust HERE.
  • src/private.pem.key: Private Key certificate you received when creating your AWS IoT Device
  • src/certificate.pem.crt: Device certificate you received when creating your AWS IoT Device

sdkconfig.h

A small change needs to be made to the src/sdkconfig.h file on the configuration option CONFIG_AWS_IOT_MQTT_HOST. You need to update it to be the AWS IoT MQTT endpoint address which can be found via one of the two ways:

  • Retrieve the data endpoint by navigating to the AWS IoT Settings UI. Make sure you are in the correct region as well.

AWS IoT Custom Endpoint UI
AWS IoT Custom Endpoint UI

  • Retrieve the endpoint by running the following CLI command
aws iot describe-endpoint --endpoint-type iot:Data-ATS

subscribe_publish_sample.c

The sample C code is taken from the existing example from the platformio/platform-espressif32 repository. You shouldn't need to change too much (if anything) within it, however take not that the custom version in my repository stubs out the AWS IoT Topic to a config variable.

Take a look at the imports at the top, there's heaps! The best part is we don't need to worry about them! ESP-IDF and PlatformIO will come together in sweet harmony and pull everything together for us.

// Lots of imports we don't need to worry about!!!
#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
#include <unistd.h>
#include <limits.h>
#include <string.h>

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/event_groups.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "esp_event_loop.h"
#include "esp_log.h"
#include "esp_vfs_fat.h"
#include "driver/sdmmc_host.h"

#include "nvs.h"
#include "nvs_flash.h"

#include "aws_iot_config.h"
#include "aws_iot_log.h"
#include "aws_iot_version.h"
#include "aws_iot_mqtt_client_interface.h"

Compile & Deploy

We're not ready to compile and deploy our project and it's as simple as one command. Plug in your ESP32 device to your computer over the USB cable it would have came with.

ESP32 Plugged in
ESP32 Plugged in

Then run the following to build and deploy

platformio run --target upload

Debugging

Once the firmware is deployed you can monitor the output of the board by running the following command

platformio device monitor
# Looking for advanced Serial Monitor with UI? Check http://bit.ly/pio-advanced-monitor
# --- Miniterm on /dev/ttyACM0  115200,8,N,1 ---
# --- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---

Summary

The Espressif IoT Development Framework (ESP-IDF) is a fantastic way to get started developing on the ESP32 and other Espressif devices. When you partner it with PlatformIO as well you'll start to realise how simple it is to develop embedded devices in 2020.

Have you used ESP-IDF for something interesting? Or maybe you're an avid user of PlatformIO and have some tips for me? Reach out to me on Twitter @nathangloverAUS and let me know!

devopstar

DevOpStar by Nathan Glover | 2020