Using PlatformIO

PlatformIO and Visual Studio Code are a great combination for IoT development. This guide describes how to use this The Things Network library with PlatformIO:

1. Create a project

• Click the Home icon in the status bar of Visual Studio Code to open the PlatformIO home page.
• Click on New Project.
• Enter a project name.
• Select your board from the list (in the Espressif 32 section). As far as I can tell, it doesn't really matter which one you choose. If you can't find your board, select Espressif ESP32 Dev Module.
• Select Espressif IoT Development Framework (fancy name for ESP-IDF) from the framework list.
• Click Finish.

2. Add the library

Download and unzip ttn-esp32 from https://github.com/manuelbl/ttn-esp32/archive/master.zip. Rename the unzipped folder to ttn-esp32.

Create a folder components within your PlatformIO project and move the entire ttn-esp32 folder it.

3. Rename main.c to main.cpp

The TTN library must be used from C++ code. So rename main.c (in src folder) to main.cpp.

You can also copy sample code from https://raw.githubusercontent.com/manuelbl/ttn-esp32/master/examples/hello_world/main/main.cpp.

Don't forget to configure the pins and the TTN keys in your code (see Get Started for more information).

4. Modify platformio.ini

Open the file platformio.ini and add the following entry to suppress many warnings in the library:

build_flags = -Wno-expansion-to-defined

A valid platformio.ini file could look like so:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = espidf
build_flags = -Wno-expansion-to-defined

5. Modify CMakeLists.txt in src folder

Open the CMakeList.txt file in the src folder and add REQUIRES ttn-esp32:

FILE(GLOB_RECURSE app_sources ${CMAKE_SOURCE_DIR}/src/*.*)

idf_component_register(SRCS ${app_sources} REQUIRES ttn-esp32)

6. Configure the library

Open a terminal within Visual Studio Code and run:

pio run -t menuconfig

In the menu, select Component config ---> and then select The Things Network ---> (at the very bottom). Now select TTN LoRa frequency / region (LoRa disabled) ---> and choose the correct frequency plan. Then select Exit several times and confirm that the new configuration should be saved.

6. Compile and upload

Compile and upload your program by clicking on the arrow button in the status bar of PlatformIO.

7. Alternative options for adding library

The preferred way in PlatformIO to add libraries is to use lib_deps entries in platformio.ini. That way, PlatformIO takes care of downloading the libraries and keeping them up-to-date. As far as I can tell, this does not properly work for the ESP-IDF framework.

So the only alternative I'm aware of is to use git submodules. As a prerequisite, your project must be under git version control and the code must have been check in at least once before you run pio run -t menuconfig:

git submodule add https://github.com/manuelbl/ttn-esp32.git components/ttn-esp32
git submodule update --init --recursive