Web Server

API Reference

class WebServer : public StoringController, public Component, public AsyncWebHandler

This class allows users to create a web server with their ESP nodes.

Behind the scenes it’s using AsyncWebServer to set up the server. It exposes 3 things: an index page under ‘/’ that’s used to show a simple web interface (the css/js is hosted by esphomelib.com by default), an event source under ‘/events’ that automatically sends all state updates in real time + the debug log. Lastly, there’s an REST API available under the ‘/light/…’, ‘/sensor/…’, … URLs. A full documentation for this API can be found under https://esphomelib.com/web-api/index.html.

Additionally, the web server is advertised via mDNS.

Public Functions

WebServer(uint16_t port)

Initialize the web server with the specified port.

void set_css_url(const char *css_url)

Set the URL to the CSS <link> that’s sent to each client.

Defaults to https://esphomelib.com/_static/webserver-v1.min.css

  • css_url: The url to the web server stylesheet.

void set_js_url(const char *js_url)

Set the URL to the script that’s embedded in the index page.

Defaults to https://esphomelib.com/_static/webserver-v1.min.js

  • js_url: The url to the web server script.

void set_port(uint16_t port)

Set the web server port.

void setup()

Setup the internal web server and register handlers.

void dump_config()
float get_setup_priority() const

MQTT setup priority.

void handle_index_request(AsyncWebServerRequest *request)

Handle an index request under ‘/’.

void handle_update_request(AsyncWebServerRequest *request)
void register_sensor(sensor::Sensor *obj)

Internally register a sensor and set a callback on state changes.

void handle_sensor_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a sensor request under ‘/sensor/<id>’.

std::string sensor_json(sensor::Sensor *obj, float value)

Dump the sensor state with its value as a JSON string.

void register_switch(switch_::Switch *obj)

Internally register a switch and set a callback on state changes.

void handle_switch_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a switch request under ‘/switch/<id>/</turn_on/turn_off/toggle>’.

std::string switch_json(switch_::Switch *obj, bool value)

Dump the switch state with its value as a JSON string.

void register_binary_sensor(binary_sensor::BinarySensor *obj)

Internally register a binary sensor and set a callback on state changes.

void handle_binary_sensor_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a binary sensor request under ‘/binary_sensor/<id>’.

std::string binary_sensor_json(binary_sensor::BinarySensor *obj, bool value)

Dump the binary sensor state with its value as a JSON string.

void register_fan(fan::FanState *obj)

Internally register a fan and set a callback on state changes.

void handle_fan_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a fan request under ‘/fan/<id>/</turn_on/turn_off/toggle>’.

std::string fan_json(fan::FanState *obj)

Dump the fan state as a JSON string.

void register_light(light::LightState *obj)

Internally register a light and set a callback on state changes.

void handle_light_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a light request under ‘/light/<id>/</turn_on/turn_off/toggle>’.

std::string light_json(light::LightState *obj)

Dump the light state as a JSON string.

void register_text_sensor(text_sensor::TextSensor *obj)

Internally register a text sensor and set a callback on state changes.

void handle_text_sensor_request(AsyncWebServerRequest *request, UrlMatch match)

Handle a text sensor request under ‘/text_sensor/<id>’.

std::string text_sensor_json(text_sensor::TextSensor *obj, const std::string &value)

Dump the text sensor state with its value as a JSON string.

bool canHandle(AsyncWebServerRequest *request)

Override the web handler’s canHandle method.

void handleRequest(AsyncWebServerRequest *request)

Override the web handler’s handleRequest method.

void handleUpload(AsyncWebServerRequest *request, const String &filename, size_t index, uint8_t *data, size_t len, bool final)
bool isRequestHandlerTrivial()

This web handle is not trivial.

Protected Attributes

uint16_t port_
AsyncWebServer *server_
AsyncEventSource events_ = {"/events"}
const char *css_url_ = {nullptr}
const char *js_url_ = {nullptr}
uint32_t last_ota_progress_ = {0}
uint32_t ota_read_length_ = {0}
struct UrlMatch

Internal helper struct that is used to parse incoming URLs.

Public Members

std::string domain

The domain of the component, for example “sensor”.

std::string id

The id of the device that’s being accessed, for example “living_room_fan”.

std::string method

The method that’s being called, for example “turn_on”.

bool valid

Whether this match is valid.