[Deprecated due to a number of issues with this approach] User setup in the sketch

[combs]

Hello! I am using the Arduino IDE and am not sure how best to store a different hardware setup within each sketch.

I have a number of different projects which have different hardware setups, and editing the library's User_Setup_Select.h file for each sketch doesn't seem like a great way to store the right settings for each project.

I have tried copying one of the User_Setups/*.h files into my sketch and including it before TFT_eSPI.h, but it doesn't seem to honor the pin selections. I also tried defining USER_SETUP_LOADED with no apparent change.

What's the best way to store TFT_eSPI hardware settings along with the sketch?

Thanks so much! I appreciate any guidance you can offer.

[Bodmer]

Edit: This approach is now deprecated as it is causing a number of issues.

I have done some research on the basis that it must be possible to bypass the blockage put in place by the Arduino IDE. I found a work-around that allows a setup file inside the sketch. The procedure is as follows:

1. Find the folder containing the boards.txt file for the processor board package you are using. To do this click the IDE menu "File->Preferences". At the bottom of that window click the link to the preferences.txt file. This will open a folder. Navigate to find the folder containing the "boards.txt" file for the processor you are using. Exampe paths for RP2040 and ESP32 are:

   C:\Users\44747\AppData\Local\Arduino15\packages\rp2040\hardware\rp2040\2.5.2
   C:\Users\44747\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.4

2. Place the following file in that folder (unzip it first! You will need to remember to add this file again if you upgrade the IDE or the board package version). Note that the file must be added to each processor board package you are using:
   platform.local.zip
3. Close the Arduino IDE and open it again so the added file is recognised.
4. Add the following lines to the start of User_Setup_Select.h in the TFT_eSPI library folder (note: I will add these on the next library update):

 // The following lines allow the user setup to be included in the sketch
#if __has_include(<tft_setup.h>)
  #include <tft_setup.h>
  #ifndef USER_SETUP_LOADED
    #define USER_SETUP_LOADED
  #endif
#endif

5. Open the a sketch and add a new tab, "tft_setup.h" in the main sketch, put all the tft library setup information in that header. Now include this header in the main sketch BEFORE loading the TFT_eSPI library. Example sketch for a RP2040 setup here:
   Hello_World.zip

Let me know if you get this working, then I will include these instructions in a future library update.

[Bodmer]

Caveat:

The approach works by including the sketch folder in the compile path for all libraries and the board package.

The proposed approach works with the examples in this library however it can result in the sketch failing to compile when some additional libraries are used.

So, a known working test sketch should be used to verify the apporach is compatible with the board packages, libraries and code included in your sketch.

[stef-ladefense]

exactly, I have a somewhat complex application and I have errors with WiFiManager, too bad!
the only solution would be to send to the library via one or more init(...) all the pins, configs, choice of funds etc..
moreover version 2 ide arduino still does not transfer the #define to the rest of the libraries

[Bodmer]

I have just downloaded IDE version 2.0 to try. It does seem to cause problems as you say with the proposed approach.

I had another go at using the build_opt.h approach and it worked. You need to include a file with the name build_opt.h in the sketch. I thought this did not work until I realised that edits to this file can be ignored by the IDE becuase it uses a cached copy of the library from a previous compilation. To get around this you must clear the cache, the only way I found to do this with Arduino IDE 2.0.0 is to select a different processor, compile the sketch (even though this might generate errors) then swap back to the desired processor and compile/upload again. This clumsy cache clear process process MUST be repeated if another sketch is loaded with different content in the build_opt.h file.

See here for example and caveats:
https://github.com/stm32duino/wiki/wiki/Customize-build-options-using-build_opt.h
Note that closing the IDE and opening the IDE no longer clears the cache with version 2.0.0 of the library (it used to with pre 2.0.0 versions). Also there is no IDE option to prevent caching!

Here is an example content of the required format for the build_opt.h header file, this is for an 8 bit parallel display with an ESP32 but the same approach should work with SPI or other setups.

-DUSER_SETUP_ID=3333
-DTFT_PARALLEL_8_BIT=1
-DILI9481_DRIVER=1
-DTFT_CS=33
-DTFT_DC=15
-DTFT_RST=32
-DTFT_WR=4
-DTFT_RD=2
-DTFT_D0=12
-DTFT_D1=13
-DTFT_D2=26
-DTFT_D3=25
-DTFT_D4=17
-DTFT_D5=16
-DTFT_D6=27
-DTFT_D7=14
-DLOAD_GLCD=1
-DLOAD_FONT2=1
-DLOAD_FONT4=1
-DLOAD_FONT6=1
-DLOAD_FONT7=1
-DLOAD_FONT8=1
-DLOAD_GFXFF=1
-DSMOOTH_FONT=1

Essentially a setup #define is replaced by -D, no spaces are used and the =xx must be included.

Comment out all setup file path lines in the User_Setup_Select.h file to avoid conflicts.

[Bodmer]

I had a problem trying to compile different shetches with different setup configurations in the build_opt.h file included with each sketch.

The problem is that the IDE caches the last compiled setup to make compilation faster. Swapping to a diferent sketch does not clear the already compiled and cached library that incorporated the previous setup.

The approach therefore is to force a cache clean after editting the build_opt.h file or changing to a sketch with a differnet built_opt.h configuration by selecting a different processor, compiling (may cause errors but cahe will clear), then swapping back to the correct proessor and compiling again. Closing the IDE and opening again does not clear the cache in IDE version 2.0.0. Opening another sketch that does not use TFT_eSPI , such as "Blink" also does not clear the cached TF_eSPI and pre-compiled TFT_eSPI library.

There does not seem to be an option in the IDE menus to stop it caching old library code or forcing clearing of the cache.

[Bodmer]

I've raised this cache issue with the Arduino team on the forum here:

https://forum.arduino.cc/t/cache-clear-option/1040106

Please login and express a desire for this feature in the forum topic. Hopefully this will then encourage the Arduino team to implement such a simple and useful feature.

[stef-ladefense]

thank you bodmer for your message
I added an idea on how to do it

[Bodmer]

Note that not all board packages implement support for using build_opt.h in the sketch. The ESP32 board package does support it but sadly the RP2040 board package does not.

[TangerineDreamer]

i've tried a user setup in the sketch, putting the file in the directory of esp8266 where the board.txt is,but had an error,so i
then put it in the "variants/d1_mini" and it worked.
I find this option almost heavy to do if you have to close and reopen arduino to be accepted,why not only make a coding-copy of
the setup.h of the sketch directly in the setup.h of the library root, before compiling,so the compiler willd not have to look
outside the root-setup,and don't need to put a platformLocal.txt in each variant repertory.

[Bodmer]

Further tests reveal this only works on the ESP32.

[stef-ladefense]

I created a 'build_opt.h' file in the project directory and without any configure screen in 'User_Setup_Select.h' , and it works

-DUSER_SETUP_ID=200
-DGC9A01_DRIVER=1
-DTFT_RGB_ORDER=TFT_BGR
-DTFT_WIDTH=240
-DTFT_HEIGHT=240
-DTFT_MOSI=11
-DTFT_SCLK=7
-DTFT_CS=12
-DTFT_DC=13
-DTFT_RST=10
-DTFT_BL=14
-DTOUCH_CS=-1
-DTFT_BACKLIGHT_ON=1
-DLOAD_GLCD=0
-DLOAD_FONT2=1
-DLOAD_FONT4=1
-DLOAD_FONT6=0
-DLOAD_FONT7=1
-DLOAD_FONT8=0
-DLOAD_GFXFF=0
-DSMOOTH_FONT=0
-DSPI_FREQUENCY=80000000
-DSPI_READ_FREQUENCY=24000000
-DSPI_TOUCH_FREQUENCY=2500000
-DSUPPORT_TRANSACTIONS=0
-DUSE_HSPI_PORT=1
-DDISABLE_ALL_LIBRARY_WARNINGS=1

[Bodmer]

Currently this only works for the ESP32 since the board core package is designed to support this style of configuration. This is not a "standard" way of doing things in the Arduino world.

[hamishcunningham]

hi @Bodmer
Great Library, thanks!
I'm porting to a new board (ESP32S3, HX8357) and wondering how best to contribute pindefs etc.
Am I right in thinking that if TFT_eSPI.h were to add support for build_opt.h with something like

#if __has_include(<build_opt.h>)
  #include <build_opt.h>
...

then we would have a somewhat portable means to set library options without changing the library code?
(For the Ardiuno IDE, the cores that support build_opt.h would work; for PlatformIO and makeEspArduino
I suspect that the sketch source directory is already present in the include paths?)
Best
Hamish

[rv3bj]

Hello to everyone! First of all I would like to thank Bodmer for good library.
But I have to say that User_Setup.h located in library is not good idea.
Today I was working with my project. It contains ST7789 display and H-Bridge driver on L298N chip. All was working good.
Suddenly I've seen the arduino message that offer me to update libraries. And I did it. After that I recompiled my project and restart it.
As result I've got burned one port on my ESP32-S2. I never thought that after updating library file User_Setup.h should be corrected before compiling.
So, my opinion that all needed pins definition should be ONLY in the project.
Many thanks,
Evgeny

[Bodmer]

Unfortunately the Arduino IDE is deliberately designed to partition the sketch folder and libraries so that any #defines in the sketch are not visible to a library.

It might be worth considering including series limit resistors in the hardware design or other GPIO protection features to prevent damage from software bugs, crashes and incorrect configuration.

If a "per project" setup is required then PlatformIO is a good solution since the projects "platformio.ini" file can contain all the settings and these over-ride anything in the library.

Note that a sketch does have visibility of any #define in the library, so a sketch can be written to chack the setup is correct before configuring hardware.

The present arrangement does have a very significant advantage in that once the setup is defined any example sketches can be run without any modification.