Configure GUIslice for M5stack

This guide describes the steps to configure the GUIslice library for the M5stackL

• M5stack (ESP-32)

Target Build Environment

For M5stack, GUIslice is typically built within the Arduino IDE.

Step 1: Select display and touch driver for your display

For M5stack, the display is fixed, and so we will be configuring GUIslice to enable the following display driver: DRV_DISP_M5STACK.

While the M5stack's integrated display doesn't support touch, the device does include 3 built-in push buttons. GUIslice can support GUI element navigation with these buttons by enabling the following touch driver: DRV_TOUCH_M5STACK. Note: If no touch support is required, a DRV_TOUCH_NONE setting can be used instead.

Step 2: Confirm display works with standalone driver examples

Before attempting to run GUIslice, it is essential that the standalone graphics example included in the M5stack library runs correctly. If the M5stack example code doesn't work, GUIslice will not work, so please don't skip this step!

The M5stack must be installed first. For details on M5stack installation please refer to: M5stack Quick Start Guide

Open up the graphics test example for M5stack:

• File → Examples → M5stack → Advanced → Display → graphicstest_one_lib
• Confirm that the example successfully compiles and runs, showing a series of display patterns

Step 3: Locating GUIslice_config_ard.h

GUIslice expects to read configuration settings from the following location: GUIslice/src/GUIslice_config_ard.h

The developers of the Arduino IDE aimed to make it as easy as possible for beginners, but the downside is that advanced libraries such as GUIslice require an extra step in order to override a library's configuration defaults.

Locate the GUIslice library within the Arduino libraries folder. The libraries folder is located within the Arduino IDE sketchbook directory. To find your sketchbook directory, select File → Preferences in the Arduino IDE and look for the "Sketchbook location" (eg. C:\Users\<username>\Documents\Arduino). The libraries folder will be a folder with the same name inside the Sketchbook folder.

• 
• Typically the libraries folder would therefore be:
• C:\Users\<username>\Documents\Arduino\libraries (for Windows)

Within the Arduino libraries folder, you should find the GUIslice library that you installed earlier. It will either be named GUIslice or GUIslice-master, depending on whether you used the Arduino IDE Library Manager or manually downloaded the latest version from GitHub.

The configuration file (GUIslice_config_ard.h) is located within the \src folder within the GUIslice library folder. It is important to confirm that you can locate this file so that modifications can be made later. For example, the full path to this config file may be:

• C:\Users\<username>\Documents\Arduino\libraries\GUIslice-master\src\GUIslice_config_ard.h

It is recommended to make a backup copy of your original GUIslice_config_ard.h file before making changes (although one can always download a new copy from the repository later if needed).

Note about setting GUIslice Config modes

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.

Step 4: Update GUIslice config for display & pinout

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 M5stack is a fully integrated device, there is no wiring / pinout to be configured within GUIslice. An example config file has been created for M5stack.

Using included Example Configuration

Look in the GUIslice /configs directory for the cfg032-m5stack.h configuration file. Copy this file over top of the default GUIslice_config_ard.h file in the library's /src folder from Step 3. The easiest way to do this is:

• Rename the existing GUIslice_config_ard.h file to GUIslice_config_ard.h.bak
• Copy the example config cfg032-m5stack.h into the /src folder (which had the GUIslice_config_ard.h file)
• Rename the example config to GUIslice_config_ard.h

Step 5: Test Basic GUIslice Display Operation

Now that we have the basic driver and display settings configured, it is time to test the basic operation of the GUIslice library.

Run Display Example

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:
• 

Step 6: Test Basic GUIslice Touch Operation

If the above display test works properly, then it is time to test the button handling.

Run Touch Example

• In the Arduino IDE, open up the ex23_m5_input_btn example:
• File → Examples → GUIslice → arduino → ex23_m5_input_btn
• Upload and confirm that the physical push-buttons respond to presses and navigate through the display.

Step 7: Run other GUIslice Examples

If the display and touch appear to be working correctly, experiment by loading up the other examples provided with GUIslice. For the M5stack, these can be loaded from the Arduino IDE under:

• File → Examples → GUIslice → arduino → ex01_ard_* (normal memory examples)

In the repository, the above examples are located in the /examples/ directory.

Note Regarding Touch on M5stack

The majority of GUIslice examples were written for a touch-enabled display. As the M5stack does not include a touchscreen, most of the examples will display a GUI but not respond to the push-button presses. Example ex23 above demonstrates how the addition of a few lines of code can add GUI navigation by push-button to any of the other examples.

In most cases, updating an example to support push-button control can be done by adding an input map global as well as calling the InputMap* functions to configure the button-to-GUI mapping.

  #define MAX_INPUT_MAP       3
  gslc_tsInputMap m_asInputMap[MAX_INPUT_MAP];
  ...
  // Create the GUI input mapping (pin event to GUI action)
  gslc_InitInputMap(&m_gui, m_asInputMap, MAX_INPUT_MAP);
  gslc_InputMapAdd(&m_gui, GSLC_INPUT_PIN_ASSERT, GSLC_PIN_BTN_A, GSLC_ACTION_FOCUS_PREV, 0);
  gslc_InputMapAdd(&m_gui, GSLC_INPUT_PIN_ASSERT, GSLC_PIN_BTN_B, GSLC_ACTION_SELECT, 0);
  gslc_InputMapAdd(&m_gui, GSLC_INPUT_PIN_ASSERT, GSLC_PIN_BTN_C, GSLC_ACTION_FOCUS_NEXT, 0);

Step 8: Customize GUIslice Configuration

This section will be added soon