Skip to content

Config Mode Details

Jump to bottom Edit New page
Calvin Hass edited this page Feb 3, 2019 · 4 revisions

Overview > Configuring GUIslice >

This page provides some additional detail behind the various options available in the GUIslice_config files. Please note that some of this content may be somewhat out-of-date and is subject to revision.

Table of Contents

Configuring GUIslice_config_*.h

There a number of settings that must be configured in order for GUIslice to access your display hardware. While reasonable defaults have been provided, settings such as pin selection and driver selection will need modification.

All user-configurable settings are located in the GUIslice_config_*.h files. A separate user configuration file is provided for LINUX (GUIslice_config_linux.h) and Arduino (GUIslice_config_ard.h) platforms. The GUIslice_config.h is responsible for selecting the appropriate configuration file based on the detected device type.

The majority of settings are configured via #define assignments. Modify this config file to match your CPU, display and board settings.

General Device Mode Selection

A wide range of devices have been tested with GUIslice. Although a variety of examples and graphics drivers have been developed to support these devices, not all are applicable to every device. The following table lists the examples and available graphics drivers that are recommended for a given device:

From the above table, we can see that, when using an ESP8266 device, the /arduino examples should be used and that the DRV_DISP_TFT_ESPI graphics drivers is recommended (as indicated by dark green). The DRV_DISP_ADAGFX graphics driver is also available, but is less optimized for performance (indicated by light green).

Example Configurations

GUIslice sample configurations:

  • Please refer to the /docs/GUIslice_config_guide.xlsx Excel spreadsheet for some sample configurations using variety of device, screen and driver modes
  • GUIslice Config Spreadsheet (click on Download or View Raw to open the Excel file)

Config graphics library

The graphics library provides an interface for user code to the underlying graphics hardware. Some graphics libraries include advanced drawing capabilities while others are just wrappers to other hardware-specific libraries. In the config file, only one DRV_DISP_* should be enabled. The following graphics libraries are supported:

  • #define DRV_DISP_SDL1
    • Intended for Raspberry Pi / LINUX: This enables GUIslice to use the SDL1.2 graphics library. This option is best suited for framebuffer-based displays.
    • SDL1.2 must be installed. See Installing SDL. Typically involves the following:
      • sudo apt-get install libsdl1.2-dev
      • sudo apt-get install libsdl-ttf2.0-dev
  • #define DRV_DISP_SDL2
    • Intended for Raspberry Pi / LINUX: This enables GUIslice to use the SDL2.0 graphics library. This option is best suited for enabling hardware acceleration but may require using a framebuffer mirror (fbcp) to support framebuffer-based displays.
    • SDL2.0 must be installed. See Installing SDL. Typically involves the following:
      • sudo apt-get install libsdl2-dev
      • sudo apt-get install libsdl2-ttf-dev
    • Note that in order to provide hardware accelerated support without Xwindows, it may be necessary to compile SDL2 directly. Walkthrough commands coming soon.
  • #define DRV_DISP_ADAGFX
    • Intended for Arduino: This enables GUIslice to use the Adafruit-GFX graphics library. Note that the Adafruit-GFX library is a wrapper around a number of other display hardware libraries (specified by DRV_DISP_ADAGFX_*)
  • #define DRV_DISP_TFT_ESPI
    • Intended for ESP8266 / ESP32: This enables GUIslice to use Bodmer's TFT_eSPI optimized graphics library.
  • #define DRV_DISP_M5STACK
    • Intended for M5Stack: This enables GUIslice to use the M5Stack graphics library. Note that M5Stack is based on the ESP32 device.

Config display hardware

Depending on the display hardware (TFT, LCD, OLED, etc.) connected, you may need to specify the additional settings or library options to match the display driver chip on the board.

Configuring display hardware for SDL

Config setting: DRV_DISP_SDL1 or DRV_DISP_SDL2

