1
0
mirror of https://github.com/s00500/ESPUI.git synced 2024-11-16 09:00:53 +00:00
ESPUI/README.md

166 lines
8.6 KiB
Markdown
Raw Normal View History

2017-10-19 20:21:02 +00:00
# ESPUI
2017-11-13 10:02:15 +00:00
![ESPUI](https://github.com/s00500/ESPUI/blob/master/docs/ui_complete.png)
2017-10-19 20:25:37 +00:00
2017-10-19 20:21:02 +00:00
2017-12-01 16:22:14 +00:00
ESPUI is a simple library to make a web user interface for your projects using the **ESP8266** or the **ESP32**
2017-10-19 20:21:02 +00:00
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.
I completely rewrote the EasyUI Library created by ayushsharma82 [Here](https://github.com/ayushsharma82/)
Now it uses ESPAsyncWebserver and is mainly to be used with the ESP32 Processor.
2017-11-13 10:17:58 +00:00
## Dependencies
This library is dependent on the following libraries to function properly.
2017-12-01 16:22:14 +00:00
- [ESPAsyncWebserver](https://github.com/me-no-dev/ESPAsyncWebServer)
- [ArduinoJson](https://github.com/bblanchon/ArduinoJson)
**Plus for ESP8266**
- [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP)
**Additionally necessary for ESP32**
- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP)
2017-10-19 20:21:02 +00:00
2017-11-13 10:17:58 +00:00
## How to Install
2017-05-18 23:08:17 +00:00
2017-11-13 10:17:58 +00:00
Make sure all the dependencies are installed, then install like so:
2017-05-18 23:08:17 +00:00
2018-05-27 09:41:52 +00:00
#### Directly Through Arduino IDE (*recommended*)
2017-05-18 23:08:17 +00:00
2017-11-13 10:17:58 +00:00
You can find this Library in the Arduino IDE library manager
2017-12-01 16:22:14 +00:00
Go to Sketch > Include Library > Library Manager > Search for "ESPUI" > Install
2017-05-18 23:08:17 +00:00
2017-11-13 10:17:58 +00:00
#### Manual Install
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
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}
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
For Linux: Download the [Repository](https://github.com/s00500/ESPUI/archive/master.zip) and extract the .zip in Sketchbook/Libraries/{Place "ESPUI" folder Here}
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
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}
2017-05-18 23:08:17 +00:00
2017-11-13 10:17:58 +00:00
#### Manually through IDE
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
Download the [Repository](https://github.com/s00500/ESPUI/archive/master.zip), Go to Sketch>Include Library>Add .zip Library> Select the Downloaded .zip File.
2017-05-18 23:08:17 +00:00
2018-05-27 09:41:52 +00:00
## Getting started
2017-05-18 23:08:17 +00:00
2018-05-27 09:41:52 +00:00
ESPUI serves several Files to the browser to build up its webinterface. This can be achieved in 2 wasy:
*PROGMEM* or *SPIFFS*
2018-05-27 10:10:21 +00:00
*When `ESPUI.begin()` is called the default is serving files from Memory and ESPUI should work out of the box!*
2018-05-27 09:41:52 +00:00
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 that is already saved in the chip's filesystem and you have more programm memory to work with.
#### Manual way (mainly for development)
2017-11-13 10:17:58 +00:00
2017-12-01 16:22:14 +00:00
To do this download and install me-no-devs wonderful [ESP32 sketch data uploader](https://github.com/me-no-dev/arduino-esp32fs-plugin) or for ESP8266 [ESP8266 sketch data uploader](https://github.com/esp8266/arduino-esp8266fs-plugin)
2017-11-13 10:17:58 +00:00
2017-12-01 16:22:14 +00:00
Then open the **gui** example sketch and select "Upload Sketch Data" from the Tools menu for your processor.
2017-11-13 10:17:58 +00:00
Now you are set to go and use any code you want to with this library
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
## User interface Elements
2017-10-19 20:25:37 +00:00
- Label (updateable)
2017-10-19 20:21:02 +00:00
- Button
2017-10-19 20:25:37 +00:00
- Switch (updateable)
2017-10-19 20:21:02 +00:00
- Control pad
- Control pad with center button
2017-11-29 10:35:54 +00:00
- Slider
2017-05-18 23:08:17 +00:00
2017-10-19 20:21:02 +00:00
Checkout the example for the usage
2018-05-27 09:41:52 +00:00
## Available colors:
- COLOR_TURQUOISE
- COLOR_EMERALD
- COLOR_PETERRIVER
- COLOR_WETASPHALT
- COLOR_SUNFLOWER
- COLOR_CARROT
- COLOR_ALIZARIN
- COLOR_NONE
2017-05-18 23:31:51 +00:00
2017-10-19 20:21:02 +00:00
## Roadmap :
2017-05-18 23:08:17 +00:00
2017-12-01 16:22:14 +00:00
- ~~Setup SPIFFS using values in program memory~~
- ~~ESP8266 support~~
- ~~PlattformIO Integration~~
2018-05-27 09:41:52 +00:00
- ~~Multiline Labels~~
- ~~GZip Files and serve from memory~~
- Datagraph output -> *WIP*
- Number input -> *WIP*
2018-05-27 09:41:52 +00:00
- Text input -> *WIP*
- proper return value (as int and not as string) for slider
2018-05-27 10:01:06 +00:00
- Maybe a slider range setting, meanwhile please use *map()*
- Improve slider stability
2017-05-18 23:31:51 +00:00
2017-05-18 23:08:17 +00:00
## Documentation
2017-10-19 20:25:37 +00:00
The heart of ESPUI is [ESPAsyncWebserver](https://github.com/me-no-dev/ESPAsyncWebServer).
2017-10-19 20:21:02 +00:00
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.
2017-11-13 10:02:15 +00:00
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.
2018-05-27 10:10:21 +00:00
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:
2017-11-13 10:02:15 +00:00
2017-11-13 10:17:58 +00:00
#### Button
2017-11-13 10:02:15 +00:00
![Buttons](https://github.com/s00500/ESPUI/blob/master/docs/ui_button.png)
Buttons have a name and a callback value. They have one event for press and one for release.
2017-11-13 10:17:58 +00:00
#### Switch
2017-11-13 10:02:15 +00:00
![Switches](https://github.com/s00500/ESPUI/blob/master/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 for turning on and one for turning off.
2017-11-13 10:17:58 +00:00
#### Buttonpad
2017-11-13 10:02:15 +00:00
![control pads](https://github.com/s00500/ESPUI/blob/master/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.
2017-11-13 10:17:58 +00:00
#### Labels
2017-11-13 10:02:15 +00:00
![labels](https://github.com/s00500/ESPUI/blob/master/docs/ui_labels.png)
2018-05-27 10:10:21 +00:00
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.
2017-11-13 10:17:58 +00:00
2018-05-27 09:41:52 +00:00
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
2017-11-29 10:35:54 +00:00
#### Slider
2018-05-27 10:01:06 +00:00
![labels](https://github.com/s00500/ESPUI/blob/master/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.
2017-11-29 10:35:54 +00:00
2017-12-01 16:22:14 +00:00
#### Initialisation of the UI
2017-11-13 10:02:15 +00:00
2018-05-27 10:08:54 +00:00
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.
2017-11-13 10:02:15 +00:00
The library is designed to be easy to use and can still be extended with a lot of more functionality.
2018-05-27 09:41:52 +00:00
# Notes for Development
All changes to the client side files can be made in the examples/gui/data directory. Using the file uploader thin can be used for development. After this you have to compress them and then you can gzip them. I wrote a little useful jsfiddle for this, [CHECK IT OUT](https://jsfiddle.net/s00500/yvLbhuuv/)
2017-05-18 23:08:17 +00:00
# Contribute
2017-11-13 10:17:58 +00:00
Liked this Library? You can **support** me by sending me a :coffee: [Coffee](https://paypal.me/lukasbachschwell/3).