lbsadmin/ESPUI
1
0
Fork 0
mirror of https://github.com/s00500/ESPUI.git synced 2024-11-21 22:50:55 +00:00
Code Issues Releases Activity

Major documentation rework

Browse Source
This commit is contained in:
Ian Gray 2022-01-25 21:32:34 +00:00
parent 334bf16b09
commit 64b30d13a6
7 changed files with 322 additions and 284 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

400
README.md
View File

@ -1,8 +1,8 @@
# ESPUI
![ESPUI](https://github.com/s00500/ESPUI/blob/master/docs/ui_complete.png)
![ESPUI](docs/ui_complete.png)
ESPUI is a simple library to make a web user interface for your projects using
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,
control, and update elements on your GUI through multiple devices like phones
and tablets.
@ -14,37 +14,58 @@ 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 fine on any kind of **ESP8266** and **ESP32** (NodeMCU Boards, usw)
The Library runs on any kind of **ESP8266** and **ESP32** (NodeMCU, AI Thinker, etc.).
## Changelog for 2.0:
- [Dependencies](#dependencies)
- [How to Install](#how-to-install)
- [Getting started](#getting-started)
- [UI Elements](#documentation)
* [Button](#button)
* [Switch](#switch)
* [Buttonpad](#buttonpad)
* [Labels](#labels)
* [Slider](#slider)
* [Number Input](#number-input)
* [Text Input](#text-input)
* [Select control](#select-control)
* [Getting the Time](#getting-the-time)
* [Separators](#separators)
- [Initialisation of the UI](#initialisation-of-the-ui)
- [Tabs](#tabs)
- [Log output](#log-output)
- [Colours](#colours)
- [Advanced Features](#advanced-features)
* [Inline Styles](#inline-styles)
* [Grouped controls](#grouped-controls)
* [Wide controls](#wide-controls)
* [Graph (Experimental)](#graph--experimental-)
- [Notes for Development](#notes-for-development)
- [Contribute](#contribute)
- ArduinoJSON 6.10.0 Support
- split pad into pad and padWithCenter
- Cleaned Order or parameters on switch
- cleaned Order of parameters on pad
- Changes all numbers to actually be numbers (slider value, number value, min and max)
### Added features
### Contributed features
- Tabs by @eringerli #45
- Tabs by @eringerli
- Generic API by @eringerli
- Min Max on slider by @eringerli
- OptionList by @eringerli
- Public Access to ESPAsyncServer
- Graph Widget (Persist save graph in local storage #10)
- 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
## Further Roadmap
## Roadmap
- Slider css issues
- implement Gauge
- File upload ?
- Fully implement graphs
- Expand number input features (floats etc.)
- Support for enabling and disabling controls
## Dependencies
This library is dependent on the following libraries to function properly.
This library is dependent on the following libraries.
- [ESPAsyncWebserver](https://github.com/me-no-dev/ESPAsyncWebServer)
- [ArduinoJson](https://github.com/bblanchon/ArduinoJson) (Last tested with
@ -58,37 +79,25 @@ This library is dependent on the following libraries to function properly.
Make sure all the dependencies are installed, then install like so:
#### Using PlattformIO (_recommended_)
#### Using PlatformIO (_recommended_)
Just include this library as a dependency on lib_deps like so:
Just include this library as a dependency in `lib_deps` like so:
```
lib_deps =
ESPUI
ESPAsyncWebserver
ESPAsyncTCP # or AsyncTCP on ESP32
ESP Async WebServer
ESPAsyncTCP # (or AsyncTCP on ESP32)
LittleFS_esp32 # (ESP32 only)
```
#### Directly Through Arduino IDE (_recommended_)
#### 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" > Install
You can find this Library in the Arduino IDE library manager. Go to
`Sketch > Include Library > Library Manager` search for `ESPUI` and install.
#### Manual Install Arduino IDE
_For Windows:_ Download the
[Repository](https://github.com/s00500/ESPUI/archive/master.zip) and extract the
.zip in Documents>Arduino>Libraries>{Place "ESPUI" folder Here}
_For Linux:_ Download the
[Repository](https://github.com/s00500/ESPUI/archive/master.zip) and extract the
.zip in Sketchbook/Libraries/{Place "ESPUI" folder Here}
_For macOs:_ Download the
[Repository](https://github.com/s00500/ESPUI/archive/master.zip) and extract the
.zip in ~/Documents/Arduino/libraries/{Place "ESPUI" folder Here}
Go to Sketch>Include Library>Add .zip Library> Select the Downloaded .zip File.
If you cannot use the Library Manager, you can download the [repository](https://github.com/s00500/ESPUI/archive/master.zip) and follow
the [instructions to manually install libraries](https://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use/how-to-install-a-library).
## Getting started
@ -120,36 +129,22 @@ more program memory to work with.
- Button
- Switch
- Control pad
- Control pad with center button
- Slider
- Text Input
- Numberinput
- Graph
- Option select
- Separator
- Time
- Graph (partial implementation)
Checkout the example for the usage or see the detailed info below
## Available colors:
- Turquoise
- Emerald
- Peterriver
- Wetasphalt
- Sunflower
- Carrot
- Alizarin
- Dark
- None
(Use like `ControlColor::Sunflower`)
## Documentation
The heart of ESPUI is
[ESPAsyncWebserver](https://github.com/me-no-dev/ESPAsyncWebServer). ESPUI's
frontend is based on [Skeleton CSS](http://getskeleton.com/) and jQuery-like
lightweight [zepto.js](https://zeptojs.com/) for Handling Click Events Etc. The
communication between the _ESP_ and the client browser works using web
lightweight [zepto.js](https://zeptojs.com/) 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.
@ -162,60 +157,58 @@ 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. Here is an overview of the currently implemented different elements
of the UI library:
statement.
#### Button
![Buttons](https://github.com/s00500/ESPUI/blob/master/docs/ui_button.png)
![Buttons](docs/ui_button.png)
Buttons have a name and a callback value. They have one event for press (`B_DOWN`) and one
for release (`B_UP`).
Buttons have a name and a callback value. Their text can be changed at runtime using `ESPUI.updateButton()`.
- B_DOWN
- B_UP
Events:
- `B_DOWN` - Fired when button is pressed.
- `B_UP` - Fired when button is released.
#### Switch
![Switches](https://github.com/s00500/ESPUI/blob/master/docs/ui_switches.png)
![Switches](docs/ui_switches.png)
Switches sync their state on all connected devices. This means when you change
their value they change visibly on all tablets or computers that currently
display the interface. They also have two types of events: one when turning on (`S_ACTIVE`)
and one when turning off (`S_INACTIVE`).
their value (either by pressing them, or programmatically using `ESPUI.updateSwitcher()`) they change visibly
on all tablets or computers that currently display the interface.
- S_ACTIVE
- S_INACTIVE
Events:
- `S_ACTIVE` - Fired when turning on.
- `S_INACTIVE` - Fired when turning off.
#### Buttonpad
![control pads](https://github.com/s00500/ESPUI/blob/master/docs/ui_controlpad.png)
![control pads](docs/ui_controlpad.png)
Button pads come in two flavours: with or without a center button. They are very
useful for con-trolling all kinds of movements of vehicles or also of course our
walking robots. They use a single callback per pad and have 8 or 10 different
event types to differentiate the button actions.
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
- `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](https://github.com/s00500/ESPUI/blob/master/docs/ui_labels.png)
![labels](docs/ui_labels.png)
Labels are a nice tool to get information from the robot to the user interface.
This can be done to show states, values of sensors and configuration parameters.
To send data from the code use `ESP.print(labelId, "Text");` . Labels get a name
on creation and a initial value. The name is not changeable once the UI
initialised.
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.
@ -232,47 +225,51 @@ This requires that the client has access to the image in question, either from t
#### Slider
![slider](https://github.com/s00500/ESPUI/blob/master/docs/ui_slider.png)
![slider](docs/ui_slider.png)
The Slider can be used to slide through a value from 1 to 100. Slides provide
realtime data, are touch compatible and can be used to for example control a
Servo. The current value is shown while the slider is dragged in a little bubble
over the handle. In the Callback the slider does not return an int but a String.
Use the .toInt function to convert the value, see the **gui** example to check how it works.
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 `String` so should be converted with the `.toInt()` function. See the examples for more details. Sliders can
be updated from code using `ESP.updateSlider()`.
A slider usually only sends a new value when it is released to save the esps from being spammed with values. This behaviour can be cahnged globally using a property of the ESPUI object before `begin()`:
A slider usually only sends a new value when it is released to save network bandwidth.
This behaviour can be changed globally by setting `sliderContinuous` before `begin()`:
```
ESPUI.sliderContinuous = true;
ESPUI.begin("ESPUI Control");
```
Events:
- `SL_VALUE` - Fired when a slider value changes.
#### Number Input
![number](https://github.com/s00500/ESPUI/blob/master/docs/ui_number.png)
![number](docs/ui_number.png)
The numberinput can be used to directly input numbers to your program. You can
enter a Value into it and when you are done with your change it is sent to the
ESP.
A number box needs to have a min and a max value. To set it up just use:
The number input can be used to receive numbers from the user. You can
enter a value into it and when you are done with your change it is sent to the
ESP. 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 using `ESP.updateNumber()`.
Note that HTML number boxes will respect their min and max when the user
clicks the up and down arrows, but it is possible on most clients to simply type
any number in. As with all user input, numbers should be validated in callback code
because all client side checks can be skipped. If any value from the UI might
cause a problem, validate it.
Events:
- `N_VALUE` - Fired when a number value changes.
#### Text Input
![text](https://github.com/s00500/ESPUI/blob/master/docs/ui_text.png)
The textinput works very similar like the number input but with a string. You
can enter a String into it and when you are done with your change it is sent to
the ESP.
![text](docs/ui_text.png)
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 applied
to the control.
@ -281,28 +278,27 @@ to the control.
ESPUI.addControl(ControlType::Max, "", "32", ControlColor::None, text);
```
Text inputs can be updated from code using `ESP.updateText()`.
However even with a set maximum length, user input should still be validated
because it is easy to bypass client-side checks. Never trust user input.
#### Graph
Events:
- `T_VALUE` - Fired when a text value changes.
![graph](https://github.com/s00500/ESPUI/blob/master/docs/ui_graph.png)
The graph widget can display graph points with timestamp at wich they arrive
#### Select control
Use `ESPUI.addGraphPoint(graphId, random(1, 50));` to add a new value at the current time, use `ESPUI.clearGraph(graphId)` to clear the entire graph.
Graph points are saved in the browser in **localstorage** to be persistant, clear local storageto remove the points or use clearGraph() from a bbutton callback to provide a clear button.
![option1](docs/ui_select1.png)
![option2](docs/ui_select2.png)
#### Option select
The Select control lets the user select from a predefined list of options. First create a select widget like so
![option1](https://github.com/s00500/ESPUI/blob/master/docs/ui_select1.png)
![option2](https://github.com/s00500/ESPUI/blob/master/docs/ui_select2.png)
```
uint16_t select1 = ESPUI.addControl( ControlType::Select, "Select Title", "Initial Value", ControlColor::Alizarin, tab1, &selectExample );
```
The option select works by first creating a select widget like so
`uint16_t select1 = ESPUI.addControl( ControlType::Select, "Select:", "", ControlColor::Alizarin, tab1, &selectExample );`
And then adding Options to it like seperate widgets, specifying the select as the parent:
Then add Options to it, specifying the Select as the parent:
```
ESPUI.addControl( ControlType::Option, "Option1", "Opt1", ControlColor::Alizarin, select1);
@ -310,21 +306,49 @@ ESPUI.addControl( ControlType::Option, "Option2", "Opt2", ControlColor::Alizarin
ESPUI.addControl( ControlType::Option, "Option3", "Opt3", ControlColor::Alizarin, select1);
```
Check the **tabbedGui** example for a working demo
Check the **tabbedGui** example for a working demo. Selectors can be updated from code using `ESP.updateSelect()`.
### Using Tabs
Events:
- `S_VALUE` - Fired when a select value changes.
![tabs](https://github.com/s00500/ESPUI/blob/master/docs/ui_tabs.png)
#### Getting the Time
Tabs can be used to organize your widgets in pages. Check the tabbedGui example.
Tabs can be created using the generic functions like so:
`ESPUI.addControl( ControlType::Tab, "Settings 1", "Settings 1" );`
ESPUI can create an invisible control that can be used to fetch the current time from the client
when they are connected to the UI. This could be used to intermittently provide an accurate time
source to your ESP. Remember that clients cannot be relied upon to be correct or truthful.
Then all widgets for the tab need to be added to it by specifying the tab as the parrent (widgets not added to a tab will be shown above the tab selctor)
Create a Time control with the following:
`ESPUI.addControl( ControlType::Text, "Text Title:", "a Text Field", ControlColor::Alizarin, tab1, &textCall );`
```
//Add the invisible "Time" control
auto timeId = ESPUI.addControl(Time, "", "", None, 0, timeCallback);
```
### Separators
After creating the UI, sending an update to the Time control will cause it to fetch the current
time from the client and then fire its callback with the result.
```
//Request an update to the time
ESPUI.updateTime(timeId);
//Will trigger timeCallback
```
In `timeCallback` 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 an [ISO string](https://www.w3schools.com/jsref/jsref_toisostring.asp) as returned by the Javascript `new Date().toISOString()`. The format is `YYYY-MM-DDTHH:mm:ss.sssZ` so for example: `2022-01-20T21:44:22.913Z`.
Events:
- `TM_VALUE` - Fires when the control is updated with `updateTime()`
#### Separators
![separators](docs/ui_separators.png)
@ -336,32 +360,42 @@ ESPUI.separator("Separator name");
ESPUI.addControl(ControlType::Separator, "Separator name", "", ControlColor::None, maintab);
```
Separators fire no events.
### Initialisation of the UI
After all the elements are configured you can use `ESPUI.begin("Some Title");`
After all the elements are configured, call `ESPUI.begin("Some Title");`
to start the UI interface. (Or `ESPUI.beginLITTLEFS("Some Title");` respectively)
Make sure you setup a working network connection or AccesPoint **before** (See
gui.ino example). The web interface can then be used from multiple devices at once and
also shows an connection status in the top bar.
Make sure you setup a working network connection or AccessPoint **before** (see
the `gui.ino` example). The web interface can then be used from multiple devices at once and
also shows connection status in the top bar.
### Advanced: Generic creation and updates of control widgets
There are 2 generic functions to create and update controls, to see them in action check the **gui-generic-api** example.
To create a generic control use:
`uint16_t switchOne = ESPUI.addControl(ControlType::Switcher, "Switch one", "", ControlColor::Alizarin, Control::noParent, &switchExample);`
### Tabs
Then its value can be updated by doing:
![tabs](docs/ui_tabs.png)
`ESPUI.updateControlValue(status, "Start");`
You can also update other parameters of the control like its color using:
Tabs can be used to organize your controls into pages. Check the **tabbedGui** example to see
how this is done. Tabs can be created as follows:
```
ESPUI.getControl(switchOne)->color = ControlColor::Carrot;
ESPUI.updateControl(switchOne);
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 not
added 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 like `ESPUI.button()` or `ESPUI.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 your
controls using the full `ESPUI.addControl()` function.
### Log output
ESPUI has several different log levels. You can set them using the
@ -375,15 +409,19 @@ Loglevels are:
VerboseJSON outputs the most debug information.
### Advanced properties
### Colours
If you have many different widgets it might be necessary to adjust the JSON Buffers used internally in ESPUI before .begin() :
A selection of basic colours are available to use:
![Colours](docs/ui_colours.png)
If you want more control over the UI design, see the Inline Styles section below.
## Advanced Features
ESPUI includes a range of advanced features that can customise your UIs.
```
ESPUI.jsonUpdateDocumentSize = 2000; // This is the default, and this value is not affected by the amount of widgets
ESPUI.jsonInitialDocumentSize = 8000; // This is the default, adjust when you have too many widgets or options
ESPUI.begin("ESPUI Control");
```
### Inline Styles
@ -415,11 +453,11 @@ You can get quite creative with this.
![Inline Styles](docs/inlinestyles.gif)
Note: The images in this example are formed by setting a Label to contain an `<img>` tag:
The **completeExample** example includes a range of examples that you can do with inline styles.
![More Inline Styles](docs/ui_inlinestyles2.png)
```
ESPUI.addControl(ControlType::Label, "Label", "<img src='path/to/image'>", ControlColor::Peterriver);
```
### Grouped controls
@ -449,7 +487,7 @@ and buttons.
If you group too many elements it might throw the layout of the rest of the UI out of line. Consider adding separators to correct this.
### Advanced: Wide controls
### Wide controls
Controls can be set to be displayed "wide" with the function:
@ -466,34 +504,17 @@ This can be applied to every element to force a single column layout, or to indi
Note that this will have no effect on small screens.
### Advanced: Getting the Time
ESPUI can create an invisible control that can be used to fetch the current time from the client when they are connected to the UI. This could be used to intermittently provide an accurate time source to your ESP. Remember that clients cannot be relied upon to be correct or truthful. If this is not a concern, you can do the following:
### Graph (Experimental)
```
//Add the invisible "Time" control
auto timeId = ESPUI.addControl(Time, "", "", None, 0, timeCallback);
```
![graph](docs/ui_graph.png)
After creating the UI, sending an update to the Time control will cause it to fetch the current time from the client and then fire its callback with the result.
The graph widget can display graph points with timestamp at wich they arrive
```
//Request an update to the time
ESPUI.updateTime(timeId);
//Will trigger timeCallback
```
Use `ESPUI.addGraphPoint(graphId, random(1, 50));` to add a new value at the current time, use `ESPUI.clearGraph(graphId)` to clear the entire graph.
Graph points are saved in the browser in **localstorage** to be persistant, clear local storageto remove the points or use clearGraph() from a bbutton callback to provide a clear button.
In `timeCallback` 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 an [ISO string](https://www.w3schools.com/jsref/jsref_toisostring.asp) as returned by the Javascript `new Date().toISOString()`. The format is `YYYY-MM-DDTHH:mm:ss.sssZ` so for example: `2022-01-20T21:44:22.913Z`.
_There are many issues with the graph component currently and work is ongoing. Consider helping us out with development!_
# Notes for Development
@ -514,6 +535,23 @@ If you change something in HTML/CSS/JS and want to create a pull request, please
do include the minified versions and corresponding C header files in your
commits. (Do **NOT** commit all the minified versions for the non changed files)
## Changelog for 2.1:
- 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
## Changelog for 2.0:
- 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)
# Contribute
Liked this Library? You can **support** me by sending me a :coffee:

BIN
docs/ui_colours.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
docs/ui_complete.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 59 KiB

BIN
docs/ui_inlinestyles2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/ui_number.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
docs/ui_slider.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
docs/ui_text.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 7.2 KiB