From 876885823fb8d84ce08e4ec2c97f5af4889066bc Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Sun, 9 Jun 2024 19:36:21 -0500 Subject: [PATCH] Documentation updates for ``http_request`` component refactor (#3919) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/http_request.rst | 114 ++++++++++++++++++-------------- components/ota.rst | 6 +- components/ota_http_request.rst | 70 +++++--------------- 3 files changed, 87 insertions(+), 103 deletions(-) diff --git a/components/http_request.rst b/components/http_request.rst index ef7f7da45..a9c658e66 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -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/ (https://esphome.io)`` where ```` 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 ` that can be used to send requests. +The ``http_request`` component supports a number of :ref:`actions ` that can be used to send requests. .. _http_request-get_action: @@ -59,7 +83,6 @@ This :ref:`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 ` sends a GET request. # Short form - http_request.get: https://esphome.io -Configuration variables: +**Configuration variables:** -- **url** (**Required**, string, :ref:`templatable `): URL to send request. +- **url** (**Required**, string, :ref:`templatable `): URL to which to send the request. - **headers** (*Optional*, mapping): Map of HTTP headers. Values are :ref:`templatable `. -- **verify_ssl** (*Optional*, boolean): Verify the SSL certificate of the endpoint. Defaults to ``true``. -- **on_response** (*Optional*, :ref:`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 `. 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 `): An automation to perform after the request is received. .. _http_request-post_action: @@ -98,14 +119,14 @@ This :ref:`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 `): A HTTP body string to send with request. -- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`templatable `. See :ref:`http_request-examples`. +- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`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 ` 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 `: -* ``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 `__ 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 -------- diff --git a/components/ota.rst b/components/ota.rst index 51c821f50..f152a49ce 100644 --- a/components/ota.rst +++ b/components/ota.rst @@ -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 ` 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 diff --git a/components/ota_http_request.rst b/components/ota_http_request.rst index 61336b71b..283920b06 100644 --- a/components/ota_http_request.rst +++ b/components/ota_http_request.rst @@ -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 ` 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 ` 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 `, 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 `, it may be used in any ESPHome :ref:`automation(s) `. .. 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 `_ if they include special characters.