Configure GUIslice for ARM Cortex
Overview > Configuring GUIslice >
This guide describes the steps to configure the GUIslice library for Microchip / ARM Cortex and related devices
- Adafruit Feather M0 (Microchip ATSAMD21G18 Cortex M0)
- Adafruit Metro M4 (Microchip ATSAMD51 Cortex M4)
- Adafruit Feather nRF52 Bluefruit LE (nRF52 / nRF52832 / Cortex M4F)
- The following devices ship with CircuitPython but may work from Arduino IDE
- Adafruit Feather M4 Express (Microchip ATSAMD51 Cortex M4)
- Adafruit ItsyBitsy M4 Express (Microchip ATSAMD51 Cortex M4)
Note: STM32 (ARM Cortex M3) should use the STM32 Config Guide instead (coming soon).
For ARM Cortex 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.
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 | ST7735 | None | ard-adagfx-st7735-notouch.h |
Coming soon |
| Arduino | SSD1306 | None | ard-adagfx-ssd1306-notouch.h |
Coming soon |
| 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 |
Coming soon |
| 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 → graphicstest_kbv
- 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.
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 low memory ARM Cortex devices, available RAM may be limited. Therefore, it may be worth disabling debug messages 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).
This section will be added soon