From 79120f901f416f58630dc1ded9b8df96e4784073 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 21 Mar 2022 11:03:11 +0100 Subject: [PATCH] Add update entity platform (#22082) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Joakim Sørensen --- source/_integrations/update.markdown | 139 +++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 source/_integrations/update.markdown diff --git a/source/_integrations/update.markdown b/source/_integrations/update.markdown new file mode 100644 index 00000000000..4a30ba75a4b --- /dev/null +++ b/source/_integrations/update.markdown @@ -0,0 +1,139 @@ +--- +title: Update +description: Instructions on how to use update entities with Home Assistant. +ha_category: + - Updates +ha_release: 2022.4 +ha_quality_scale: internal +ha_domain: update +ha_codeowners: + - '@home-assistant/core' +--- + +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. + +The state of the update entity indicates if there is an update pending or not, +and if there is an update available, more information on that update can be +provided by an integration to the entity. For example, the version that is +available, a summary of the release notes, and even links that provide more +information on the available update. + +Lastly, there are two services available for the update entity. If possible and +made available by the integration providing the update entity, triggering +the actual update from Home Assistant. The other service exposed allows for +skipping the offered update. + +
+ +Update entities are here to be consumed and provided by other integrations and +are are not designed to be created manually directly. + +This page, therefore, does not provide instructions on how to create update +entities. Please see the ["Updates" category](/integrations/#updates) on the +integrations page to find integration offering update entities. + +
+ +## The state of an update entity + +The state of an update entity reflects whether an update is available or not. +When the state is `on`, it means there is an update available; when everything +is up-to-date, the state is `off`. + +Additionally, the following state attributes are exposed to provide more +information on the update state: + +- `title`: The title/name of the available software or firmware. As the device + name or entity name can be changed in Home Assistant, this title will provide + the actual name of the software or firmware. +- `current_version`: The current version that is currently installed and in use. +- `latest_version`: The latest version that is available for installation. +- `skipped_version`: If a version update is skipped, this attribute will be set + and contains the actual version that was skipped. +- `release_summary`: A summary of the release notes for the update available. +- `release_url`: A link to the full release announcement for the update available. + +## Device Classes + +The way these update entities are displayed in the frontend depend on their +device classes. The following device classes are supported for switches: + +- **`None`**: A generic software update. This is the default and doesn't need + to be set. +- **`firmware`**: This update integration provides firmwares. + +## Services + +The update entity exposes two services that can be used to install or skip +an offered software update. + +### Service {% my developer_call_service service="update.install" %} + +The {% my developer_call_service service="update.install" %} service can be used +to install an offered update to the device or service. + +This service is only available for an update entity if an integration provides +this capability. Additionally, if allowed by the integration, the service +provides for installing a specific version and even could make a +backup before installing the update. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | String or list of strings that point at `entity_id`s of updates. To target all updates, set `entity_id` to `all`. +| `version` | yes | A specific update version to install, if not provided, the latest available update will be installed. Availability of this atrribute is dependent on the integration. +| `backup` | yes | If set to `true`, a backup will be made before installing the update. Availability of this attribute is dependent on the integration. + +Example service call: + +```yaml +service: update.install +target: + entity_id: + - update.my_light_bulb +``` + +### Service {% my developer_call_service service="update.skip" %} + +The {% my developer_call_service service="update.skip" %} service can be used +to skip an offered update to the device or service. + +After skipping an offered update, the entity will return to the `off` state, +which means there is no update available. + +```yaml +service: update.skip +target: + entity_id: + - update.my_light_bulb +``` + +Even if an update is skipped and shows as `off` (meaning no update), if there +is a newer version available, calling the `update.install` service on the entity +will still install the latest version. + +## Example: Sending update available notifications + +A common use case for using update entities is to notify you if an update +has become available for installation. Using the update entities, +this is fairly straightforward to do. + +This is a YAML example for an automation that sends out a notification when +the update for a light bulb becomes available. + +```yaml +automation: + - alias: "Send notification when update available" + trigger: + platform: state + entity_id: update.my_light_bulb + to: "on" + action: + alias: "Send notification to my phone about the update" + service: notify.iphone + data: + title: "New update available" + message: "New update available for my_light_bulb!" +```