Skip to main content

Developing Micro Web Pages for ESP8266

ESP8266 is a WiFi module that can be programmed to serve web pages. The capability is similar to a typical WiFi router serving its own administrative web pages. We can hack a WiFi router with OpenWRT or we can just program ESP8266.

The server-side example codes can be found at the micro-api framework repo. Here we are going to prepare for the client-side development.

ESP8266 is a general purpose WiFi module where the web pages can be more than just administrative. However, due to the limited resources of ESP8266 the processes should be mostly pushed to the client side. See libesphttpd and Micro API.


Localhost


Our web server will be based on libesphttpd. It comes with a tiny read-only file system (espfs) and a utility to pack the entire web file structure into a single blob file which is to be flashed into ESP8266. The web server will serve the files just like any other web server.

We need to set up a localhost web server and start developing for the client side. We can use any web framework. We can use Javascript, CSS, images, etc. They will all run at the client side. However, we need to observe the total file size so that they will fit into ESP8266. And we need to minimize the processes on the server so that to lessen the burden of the ESP8266 module. Make use of the micro API framework.

Do develop and test as much as possible on localhost. Once we are satisfied with the web pages than we can pack them into a blob and flash it into ESP8266. Then we can continue with further development, integration and testing.


Web Pages Blob


 mkespfsimage is the utility to pack the entire web file structure into a blob file. It is a bit primitive. It makes use of the find command to list all the files in a given folder. And then pipes the list to the utility which will print out the blob into stdout. We need to redirect the output into a file.

$ find | mkespfsimage > webpages.espfs

mkespfsimage can be found within our libesphttpd installation at

libesphttpd/espfs/mkespfsimage/mkespfsimage.

Make sure that the find command is executed from within our web folder. We can have something like the following in our makefile:

webpages: $(WEBDIR)/webpages.espfs

 $(WEBDIR)/webpages.espfs:
    cd $(WEBDIR); \
    find ! -name 'webpages.espfs' | $(ESPFS)/mkespfsimage > webpages.espfs; \
    cd -


Notice that we can tell find not to include the blob file webpages.espfs. The command line 'cd -' means to go back to the previous folder.

To make the web pages blob file:

$ make webpages

The webpages.espfs file will be created in the web folder.


Flashing Web Pages Blob


We need to be prepared with the address to flash the web pages blob into. It depends on our ESP8266 flash size and our code size. We don't want to overlap our codes with the blob and causes unpredictable run time errors. And the address for the blob must start at a sector of 4 kB, above the codes. See the notes on ESP8266's flash.

ESPFS_ADDR = 0x200000
ESPFS_SIZE = 0x100000

webpages_flash: $(WEBDIR)/webpages.espfs
    if [ $$(stat -c '%s' $(WEBDIR)/webpages.espfs) -gt $$(( $(ESPFS_SIZE) )) ]; then echo "webpages.espfs too big!"; false; fi
    esptool.py write_flash $(ESPFS_ADDR) $(WEBDIR)/webpages.espfs

In the makefile sample above it will check the size of the blob before flashing it into ESP8266.

To flash the web pages blob file:

$ make webpages_flash


Serving Web Pages


We are going to extend the micro api sample code so that it will serve our web pages. Add a line with cgiEspFsHook:

static HttpdBuiltInUrl builtInUrls[] = {
    {"/api.cgi", cgiApi, NULL},
    {"*", cgiEspFsHook, NULL},
    {NULL, NULL, NULL}
};

And initialize the file system:

#define ESPFS_POS 0x200000

void ICACHE_FLASH_ATTR user_init()
{
    ...

     captdnsInit();

     // 0x40200000 is the base address for spi flash memory mapping, ESPFS_POS is the position
    // where image is written in flash that is defined in Makefile.
    espFsInit((void*)(0x40200000 + ESPFS_POS));

     httpdInit(builtInUrls, 80);

    ...
}


Heatshrink


The web files blob will be compressed with heatshrink. It is the default behavior. However, the heatshrink decoder's codes are not wrapped with ICACHE_FLASH_ATTR. Hence, it will use up the iRAM segment and squeeze our code. We may need to rebuild libesphttpd to disable heatshrink by setting USE_HEATSHRINK to no in the makefile.  


Comments

Post a Comment

Popular posts from this blog

Setting Up PyScripter for Quantum GIS

PyScripter is a general purpose Python Integrated Development Environment (IDE). Quantum GIS (QGIS) is a desktop GIS application that can be extended with Python plugins. Both are open source softwares. We intend to use PyScripter as an IDE to build QGIS Python plugin. We are using PyScripter 2.4.1.0 and QGIS 1.6.0 in Windows. PyScripter does not come with Python. On the other hand, QGIS is built in with Python. Thus, we will setup up PyScripter to use the build in Python in QGIS. We assume both PyScripter and QGIS are already installed. Preparing PyScripter batch file We assume that QGIS is installed in C:\OSGeo4W\ folder and PyScripter is installed in C:\Program Files\PyScripter\ . 1. Copy qgis.bat in C:\OSGeo4W\ bin to pyscripter.bat 2. Edit pyscripter.bat to remove the last line that read something like this start "Quantum GIS" /B "%OSGEO4W_ROOT%"\apps\qgis\bin\qgis.exe %* and replace it with this in one line Start "PyScripter" /B "C:\Progr...
8 comments
Read more

Using React in Foundation for Sites

This post was the precursor to the Foundation-React Template . React and Foundation are two different web UI frameworks addressing different needs. They evolve differently. Both of them are powerful on their own accord. Fusing them together may create superpower. We will walk through the process of adding React into Foundation. We will start by installing both Foundation and React through command line interface (CLI). Then we will create a simple Todo web app. Along the way we will highlight the development process. But before all that, let us summarize React and Foundation. The details can be found at their respective websites. Both of them are well documented. React is a run-time UI rendering engine. It renders dynamic UI elements in its own fast virtual DOM, and only update necessary changes to the slow browser DOM. This behaves like a  double buffering DOM which makes any UI update feels fast. React wraps a UI rendering script in a component. A React component can ...
Post a Comment
Read more

Debugging PHP using Apache Error Log

PHP runs on the server side and behaves like a function that return a value against the given arguments. A remote client may call this function and expect a specified return value and nothing else. So how do we debug this function ? It must not return debugging messages since the client is never designed to handle them. We must never burden any client to handle debugging messages. If we run PHP through Apache server then we can use the error log to keep our debugging messages. It may not be the best way to do it. But we only want to talk about this approach now. Error Logs The Apache error log files generally can be found in the following directory: var/log/apache2 We issue the following command from within the directory to read the latest error messages: # tail error.log The tail command reads the last few lines from the error.log file and prints them on the terminal. If we need to read a specific number of lines from the end of the file then we can specify the -n opti...
Post a Comment
Read more