Use Bodmer TFT_eSPI Library with PlatformIO

If you start playing around with TFT on your ESP8266 or ESP32, you will arrive at the excellent TFT_eSPI Library by Bodmer. It's not only magnitudes faster than the Adafruit driver, it's also comes with support for a wide range of display drivers.

Test results of the TFT_eSPI library

Unfortunately it has one catch: The library is not really ready to be included as a library in your projects as it requires adjustments in the library itself. While it's not uncommon to define your settings with #define directives, this library expects you to patch files to configure it. The official way goes like this
  1. Locate the library folder (Windows would be Documents\Arduino\libraries\TFT_eSPI) and create your own setup in the library sub folder User_Setups
  2. To use your configuration, patch the file User_Setup_Select.h to include your configuration
This has obviously some disadvantages. At latest when you wan't to update the library or work with different screens at the same time. A couple of people have highlighted that as issues on the project page. There is also a comment from Bodmer where he explains why the library is structured in this way


PlatformIO to the rescue! We can use the library without patching anything, by simply including the required variables as build flags. There is even a almost hidden hint in the tools-folder of the library referring to PlatformIO configuration: TFT_eSPI/Tools/PlatformIO/Configuring%20options.txt

In my case, the configuration looks like the one below.
build_flags = 
In addition to the required USER_SETUP_LOADED=1, I'm using the exact same names as I would to in the User Setup version of the configuration.

Working with multiple displays also be achieved pretty by setting up different configuration sections, which can extend from each other. Working with multiple screens would only require to a different profile.

Still no dynamic configuration, but how often is that a requirement?


  1. Thank you for your solution. I just started playing with PlatformIO and had a TTGO ESP32 board (with built in TFT display) that I wanted to play with. I had it working properly in the Arduino IDE but had a hard time getting the display working in PlatformIO. Your approach is nice and simple, to just transfer the desired user board defines from the header to the platformio.ini file. I think I will write a simple tool that can parse any header file and convert all "#define"s into "-D" format so I can just paste them into the ini file when I work with other displays in the future.

    1. Thanks for your feedback! Glad to hear that my example helped you with your project. Happy coding!


Post a Comment

Popular posts from this blog

Migrating from Arduino IDE to Visual Studio Code to PlatformIO

Synology Presto Review