diff --git a/components/index.rst b/components/index.rst index b1f4c8739..586e1f8ee 100644 --- a/components/index.rst +++ b/components/index.rst @@ -30,5 +30,6 @@ Components time/index alarm_control_panel/index text/index + update/index valve/index * diff --git a/components/ota_http_request.rst b/components/ota_http_request.rst index 283920b06..93810bfc4 100644 --- a/components/ota_http_request.rst +++ b/components/ota_http_request.rst @@ -1,5 +1,5 @@ -OTA Update via HTTP Request Component -===================================== +OTA Update via HTTP Request +=========================== .. seo:: :description: Instructions for setting up Over-The-Air (OTA) updates for ESPs to download firmwares remotely by HTTP. diff --git a/components/update/http_request.rst b/components/update/http_request.rst new file mode 100644 index 000000000..93331742d --- /dev/null +++ b/components/update/http_request.rst @@ -0,0 +1,77 @@ +Managed Updates via HTTP Request +================================ + +.. seo:: + :description: Instructions for using ESPHome's http_request update platform to manage updates on your devices. + :image: system-update.svg + :keywords: Updates, OTA, ESP32, ESP8266 + +This platform allows you to manage the deployment of updates to your ESPHome devices. It works by reading a +:ref:`JSON manifest file ` and using it to determine the presence of an update. + +To use it, the following components are required in your device's configuration: + +- :doc:`/components/http_request` +- :doc:`/components/ota_http_request` + +.. code-block:: yaml + + # Example configuration entry + update: + - platform: http_request + name: Firmware Update + source: http://example.com/manifest.json + +.. _update_http_request-configuration_variables: + +Configuration variables: +------------------------ + +- **source** (**Required**, string): The URL of the YAML manifest file containing the firmware metadata. +- **update_interval** (*Optional*, :ref:`config-time`): The interval at which to check for updates. Defaults to 6 hours. +- All other options from :ref:`Update `. + +.. _update_http_request-manifest_format: + +Update Manifest Format +---------------------- + +This component expects the `ESP-Web-Tools manifest `__ with an extension in +the ``ota`` block that is structured as follows: + +.. code-block:: json + + { + "name": "My ESPHome Project", + "version": "2024.6.1", + "builds": [ + { + "chipFamily": "ESP32-C3", + "ota": { + "md5": "1234567890abcdef1234567890abcdef", + "path": "/local/esp32c3/firmware.bin", + "release_url": "http://example.com/releases/10", + "summary": "Another update", + } + } + ] + } + +While ``release_url`` and ``summary`` are optional, all other fields shown here are required. + +If ``path`` begins with: + +- ``http`` or ``https``: ``path`` is treated as full URL which will be used to obtain the firmware binary. +- A forward slash (``/``): ``path`` will be appended to the hostname (an "absolute" path) specified for ``source`` (as above). +- Any other character: ``path`` will be appended to ``source`` (as specified above) after trimming the manifest file name. + +Note that there may be multiple ``builds`` specified within a single JSON file. + +See Also +-------- + +- :doc:`http_request` +- :doc:`/components/ota_http_request` +- :doc:`/components/ota` +- :apiref:`update/update_entity.h` +- :ghedit:`Edit` diff --git a/components/update/index.rst b/components/update/index.rst new file mode 100644 index 000000000..c21dab0e5 --- /dev/null +++ b/components/update/index.rst @@ -0,0 +1,45 @@ +Update Core +=========== + +.. seo:: + :description: Instructions for using Update entities to manage updates on your ESPHome devices. + :image: system-update.svg + :keywords: Updates, OTA, ESP32, ESP8266 + +The `update` component allows your ESPHome devices to install updates from a remote source; instead of +:doc:`"pushing" an update to your device `, the device can retrieve an update and install it on its own. + +.. code-block:: yaml + + # Example configuration entry + update: + - platform: ... + +.. _config-update: + +Configuration variables: +------------------------ + +- **name** (*Optional*, string): The name to use for the update component. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **device_class** (*Optional*, string): The device class for the update entity. See + https://www.home-assistant.io/integrations/binary_sensor/#device-class for a list of available options. +- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend + (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``. +- **entity_category** (*Optional*, string): The category of the update entity. See + https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. +- **icon** (*Optional*, icon): The icon to use for the update entity in the frontend. +- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will + not be exposed to the frontend (like Home Assistant). Specifying an ``id`` without a ``name`` will + implicitly set this to true. + +See Also +-------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +- :ghedit:`Edit` diff --git a/index.rst b/index.rst index 399606f4b..c79f7f8b9 100644 --- a/index.rst +++ b/index.rst @@ -203,6 +203,16 @@ Management and Monitoring Web Server, components/web_server, http.svg, dark-invert ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert +Update Management +----------------- + +Create update entities simplifying management of OTA updates. + +.. imgtable:: + + Update Core, components/update/index, system-update.svg, dark-invert + Managed Updates, components/update/http_request, system-update.svg, dark-invert + Hardware Peripheral Interfaces/Busses -------------------------------------