Configure GUIslice for ESP8266 & ESP32
Overview > Configuring GUIslice >
This guide describes the steps to configure the GUIslice library for Arduino and related devices
- ESP8266 (ESP8266)
- NodeMCU (ESP8266)
- Adafruit HUZZAH (ESP8266)
- ESP32 (ESP32)
- Adafruit HUZZAH32 (ESP32)
NOTE: users of M5stack ESP-32 devices should refer to the Configuration Guide for M5stack instead.
For ESP8266 / ESP32 devices, GUIslice can be built within the Arduino IDE.
In the case of ESP8266 / ESP32 devices, it is strongly recommended that users utilize bodmer's TFT_eSPI graphics library as the display driver. His library has been highly optimized for these devices.
If using TFT_eSPI, the GUIslice configuration should enable the following display driver: DRV_DISP_TFT_ESPI. In this mode, GUIslice will depend on the correct display configuration in the TFT_eSPI library. This is done by default in the ESP example configurations: configs/esp-tftespi-*.
Display modules may also incorporate a resistive or capacitive touch capability. These modules will generally have a separate Touch Driver, which may be marked on the product info. In some cases, a display with a resistive overlay will provide an analog 4-wire interface without a controller. In these cases, the simple touch driver (DRV_TOUCH_ADA_SIMPLE) should be selected. If no touch support is provided / desired, the notouch driver (DRV_TOUCH_NONE) should be selected.
Note that the Adafruit_TouchScreen library does not support ESP8266 or ESP32, so the simple 4-wire resistive touchscreen mode (DRV_TOUCH_ADA_SIMPLE) is not recommended.
At this time, the following example configs are provided:
| CPU | Display Driver | Touch Driver | Example Config | Notes |
|---|---|---|---|---|
| ESP8266 / ESP32 | TFT_eSPI | None | esp-tftespi-default-notouch.h |
|
| ESP8266 / ESP32 | TFT_eSPI | STMPE610 (res) | esp-tftespi-default-stmpe610.h |
|
| ESP8266 / ESP32 | TFT_eSPI | XPT2046 (res) | esp-tftespi-default-xpt2046.h |
|
| ESP8266 / ESP32 | TFT_eSPI | FT6206 (cap) | esp-tftespi-default-ft6206.h |
Take note of the Example Config that best matches your setup, as you will be selecting this file in Step 4.
Before attempting to run GUIslice, it is essential that the standalone graphics example included in the TFT_eSPI display library has been configured and runs correctly. If the TFT_eSPI example code doesn't work, GUIslice will not work, so please don't skip this step!
In all cases, the TFT_eSPI base graphics library needs to be installed first.
First, follow the directions in the TFT_eSPI library to configure your User_Setup file according to your display and associated wiring. Then, open the TFT_eSPI graphics example:
- File → Examples → TFT_eSPI → 320x240 → TFT_graphicstest_one_lib (or select an example matching your resolution)
- Confirm that the example successfully compiles and runs, showing a series of display patterns
GUIslice selects a configuration file to load according to the /src/GUIslice_config.h. This file includes a line for each of the example configurations provided in the /configs directory. Uncommenting one of these example configuration lines will load the corresponding config file settings. If no row is uncommented, then the default combined /src/GUIslice_config_ard.h file will be loaded.
Users can also create their own configurations by copying one of the existing example configurations and adding an uncommented row to the GUIslice_config.h file.
Please see how to locate GUIslice_config for details.
Many of the GUIslice configuration options are dictated by either #define <mode> <value> or #define <mode> lines within the config file.
In some cases the config file provides multiple related #define <mode> lines (such as DRV_DISP_*, with one line uncommented, and the remainder of the related modes commented out (with //). In order to change one of these config options, uncomment the desired mode and then comment out (or delete) the other related modes.
For other configuration modes, a single line #define <mode> <value> is provided, with a value of 0 or 1 dictating that the feature is disabled or enabled, respectively. Simply change the value between 0 and 1 as needed.
From this point onwards, references will be made to "enabling" or "disabling" a config setting, with the above convention used.
GUIslice supports a wide range of display and touch hardware in addition to the accompanying software drivers. We need to start by ensuring that GUIslice imports the appropriate display and touch drivers.
Since the TFT_eSPI library's User_Setup already takes care of the physical configuration, there is no wiring / pinout to be configured within GUIslice. An example GUIslice config file has been created for TFT_eSPI users.
Look in the GUIslice /configs directory for an example device + display + touch combination that matches your setup. In general, the example configs use the following naming convention:
<CPU>-<display_driver>-<display_controller>-<touch_controller>.h- For ESP8266/ESP-32 devices, they will generally be of the form:
esp-tftespi-default-<touch_controller>.h
If a matching configuration exists, uncomment the corresponding line in the GUIslice_config.h file. Alternately, a user config file can be linked in by adding an uncommented line with its filename in the GUIslice_config.h file. Note that only one configuration line should be uncommented.
Note that more example configurations will be added to the library over time, and users are encouraged to submit their own (if it is a combination that hasn't been provided yet).
Now that we have the basic driver and display settings configured, it is time to test the basic operation of the GUIslice library.
In the Arduino IDE, open up the ex01_ard_basic example:
- File → Examples → GUIslice → arduino → ex01_ard_basic
Enable the Serial Monitor in the Arduino IDE:
- Tools → Serial Monitor
- Change the baud rate to 9600 (located in bottom right corner of window) as this is the default used in the GUIslice examples (look for the
Serial.begin(9600);line). If you don't set a baud rate that matches the sketch serial initialization, random characters may be written to the display.
Run the sketch with Sketch → Upload
- Look for any error messages reported on the Serial Monitor
- See if the display shows a gray background with write-framed box:
If the above display test works properly, then it is time to enable the touch driver and test again (if a touch device is used).
A number of configuration steps are often required to ensure that the touch presses respond as expected.
- Please follow the detailed steps Configuring Touch Support.
- If you are using an XPT2046 touch controller, there are two touch drivers available for TFT_eSPI:
-
XPT2046_Touchscreen library. Config filename:
esp-tftespi-default-xpt2046, setting:DRV_TOUCH_XPT2046_PS. Configuring touch for XPT2046 (XPT2046_Touchscreen) -
TFT_eSPI library. Config filename:
esp-tftespi-default-xpt2046_int, setting:DRV_TOUCH_TFT_ESPI. Configuring Touch for XPT2046 (TFT_eSPI) - It is recommended that users select the XPT2046_Touchscreen driver and not the TFT_eSPI touch driver, simply because the first option integrates with GUIslice's configuration and calibration more easily.
-
XPT2046_Touchscreen library. Config filename:
- In the Arduino IDE, open up the ex02_ard_btn_txt example:
- File → Examples → GUIslice → arduino → ex02_ard_btn_txt
- Upload and confirm that a button responds to touch presses OK. Using the Serial Monitor (again at 9600 baud), confirm that the message "Quit button pressed" is displayed after releasing a touch on the button.
If the touch presses don't appear to line up as expected, it may be necessary to adjust the touch-to-display mapping setting. Please refer to the Configuring Touch Support page for details.
If the display and touch appear to be working correctly, experiment by loading up the other examples provided with GUIslice. For arduino devices, these can be loaded from the Arduino IDE under:
- File → Examples → GUIslice → arduino → ex01_ard_* (normal memory examples)
- File → Examples → GUIslice → arduino_min → ex01_ardmin_* (minimum memory examples)
In the repository, the above examples are located in the /examples/ directory.
RAM constraints are less of a problem on the ESP8266 platform versus other Arduino devices. Therefore, the simpler examples in examples/arduino can be used. Note that the Flash-optimized examples (under examples/arduino_min) may have some incompatibility issues with ESP8266 at this time.
This section will be added soon