Add blogpost and documentation for the update integration

This commit is contained in:
Ludeeus 2022-03-04 11:13:13 +00:00
parent 6378bf4875
commit cd67197cfc
4 changed files with 82 additions and 3 deletions

View File

@ -0,0 +1,17 @@
---
author: Joakim Sørensen
authorURL: https://github.com/ludeeus
authorImageURL: /img/profile/ludeeus.jpg
authorTwitter: ludeeus
title: "Update all the things!🎉"
---
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, starting with Home Assistant Core 2022.4 this is no longer limited to the Supervisor integration.
All integrations can now provide an update platform (`update.py`) to show and
perform updates.
Previously we had the `update` device class for the [button entity](/docs/core/entity/button), this is now considered deprecated and you should move to the update platform instead.
For more details on how to implement the update platform in your integration have a look at the [update platform documentation](/docs/core/update_platform)

View File

@ -9,7 +9,6 @@ It can be compared to a real live momentary switch, push-button, or some other f
A switch button entity is derived from the [`homeassistant.components.button.ButtonEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/button/__init__.py),
and can be helpful for controlling device features like (but not limited to):
- Upgrading firmware
- Reboot/Restart a device
- Brew a cup of coffee
- Reset something (like a counter, filter usage)
@ -47,4 +46,4 @@ 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. (This device_class is deprecated and you should implement an [update platform](/docs/core/update_platform) instead)

View File

@ -0,0 +1,63 @@
---
title: Update platform
---
The update platform allow you to provide updates that the user can manage in the configuration panel of the Home Assistant UI[^1].
Add a new `update.py` file to your integration with the 2 public functions
described below to enable this feature.
:::tip
You can also use the `update` scaffold template.
```shell
python3 -m script.scaffold --integration [domain] update
```
:::
## Public functions
The update platform needs 2 public functions to be present in
### `async_list_updates`
This is where you gather all the updates the integration provides, and return that as a list of `UpdateDescription` objects.
```python
async def async_list_updates(hass: HomeAssistant) -> list[UpdateDescription]:
```
### `async_perform_update`
This is the function that will be called when an user starts an update.
The `identifier` and the `version` attributes you declared for the `UpdateDescription` in `async_list_updates` will be passed to the function.
```python
async def async_perform_update(
hass: HomeAssistant,
identifier: str,
version: str,
**kwargs: Any,
) -> None:
```
If you set `supports_backup` to `True` in `UpdateDescription` a `backup` key will be present in `kwargs` with a `bool` that represent the choice the user made.
## UpdateDescription
The update description provides a interface to describe the update.
Attribute | Type | Description
-- | -- | --
`identifier` | `str` | This identifies the update, this attribute is passed to the `async_perform_update` function when the user starts the update.
`name` | `str` | This is the name of the update that will be show to the user
`current_version` | `str` | This represent the current version (the version the user updates from)
`available_version` | `str` | This represents the version that are available (the version the user updates to), this attribute is passed to the `async_perform_update` function as `version` when the user starts the update.
`changelog_url` | `str` (Optional) | An URL to where the user can get to the changelog for the update.
`changelog_content` | `str` (Optional) | Markdown formatted changelog content that will be displayed in the update dialog.
`icon_url` | `str` (Optional) | URL to an icon that will be shown in the UI, if not present it will use the [brands](https://github.com/home-assistant/brands) icon for the integration.
`supports_backup` | `bool` (Optional) | Set this to `True` if the integration have a way to perform backup before an update take place.
[^1]: _This require the user to have enabled the `update` integration._

View File

@ -184,7 +184,7 @@ module.exports = {
"device_automation_condition",
"device_automation_action",
],
Misc: ["development_validation", "development_typing", "instance_url"],
Misc: ["development_validation", "development_typing", "instance_url", "core/update_platform"],
},
Misc: {
Introduction: ["misc"],