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.
Before getting started on this post it will help if you have most of the following:
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 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.
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
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.
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
- When creating the policy, if asked for a topic use
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.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
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
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.
- Retrieve the endpoint by running the following CLI command
aws iot describe-endpoint --endpoint-type iot:Data-ATS
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"
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.
Then run the following to build and deploy
platformio run --target upload
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 ---
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!