ESPUI

ESPUI is a simple library to make a web-based user interface for your projects using the ESP8266 or the ESP32 It uses web sockets and lets you create,

ol, and update elements on your GUI through multiple devices like phones and tablets.

ESPUI uses simple Arduino-style syntax for creating a solid, functioning user interface without too much boilerplate code.

So if you either don't know how or just don't want to waste time: this is your simple solution user interface without the need of internet connectivity or any additional servers.

The Library runs on any kind of ESP8266 and ESP32 (NodeMCU, AI Thinker, etc.).

• Dependencies
• How to Install
• Getting started
• UI Elements
  • Button
  • Switch
  • Buttonpad
  • Labels
  • Slider
  • Number Input
  • Text Input
  • File Display
  • Date, Time, Colour and Password Input
  • Select control
  • Getting the Time
  • Separators
• Initialisation of the UI
• Tabs
• Log output
• Colours
• Advanced Features
  • Dynamic Visibility
  • Inline Styles
  • Disabling Controls
  • Grouped controls
  • Wide controls
  • Graph (Experimental)
  • Captive Portal
• Notes for Development
• Contribute

Contributed features

• Tabs by @eringerli
• Generic API by @eringerli
• Min Max on slider by @eringerli
• OptionList by @eringerli
• Public Access to ESPAsyncServer
• Inline CSS styles by @iangray001
• Separators by @iangray001
• Grouped and wide controls by @iangray001
• Transport layer rework by @iangray001
• Time control by @iangray001
• Vertical controls by @iangray001
• Time/date/password/color input types by @pcbbc
• Delayed response support @MartinMueller2003
• Fragmented control transfer @MartinMueller2003
• Extended Callback @MartinMueller2003
• Added a file display element @MartinMueller2003

Roadmap

• Fully implement graphs
• Expand number input features (floats etc.)
• Support for enabling and disabling controls

Dependencies

This library is dependent on the following libraries.

• ESPAsyncWebserver

• ArduinoJson (Last tested with version 6.10.0)

• (For ESP8266) ESPAsyncTCP

• (For ESP32) AsyncTCP

• (For ESP32) lorol/LittleFS_esp32

How to Install

Make sure all the dependencies are installed, then install like so:

Using PlatformIO (recommended)

Just include this library as a dependency in lib_deps like so:

lib_deps =
    ESPUI
    ESP Async WebServer
    ESPAsyncTCP # (or AsyncTCP on ESP32)
    LittleFS_esp32 # (ESP32 only)

Using the Arduino IDE (recommended)

You can find this Library in the Arduino IDE library manager. Go to Sketch > Include Library > Library Manager search for ESPUI and install.

If you cannot use the Library Manager, you can download the repository and follow the instructions to manually install libraries.

Getting started

ESPUI serves several files to the browser to build up its web interface. This can be achieved in 2 ways: PROGMEM or LITTLEFS

When ESPUI.begin() is called the default is serving files from Memory and ESPUI should work out of the box!

OPTIONAL: But if this causes your program to use too much memory you can burn the files into the LITTLEFS filesystem on the ESP. There are now two ways to do this: you can either use the ESP file upload tool or you use the library function ESPUI.prepareFileSystem()

Simple filesystem preparation (recommended)

Just open the example sketch prepareFileSystem and run it on the ESP, (give it up to 30 seconds, you can see the status on the Serial Monitor), The library will create all needed files. Congratulations, you are done, from now on you just need to do this again when there is a library update, or when you want to use another chip :-) Now you can upload your normal sketch, when you do not call the ESPUI.prepareFileSystem() function the compiler will strip out all the unnecessary strings that are already saved in the chip's filesystem and you have more program memory to work with.

User interface Elements

• Label
• Button
• Switch
• Control pad
• Slider
• Text Input
• Date, Time, Colour and Password Input
• Numberinput
• Option select
• Separator
• Time
• Graph (partial implementation)
• File Display

