Add update entity platform (#1243)

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Franck Nijhof 2022-03-21 11:03:19 +01:00 committed by GitHub
parent be55cecdb9
commit 5ab770d4ee
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 128 additions and 2 deletions

View File

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

View File

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

View File

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

View File

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

View File

@ -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",