ESPHome  2023.3.2
Public Member Functions | Protected 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 ()
 
bool is_ready ()
 
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 Member Functions

void schedule_ (std::function< void()> &&f)
 
- 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(uint8_t)> &&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(uint8_t)> &&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...
 

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}
 
std::deque< std::function< void()> > to_schedule_
 
SemaphoreHandle_t to_schedule_lock_
 
- 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}
 

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 39 of file web_server.h.

Constructor & Destructor Documentation

◆ WebServer()

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

Definition at line 86 of file web_server.cpp.

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 486 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 460 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 996 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 872 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 698 of file web_server.cpp.

◆ dump_config()

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

Reimplemented from esphome::Component.

Definition at line 150 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 505 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 154 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 491 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 465 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 818 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 657 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 335 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 517 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 157 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 346 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 578 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 970 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 714 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 771 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 377 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 433 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 406 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 1075 of file web_server.cpp.

◆ isRequestHandlerTrivial()

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

This web handle is not trivial.

Definition at line 1182 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 636 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 964 of file web_server.cpp.

◆ loop()

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

Reimplemented from esphome::Component.

Definition at line 131 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 744 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 483 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 814 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 654 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 504 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 575 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 961 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 711 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 768 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 374 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 425 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 403 of file web_server.cpp.

◆ schedule_()

void esphome::web_server::WebServer::schedule_ ( std::function< void()> &&  f)
protected

Definition at line 1184 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 800 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 387 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 79 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 94 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 93 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 74 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 96 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 95 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 98 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 428 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 416 of file web_server.cpp.

Field Documentation

◆ allow_ota_

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

Definition at line 237 of file web_server.h.

◆ base_

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

Definition at line 229 of file web_server.h.

◆ css_include_

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

Definition at line 233 of file web_server.h.

◆ css_url_

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

Definition at line 232 of file web_server.h.

◆ entities_iterator_

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

Definition at line 231 of file web_server.h.

◆ events_

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

Definition at line 230 of file web_server.h.

◆ include_internal_

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

Definition at line 236 of file web_server.h.

◆ js_include_

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

Definition at line 235 of file web_server.h.

◆ js_url_

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

Definition at line 234 of file web_server.h.

◆ ListEntitiesIterator

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

Definition at line 228 of file web_server.h.

◆ to_schedule_

std::deque<std::function<void()> > esphome::web_server::WebServer::to_schedule_
protected

Definition at line 239 of file web_server.h.

◆ to_schedule_lock_

SemaphoreHandle_t esphome::web_server::WebServer::to_schedule_lock_
protected

Definition at line 240 of file web_server.h.


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