MicroGUI Embedded

Open-source Arduino library for deploying GUIs created with MicroGUI on embedded displays.
Explore the docs »

Report Bug · Request Feature

About The Project

The main purpose of MicroGUI is to offer a convenient solution for makers to implement touch displays in their embedded projects. This library is supposed to be used together with the web application to enable rapid prototyping of your own GUI.

MicroGUI-Embedded takes care of making your GUI work on embedded displays with minimal coding from your part, so that you can focus on the project at hand instead of having to learn how to program displays. You will also be able to monitor and control your displays remotely by connecting them to your WiFi with the MicroGUI Remote extension. Read more about this in the following sections.

(back to top)

Features

MicroGUI-Embedded Core

• Easily render a GUI created with the MicroGUI web application
• Provides a touch interface to GUI objects
• Allows for event-driven main sketch
• Very little boilerplate code needed to get started

MicroGUI-Embedded Remote extension

• Remote monitoring & control of GUI
• Rendering remotely uploaded GUIs on the fly
• Non-blocking WiFi handling
• Automatic connection to known WiFi network
• Custom light-weight captive portal for entering WiFi network credentials

(back to top)

Prerequisites

• Any of the below listed embedded displays:

  • WT32-SC01

• IDE (Integrated Development Environment)

  • It is recommended to use the PlatformIO extension for VS Code to program your embedded display for use with MicroGUI. The installation instructions below are for PlatformIO, but you can install this library in Arduino IDE as well if you would prefer that.

Installation

The instructions in this installation guide are for PlatformIO

Note: These instructions are specific to the WT32-SC01 display. As more displays are supported by MicroGUI in the future, this section will most likely change.

PlatformIO registry

MicroGUI-Embedded is now available from the PlatformIO registry! Click the badge below to learn how to add the library to your project.

Or simply follow the guides below.

New project

1. Create a new PlatformIO project and select Espressif ESP32 Dev Module as development board. Make sure that Arduino is set as framework. For detailed instructions, look here.
2. Open the platformio.ini and paste the following:

    [env:esp32dev]
    platform = https://github.com/platformio/platform-espressif32.git
    board = esp32dev
    framework = arduino
    platform_packages = framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32#master
    upload_speed = 921600
    monitor_speed = 115200
    lib_deps = microgui/MicroGUI Embedded@^1.1.0

   This makes sure that you use the latest Arduino core for the ESP32 as well as adds MicroGUI-Embedded to the list of library dependencies.
3. That should be all, have fun!

Existing project

1. Simply add MicroGUI-Embedded to your library dependencies, like this:

    lib_deps = microgui/MicroGUI Embedded@^1.1.0

2. Done, enjoy!

Absolute latest changes

If for some reason you would like the latest changes committed to the library repository instead of the latest release, then add this as a library dependency instead of the above:

    lib_deps = https://github.com/microgui/MicroGUI-Embedded.git

(back to top)

Tutorial

One of the many beauties of MicroGUI 😉 is the fact that you DO NOT have to touch any code to get started with making and testing your GUIs. Sure, you have to copy & paste some code as well as upload it to your display, but you don't have to do any coding yourself. Follow the steps below to see how easy MicroGUI is to use.

First test

After you've installed both the MicroGUI web application and this library, you are set to create and deploy GUIs.

However, as a quick first test to see that the library installation was successful, copy the template below into your main sketch. Hit upload and wait for it to finish. The default GUI should appear prompting you to continue reading the tutorials.

Default GUI

This is the GUI which is rendered by default.

Template

This is all the boilerplate code needed to run MicroGUI Embedded. You can continue using this template as a base for any new projects you create with MicroGUI.

#include <MicroGUI.h>
//#include <RemoteMicroGUI.h>     // Uncomment if you want to use MicroGUI Remote features

void setup() {
  //Serial.begin(115200);         // Recommended! MicroGUI will print useful messages

  mgui_init();
  //mgui_remote_init();           // Uncomment if you want to use MicroGUI Remote features
}

