Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-10-05 05:27:54 +02:00
Code Issues Projects Releases Wiki Activity

Documentation updates for `http_request` component refactor (#3919)

Browse Source 
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Keith Burzinski 2024-06-09 19:36:21 -05:00 committed by GitHub
parent 74b02f0253
commit 876885823f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 87 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
components/http_request.rst
View File

@ -7,7 +7,7 @@ HTTP Request
:keywords: http, request
The ``http_request`` component lets you make HTTP/HTTPS requests. First, you need to setup a component:
The ``http_request`` component lets you make HTTP/HTTPS requests. To do so, you need to add it to your device's configuration:
.. code-block:: yaml
@ -16,34 +16,58 @@ The ``http_request`` component lets you make HTTP/HTTPS requests. First, you nee
useragent: esphome/device
timeout: 10s
.. _http_request-configuration_variables:
Configuration variables:
------------------------
- **useragent** (*Optional*, string): User-Agent header for requests. Defaults to ``ESPHome``.
- **timeout** (*Optional*, :ref:`config-time`): Timeout for request. Defaults to ``5s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **follow_redirects** (*Optional*, boolean): Enable following HTTP redirects. Defaults to ``true``.
- **redirect_limit** (*Optional*, integer): Maximum amount of redirects to follow when enabled. Defaults to ``3``.
- **timeout** (*Optional*, :ref:`config-time`): Timeout for request. Defaults to ``5s``.
- **useragent** (*Optional*, string): User-Agent header for requests. Defaults to
``ESPHome/<version> (https://esphome.io)`` where ``<version>`` is the version of ESPHome the device is running.
For example: ``ESPHome/2024.6.0 (https://esphome.io)``
- **verify_ssl** (*Optional*, boolean): When set to ``true`` (default), SSL/TLS certificates will be validated upon
connection; if invalid, the connection will be aborted. To accomplish this, ESP-IDF's default ESP x509 certificate
bundle is included in the build. This certificate bundle includes the complete list of root certificates from
Mozilla's NSS root certificate store. **May only be set to true when using the ESP-IDF framework; must be explicitly
set to false when using the Arduino framework.**
- **watchdog_timeout** (*Optional*, :ref:`config-time`): Change the watchdog timeout during connection/data transfer.
May be useful on slow connections or connections with high latency. **Do not change this value unless you are
experiencing device reboots due to watchdog timeouts;** doing so may prevent the device from rebooting due to a
legitimate problem. **Only available on ESP32 and RP2040**.
ESP8266 Options:
**For the ESP8266:**
- **esp8266_disable_ssl_support** (*Optional*, boolean): Whether to include SSL support on ESP8266s.
Defaults to ``no``. See :ref:`esphome-esp8266_disable_ssl_support` for more info
- **esp8266_disable_ssl_support** (*Optional*, boolean): Determines whether to include HTTPS/SSL support in the
firmware binary. Excluding the SSL libraries from your build will result in a smaller binary, which may be
necessary for memory-constrained devices (512 kB or 1 MB). If you see
``Error: ESP does not have enough space to store OTA file`` in your device's logs, you may need to enable this
option. Defaults to ``false``. By setting this option to ``true``:
.. _esphome-esp8266_disable_ssl_support:
- HTTPS connections will not be possible
- ``verify_ssl: false`` is implied
``esp8266_disable_ssl_support``
-------------------------------
.. warning::
This options allows you to disable inclusion of SSL libraries. This is required on a flash
constrained devices (512k or 1M) which does not have enough space to support
SSL and OTA concurrently. The flashing will fail with the following error
``Error: ESP does not have enough space to store OTA file``.
Setting ``verify_ssl`` to ``false`` **reduces security** when using HTTPS connections!
Without the root certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the
HTTPS connection up to person-in-the-middle attacks.
To maximize security, do not set ``verify_ssl`` to ``false`` *unless:*
- a custom CA/self-signed certificate is used,
- the Arduino framework is used, or
- the device does not have sufficient memory to store the certificate bundle
**We strongly recommend using hardware which properly supports TLS/SSL.**
HTTP Request Actions
--------------------
Component support a number of :ref:`actions <config-action>` that can be used to send requests.
The ``http_request`` component supports a number of :ref:`actions <config-action>` that can be used to send requests.
.. _http_request-get_action:
@ -59,7 +83,6 @@ This :ref:`action <config-action>` sends a GET request.
url: https://esphome.io
headers:
Content-Type: application/json
verify_ssl: false
on_response:
then:
- logger.log:
@ -70,17 +93,15 @@ This :ref:`action <config-action>` sends a GET request.
# Short form
- http_request.get: https://esphome.io
Configuration variables:
**Configuration variables:**
- **url** (**Required**, string, :ref:`templatable <config-templatable>`): URL to send request.
- **url** (**Required**, string, :ref:`templatable <config-templatable>`): URL to which to send the request.
- **headers** (*Optional*, mapping): Map of HTTP headers. Values are :ref:`templatable <config-templatable>`.
- **verify_ssl** (*Optional*, boolean): Verify the SSL certificate of the endpoint. Defaults to ``true``.
- **on_response** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the request is finished.
.. note::
Currently ESPHome **can't verify the SSL certificate** of the endpoint.
Set ``verify_ssl: false`` to make HTTPS request.
- **capture_response** (*Optional*, boolean): when set to ``true``, the response data will be captured and placed into
the ``body`` variable as a ``std::string`` for use in :ref:`lambdas <config-lambda>`. Defaults to ``false``.
- **max_response_buffer_size** (*Optional*, integer): The maximum buffer size to be used to store the response.
Defaults to ``1 kB``.
- **on_response** (*Optional*, :ref:`Automation <automation>`): An automation to perform after the request is received.
.. _http_request-post_action:
@ -98,14 +119,14 @@ This :ref:`action <config-action>` sends a POST request.
Content-Type: application/json
json:
key: value
verify_ssl: false
# Short form
- http_request.post: https://esphome.io
Configuration variables:
**Configuration variables:**
- **body** (*Optional*, string, :ref:`templatable <config-templatable>`): A HTTP body string to send with request.
- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`templatable <config-templatable>`. See :ref:`http_request-examples`.
- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`templatable <config-templatable>`.
See :ref:`http_request-examples`.
- All other options from :ref:`http_request-get_action`.
.. _http_request-send_action:
@ -124,22 +145,23 @@ This :ref:`action <config-action>` sends a request.
headers:
Content-Type: application/json
body: "Some data"
verify_ssl: false
Configuration variables:
**Configuration variables:**
- **method** (**Required**, string): HTTP method to use (``GET``, ``POST``, ``PUT``, ``DELETE``, ``PATCH``).
- All other options from :ref:`http_request-post_action`.
- All other options from :ref:`http_request-post_action` and :ref:`http_request-get_action`.
.. _http_request-on_response:
``on_response`` Trigger
-----------------------
This automation will be triggered when the HTTP request is finished and will supply these parameters:
This automation will be triggered when the HTTP request is complete.
The following variables are available for use in :ref:`lambdas <config-lambda>`:
* ``status_code`` as ``int`` - http response code
* ``duration_ms`` as ``uint32`` - time taken to complete the request
- ``response`` as a ``HttpContainer`` object which contains ``content_length``, ``status_code`` and ``duration_ms``.
- ``body`` as ``std::string`` which contains the response body when ``capture_response``
(see :ref:`http_request-get_action`) is set to ``true``.
.. code-block:: yaml
@ -147,14 +169,13 @@ This automation will be triggered when the HTTP request is finished and will sup
then:
- http_request.get:
url: https://esphome.io
verify_ssl: false
on_response:
then:
- logger.log:
format: "Response status: %d, Duration: %u ms"
args:
- status_code
- duration_ms
- response.status_code
- response.duration_ms
.. _http_request-examples:
@ -181,15 +202,14 @@ Templatable values
POST Body in JSON format (syntax 1)
***********************************
**Note:** all values of the map should be a strings.
It's impossible to send ``boolean`` or ``numbers`` with this syntax.
**Note:** all values of the map must be strings. It is not possible to send JSON ``boolean`` or ``numbers`` with this
syntax.
.. code-block:: yaml
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json:
key: !lambda |-
return id(my_sensor).state;
@ -204,16 +224,14 @@ POST Body in JSON format (syntax 2)
**Note:** use this syntax to send ``boolean`` or ``numbers`` in JSON.
The JSON message will be constructed using the `ArduinoJson <https://github.com/bblanchon/ArduinoJson>`__ library.
In the ``json`` option you have access to a ``root`` object which will represents the base object
of the JSON message. You can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax
as seen below.
In the ``json`` option you have access to a ``root`` object which represents the base object of the JSON message. You
can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax as shown below.
.. code-block:: yaml
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json: |-
root["key"] = id(my_sensor).state;
root["greeting"] = "Hello World";
@ -224,25 +242,25 @@ as seen below.
GET values from a JSON body response
************************************
Assuming that the server returns a response in a JSON object over HTTP similar to this:
This example assumes that the server returns a response as a JSON object similar to this:
``{"status":"play","vol":"42","mute":"0"}``
If you want to retrieve the value for the ``vol`` key and assign it to a template ``sensor`` or ``number`` component (with ``id`` set to ``player_volume``):
If you want to retrieve the value for the ``vol`` key and assign it to a template ``sensor`` or ``number`` component
whose ``id`` is set to ``player_volume``:
.. code-block:: yaml
on_...:
- http_request.get:
url: https://esphome.io
capture_response: true
on_response:
then:
- lambda: |-
json::parse_json(id(http_request_data).get_string(), [](JsonObject root) {
json::parse_json(body, [](JsonObject root) {
id(player_volume).publish_state(root["vol"]);
});
**Note:** don't forget to set the ``id`` for the main ``http_request`` component, to ``http_request_data``.
See Also
--------

6
components/ota.rst
View File

@ -55,11 +55,13 @@ Configuration variables:
update and receive the error message ``Bad Answer: ERR: ERROR[11]: Invalid bootstrapping``, the ESP module/board
must be power-cycled.
.. _ota-automations:
OTA Automations
---------------
The OTA component provides various automations that can be used to provide feedback during the OTA update process.
When using these automation triggers, note that:
The OTA component provides various :ref:`automations <automation>` that can be used to provide feedback during the OTA
update process. When using these automation triggers, note that:
- OTA updates block the main application loop while in progress. You won't be able to represent state changes using
components that update their output only from within their ``loop()`` method. Explained differently: if you try to

70
components/ota_http_request.rst
View File

@ -5,7 +5,7 @@ OTA Update via HTTP Request Component
:description: Instructions for setting up Over-The-Air (OTA) updates for ESPs to download firmwares remotely by HTTP.
:image: system-update.svg
With the OTA (Over The Air) via HTTP Request update component, your devices can install updated firmware on their own.
The OTA (Over The Air) via HTTP Request update component allows your devices to install updated firmware on their own.
To use it, in your device's configuration, you specify a URL from which the device will download the binary
file (firmware). To trigger the update, an ESPHome :ref:`action <config-action>` is used which initiates the
download and installation of the new firmware. Once complete, the device is rebooted, invoking the new firmware.
@ -13,77 +13,32 @@ download and installation of the new firmware. Once complete, the device is rebo
Since the device functions as an HTTP(S) client, it can be on a foreign network or behind a firewall. This mechanism
is primarily useful with either standalone or MQTT-only devices.
To use this platform, the :doc:`http_request` component must be present in your configuration.
.. code-block:: yaml
# Example configuration entry
ota:
- platform: http_request
# OTA updade trigerred by a button
button:
- platform: template
name: Firmware update
on_press:
then:
- ota_http_request.flash:
md5_url: http://example.com/firmware.md5
url: http://example.com/firmware.bin
- logger.log: "This message should be not displayed because the device reboots"
Configuration variables:
------------------------
- **esp8266_disable_ssl_support** (*Optional*, boolean): When set to ``true``, HTTPS/SSL support is excluded from the
build, resulting in a smaller binary. HTTPS connections will not be possible. **Only available on ESP8266.** Defaults
to ``false``. See :ref:`esphome-esp8266_disable_ssl_support` for more information.
- **verify_ssl** (*Optional*, boolean): When set to ``true`` (default), SSL/TLS certificates will be validated upon
connection; if invalid, the connection will be aborted. To accomplish this, ESP-IDF's default ESP x509 certificate
bundle is included in the build. This certificate bundle includes the complete list of root certificates from
Mozilla's NSS root certificate store. **May only be set to true when using the ESP-IDF framework; must be explicitly
set to false when using the Arduino framework.**
- **watchdog_timeout** (*Optional*, :ref:`config-time`): Change the watchdog timeout during flash operation.
May be useful on slow connections or connections with high latency. **Do not change this value unless you are
experiencing device reboots due to watchdog timeouts;** doing so may prevent the device from rebooting due to a
legitimate problem. **Only available on ESP32 and RP2040**.
.. warning::
Setting ``verify_ssl`` to ``false`` **reduces security** when using HTTPS connections!
Without the certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the update
process up to man-in-the-middle attacks.
To maximize security, do not set ``verify_ssl`` to ``false`` *unless:*
- the device does not have sufficient memory to store the certificate bundle
- a custom CA/self-signed certificate is used, or
- the Arduino framework is used
.. note::
You can obtain the ``firmware.bin`` from either:
- **ESPHome dashboard** (HA add-on): download in *"Legacy format"*
- **ESPHome CLI**: the directory ``.esphome/build/project/.pioenvs/project/firmware.bin``
...where *"project"* is the name of your ESPHome device/project.
You **cannot** use ``firmware-factory.bin`` or *"Modern format"* with ``ota_http_request``.
- All :ref:`automations <ota-automations>` supported by :doc:`ota`.
.. _ota_http_request-flash_action:
``ota_http_request.flash`` Action
``ota.http_request.flash`` Action
---------------------------------
This action triggers the download and installation of the updated firmware from the configured URL.
As it's an ESPHome :ref:`action <config-action>`, it may be used in any ESPHome automation(s).
This action triggers the download and installation of the updated firmware from the configured URL. As it's an
ESPHome :ref:`action <config-action>`, it may be used in any ESPHome :ref:`automation(s) <automation>`.
.. code-block:: yaml
on_...:
then:
- ota_http_request.flash:
- ota.http_request.flash:
md5_url: http://example.com/firmware.md5
url: https://example.com/firmware.bin
- logger.log: "This message should be not displayed because the device reboots"
@ -106,6 +61,15 @@ Configuration variables:
.. note::
- You can obtain the ``firmware.bin`` file from either:
- **ESPHome dashboard** (HA add-on): download in *"Legacy format"*
- **ESPHome CLI**: the directory ``.esphome/build/project/.pioenvs/project/firmware.bin``
...where *"project"* is the name of your ESPHome device/project.
You **cannot** use ``firmware-factory.bin`` or *"Modern format"* with this component.
- ``username`` and ``password`` must be `URL-encoded <https://en.wikipedia.org/wiki/Percent-encoding>`_ if they
include special characters.