In order to use SDL, a number of LINUX device settings must be configured. A typical setup would include all of the following:

  • #define GSLC_DEV_FB "/dev/fb1"
    • This defines the framebuffer that SDL will be writing into. Typically set to fb1 but could also be fb0. Most framebuffer-based displays (such as PiTFT) work with fb1.
  • #define GSLC_DEV_TOUCH "/dev/input/touchscreen"
    • This defines the touch input device that SDL uses. Note that more reliable touchscreen tracking may be possible when using an external touch driver such as tslib instead of SDL (see below).
  • #define DRV_SDL_FIX_START 0
    • Unfortunately, the SDL1.2 library (outside of GUIslice) has a bug/sensitivity in how it handles programs "cleaning up" after themselves. If a program aborts without cleaning up nicely first, the graphics display may appear to be hung. GUIslice provides an optional workaround (enabled by #define DRV_SDL_FIX_START 1) that attempts to unlock any cases where SDL didn't clean up the terminal from the previous execution.
    • Warning: while this workaround often appears to work on Raspberry Pi, it does appear to cause a crash on other systems (such as in Ubuntu LINUX VM). Therefore, it is not recommended to enable this workaround mode unless it appears stable in your system. Recommendation: #define DRV_SDL_FIX_START 0

Configuring display hardware for Adafruit-GFX

Config setting: DRV_DISP_ADAGFX

The specific display hardware must be selected to match the onboard driver chip. The currently supported hardware libraries are listed below. Include one of the following defines in your code and comment out the rest.

  • #define DRV_DISP_ADAGFX_ILI9341
    • GUIslice uses the Adafruit-ILI9341 library to access a display using the ILI9341 driver chip. You can either install "Adafruit ILI9341" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_DISP_ADAGFX_ILI9341_8BIT
    • GUIslice uses the Adafruit-ILI9341 library (in 8-bit/parallel mode) to access a display using the ILI9341 driver chip. You can either install "Adafruit ILI9341" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_DISP_ADAGFX_SSD1306
    • GUIslice uses the Adafruit-SSD1306 library to access a display using the SSD1306 driver chip. You can either install "Adafruit SSD1306" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_DISP_ADAGFX_ST7735
    • GUIslice uses the Adafruit-ST7735 library to access a display using the ST7735 driver chip. You can either install "Adafruit ST7736" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_DISP_ADAGFX_HX8357
    • GUIslice uses the Adafruit-HX8357 library to access a display using the HX8357 driver chip. You can either install "Adafruit HX8357" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_DISP_ADAGFX_PCD8544
    • GUIslice uses the Adafruit-PCD8544 library to access a display using the PCD8544 driver chip. You can either install "Adafruit PCD8544" directly from the Arduino IDE Library Manager or download from GitHub.
See the table below for the appropriate DRV_DISP_ADAGFX_* line to define.

In addition to the graphics chip selection, the physical pin connections must be selected to match the breakout board / shield. These are specified by #define ADAGFX_PIN_*. ...

Support for an external SPI-based SD card reader is enabled by #define ADAGFX_SD_EN 1. Note that inclusion of the SD card support consumes considerable flash and SRAM memory which may make it unsuitable for smaller Arduino CPUs (should work fine on ATmega2560, for example).

Configuring display hardware for TFT_eSPI

Config setting: DRV_DISP_TFT_ESPI

When using the TFT_eSPI graphics library, the detailed configuration (including pin connections) are defined that library's User_Setup.h file. Please refer to the TFT_eSPI for more details and examples.

Config touch hardware

A touchscreen display often incorporates a separate graphics driver chip from the touchscreen chip. Some touch driver chips support resistive displays while others support capacitive displays. If the display does not include touch support, it is possible to run GUIslice with no touch driver. Touch libraries are specified by uncommenting a single DRV_TOUCH_* in the config file.

Configuring touch hardware for Arduino

It is important to select the mode that matches the touch driver chip on the board. At this time, the following touch driver modes are supported for Arduino. Include one of the following defines in your code and comment out the rest:

  • #define DRV_TOUCH_NONE
    • GUIslice does not enable touchscreen functionality
  • #define DRV_TOUCH_ADA_STMPE610
    • GUIslice uses the Adafruit-STMPE610 library to access the touch input using the STMPE610 driver chip. You can either install "Adafruit STMPE610" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_TOUCH_ADA_FT6206
    • GUIslice uses the Adafruit-FT6206 library to access the touch input using the FT6206 driver chip. You can either install "Adafruit FT6206" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_TOUCH_TFT_ESPI
    • GUIslice uses the TFT_eSPI library to access the touch input using the XPT2046 driver chip. This driver is included in the installation of "TFT_eSPI" directly from the Arduino IDE Library Manager or download from GitHub.
  • #define DRV_TOUCH_SIMPLE
    • GUIslice uses the Touch-Screen-Libraryto access the touch input using the 4-wire resistive touch driver. You can install directly from GitHub.

Configuring touch hardware for Raspberry Pi / LINUX

When using Raspberry Pi, you have two options for touch driver support: native SDL or tslib (libts). In the config file, add the appropriate defines according to the driver selected:

  • Native SDL:
    • #define DRV_TOUCH_SDL
    • #define DRV_TOUCH_IN_DISP 1
  • tslib:
    • #define DRV_TOUCH_TSLIB
    • Also ensure that the environment variable paths have been set correctly in your program. Please refer to the `UserInitEnv()` function in the GUIslice example programs.

Configuring touch hardware for Adafruit STMPE610

Set one of the following to 1 and the remainder to 0:

  • #define ADATOUCH_I2C_HW 1: Use I2C hardware interface.
    • Specify the I2C address with #define ADATOUCH_I2C_ADDR 0x41 (change 0x41 to match your device)
  • #define ADATOUCH_SPI_HW 1: TODO - Use SPI hardware interface
  • #define ADATOUCH_SPI_SW 1: TODO - Use SPI software interface

Configuring touch hardware for Adafruit FT6206

Only one parameter is required for the FT6206 touch driver:

  • #define ADATOUCH_SENSITIVITY 40: Define the sensitivity of the capacitive touch display

General Configuration

A few configuration options are common to all graphics modes. ...

  • #define GSLC_LOCAL_STR 1
  • #define GSLC_LOCAL_STR_LEN 20
  • #define GSLC_BMP_TRANS_EN 1
  • #define GSLC_BMP_TRANS_RGB 0xFF,0x00 0xFF

Display hardware drivers

When interfacing with an external display, it is important to know what graphics controller IC (or driver chip) is used by the breakout board or shield. Here are a few examples:

Driver Chip Display hardware lib
Config #define 		Devices Supported by GUIslice? Tested?
ILI9341 DRV_DISP_ADAGFX_ILI9341 Yes Yes
SSD1306 DRV_DISP_ADAGFX_SSD1306 Yes Yes
PCD8544 ? ? No
ST7735S DRV_DISP_ADAGFX_ST7735 Yes Yes

Board Pinout Connections

The GUIslice_config_ard.h file has a section that specifies the pin mapping between the CPU and the display board. These will need to be customized for your particular devices. The following describes a number of example setups for boards and CPUs that have been tested.

For a more complete listing, please refer to the GUIslice Config Spreadsheet

Board Configuration for Raspberry Pi

No specific board configuration is required for SDL.

Board Configuration for Arduino / Feather

Shield Connections

  • Adafruit 2.8" Touch Shield
  #define ADAGFX_PIN_CS    10
  #define ADAGFX_PIN_DC     9
  #define ADAGFX_PIN_RST    0
  #define ADAGFX_PIN_MOSI
  #define ADAGFX_PIN_MISO
  #define ADAGFX_PIN_CLK
  #define ADAGFX_PIN_SDCS   4

Breakout board Connections

Breakout boards don't require a specific set of pin connections. Nonetheless, not all CPU pins are available. The following are some example pin assignments that have been tested to work:

  • Adafruit 2.2" TFT Breakout -> Arduino Pro Mini 
  #define ADAGFX_PIN_CS    10
  #define ADAGFX_PIN_DC     9
  #define ADAGFX_PIN_RST    8
  #define ADAGFX_PIN_MOSI
  #define ADAGFX_PIN_MISO
  #define ADAGFX_PIN_CLK
  #define ADAGFX_PIN_SDCS   4
  • Adafruit 2.2" TFT Breakout -> ATmega2560 
  #define ADAGFX_PIN_CS    53
  #define ADAGFX_PIN_DC    47
  #define ADAGFX_PIN_RST   49
  #define ADAGFX_PIN_MOSI
  #define ADAGFX_PIN_MISO
  #define ADAGFX_PIN_CLK
  #define ADAGFX_PIN_SDCS  48
  • Adafruit 2.2" TFT Breakout -> Feather M0 
  #define ADAGFX_PIN_CS    10
  #define ADAGFX_PIN_DC     9
  #define ADAGFX_PIN_RST   11
  #define ADAGFX_PIN_MOSI
  #define ADAGFX_PIN_MISO
  #define ADAGFX_PIN_CLK
  #define ADAGFX_PIN_SDCS   4
Add a custom footer
Clone this wiki locally