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.
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 | 4-wire (res) | esp-tftespi-default-simple.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).
Please refer to the Configuring Touch Support for details.
- 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. Note that after releasing a touch on the button that the sketch is expected to "quit" and stop responding. Resetting the device will start the test again.
If the touch presses don't appear to line up as expected, it may be necessary to adjust the touch-to-display mapping setting.
- In most cases this can be done by changing the
GSLC_TOUCH_ROTATEsetting to a value 0,1,2 or 3. These settings will adjust the flip and swapping of touch axes versus the display orientation. - To further help debug any touch handling, you can enable the
DBG_TOUCHfeature which will display yellow markers corresponding to where the display is detecting touch presses (according to the above mapping settings). - Also, note that resistive displays may require calibration to be performed in order to ensure the touch presses line up as expected.
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