mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-24 17:56:31 +00:00
Add blogpost and documentation for the update integration
This commit is contained in:
parent
6378bf4875
commit
cd67197cfc
17
blog/2022-03-07-update_all_the_things.md
Normal file
17
blog/2022-03-07-update_all_the_things.md
Normal 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)
|
@ -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)
|
||||
|
63
docs/core/update_platform.md
Normal file
63
docs/core/update_platform.md
Normal 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._
|
@ -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"],
|
||||
|
Loading…
x
Reference in New Issue
Block a user