ESPHome  2022.6.2
Public Member Functions | Protected Attributes
esphome::web_server::WebServer Class Reference

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

#include <web_server.h>

Inheritance diagram for esphome::web_server::WebServer:
esphome::Controller esphome::Component

Public Member Functions

 WebServer (web_server_base::WebServerBase *base)
 
void set_css_url (const char *css_url)
 Set the URL to the CSS <link> that's sent to each client. More...
 
void set_css_include (const char *css_include)
 Set local path to the script that's embedded in the index page. More...
 
void set_js_url (const char *js_url)
 Set the URL to the script that's embedded in the index page. More...
 
void set_js_include (const char *js_include)
 Set local path to the script that's embedded in the index page. More...
 
void set_include_internal (bool include_internal)
 Determine whether internal components should be displayed on the web server. More...
 
void set_allow_ota (bool allow_ota)
 Set whether or not the webserver should expose the OTA form and handler. More...
 
void setup () override
 Setup the internal web server and register handlers. More...
 
void loop () override
 
void dump_config () override
 
float get_setup_priority () const override
 MQTT setup priority. More...
 
void handle_index_request (AsyncWebServerRequest *request)
 Handle an index request under '/'. More...
 
void handle_css_request (AsyncWebServerRequest *request)
 Handle included css request under '/0.css'. More...
 
void handle_js_request (AsyncWebServerRequest *request)
 Handle included js request under '/0.js'. More...
 
void on_sensor_update (sensor::Sensor *obj, float state) override
 
void handle_sensor_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a sensor request under '/sensor/<id>'. More...
 
std::string sensor_json (sensor::Sensor *obj, float value, JsonDetail start_config)
 Dump the sensor state with its value as a JSON string. More...
 
void on_switch_update (switch_::Switch *obj, bool state) override
 
void handle_switch_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a switch request under '/switch/<id>/</turn_on/turn_off/toggle>'. More...
 
std::string switch_json (switch_::Switch *obj, bool value, JsonDetail start_config)
 Dump the switch state with its value as a JSON string. More...
 
void handle_button_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a button request under '/button/<id>/press'. More...
 
std::string button_json (button::Button *obj, JsonDetail start_config)
 Dump the button details with its value as a JSON string. More...
 
void on_binary_sensor_update (binary_sensor::BinarySensor *obj, bool state) override
 
void handle_binary_sensor_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a binary sensor request under '/binary_sensor/<id>'. More...
 
std::string binary_sensor_json (binary_sensor::BinarySensor *obj, bool value, JsonDetail start_config)
 Dump the binary sensor state with its value as a JSON string. More...
 
void on_fan_update (fan::Fan *obj) override
 
void handle_fan_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a fan request under '/fan/<id>/</turn_on/turn_off/toggle>'. More...
 
std::string fan_json (fan::Fan *obj, JsonDetail start_config)
 Dump the fan state as a JSON string. More...
 
void on_light_update (light::LightState *obj) override
 
void handle_light_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a light request under '/light/<id>/</turn_on/turn_off/toggle>'. More...
 
std::string light_json (light::LightState *obj, JsonDetail start_config)
 Dump the light state as a JSON string. More...
 
void on_text_sensor_update (text_sensor::TextSensor *obj, const std::string &state) override
 
void handle_text_sensor_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a text sensor request under '/text_sensor/<id>'. More...
 
std::string text_sensor_json (text_sensor::TextSensor *obj, const std::string &value, JsonDetail start_config)
 Dump the text sensor state with its value as a JSON string. More...
 
void on_cover_update (cover::Cover *obj) override
 
void handle_cover_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a cover request under '/cover/<id>/<open/close/stop/set>'. More...
 
std::string cover_json (cover::Cover *obj, JsonDetail start_config)
 Dump the cover state as a JSON string. More...
 
void on_number_update (number::Number *obj, float state) override
 
void handle_number_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a number request under '/number/<id>'. More...
 