void loop() {
  MGUI_event * latest = mgui_run();
}

Second test

After you've seen that this works, test the MicroGUI Remote features by uncommenting the commented out lines of the template. Once the display is programmed you will be presented with the same default GUI except for this time you will see a red border indicating that the display is not connected to any WiFi network. The display is now in AP (access point) mode, meaning you can connect to it like any other WiFi network.

When you connect to the display's AP, either with your computer or mobile phone, you will be served a captive portal where you can enter WiFi network credentials for the display to connect to. Note: If the captive portal does not appear, browse to http://192.168.4.1/ to enter the same portal for entering your WiFi network credentials.

Once you've entered your WiFi network credentials and click the 'Submit' button, the display will start trying to connect to the provided network. If successful, the display will switch to stationary mode, meaning the access point closes.

At this point, you are ready to use MicroGUI Remote features including remote monitoring and control as well as GUI upload which you can find in the web application. Your display's IP adress will be displayed on the screen.

Captive portal

(back to top)

Examples

The examples located in the "examples" folder are there to demonstrate how MicroGUI can be used.

In order to test an example, simply copy the example code into your own main sketch and upload it to your display.

Example 1

Example 2

Simple home automation interface

(back to top)

User API

Short explanations of all user available MicroGUI functions. Have a look at the examples to better understand how and where to use them.

MicroGUI Core

The "Core" API documentation is a reference to functions available to the user in the MicroGUI Embedded library without any other MicroGUI extensions.

Initialization of MicroGUI

There are three ways of initializing MicroGUI Embedded to allow for either more or less advanced usage of the library.

Without any parameters

This will render either a GUI stored in flash or the default GUI if flash is empty.

void mgui_init();

With a hard-coded GUI stored as a string

Initializing like this will always render the hard-coded GUI on reboot.

void mgui_init(char json[]);

With a hard-coded GUI stored as a string & setting display orientation

This gives the option of setting display orientation.

void mgui_init(char json[], int rotation);

There are four different orientations in which the display can be set in. It is recommended to use this typedef:

typedef enum {
  MGUI_PORTRAIT,
  MGUI_LANDSCAPE,
  MGUI_PORTRAIT_FLIPPED,
  MGUI_LANDSCAPE_FLIPPED  
}MGUI_orientation;

Example:

char json[] = "...{MicroGUI JSON string}...";
mgui_init(json, MGUI_LANDSCAPE_FLIPPED);

MicroGUI Run

Takes care of updating the GUI.

This needs to be placed inside of the loop in order for the GUI to update. The function returns an object pointer to an MGUI_event, which holds information on which object triggered the event, an event id/type as well as a value associated with the event. Take care of this event to make stuff happen on display events.

MGUI_event * mgui_run();

Compare two strings

Compares two strings and returns true if they have the same content. Useful for taking care of MGUI events, see examples.

bool mgui_compare(const char * string1, const char * string2);

Setting a value to an on-screen object

void mgui_set_value(const char * obj_name, int value);

Setting the text of a label/textfield

void mgui_set_text(const char * obj_name, const char * text);

Getting the value to an on-screen object

int mgui_get_value(const char * obj_name);

(back to top)

MicroGUI Remote

The "Remote" API documentation is a reference to functions available to the user in the MicroGUI Remote extension.

Initialization of MicroGUI Remote extension

Without any parameters

No hard-coded WiFi credentials.

void mgui_remote_init();

With the name of a label

No hard-coded WiFi credentials. Will set a label/textfield to show the display's IP address.

void mgui_remote_init(const char * textfield);

With hard-coded WiFi credentials

Works great if you are 100% certain of the available WiFi networks wherever you are putting your display. Will always try to connect to this network on reboot.

void mgui_remote_init(const char * ssid, const char * password);

With hard-coded WiFi credentials and the name of a label

Hard-coded WiFi credentials and sets a label/textfield to show the display's IP address.

void mgui_remote_init(const char * ssid, const char * password, const char * textfield);

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.md for more information.

(back to top)