Repository files navigation

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

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

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

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

The Library runs on any kind ofESP8266 andESP32 (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

• 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

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

This library is dependent on the following libraries.

• ESPAsyncWebserver

• ArduinoJson (Last tested withversion 6.10.0)

• (For ESP8266)ESPAsyncTCP

• (For ESP32)AsyncTCP

• (For ESP32)lorol/LittleFS_esp32

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

Just include this library as a dependency inlib_deps like so:

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

You can find this Library in the Arduino IDE library manager. Go toSketch > Include Library > Library Manager search forESPUI and install.

If you cannot use the Library Manager, you can download therepository and followtheinstructions to manually install libraries.

ESPUI serves several files to the browser to build up its web interface. Thiscan be achieved in 2 ways:PROGMEM orLITTLEFS

WhenESPUI.begin() is called the default is serving files from Memory andESPUI should work out of the box!

OPTIONAL: But if this causes your program touse too much memory you canburn the files into the LITTLEFS filesystem on the ESP. There are now two ways todo this: you can either use the ESP file upload tool or you use the libraryfunctionESPUI.prepareFileSystem()

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

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

The heart of ESPUI isESPAsyncWebserver. ESPUI's frontend is based onSkeleton CSS and jQuery-like lightweightzepto.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.

This section will explain in detail how the Library is to be used from the Arduino code side. In the arduinosetup() routine the interface can be customised by adding UI Elements. This is done by calling the corresponding library methods on the Library objectESPUI. Eg:ESPUI.button("button", &myCallback); creates a button in the interface that calls themyCallback(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 aswitch(){}case{} statement.

Alternativly you may use the extended callback funtion which provides three parameters to the callback functionmyCallback(Control *sender, int eventname, void * UserParameter). TheUserParameter is provided as part of theESPUI.addControl method set and allows the user to define contextual information that is to be presented to the callback function in an unmodified form.

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 thecompleteLambda example.

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  }}

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

Events:

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

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

Events:

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

Button pads come in two flavours: with or without a center button. They areuseful for controlling movements of vehicles/cameras etc. They use a singlecallback per pad and have 8 or 10 different event types to differentiate thebutton 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 are used to display textual information (i.e. states, values of sensors,configuration parameters etc.). To send data from the code useESP.updateLabel() .Labels get a name on creation and a initial value.

Labels automatically wrap your text. If you want them to have multiple lines usethe 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 displayimages 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.

Sliders can be used to select (or display) a numerical value. Sliders providerealtime data and are touch compatible. Note that like all ESPUI functions, the callback does not return anintbut aString so should be converted with the.toInt() function. See the examples for more details. Sliders canbe updated from code usingESP.updateSlider().

A slider usually only sends a new value when it is released to save network bandwidth.This behaviour can be changed globally by settingsliderContinuous beforebegin():

ESPUI.sliderContinuous = true;ESPUI.begin("ESPUI Control");

Events:

• SL_VALUE - Fired when a slider value changes.

The number input can be used to receive numbers from the user. You canenter a value into it and when you are done with your change it is sent to theESP. A number box needs to have a min and a max value. To set it up just use:

ESPUI.number("Numbertest", &numberCall, ControlColor::Alizarin, 5, 0, 10);

Number inputs can be updated from code usingESP.updateNumber().

Note that HTML number boxes will respect their min and max when the userclicks the up and down arrows, but it is possible on most clients to simply typeany number in. As with all user input, numbers should be validated in callback codebecause all client side checks can be skipped. If any value from the UI mightcause a problem, validate it.

Events:

• N_VALUE - Fired when a number value changes.

The text input works very similar like the number input but allows any string to be entered.If you attach a Max control to the text input then a max length will be appliedto the control.

text = ESPUI.text("Label", callback, ControlColor::Dark, "Initial value");ESPUI.addControl(ControlType::Max, "", "32", ControlColor::None, text);

Text inputs can be updated from code usingESP.updateText().

However even with a set maximum length, user input should still be validatedbecause it is easy to bypass client-side checks. Never trust user input.

Events:

