Update entity

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
auto_update	bool	False	The device or service that the entity represents has auto update logic. When this is set to True you can not skip updates.
in_progress	bool	None	Update installation progress. Should return a boolean (True if in progress, False if not).
installed_version	str	None	The currently installed and used version of the software.
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.
update_percentage	int	None	Update installation progress. Can either return a number to indicate the progress from 0 to 100% or None.

Other properties that are common to all entities such as device_class, entity_category, icon, name etc are still applicable.

Supported features

Supported features are defined by using values in the UpdateEntityFeature enum.

Value	Description
'BACKUP'	A backup can be made automatically, before installing an update.
'INSTALL'	The update can be installed from Home Assistant.
'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.
'SPECIFIC_VERSION'	A specific version of an update can be installed using the update.install service action.
'RELEASE_NOTES'	The entity provides methods to fetch a complete changelog.

Methods

Compare versions

This method should be implemented when needed to override the default version comparison logic. Here's an example:

def version_is_newer(self, latest_version: str, installed_version: str) -> bool:
    """Return True if latest_version is newer than installed_version."""
    return AwesomeVersion(
        latest_version,
        find_first_match=True,
        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
    ) > AwesomeVersion(
        installed_version,
        find_first_match=True,
        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
    )

It allows developers to specify custom logic for determining if one version is newer than another. First attempt should be based on the strategies provided by the AwesomeVersion library.

Install

This method can be implemented so users can install an offered update directly from within Home Assistant.

This method requires UpdateEntityFeature.INSTALL to be set. Additionally, if this integration supports installing specific version or is capable of backing up before starting the update installation process, UpdateEntityFeature.SPECIFIC_VERSION and UpdateEntityFeature.BACKUP can be set respectively.

class MyUpdate(UpdateEntity):
    # Implement one of these methods.

    def install(
        self, version: str | None, backup: bool, **kwargs: Any
    ) -> None:
        """Install an update."""

    async def async_install(
        self, version: str | None, backup: bool, **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.
        """

Release notes

This method can be implemented so users can can get the full release notes in the more-info dialog of the Home Assistant Frontend before they install the update.

The returned string can contain markdown, and the frontend will format that correctly.

This method requires UpdateEntityFeature.RELEASE_NOTES to be set.

class MyUpdate(UpdateEntity):
    # Implement one of these methods.

    def release_notes(self) -> str | None:
        """Return the release notes."""
        return "Lorem ipsum"

    async def async_release_notes(self) -> str | None:
        """Return the release notes."""
        return "Lorem ipsum"

Available device classes

Optionally specifies what type of entity it is.

Constant	Description
UpdateDeviceClass.FIRMWARE	The update is a firmware update for a device.