A web based setup and configuration module for your MicroPython projects on ESP8266.
The best way to learn how to use MicroSetup is to read
DON'T FORGET TO COPY THE
The access point is named as defined in
device_name during the initialization of the MicroSetup object.
Connect your Wifi compatible device with the access point and enter the IP address into your browser to change the configuration.
MicroSetup uses the Parameter object to store parameters and constraints.
Parameter accepts the following arguments:
param_name: The value for each parameter is loaded into a dict with this value as it's key
display_name: This is the name of the parameter that is shown on the configuration web page
param_type: The data type of your parameter. Default is
MicroSetup.PARAMETER_STRINGadditional supported values are:
decimals: The number of decimals for float types default: 0
min: The lowest allowed value for int and float types
max: The highest allowed value for int and float types
Put all your configuration parametes into a list. This list is later passed to MicroSetup.
Only import MicroSetup where needed to avoid unnessecary memory use.
Create an instance of MicroSetup using the follwoing parameters:
device_settings: A list of parameters, as described in the previous section
device_name: This name is used as the SSID of the device
callback: A function that accepts 1 parameter (a dict with all your settings).
This function is called after the settings where loaded.
debug: Set debug to
Trueto regenerate the HTML files and ignore and overwrite the stored settings. This can be used during development or to reset the devices configuration.
Your settings.cfg file will be loaded automatically if it is present duriong initialization.
You can validate the configuration before it is stored by setting a validator.
Assuming your instance of MicroSetup is called ms you can set your validator function using
ms.validator = function_name before you start the server.
You validator has to accept a dict as an argument (this will contain the configuration for you to validate) and return
True when the validation was successfull or
False when the validation failed.
The server is shutdown during validation, so you can freely use wifi during your validation, as long as you disable it after your use.
Assuming your MicroSetup object is called
ms.start_server(), this call is blocking.
I strongly advice to follow the section about memory efficiency or you will run yourself out of memory very easily!
Only import MicroSetup when it's needed and run
gc.collect() when it isn't in use anymore. Take a look at
example.py for an efficient example.
Call the following after MicroSetup.start_server():
# ms would be your MicroSetup object
from sys import modules
gc.collect() # Use example.py to learn where to put this
MicroSetup only requires a lot of memory (about 25-30KB) when it generates a new config file. Reading an existing configuration only uses around 8KB of RAM.
(You can skip this part if you downloaded the precompiled libraries)
Install mpy-cross if you don't have it already:
pip install mpy-cross
You might need to use
pip3in replacement of
pipdepending on your operating system.
Clone this repository and cd into it's directory:
git clone https://github.com/serious-scribbler/MicroSetup.git; cd MicroSetup
Compile the included version of MicroWebSrv and MicroSetup:
Note that MicroSetup uses a heavily modified version of MicroWebSrv, the original version is incompatible to MicroSetup on ESP8266
python -m mpy_cross -march=xtensa MicroSetup.py python -m mpy_cross -march=xtensa microWebSrv.py
If you are not using Windows, replace
microWebSrv.mpy and the
www/-directory and it's contents to your ESP with your tool of choice.
I use ampy for this purpose:
ampy -p <port> put MicroSetup.mpy
ampy -p <port> put microWebSrv.mpy
ampy -p <port> put www/
Do not forget the www folder, it is very important!
You can now use MicroSetup like you would use any other module
MicroSetup has only been tested on ESP8266, other devices might be compatible.
MicroSetup should be compatible to ESP32, I will test this as soon as possible. I would expect the performance to be quite a bit better than on the ESP8266
_threading, lots of unused getters, everything in connection to pyhtml-templates and some more unused functions from MicroWebSrv to safe memory, modified
Stop() and added better Exception handling to
WriteResponseFilefor debugging purposes.