• T_VALUE - Fired when a text value changes.

As an extension to the text input control, you can also specify the type attribute to be used for the HTML input element.This allows you to easily create input controls for Date, Time, Colour and Passwords, or indeed any otherHTML Input Types supported by your browser.

text_date = ESPUI.text("Date", callback, ControlColor::Dark, "2022-05-24");ESPUI.setInputType(text_date, "date");text_time = ESPUI.text("Time", callback, ControlColor::Dark, "13:00");ESPUI.setInputType(text_time, "time");text_colour = ESPUI.text("Colour", callback, ControlColor::Dark, "#FF0000");ESPUI.setInputType(text_colour, "color");text_password = ESPUI.text("Password", callback, ControlColor::Dark, "tiddles123");ESPUI.setInputType(text_password, "password");

Important! This function should be calledbeforeESPUI.begin or results will be unreliable.

Note that not all browsers support all input types, and that the control displayed to edit the input is browser dependent.

However even with a type set, user input should still be validatedbecause it is easy to bypass client-side checks. Never trust user input.

The File Display control is used to upload a file from the ESP file system and display the contents on the UI. The content is Auto Scrolledto the last line in the file. Syntax:

fileDisplayId = ESPUI.fileDisplay("Filetest", ControlColor::Turquoise, FullyQualified FilePath);

After updating the contents of the file, trigger a display update using:ESPUI.updateControl(fileDisplayId);

The Select control lets the user select from a predefined list of options. First create a select widget like so

uint16_t select1 = ESPUI.addControl( ControlType::Select, "Select Title", "Initial Value", ControlColor::Alizarin, tab1, &selectExample );

Then add Options to it, specifying the Select as the parent:

ESPUI.addControl( ControlType::Option, "Option1", "Opt1", ControlColor::Alizarin, select1);ESPUI.addControl( ControlType::Option, "Option2", "Opt2", ControlColor::Alizarin, select1);ESPUI.addControl( ControlType::Option, "Option3", "Opt3", ControlColor::Alizarin, select1);

Check thetabbedGui example for a working demo. Selectors can be updated from code usingESP.updateSelect().

Events:

• S_VALUE - Fired when a select value changes.

ESPUI can create an invisible control that can be used to fetch the current time from the clientwhen they are connected to the UI. This could be used to intermittently provide an accurate timesource to your ESP. Remember that clients cannot be relied upon to be correct or truthful.

Create a Time control with the following:

//Add the invisible "Time" controlauto timeId = ESPUI.addControl(Time, "", "", None, 0, timeCallback);

After creating the UI, sending an update to the Time control will cause it to fetch the currenttime from the client and then fire its callback with the result.

//Request an update to the timeESPUI.updateTime(timeId);//Will trigger timeCallback

IntimeCallback you can then print the control's value as normal:

void timeCallback(Control *sender, int type) {  if(type == TM_VALUE) {     Serial.println(sender->value);  }}

The returned string will be anISO string as returned by the Javascriptnew Date().toISOString(). The format isYYYY-MM-DDTHH:mm:ss.sssZ so for example:2022-01-20T21:44:22.913Z.

Events:

• TM_VALUE - Fires when the control is updated withupdateTime()

You can use separators to break up the UI and better organise your controls. Adding a separator will force any following controls onto the subsequent line. Add separators as follows:

ESPUI.separator("Separator name");//orESPUI.addControl(ControlType::Separator, "Separator name", "", ControlColor::None, maintab);

Separators fire no events.

After all the elements are configured, callESPUI.begin("Some Title");to start the UI interface. (OrESPUI.beginLITTLEFS("Some Title"); respectively)Make sure you setup a working network connection or AccessPointbefore (seethegui.ino example). The web interface can then be used from multiple devices at once andalso shows connection status in the top bar.

Tabs can be used to organize your controls into pages. Check thetabbedGui example to seehow this is done. Tabs can be created as follows:

ESPUI.addControl(ControlType::Tab, "Settings 1", "Settings 1");

Then all widgets for the tab need to be added to it by specifying the tab as the parent. Widgets notadded to a tab will be shown above the tab selctor.