Documentation

The heart of ESPUI is ESPAsyncWebserver. ESPUI's frontend is based on Skeleton CSS and jQuery-like lightweight zepto.js for handling events. The communication between the ESP and the client browser works using web sockets. ESPUI does not need network access and can be used in standalone access point mode, all resources are loaded directly from the ESPs memory. <br><br> This section will explain in detail how the Library is to be used from the Arduino code side. In the arduino setup() routine the interface can be customised by adding UI Elements. This is done by calling the corresponding library methods on the Library object ESPUI. Eg: ESPUI.button("button", &myCallback); creates a button in the interface that calls the myCallback(Control *sender, int eventname) function when changed. All buttons and items call their callback whenever there is a state change from them. This means the button will call the callback when it is pressed and also again when it is released. To separate different events, an integer number with the event name is passed to the callback function that can be handled in a switch(){}case{} statement. <br><br> Alternativly you may use the extended callback funtion which provides three parameters to the callback function myCallback(Control *sender, int eventname, void * UserParameter). The UserParameter is provided as part of the ESPUI.addControl method set and allows the user to define contextual information that is to be presented to the callback function in an unmodified form. <br><br> It also possible to use a lambda function in the callback parameter. It also allows the user to define, in a more C++ way, contextual information in any form. This is shown by the completeLambda example. <br><br> The below example creates a button and defines a lambda function to invoke a more specialized button callback handler:

void YourClassName::setup()
{
  ButtonElementId = ESPUI.addControl(
  ControlType::Button,
  ButtonLabel.c_str(),
  " Button Face Text ",
  ControlColor::None,
  ParentElementId,
  [&](Control *sender, int eventname)
  {
    myButtonCallback(sender, eventname); // class method
  });

  // or
  ButtonElementId = ESPUI.button(
  " Button Face Text ",
  [&](Control *sender, int eventname)
  {
    myButtonCallback(sender, eventname); // class method
  });
}

void YourClassName::myButtonCallback(Control* sender, int eventname)
{
  if (eventname == B_DOWN)
  {
    // Handle the button down event
  }
  else if (eventname == B_UP)
  {
    // Handle the button up event
  }
}

<br> <br> #### Button

Buttons have a name and a callback value. Their text can be changed at runtime using ESPUI.updateButton().

Events:

• B_DOWN - Fired when button is pressed.
• B_UP - Fired when button is released.

Switch

Switches sync their state on all connected devices. This means when you change their value (either by pressing them, or programmatically using ESPUI.updateSwitcher()) they change visibly on all tablets or computers that currently display the interface.

Events:

• S_ACTIVE - Fired when turning on.
• S_INACTIVE - Fired when turning off.

Buttonpad

Button pads come in two flavours: with or without a center button. They are useful for controlling movements of vehicles/cameras etc. They use a single callback per pad and have 8 or 10 different event types to differentiate the button actions.

• P_LEFT_DOWN
• P_LEFT_UP
• P_RIGHT_DOWN
• P_RIGHT_UP
• P_FOR_DOWN
• P_FOR_UP
• P_BACK_DOWN
• P_BACK_UP
• P_CENTER_DOWN
• P_CENTER_UP

Labels

Labels are used to display textual information (i.e. states, values of sensors, configuration parameters etc.). To send data from the code use ESP.updateLabel() . Labels get a name on creation and a initial value.

Labels automatically wrap your text. If you want them to have multiple lines use the normal <br> tag in the string you print to the label.

In fact, because HTML can be used in the label's value, you can make a label display images by including an <img> tag.

 ESPUI.label("An Image Label", ControlColor::Peterriver, "<img src='path/to/image'>");

This requires that the client has access to the image in question, either from the internet or a local web server.

Slider

Sliders can be used to select (or display) a numerical value. Sliders provide realtime data and are touch compatible. Note that like all ESPUI functions, the callback does not return an int but a `