Add update entity platform (#1243)

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

blog/2022-03-20-update-entity.md

@@ -0,0 +1,34 @@
+---
+author: Franck Nijhof
+authorURL: https://twitter.com/frenck
+authorTwitter: frenck
+title: "Introducing the update entity"
+---
+
+Home Assistant 2022.4 will provide a brand new entity platform:
+the `update` entity.
+
+The `update` entity can be provided by integrations to indicate there is an
+update available, for a device or service, towards the Home Assistant user. It
+allows you to provide additional information about the update, such as
+the latest version available, a summary of the release notes and a link to the
+full release announcement online.
+
+Additionally, the `install` method can be implemented, so the user can install
+the update directly from within Home Assistant.
+
+Adding the `update` platform to your integration is relatively simple to do, as
+it is just a couple of properties and, if available for the integration,
+a single `install` method. Most other details are handled by Home Assistant 
+automatically.
+
+In Home Assistant Core [2021.12](https://www.home-assistant.io/blog/2021/12/11/release-202112/#brand-new-configuration-panel) we moved updates provided by
+the Supervisor to the Configuration panel, using this new platform, we will
+be able to extend that in the near future by the information provided by these
+brand new entities.
+
+See our [developer documentation](/docs/core/entity/update) for how to implement this in an integration.
+
+If your integration previously provided a `binary_sensor` or `button` entity
+with the `update` device class, please consider replacing those with the
+`update` entity.

docs/core/entity/binary-sensor.md

@@ -45,6 +45,6 @@ Properties should always only return information from memory and not do I/O (lik
 | smoke | On means smoke detected, Off means no smoke (clear).
 | sound | On means sound detected, Off means no sound (clear).
 | tamper | On means tampering detected, Off means no tampering (clear)
-| update | On means update available, Off means up-to-date.
+| update | On means update available, Off means up-to-date. The use of this device class should be avoided, please consider using the [`update`](/docs/core/entity/update) entity instead.
 | vibration | On means vibration detected, Off means no vibration.
 | window | On means open, Off means closed.

docs/core/entity/button.md

@@ -47,4 +47,5 @@ Optionally specifies what type of entity it is. It will possibly map to Google d
 | Value | Description
 | ----- | -----------
 | restart | The button entity restarts the device.
-| update | The button entity updates the software of the device.
+| update | The button entity updates the software of the device. The use
+of this device class should be avoided, please consider using the [`update`](/docs/core/entity/update) entity instead.

docs/core/entity/update.md

@@ -0,0 +1,90 @@
+---
+title: Update Entity
+sidebar_label: Update
+---
+
+An update entity is an entity that indicates if an update is available for a
+device or service. This can be any update, including update of a firmware
+for a device like a light bulb or router, or software updates for things like
+add-ons or containers.
+
+It can be used for:
+
+- Providing an indicator if an update is available for a device or service.
+- An install method to allow installing an update or a specific version
+  of the software.
+- Allow for offering backups before installing a new update.
+
+## Properties
+
+:::tip
+Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
+:::
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| current_version | str | `None` | The current version of the software installed.
+| in_progress | bool, int | `None` | Update installation progress. Can either return a boolean (True if in progress, False if not) or an integer to indicate the progress from 0 to 100%.
+| latest_version | str | `None` | The latest version of the software available.
+| release_summary | str | `None` | Summary of the release notes or changelog. This is not suitable for long changelogs but merely suitable for a short excerpt update description of max 255 characters.
+| release_url | str | `None` | URL to the full release notes of the latest version available.
+| title | str | `None` | Title of the software. This helps to differentiate between the device or entity name versus the title of the software installed.
+
+Other properties that are common to all entities such as `device_class`, `entity_category`, `icon`, `name` etc are still applicable.
+
+## Supported Features
+
+| Constant | Description |
+|----------|--------------------------------------|
+| 'UpdateEntityFeature.BACKUP' | A backup can be made automatically, before installing an update.
+| 'UpdateEntityFeature.INSTALL' | The update can be installed from Home Assistant. 
+| 'UpdateEntityFeature.PROGRESS' | This integration is able to provide progress information. If omitted, Home Assistant will try to provide a progress status; although it is better if the progress can be extracted from the device or service API.
+| 'UpdateEntityFeature.SPECIFIC_VERSION' | A specific version of an update can be installed using the `update.install` service.
+
+## Methods
+
+### Install
+
+This method can be implemented so users can install an offered update directly
+from within Home Assistant.
+
+This method requires `SUPPORT_INSTALL` to be set. Additionally, if this
+integration supports installing specific version or is capable of backing up
+before starting the update installation process, `SUPPORT_SPECIFIC_VERSION` and
+`SUPPORT_BACKUP` can be set respectively.
+
+```python
+class MyUpdate(UpdateEntity):
+    # Implement one of these methods.
+
+    async def async_install(
+        self,
+        version: str | None = None,
+        backup: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Install an update."""
+
+    def install(
+        self,
+        version: str | None = None,
+        backup: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Install an update.
+
+        Version can be specified to install a specific version. When `None`, the
+        latest version needs to be installed.
+
+        The backup parameter indicates a backup should be taken before
+        installing the update.
+        """
+```
+
+### Available device classes
+
+Optionally specifies what type of entity it is.
+
+| Value | Description
+| ----- | -----------
+| firmware | The update is a firmware update for a device.

sidebars.js

@@ -174,6 +174,7 @@ module.exports = {
       "core/entity/sensor",
       "core/entity/siren",
       "core/entity/switch",
+      "core/entity/update",
       "core/entity/vacuum",
       "core/entity/water-heater",
       "core/entity/weather",