ESPUI.addControl(ControlType::Text, "Text Title", "a Text Field", ControlColor::Alizarin, tab1, &textCall);

Note that the basic functions to add controls likeESPUI.button() orESPUI.slider() do not add to any tab,so they are good for building small UIs. However if you need to use tabs then you will have to add all yourcontrols using the fullESPUI.addControl() function.

ESPUI has several different log levels. You can set them using theESPUI.setVerbosity(Verbosity::VerboseJSON) function.

Loglevels are:

• Verbosity::Quiet (default)
• Verbosity::Verbose
• Verbosity::VerboseJSON

VerboseJSON outputs the most debug information.

A selection of basic colours are available to use:

If you want more control over the UI design, see the Inline Styles section below.

ESPUI includes a range of advanced features that can customise your UIs.

Controls can be made visible or invisible at runtime with theupdateVisibility() function.

ESPUI.updateVisibility(controlId, false);

Note that you cannot hide individual controls from acontrol group, you have to hide the entire group.

You can add custom CSS styles to controls. This allows you to style the UI with custom colors, drop shadows,or other CSS effects. Add styles with the following functions:

setPanelStyle(uint16_t id, String style);setElementStyle(uint16_t id, String style)

A panel style is applied to the panel on which the UI element is placed, an element style is applied to the element itself.Because CSS inline styles can only style one specific DOM element, for controls made up of multiple elements (like the pad)this is limited. Element styles can be applied to all controls, but will only work correctly for the Button, Label, Slider,Switcher, Number, Text, and Selector.

Dynamic update of styles is supported. When either of the above functions are called, the control is updated live. This couldbe used to refect a warning state by changing the color of a button, or for similar effects.

For example, this code will set a control's panel to a random background color:

char stylecol[30];sprintf(stylecol, "background-color: #%06X;", (unsigned int) random(0x0, 0xFFFFFF));ESPUI.setPanelStyle(switch1, stylecol);

You can get quite creative with this.

ThecompleteExample example includes a range of things that you can do with inline styles.

It is possible to dynamically enable and disable controls to, for example, provide feedback to the user that a particular feature istemporarily unavailable. To do this use the following function call:

ESPUI.setEnabled(controlId, enabled);

Settingenabled to false will make the control noninteractive and it will visually change to illustrate this to the user. The controlwill stop firing any events. Note that whilst the widget will change appearance, the panel of the control will remain whatever colourit was set to. If you wish to also change the colour of the panel then you should use inline styles to show the noninteractive state. For example:

ESPUI.setEnabled(mainButton, false);const String disabledstyle = "background-color: #bbb; border-bottom: #999 3px solid;";ESPUI.setPanelStyle(mainButton, disabledstyle);

This CSS style sets the panel background and its border to grey. To put the control back to enabled use the following:

ESPUI.setEnabled(mainButton, true);ESPUI.setPanelStyle(mainButton, ";");

Note that we have to set the inline style to";" (i.e. an empty CSS rule) because if we just try to set it to"" this will beinterpreted as "do not change the style".

Controls can also be set to disabled before the UI is started.

Normally, whenever a control is added to the UI, a new panel is generated with a title. However, you can insteadset the "parent" of a new control to be an existing control. This allows you to add multiple widgets into the samepanel. For example:

panel1 = ESPUI.addControl(ControlType::Button, "Button Set", "Button A", ControlColor::Turquoise, Control::noParent, btncallback);ESPUI.addControl(ControlType::Button, "", "Button B", ControlColor::None, panel1, btncallback);ESPUI.addControl(ControlType::Button, "", "Button C", ControlColor::None, panel1, btncallback);

The first call toaddControl has no parent (or it could be set to a tab if you are using a tabbed UI), so therefore a new panel is added containing one buttonwith the valueButton A. The two subsequent calls have their parent set to the first control we added, so instead of creatinga new panel, the result is the following:

The grouped controls operate entirely independently, and can be assigned different callbacks, or updated separately. The groupingis purely visual.

Most controls can be grouped this way, but the result is not always visually pleasant. This works best with labels, sliders, switchers,and buttons.

