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!

  2. It is really a helpful blog to find some different source to add my knowledge.

  3. For my setup and display to work, I had to use this:

    build_flags =

    1. That’s great news! Thanks for sharing and happy coding!

  4. Szia Michael!
    Lehet hogy én is ilyen hibával kínlódok:
    (Version: 1.62.2 (user setup)
    Commit: 3a6960b964327f0e3882ce18fcebd07ed191b316
    Date: 2021-11-11T20:56:38.428Z
    Electron: 13.5.2
    Chrome: 91.0.4472.164
    Node.js: 14.16.0
    OS: Windows_NT x64 10.0.19043
    PlatformIO v2.4.0 Core 5.2.3, Home 3.4.0
    C/C++ v1.7.1)
    de nem látom a megoldást,
    Próbáltam az platformio.ini-t átirni, ( a USER SETUP után):

    ; PlatformIO Project Configuration File
    ; Build options: build flags, source filter
    ; Upload options: custom upload port, speed and extra flags
    ; Library options: dependencies, extra library storages
    ; Advanced options: extra scripting
    ; Please visit documentation for the other options and examples

    platform = espressif32
    board = esp32doit-devkit-v1
    framework = arduino

    -DILI9341_DRIVER = 1
    -DTFT_MOSI = 23
    -DTFT_SCLK = 18
    -DTFT_CS = 17
    -DTFT_DC = 16
    -DTFT_RST = 5
    -DLOAD_GLCD = 1
    -DLOAD_FONT2 = 1
    -DLOAD_FONT4 = 1
    -DLOAD_GFXFF = 1
    -DSPI_FREQUENCY = 40000000

    lib_deps =

    de nem segített.
    Nálam itt látszik a hiba:

    #include // only for VS Code
    #include // Serial Peripheral Interface (SPI) library
    #include // tft display library < ----- HULLÁMOSAN ALÁHÚZVA!!!
    #include // sound library
    #include // TWI/I2C library
    #include // sounds definition

    probáltam ide képet betenni de nem sikerült.
    Légyszíves ha tudsz, segíts kérlek.
    Üdvözlettel, Steve


Post a Comment

Popular posts from this blog

Kernel Integrated exFAT Support Performance has saved my Chia farmer

Azure Active Directory Domain Services Limitations