esphome-docs/components/web_server.rst

87 lines
3.3 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Web Server Component
====================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up a web server in ESPHome.
:image: http.png
2018-11-14 22:12:27 +01:00
:keywords: web server, http, REST API
2018-05-13 11:37:02 +02:00
The ``web_server`` component creates a simple web server on the node that can be accessed
through any browser and a simple `REST API`_. Please note that enabling this component
will take up *a lot* of memory and can lead to problems, especially on the ESP8266.
To navigate to the web server in your browser, either use the IP address of the node or
use ``<node_name>.local/`` (note the trailing forward slash) via mDNS.
To conserve flash size, the CSS and JS files used on the root page to show a simple user
2019-02-16 23:25:23 +01:00
interface are hosted by esphome.io. If you want to use your own service, use the
2018-05-13 11:37:02 +02:00
``css_url`` and ``js_url`` options in your configuration.
.. _REST API: /web-api/index.html
.. figure:: /components/images/web_server.png
2018-05-13 11:37:02 +02:00
:align: center
Example web server frontend.
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
# Example configuration entry
web_server:
port: 80
2018-05-13 11:37:02 +02:00
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
- **port** (*Optional*, int): The port the web server should open its socket on.
- **css_url** (*Optional*, url): The URL that should be used for the CSS stylesheet. Defaults
to https://esphome.io/_static/webserver-v1.min.css (updates will go to ``v2``, ``v3``, etc). Can be set to empty string.
- **css_include** (*Optional*, local file): Path to local file to be included in web server index page.
Contents of this file will be served as ``/0.css`` and used as CSS stylesheet by internal webserver.
Useful when building device without internet access, where you want to use built-in AP and webserver.
2018-06-01 18:10:00 +02:00
- **js_url** (*Optional*, url): The URL that should be used for the JS script. Defaults
to https://esphome.io/_static/webserver-v1.min.js. Can be set to empty string.
- **js_include** (*Optional*, local file): Path to local file to be included in web server index page.
Contents of this file will be served as ``/0.js`` and used as JS script by internal webserver.
Useful when building device without internet access, where you want to use built-in AP and webserver.
- **auth** (*Optional*): Enables basic authentication with username and password.
- **username** (**Required**, string): The username to use for authentication.
- **password** (**Required**, string): The password to check for authentication.
2018-06-01 18:10:00 +02:00
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2018-11-09 20:06:40 +01:00
.. note::
Example web_server configuration using HTTP authentication:
.. code-block:: yaml
# Example configuration entry
web_server:
port: 80
auth:
username: admin
password: !secret web_server_password
2018-11-09 20:06:40 +01:00
Example web_server configuration with CSS and JS included from esphome-docs.
CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface.
.. code-block:: yaml
# Example configuration entry
web_server:
port: 80
css_include: "../../../esphome-docs/_static/webserver-v1.min.css"
css_url: ""
js_include: "../../../esphome-docs/_static/webserver-v1.min.js"
js_url: ""
2018-06-01 18:10:00 +02:00
See Also
--------
2019-05-12 22:44:59 +02:00
- :apiref:`web_server/web_server.h`
2020-07-27 12:06:56 +02:00
- :doc:`prometheus`
- :ghedit:`Edit`