For sliders and switchers, you can also set the controls to be displayed vertically.

auto vertswitcher = ESPUI.addControl(Switcher, "Vertical Switcher", "0", Dark, tab1);ESPUI.setVertical(vertswitcher);

This must be done beforeESPUI.begin() is called. Vertical layouts are currently only supported for sliders and switchers, and itis a purely visual change. Behaviour is identical. Mixing horizontal and vertical controls can result in some unpredictable layouts.

When you add multiple buttons to a single panel, the buttons have a title so they can be differentiated. For sliders and switchers this isnot the case. Therefore you might want to add additional labels so that the controls can be distinguished. There is not yet automaticsupport for doing this, so the approach is to add labels that have been styled usinginline styles. By doing thisyou can acheieve effects such as this:

The code to do this is in thecompleteExample example.

Controls can be set to be displayed "wide" with the function:

ESPUI.setPanelWide(controlid, true);

Important! This function should be calledbeforeESPUI.begin or results will be unreliable.

Setting a control to wide tells ESPUI to lay out that control as if there was only a single column, even on wide displays.This can be applied to every element to force a single column layout, or to individual elements to customise the display.

Note that this will have no effect on small screens.

The graph widget can display graph points with timestamp at wich they arrive

UseESPUI.addGraphPoint(graphId, random(1, 50)); to add a new value at the current time, useESPUI.clearGraph(graphId) to clear the entire graph.Graph points are saved in the browser inlocalstorage to be persistant, clear local storageto remove the points or use clearGraph() from a bbutton callback to provide a clear button.

There are many issues with the graph component currently and work is ongoing. Consider helping us out with development!

ESPUI will redirect all unknown URLs it is asked for to the 'root' of the local HTTP server instead of responding with an HTTP code 404. This makes it act as a simple 'captive portal'. Note you must also set up the ESP to be a DNS server that responds to all DNS requests with the IP address of the ESP. This only effective when the ESP is acting as a WiFi hotspot in AP mode and assigning itself as the DNS server to connected clients.

All the example sketches include the DNS related code and will work as captive portals when used as a hotspot. In the event you wish to disable this feature you can do so by removing the DNS server code and adding the code below.

ESPUI.captivePortal = false;

If you want to work on the HTML/CSS/JS files, do make changes in thedatadirectory. When you need to transfer that code to the ESP, runtools/prepare_static_ui_sources.py -a (this script needspython3 with themoduleshtmlmin,jsmin andcsscompressor). This will generate a) minified filesnext to the original files and b) the C header files insrc that contain the minified andgzipped HTML/CSS/JS data. Alternatively, you can specify the--source and--target arguments to theprepare_static_ui_sources.py script (run the script without arguments forhelp) if you want to use different locations.

If you don't have a python environment, you need to minify and gzip theHTML/CSS/JS files manually. I wrote a little useful jsfiddle for this,see here.

If you change something in HTML/CSS/JS and want to create a pull request, pleasedo include the minified versions and corresponding C header files in yourcommits. (DoNOT commit all the minified versions for the non changed files)

It is possible to run or debug this library on a unix-like computer (Linux,macOS, WSL) without flashing on hardware, and with your favourite debuggingtools (gdb, valgrind, ...). This is accomplished through theesp8266/Arduino "emulation on host" environment.

A fake AsyncWebserver library is needed because lwIP is not yet ported tothe emulation environment. Full instructions can be found in this project'sreadme page.

• Adds the ability to have inline styles for widgets and panels
• Adds LittleFS on the ESP32
• Cleans up examples
• Adds Button Animation
• Adds chunking for the widgets so you can add even more of them
• Fixes lots of bugs related to invisible UI elements and sliders
• Adds the ability to change port

• ArduinoJSON 6.10.0 Support
• Split pad into pad and padWithCenter
• Cleaned order of parameters on switch and pad
• Changes all numbers to actually be numbers (slider value, number value, min and max)

Liked this Library? You cansupport me by sending me a ☕Coffee.

Otherwise I really welcomePull Requests.