std::string number_json (number::Number *obj, float value, JsonDetail start_config)
 Dump the number state with its value as a JSON string. More...
 
void on_select_update (select::Select *obj, const std::string &state, size_t index) override
 
void handle_select_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a select request under '/select/<id>'. More...
 
std::string select_json (select::Select *obj, const std::string &value, JsonDetail start_config)
 Dump the select state with its value as a JSON string. More...
 
void on_climate_update (climate::Climate *obj) override
 
void handle_climate_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a climate request under '/climate/<id>'. More...
 
std::string climate_json (climate::Climate *obj, JsonDetail start_config)
 Dump the climate details. More...
 
void on_lock_update (lock::Lock *obj) override
 
void handle_lock_request (AsyncWebServerRequest *request, const UrlMatch &match)
 Handle a lock request under '/lock/<id>/</lock/unlock/open>'. More...
 
std::string lock_json (lock::Lock *obj, lock::LockState value, JsonDetail start_config)
 Dump the lock state with its value as a JSON string. More...
 
bool canHandle (AsyncWebServerRequest *request) override
 Override the web handler's canHandle method. More...
 
void handleRequest (AsyncWebServerRequest *request) override
 Override the web handler's handleRequest method. More...
 
bool isRequestHandlerTrivial () override
 This web handle is not trivial. More...
 
- Public Member Functions inherited from esphome::Controller
void setup_controller (bool include_internal=false)
 
virtual void on_media_player_update (media_player::MediaPlayer *obj)
 
- Public Member Functions inherited from esphome::Component
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop(). More...
 
void call ()
 
virtual void on_shutdown ()
 
virtual void on_safe_shutdown ()
 
uint32_t get_component_state () const
 
virtual void mark_failed ()
 Mark this component as failed. More...
 
bool is_failed ()
 
virtual bool can_proceed ()
 
bool status_has_warning ()
 
bool status_has_error ()
 
void status_set_warning ()
 
void status_set_error ()
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const std::string &name, uint32_t length=5000)
 
void status_momentary_error (const std::string &name, uint32_t length=5000)
 
bool has_overridden_loop () const
 
void set_component_source (const char *source)
 Set where this component was loaded from for some debug messages. More...
 
const char * get_component_source () const
 Get the integration where this component was declared as a string. More...
 

Protected Attributes

friend ListEntitiesIterator
 
web_server_base::WebServerBasebase_
 
AsyncEventSource events_ {"/events"}
 
ListEntitiesIterator entities_iterator_
 
const char * css_url_ {nullptr}
 
const char * css_include_ {nullptr}
 
const char * js_url_ {nullptr}
 
const char * js_include_ {nullptr}
 
bool include_internal_ {false}
 
bool allow_ota_ {true}
 
- Protected Attributes inherited from esphome::Component
uint32_t component_state_ {0x0000}
 State of this component. More...
 
float setup_priority_override_ {NAN}
 
const char * component_source_ = nullptr
 

Additional Inherited Members

- Protected Member Functions inherited from esphome::Component
virtual void call_loop ()
 
virtual void call_setup ()
 
virtual void call_dump_config ()
 
void set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name. More...
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const std::string &name)
 Cancel an interval function. More...
 
void set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult()> &&f, float backoff_increase_factor=1.0f)
 Set an retry function with a unique name. More...
 
void set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult()> &&f, float backoff_increase_factor=1.0f)
 
bool cancel_retry (const std::string &name)
 Cancel a retry function. More...
 
void set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name. More...
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const std::string &name)
 Cancel a timeout function. More...
 
