MQTT Update
The mqtt Update platform allows you to integrate devices that might expose firmware/software installed and the latest versions through MQTT into Home Assistant as an Update entity. Every time a message under the topic in the configuration is received, the entity will be updated in Home Assistant.
Configuration
To enable MQTT Update in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:
# Example configuration.yaml entry
mqtt:
- update:
state_topic: topic-installed
latest_version_topic: topic-latest
Configuration Variables
A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic.
The payload that represents the available state.
The payload that represents the unavailable state.
The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability.
When availability is configured, this controls the conditions needed to set the entity to available. Valid entries are all, any, and latest. If set to all, payload_available must be received on all configured availability topics before the entity is marked as online. If set to any, payload_available must be received on at least one configured availability topic before the entity is marked as online. If set to latest, the last payload_available or payload_not_available received on any configured availability topic controls the availability.
Defines a template to extract device’s availability from the availability_topic. To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available.
The MQTT topic to publish payload_install to start installing process.
Information about the device this Update is a part of to tie it into the device registry. Only works when unique_id is set. At least one of identifiers or connections must be present to identify the device.
A link to the webpage that can manage the configuration of this device. Can be either an http://, https:// or an internal homeassistant:// URL.
A list of connections of the device to the outside world as a list of tuples [connection_type, connection_identifier]. For example the MAC address of a network interface: "connections": [["mac", "02:5b:26:a8:dc:12"]].
A list of IDs that uniquely identify the device. For example a serial number.
The type/class of the update to set the icon in the frontend. The device_class can be null.
Number of decimal digits for display of update progress.
Flag which defines if the entity should be enabled when first added.
The encoding of the payloads received and published messages. Set to "" to disable decoding of incoming payload.
The category of the entity.
Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic.
The MQTT topic subscribed to receive a JSON dictionary payload and then set as entity attributes. Implies force_update of the current select state when a message is received on this topic.
The MQTT topic subscribed to receive an update of the latest version.
The name of the Update. Can be set to null if only the device name is relevant.
Must be update. Only allowed and required in MQTT auto discovery device messages.
The maximum QoS level to be used when receiving and publishing messages.
Summary of the release notes or changelog. This is suitable a brief update description of max 255 characters.
If the published message should have the retain flag on or not.
The MQTT topic subscribed to receive state updates. The state update may be either JSON or a simple string with installed_version value. When a JSON payload is detected, the state value of the JSON payload should supply the installed_version and can optional supply: latest_version, title, release_summary, release_url or an entity_picture URL.
Title of the software, or firmware update. This helps to differentiate between the device or entity name versus the title of the software installed.
An ID that uniquely identifies this Update. If two Updates have the same unique ID Home Assistant will raise an exception.
Make sure that your topic matches exactly. some-topic/ and some-topic are different topics.
Examples
This is an example of Update entity configuration for Shelly Gen1 device.
# Example configuration.yaml entry
mqtt:
- update:
name: "Shelly Plug S Firmware Update"
title: "Shelly Plug S Firmware"
release_url: "https://shelly-api-docs.shelly.cloud/gen1/#changelog"
entity_picture: "https://brands.home-assistant.io/_/shelly/icon.png"
state_topic: "shellies/shellyplug-s-112233/info"
value_template: "{{ value_json['update'].old_version }}"
latest_version_topic: "shellies/shellyplug-s-112233/info"
latest_version_template: "{% if value_json['update'].new_version %}{{ value_json['update'].new_version }}{% else %}{{ value_json['update'].old_version }}{% endif %}"
device_class: "firmware"
command_topic: "shellies/shellyplug-s-112233/command"
payload_install: "update_fw"
JSON can also be used as state_topic payload. Note that this feature also allows to process and show live progress information.
{
"installed_version": "1.21.0",
"latest_version": "1.22.0",
"title": "Device Firmware",
"release_url": "https://example.com/release",
"release_summary": "A new version of our amazing firmware",
"entity_picture": "https://example.com/icon.png"
}
Simple progress state update example:
{
"installed_version": "1.21.0",
"latest_version": "1.22.0",
"title": "Device Firmware",
"release_url": "https://example.com/release",
"release_summary": "A new version of our amazing firmware",
"entity_picture": "https://example.com/icon.png",
"in_progress": true
}
Update percentage state update example:
{
"installed_version": "1.21.0",
"latest_version": "1.22.0",
"title": "Device Firmware",
"release_url": "https://example.com/release",
"release_summary": "A new version of our amazing firmware",
"entity_picture": "https://example.com/icon.png",
"update_percentage": 78
}
Publish null to reset the update percentage state update’s:
{
"installed_version": "1.22.0",
"latest_version": "1.22.0",
"title": "Device Firmware",
"release_url": "https://example.com/release",
"release_summary": "A new version of our amazing firmware",
"entity_picture": "https://example.com/icon.png",
"update_percentage": null
}
The values in the JSON are optional but must be valid within the following schema:
For the above JSON payload examples, the update entity configuration should look like this:
# Example configuration.yaml entry
mqtt:
- update:
name: "Amazing Device Update"
title: "Device Firmware"
state_topic: "amazing-device/state-topic"
device_class: "firmware"
command_topic: "amazing-device/command"
payload_install: "install"
If the device/service sends data as JSON but the schema differs, value_template can be use to reformat the JSON.
{
"installed_ver": "2022.11",
"new_ver": "2022.12"
}
For the above JSON payload, the update entity configuration should look like this:
# Example configuration.yaml entry
mqtt:
update:
name: "Amazing Device Update"
title: "Device Firmware"
state_topic: "amazing-device/state-topic"
value_template: "{{ {'installed_version': value_json.installed_ver, 'latest_version': value_json.new_ver } | to_json }}"
device_class: "firmware"
command_topic: "amazing-device/command"
payload_install: "install"