[core] Update Entities documentation (#3935)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/index.rst

@@ -30,5 +30,6 @@ Components
     time/index
     alarm_control_panel/index
     text/index
+    update/index
     valve/index
     *

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.

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 <update_http_request-manifest_format>` 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 <config-update>`.
+
+.. _update_http_request-manifest_format:
+
+Update Manifest Format
+----------------------
+
+This component expects the `ESP-Web-Tools manifest <https://github.com/esphome/esp-web-tools>`__ 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`

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 </components/ota>`, 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`

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
 -------------------------------------