void defer (const std::string &name, std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
bool cancel_defer (const std::string &name)
 Cancel a defer callback using the specified name, name must not be empty. More...
 

Detailed Description

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 esphome.io 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://esphome.io/web-api/index.html.

Definition at line 35 of file web_server.h.

Constructor & Destructor Documentation

◆ WebServer()

esphome::web_server::WebServer::WebServer ( web_server_base::WebServerBase base)
inline

Definition at line 37 of file web_server.h.

Member Function Documentation

◆ binary_sensor_json()

std::string esphome::web_server::WebServer::binary_sensor_json ( binary_sensor::BinarySensor obj,
bool  value,
JsonDetail  start_config 
)

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

Definition at line 455 of file web_server.cpp.

◆ button_json()

std::string esphome::web_server::WebServer::button_json ( button::Button obj,
JsonDetail  start_config 
)

Dump the button details with its value as a JSON string.

Definition at line 429 of file web_server.cpp.

◆ canHandle()

bool esphome::web_server::WebServer::canHandle ( AsyncWebServerRequest *  request)
override

Override the web handler's canHandle method.

Definition at line 948 of file web_server.cpp.

◆ climate_json()

std::string esphome::web_server::WebServer::climate_json ( climate::Climate obj,
JsonDetail  start_config 
)

Dump the climate details.

Definition at line 838 of file web_server.cpp.

◆ cover_json()

std::string esphome::web_server::WebServer::cover_json ( cover::Cover obj,
JsonDetail  start_config 
)

Dump the cover state as a JSON string.

Definition at line 667 of file web_server.cpp.

◆ dump_config()

void esphome::web_server::WebServer::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 124 of file web_server.cpp.

◆ fan_json()

std::string esphome::web_server::WebServer::fan_json ( fan::Fan obj,
JsonDetail  start_config 
)

Dump the fan state as a JSON string.

Definition at line 474 of file web_server.cpp.

◆ get_setup_priority()

float esphome::web_server::WebServer::get_setup_priority ( ) const
overridevirtual

MQTT setup priority.

Reimplemented from esphome::Component.

Definition at line 128 of file web_server.cpp.

◆ handle_binary_sensor_request()

void esphome::web_server::WebServer::handle_binary_sensor_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

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

Definition at line 460 of file web_server.cpp.

◆ handle_button_request()

void esphome::web_server::WebServer::handle_button_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a button request under '/button/<id>/press'.

Definition at line 434 of file web_server.cpp.

◆ handle_climate_request()

void esphome::web_server::WebServer::handle_climate_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a climate request under '/climate/<id>'.

Definition at line 784 of file web_server.cpp.

◆ handle_cover_request()

void esphome::web_server::WebServer::handle_cover_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a cover request under '/cover/<id>/<open/close/stop/set>'.

Definition at line 626 of file web_server.cpp.

◆ handle_css_request()

void esphome::web_server::WebServer::handle_css_request ( AsyncWebServerRequest *  request)

Handle included css request under '/0.css'.

Definition at line 309 of file web_server.cpp.

◆ handle_fan_request()

void esphome::web_server::WebServer::handle_fan_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

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

Definition at line 486 of file web_server.cpp.

◆ handle_index_request()

void esphome::web_server::WebServer::handle_index_request ( AsyncWebServerRequest *  request)

Handle an index request under '/'.

Definition at line 131 of file web_server.cpp.

◆ handle_js_request()

void esphome::web_server::WebServer::handle_js_request ( AsyncWebServerRequest *  request)

Handle included js request under '/0.js'.

Definition at line 320 of file web_server.cpp.

◆ handle_light_request()

void esphome::web_server::WebServer::handle_light_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

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

Definition at line 547 of file web_server.cpp.

◆ handle_lock_request()

void esphome::web_server::WebServer::handle_lock_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a lock request under '/lock/<id>/</lock/unlock/open>'.

Definition at line 922 of file web_server.cpp.

◆ handle_number_request()

void esphome::web_server::WebServer::handle_number_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a number request under '/number/<id>'.

Definition at line 683 of file web_server.cpp.

◆ handle_select_request()

void esphome::web_server::WebServer::handle_select_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a select request under '/select/<id>'.

Definition at line 737 of file web_server.cpp.

◆ handle_sensor_request()

void esphome::web_server::WebServer::handle_sensor_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

Handle a sensor request under '/sensor/<id>'.

Definition at line 351 of file web_server.cpp.

◆ handle_switch_request()

void esphome::web_server::WebServer::handle_switch_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

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

Definition at line 402 of file web_server.cpp.

◆ handle_text_sensor_request()

void esphome::web_server::WebServer::handle_text_sensor_request ( AsyncWebServerRequest *  request,
const UrlMatch match 
)

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

Definition at line 375 of file web_server.cpp.

◆ handleRequest()

void esphome::web_server::WebServer::handleRequest ( AsyncWebServerRequest *  request)
override

Override the web handler's handleRequest method.

Definition at line 1027 of file web_server.cpp.

◆ isRequestHandlerTrivial()

bool esphome::web_server::WebServer::isRequestHandlerTrivial ( )
override

This web handle is not trivial.

Definition at line 1134 of file web_server.cpp.

◆ light_json()

std::string esphome::web_server::WebServer::light_json ( light::LightState obj,
JsonDetail  start_config 
)

Dump the light state as a JSON string.

Definition at line 605 of file web_server.cpp.

◆ lock_json()

std::string esphome::web_server::WebServer::lock_json ( lock::Lock obj,
lock::LockState  value,
JsonDetail  start_config 
)

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

Definition at line 916 of file web_server.cpp.

◆ loop()

void esphome::web_server::WebServer::loop ( )
overridevirtual

Reimplemented from esphome::Component.

Definition at line 123 of file web_server.cpp.

◆ number_json()

std::string esphome::web_server::WebServer::number_json ( number::Number obj,
float  value,
JsonDetail  start_config 
)

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

Definition at line 713 of file web_server.cpp.

◆ on_binary_sensor_update()

void esphome::web_server::WebServer::on_binary_sensor_update ( binary_sensor::BinarySensor obj,
bool  state 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 452 of file web_server.cpp.

◆ on_climate_update()

void esphome::web_server::WebServer::on_climate_update ( climate::Climate obj)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 780 of file web_server.cpp.

◆ on_cover_update()

void esphome::web_server::WebServer::on_cover_update ( cover::Cover obj)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 623 of file web_server.cpp.

◆ on_fan_update()

void esphome::web_server::WebServer::on_fan_update ( fan::Fan obj)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 473 of file web_server.cpp.

◆ on_light_update()

void esphome::web_server::WebServer::on_light_update ( light::LightState obj)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 544 of file web_server.cpp.

◆ on_lock_update()

void esphome::web_server::WebServer::on_lock_update ( lock::Lock obj)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 913 of file web_server.cpp.

◆ on_number_update()

void esphome::web_server::WebServer::on_number_update ( number::Number obj,
float  state 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 680 of file web_server.cpp.

◆ on_select_update()

void esphome::web_server::WebServer::on_select_update ( select::Select obj,
const std::string &  state,
size_t  index 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 734 of file web_server.cpp.

◆ on_sensor_update()

void esphome::web_server::WebServer::on_sensor_update ( sensor::Sensor obj,
float  state 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 348 of file web_server.cpp.

◆ on_switch_update()

void esphome::web_server::WebServer::on_switch_update ( switch_::Switch obj,
bool  state 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 394 of file web_server.cpp.

◆ on_text_sensor_update()

void esphome::web_server::WebServer::on_text_sensor_update ( text_sensor::TextSensor obj,
const std::string &  state 
)
overridevirtual

Reimplemented from esphome::Controller.

Definition at line 372 of file web_server.cpp.

◆ select_json()

std::string esphome::web_server::WebServer::select_json ( select::Select obj,
const std::string &  value,
JsonDetail  start_config 
)

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

Definition at line 766 of file web_server.cpp.

◆ sensor_json()

std::string esphome::web_server::WebServer::sensor_json ( sensor::Sensor obj,
float  value,
JsonDetail  start_config 
)

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

Definition at line 361 of file web_server.cpp.

◆ set_allow_ota()

void esphome::web_server::WebServer::set_allow_ota ( bool  allow_ota)
inline

Set whether or not the webserver should expose the OTA form and handler.

Parameters
allow_ota.

Definition at line 75 of file web_server.h.

◆ set_css_include()

void esphome::web_server::WebServer::set_css_include ( const char *  css_include)

Set local path to the script that's embedded in the index page.

Defaults to

Parameters
css_includeLocal path to web server script.

Definition at line 87 of file web_server.cpp.

◆ set_css_url()

void esphome::web_server::WebServer::set_css_url ( const char *  css_url)

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

Defaults to https://esphome.io/_static/webserver-v1.min.css

Parameters
css_urlThe url to the web server stylesheet.

Definition at line 86 of file web_server.cpp.

◆ set_include_internal()

void esphome::web_server::WebServer::set_include_internal ( bool  include_internal)
inline

Determine whether internal components should be displayed on the web server.

Defaults to false.

Parameters
include_internalWhether internal components should be displayed.

Definition at line 70 of file web_server.h.

◆ set_js_include()

void esphome::web_server::WebServer::set_js_include ( const char *  js_include)

Set local path to the script that's embedded in the index page.

Defaults to

Parameters
js_includeLocal path to web server script.

Definition at line 89 of file web_server.cpp.

◆ set_js_url()

void esphome::web_server::WebServer::set_js_url ( const char *  js_url)

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

Defaults to https://esphome.io/_static/webserver-v1.min.js

Parameters
js_urlThe url to the web server script.

Definition at line 88 of file web_server.cpp.

◆ setup()

void esphome::web_server::WebServer::setup ( )
overridevirtual

Setup the internal web server and register handlers.

Reimplemented from esphome::Component.

Definition at line 91 of file web_server.cpp.

◆ switch_json()

std::string esphome::web_server::WebServer::switch_json ( switch_::Switch obj,
bool  value,
JsonDetail  start_config 
)

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

Definition at line 397 of file web_server.cpp.

◆ text_sensor_json()

std::string esphome::web_server::WebServer::text_sensor_json ( text_sensor::TextSensor obj,
const std::string &  value,
JsonDetail  start_config 
)

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

Definition at line 385 of file web_server.cpp.

Field Documentation

◆ allow_ota_

bool esphome::web_server::WebServer::allow_ota_ {true}
protected

Definition at line 232 of file web_server.h.

◆ base_

web_server_base::WebServerBase* esphome::web_server::WebServer::base_
protected

Definition at line 224 of file web_server.h.

◆ css_include_

const char* esphome::web_server::WebServer::css_include_ {nullptr}
protected

Definition at line 228 of file web_server.h.

◆ css_url_

const char* esphome::web_server::WebServer::css_url_ {nullptr}
protected

Definition at line 227 of file web_server.h.

◆ entities_iterator_

ListEntitiesIterator esphome::web_server::WebServer::entities_iterator_
protected

Definition at line 226 of file web_server.h.

◆ events_

AsyncEventSource esphome::web_server::WebServer::events_ {"/events"}
protected

Definition at line 225 of file web_server.h.

◆ include_internal_

bool esphome::web_server::WebServer::include_internal_ {false}
protected

Definition at line 231 of file web_server.h.

◆ js_include_

const char* esphome::web_server::WebServer::js_include_ {nullptr}
protected

Definition at line 230 of file web_server.h.

◆ js_url_

const char* esphome::web_server::WebServer::js_url_ {nullptr}
protected

Definition at line 229 of file web_server.h.

◆ ListEntitiesIterator

friend esphome::web_server::WebServer::ListEntitiesIterator
protected

Definition at line 223 of file web_server.h.


The documentation for this class was generated from the following files: