Configure GUIslice for M5stack
Overview > Configuring GUIslice >
This guide describes the steps to configure the GUIslice library for the M5stack:
- M5stack (ESP-32)
For M5stack, GUIslice is typically built within the Arduino IDE.
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 (automatically enabled in the sample config: esp-shld-m5stack).
At this time, the following example configs are provided:
| CPU | Display Driver | Touch Driver | Example Config | Notes |
|---|---|---|---|---|
| M5stack | M5stack | 3-button | esp-shld-m5stack |
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
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 M5stack library 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 M5stack 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 the integrated M5stack device, the following shield config is used:
esp-shld-m5stack.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 test the button handling.
NOTE: The M5stack does not support a touchscreen, so the following guidance is specific to the integrated button handling instead.
- 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.
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);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.
This section will be added soon