Configure GUIslice for Arduino
Overview > Configuring GUIslice >
This guide describes the steps to configure the GUIslice library for Arduino and related devices
- Arduino UNO (ATmega328P)
- Arduino Pro Mini (ATmega328P)
- Arduino Mega (ATmega2560)
- ... and many other similar devices
Return to GUIslice Config Guide
For Arduino devices, GUIslice can be built either within the Arduino IDE (recommended for most users) or within PlatformIO. This guide will describe operation within the Arduino IDE, documentation for PlatformIO may be written at a later date.
Important Note
Due to a bug in the Arduino IDE compiler, it is important that the Arduino AVR Boards is not set to version 1.6.22 or 1.6.23. Please refer to the Installing GUIslice for Arduino guide.
As is the case with any library, you must determine exactly which Display Driver is appropriate for your display device. In most cases this will be marked on the product page. In the case of the cheaper eBay knock-offs, it can sometimes be more challenging to determine this, especially because received parts don't always match the listing.
Display modules may also incorporate a resistive (res) or capacitive (cap) 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 analog 4-wire 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.
For a list of common displays and the recommended drivers, please refer to:
By convention, the Example Configurations are named as: (cpu)-(display_driver)-(display_controller)-(touch_controller)-cfg###.h.
At this time, the following example configs are provided:
| CPU | Display Driver | Touch Driver | Example Config | Notes |
|---|---|---|---|---|
| Arduino | ILI9341 | None | ard-adagfx-ili9341-notouch.h | |
| Arduino | ILI9341 | STMPE610 (res) | ard-adagfx-ili9341-stmpe610.h | |
| Arduino | ILI9341 | 4-wire (res) | ard-adagfx-ili9341-simple.h | |
| Arduino | ILI9341 | FT6206 (cap) | ard-adagfx-ili9341-ft6206.h | |
| Arduino | ILI9341 | GPIO | ard-adagfx-ili9341-input.h | |
| Arduino | ST7735 | None | ard-adagfx-st7735-notouch.h | |
| Arduino | SSD1306 | None | ard-adagfx-ssd1306-notouch.h | |
| Arduino | HX8357 | None | ard-adagfx-hx8357-notouch.h | |
| Arduino | HX8357 | STMPE610 (res) | ard-adagfx-hx8357-stmpe610.h | |
| Arduino | HX8357 | 4-wire (res) | ard-adagfx-hx8357-simple.h | |
| Arduino | HX8357 | FT6206 (cap) | ard-adagfx-hx8357-ft6206.h | |
| Arduino | PCD8544 | None | ard-adagfx-pcd8544-notouch.h | |
| Arduino | mcufriend | None | ard-adagfx-mcufriend-notouch.h | |
| Arduino | mcufriend | 4-wire (res) | ard-adagfx-mcufriend-simple.h | |
| Arduino | mcufriend | STMPE610 (res) | ard-adagfx-mcufriend-stmpe610.h | Coming soon |
| Arduino | mcufriend | FT6206 (cap) | ard-adagfx-mcufriend-ft6206.h | Coming soon |
- More examples will appear shortly...
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 Adafruit-GFX display library has been configured and runs correctly. If the Adafruit example code doesn't work, GUIslice will not work, so please don't skip this step!
In all cases, the Adafruit-GFX base graphics library needs to be installed first.
For example, if you are intending to use an ILI9341-based display, then open the Adafruit-ILI9341 graphics example:
- File → Examples → Adafruit ILI9341 → graphicstest
- Modify the
TFT_*pin settings in the sketch to match your shield connections or manual wiring 
- Confirm that the example successfully compiles and runs, showing a series of display patterns
- For more details, please refer to the Adafruit display library documentation (eg. Connecting Adafruit 2.8" Touch Shield)
- For any other devices, please locate the corresponding Adafruit display driver library and run its corresponding graphicstest sketch
If your display has been marked with "mcufriend" then please download and install David Prentice's MCUfriend_kbv library. After installing the library, please run the following example instead of the Adafruit examples:
- File → Examples → MCUFRIEND_kbv → diagnose_TFT_support
- Confirm that the example successfully compiles and runs, and reporting no errors on the serial monitor. The display should probably show a colored screen with a message like
ID=0x9341.
- Confirm that the example successfully compiles and runs, and reporting no errors on the serial monitor. The display should probably show a colored screen with a message like
- File → Examples → MCUFRIEND_kbv → graphicstest_kbv
- Confirm that the example successfully compiles and runs, showing a series of display patterns
- If either of the above sketches report errors, then please followup with the MCUfriend_kbv library for support. GUIslice will not work correctly unless these examples are working!
The GUIslice library supports a large number of microcontrollers and displays. The default library configuration in Arduino mode supports the Arduino UNO / ATmega2560 with an ILI9341 display and STMPE610 resistive touch controllers, for example: Adafruit 2.8" TFT Touch Shield for Arduino with Resistive Touch Screen.
If you are using this device and display combination, then no further changes should be required to run the examples that come with GUIslice. Otherwise, read on for the changes needed to adapt for other device combinations.
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.
If you are using a display shield, then the pinout wiring between the microcontroller and the display is hardcoded, making it much easier to ensure proper configuration and setup. In fact, a few of the more common display combinations are provided as canned example configurations within GUIslice. If the display is not a shield, then care must be taken to note that the wiring and GUIslice's ADAGFX_PIN_* configuration matches.
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
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).
If you are using a shield, the example configuration pinouts may be adequate as-is. However, for any custom wiring, it is essential that the configuration matches your wiring pinout.
- In the Adafruit example run in Step 2, look for the line that instantiates the Adafruit display (such as Adafruit_ILI9341):
- Note the settings on
TFT_DC,TFT_CS, etc. that worked earlier. Copy these same values to the GUIslice_config_ard.h'sADAGFX_PIN_*settings: 
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.
- 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. 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.
In the case of Arduino devices, available RAM is very limited. Therefore, it is recommended that debug messages are disabled once the devices and basic examples are running as expected. To disable debug messaging, look for a DEBUG_ERR line in the config and change it from 1 (enabled) to 0 (disabled).
It is important to note that Arduino devices based on the ATmega328P microcontroller (such as Arduino UNO, Arduino Pro Mini, etc.) are extremely limited in the amount of memory (RAM) that they provide, 2KB! In order to enable GUIs to work on these devices, it is recommended to use the GUIslice Flash-based Elements otherwise it is likely that you will encounter compiler errors indicating Not enough memory.
- For more details, please see GUIslice on low-memory Arduino Devices
- Examples designed for low-memory operation are located in:
/examples/arduino_min/
This section will be added soon