mirror of
https://github.com/s00500/ESPUI.git
synced 2024-11-25 14:10:54 +00:00
297 lines
10 KiB
Markdown
297 lines
10 KiB
Markdown
# ESPUI 2.0
|
|
|
|
 //
|
|
TODO: Update Logo
|
|
|
|
ESPUI is a simple library to make a web 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.
|
|
|
|
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 fine on any kind of ESP8266 and ESP32 (NodeMCU Boards, usw)
|
|
|
|
# Important notes
|
|
|
|
THIS IS THE 2.0.0 DEVELOPMENT BRANCH, NOT GUARANTIED TO WORK
|
|
|
|
**Roadmap for 2.0.0:**
|
|
|
|
- ArduinoJSON 6.10.0 Support ✅
|
|
- Tabs by @eringerli ISSUE #45 ✅
|
|
- remove black line without tabs ✅
|
|
- API changes by @eringerli ✅
|
|
- less updateControl functions ✅
|
|
- proper wrappers for all create/update actions ✅
|
|
- Min Max on slider by @eringerli ✅
|
|
- OptionList by @eringerli ✅
|
|
- Public Access to ESPAsyncServer ✅
|
|
- Graph Widget ✅
|
|
|
|
* Persist save graph in local storage #10
|
|
* Switch slider behaviour ?
|
|
* Cleanup Example, DNS and autojoin
|
|
* data upload new info to doc? (copy to folder?)
|
|
* Cleanup and extend Documentation
|
|
- Number field ✅
|
|
- Text field ✅
|
|
- Data directory ✅
|
|
- Graph Usage
|
|
- Number min and max value to docs
|
|
- Slider
|
|
- OptionList
|
|
- Tab usage
|
|
- Verbosity setting
|
|
|
|
## Changelog for 2.0 functions:
|
|
|
|
- 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)
|
|
|
|
## Dependencies
|
|
|
|
This library is dependent on the following libraries to function properly.
|
|
|
|
- [ESPAsyncWebserver](https://github.com/me-no-dev/ESPAsyncWebServer)
|
|
- [ArduinoJson](https://github.com/bblanchon/ArduinoJson) (Last tested with
|
|
version 6.10.0) **Plus for ESP8266**
|
|
|
|
- (_For ESP8266_) [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP)
|
|
- (_For ESP32_) [AsyncTCP](https://github.com/me-no-dev/AsyncTCP)
|
|
|
|
## How to Install
|
|
|
|
Make sure all the dependencies are installed, then install like so:
|
|
|
|
#### Using PlattformIO (_recommended_)
|
|
|
|
Just include this library as a dependency on lib_deps like so:
|
|
|
|
```
|
|
lib_deps = ESPUI
|
|
```
|
|
|
|
#### Directly Through 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
|
|
|
|
#### 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.
|
|
|
|
## Getting started
|
|
|
|
ESPUI serves several files to the browser to build up its web interface. This
|
|
can be achieved in 2 ways: _PROGMEM_ or _SPIFFS_
|
|
|
|
_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 SPIFFS 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 to 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 (updateable)
|
|
- Button
|
|
- Switch (updateable)
|
|
- Control pad
|
|
- Control pad with center button
|
|
- Slider
|
|
- Text Input (updateable)
|
|
- Numberinput (updateable)
|
|
|
|
Checkout the example for the usage
|
|
|
|
## Available colors:
|
|
|
|
- COLOR_TURQUOISE
|
|
- COLOR_EMERALD
|
|
- COLOR_PETERRIVER
|
|
- COLOR_WETASPHALT
|
|
- COLOR_SUNFLOWER
|
|
- COLOR_CARROT
|
|
- COLOR_ALIZARIN
|
|
- COLOR_NONE
|
|
|
|
## 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 _ESP32_ and the client browser works using web
|
|
sockets. ESPUI does not need network access and can be used in standalone access
|
|
point mode. All assets are loaded from the internal SPIFFS filesystem of the
|
|
ESP32.
|
|
|
|
This section will explain in detail how the Library is to be used from the
|
|
Arduino code side. As of now the Facilino blocks are not implemented. 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” 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. Here is an overview of the currently implemented different elements
|
|
of the UI library:
|
|
|
|
#### Button
|
|
|
|
|
|
|
|
Buttons have a name and a callback value. They have one event for press and one
|
|
for release.
|
|
|
|
#### Switch
|
|
|
|
|
|
|
|
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 for turning on
|
|
and one for turning off.
|
|
|
|
#### Buttonpad
|
|
|
|
|
|
|
|
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.
|
|
|
|
#### Labels
|
|
|
|
|
|
|
|
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 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
|
|
|
|
#### Slider
|
|
|
|
|
|
|
|
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
|
|
|
|
#### Number Input
|
|
|
|
TODO: Add image
|
|
|
|
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.
|
|
|
|
#### Text Input
|
|
|
|
TODO: Add image
|
|
|
|
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.
|
|
|
|
#### Using Tabs
|
|
|
|
TODO: Add image
|
|
|
|
// TODO: add Text for tabs
|
|
|
|
#### Initialisation of the UI
|
|
|
|
After all the elements are configured you can use `ESPUI.begin(“Some Title”);`
|
|
to start the UI interface. (Or `ESPUI.beginSPIFFS(“Some Title”);` respectively)
|
|
Make sure you setup a working network connection or AccesPoint **before** (See
|
|
example). The web interface can then be used from multiple devices at once and
|
|
also shows an connection status in the top bar. The library is designed to be
|
|
easy to use and can still be extended with a lot of more functionality.
|
|
|
|
#### Log output
|
|
|
|
ESPUI has several different log levels. You can set them using the
|
|
`ESPUI.setVerbosity(Verbosity::VerboseJSON)` function.
|
|
|
|
Loglevels are:
|
|
|
|
- Verbosity::Quiet (default)
|
|
- Verbosity::Verbose
|
|
- Verbosity::VerboseJSON
|
|
|
|
// TODO: Add some more notes here
|
|
|
|
# Notes for Development
|
|
|
|
If you want to work on the HTML/CSS/JS files, do make changes in the `data`
|
|
directory. When you need to transfer that code to the ESP, run
|
|
`tools/prepare_static_ui_sources.py -a` (this script needs python3 with the
|
|
modules htmlmin, jsmin and csscompressor). This will generate a) minified files
|
|
next to the original files to be uploaded with the ESP32 sketch data uploader
|
|
mentioned above and b) the C header files in `src` that contain the minified and
|
|
gzipped HTML/CSS/JS data (which are used by the **prepareFileSystem** example
|
|
sketch or when they are served from PROGMEM; see above in the section "Getting
|
|
started"). Alternatively, you can duplicate the `examples/gui` directory and
|
|
work on the copy. Then specify the `--source` and `--target` arguments to the
|
|
`prepare_static_ui_sources.py` script (run the script without arguments for
|
|
help).
|
|
|
|
If you don't have a python environment, you need to minify and gzip the
|
|
HTML/CSS/JS files manually. I wrote a little useful jsfiddle for this,
|
|
[see here](https://jsfiddle.net/s00500/yvLbhuuv/).
|
|
|
|
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.
|
|
|
|
# Contribute
|
|
|
|
Liked this Library? You can **support** me by sending me a :coffee:
|
|
[Coffee](https://paypal.me/lukasbachschwell/3).
|
|
|
|
Otherwise I really welcome **Pull Requests**.
|