mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-19 07:16:29 +00:00
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:
parent
be55cecdb9
commit
5ab770d4ee
34
blog/2022-03-20-update-entity.md
Normal file
34
blog/2022-03-20-update-entity.md
Normal 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.
|
@ -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.
|
||||
|
@ -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.
|
||||
|
90
docs/core/entity/update.md
Normal file
90
docs/core/entity/update.md
Normal 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.
|
@ -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",
|
||||
|
Loading…
x
Reference in New Issue
Block a user