Skip to content

DS_CAP_WEBSERVER

Jump to bottom
Denis Stepanov edited this page Aug 31, 2023 · 12 revisions

DS_CAP_WEBSERVER — Web Server

Description

This capability adds support for a web server. The following fields are implemented:

Field Description Default Value
ESP8266WebServer System::web_server Web server (empty)
String System::web_page Web page buffer (empty)
void (*System::registerWebPages)() Hook for registering user-supplied pages nullptr

Web server is implemented by ESP8266WebServer Arduino Core class. web_server is a web server instance which gives you full access to the native API. To construct web pages (one at a time), a dedicated field web_page could be used. web_page has a pre-allocated buffer of 2048 bytes, meaning you can use += operator efficiently as long as you stay below 2 kiB page size. Exceeding it will not result in an error, but web_page will claim more memory. If you want to change the default pre-allocation, define additionally a DS_MAX_WEB_PAGE_SIZE macro. Setting it to 0 will disable pre-allocation altogether.

To inform web server of the pages to serve, a void registerPages() function has to be created and hooked up to the registerWebPages field:

void (*System::registerWebPages)() = registerPages;

This can be done in a global section, or in setup() (before calling System::begin()). Inside the function, a native ESP8266WebServer method of registering page should be used, i.e.:

System::web_server.on("/", serveRoot);

The following methods are available to assist with web page construction:

// Add standard header to the web page
void System::pushHTMLHeader(const String& title = "", const String& head_user = "", bool redirect = false);
void System::pushHTMLFooter();                   // Add standard footer to the web page
void System::sendWebPage();                      // Send a web page

Similarly to the native API, each web page has to be provided using dedicated function with void func() signature. Within the function, a typical page construction process would look as follows:

  1. create a page header with the help of pushHTMLHeader() function;
  2. add your own content using web_page += ... construct;
  3. add a page footer with the help of pushHTMLFooter() function;
  4. send the resulting web page with the help of sendWebPage() function.

See the complete example in the Usage section below.

pushHTMLHeader() will initialize web_page buffer with a predefined page header. Among other things, the header will include viewport property to make pages look nice on a mobile phone. If a title is specified, it will be used as a page title. If file system is enabled, and favicon file is present, it will be referred to. If redirect is specified, the page will jump to root page / after 5 seconds delay. This is useful when creating small confirmation pages in response to some user actions. Finally, head_user is any other header content which needs to be inserted in the page header, such as custom styles. The last tag placed in web_page buffer by this function is <body>, after which user content can be added.

pushHTMLFooter() does no more than just closing the <body> section. A horizontal rule is inserted at the bottom of the page. This could be useful, as sometimes controller may get overloaded and send only portion of the page; the rule allows recognizing such cases more easily.

sendWebPage() sends contents of web_page to the client. If DS_MAX_WEB_PAGE_SIZE macro has been set to 0, this function will also release memory from the web_page buffer. This can be also achieved at arbitrary moment of time by direct reset:

System::web_page = String();

Note that assigning empty string "" to the buffer will not release memory.

Favicon file must be called favicon.png, be of a PNG type and provide an icon of 192x192 px. You can load it to the file system root folder using ESP8266 LittleFS plugin. This operation will erase any other information on the file system.

Web server will automatically serve a "System Information" page on /about URL. If you want to inform user about it, you need to add a link onto your own pages. The page provides a lot of information about controller configuration; the exact output depends on the capabilities that have been enabled. Lines that are always provided include:

  • CPU and flash memory information;
  • memory heap status;
  • ESP8266 Arduino Core components version;
  • version of DS-System library and the list of enabled capabilities.

Example of an information page:

About

If application log is enabled, a /log page containing log browser will be served. See the capability description for more information.

If user-configurable timers are enabled, additional pages /timers and /timers-save will be served to support this capability. See the capability description for more information.

In absence of a user-configured root page /, the library will serve a stub page linking to all other active pages according to the configured capabilities.

Requires

Cooperates With

  • DS_CAP_APP_LOG — if application log is enabled, additional page /log will be activated to browse the log;
  • DS_CAP_WEB_TIMERS — if user-configured timers are enabled, additional pages /timers and /timers-save will be served to capture timer configuration;
  • DS_CAP_SYS_FS — if file system is enabled, a favicon file /favicon.png will be automatically probed and served if present;
  • DS_CAP_SYS_LOG — if syslog is enabled, served pages will be logged along with the IP-address of the client;
  • DS_CAP_WIFIMANAGER — since Wi-Fi manager brings its own web server, the existing web server will shut down for the time that the manager is active, in order to avoid conflict.

Many capabilities, when enabled, contribute status lines to the "System Information" page.

Conflicts With

None.

Usage

MySystem.h:

#define DS_CAP_SYS_NETWORK  // Enable network
#define DS_CAP_WEBSERVER    // Enable web server

#include "System.h"         // System global definitions

sketch.ino:

#include "MySystem.h"

using namespace ds;

// Home page
void serveRoot() {
    System::pushHTMLHeader("My Home Page");
    System::web_page += "<p>Hello, world!</p>";
    System::pushHTMLFooter();
    System::sendWebPage();
}

// Let the web server know we have a page to serve
void registerPages() {
    System::web_server.on("/", serveRoot);
    // .. more pages
}
void (*System::registerWebPages)() = registerPages;

void setup() {
    System::begin();
}

void loop() {
    System::update();
}

To avoid cluttering the main sketch with bulky web pages code, it is often convenient to split it into a separate web.cpp file next to the .ino file. Arduino IDE will automatically compile and link it to the sketch.

Mandatory Calls

System::begin() Required
System::update() Required

Examples

Bugs

  • Page headers and footers support only limited customization. In particular, external CSS is not supported. If you are not satisfied with the default appearance, edit System.cpp directly;
  • The function registering web pages by assignment to System::registerWebPages cannot itself be named void registerWebPages(). This will compile and run, but not work for an obscure reason. Any other name is fine.

Availability

Version 1.0 or later.

Default root page is provided from version 1.1.

Macro DS_MAX_WEB_PAGE_SIZE is available from version 1.2.

See Also

None.

Home

Capabilities

Clone this wiki locally