From 5ab770d4ee8725c9953ea8d4426ac3be2e784d77 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 21 Mar 2022 11:03:19 +0100 Subject: [PATCH] Add update entity platform (#1243) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Joakim Sørensen Co-authored-by: Martin Hjelmare --- blog/2022-03-20-update-entity.md | 34 ++++++++++++ docs/core/entity/binary-sensor.md | 2 +- docs/core/entity/button.md | 3 +- docs/core/entity/update.md | 90 +++++++++++++++++++++++++++++++ sidebars.js | 1 + 5 files changed, 128 insertions(+), 2 deletions(-) create mode 100644 blog/2022-03-20-update-entity.md create mode 100644 docs/core/entity/update.md diff --git a/blog/2022-03-20-update-entity.md b/blog/2022-03-20-update-entity.md new file mode 100644 index 00000000..46054f8d --- /dev/null +++ b/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. diff --git a/docs/core/entity/binary-sensor.md b/docs/core/entity/binary-sensor.md index 3f9933d4..8fb4b694 100644 --- a/docs/core/entity/binary-sensor.md +++ b/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. diff --git a/docs/core/entity/button.md b/docs/core/entity/button.md index d961924b..7d2c4d2c 100644 --- a/docs/core/entity/button.md +++ b/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. diff --git a/docs/core/entity/update.md b/docs/core/entity/update.md new file mode 100644 index 00000000..f33c7646 --- /dev/null +++ b/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. diff --git a/sidebars.js b/sidebars.js index 750a5083..6ae157cd 100644 --- a/sidebars.js +++ b/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",