Allow mqtt update entity to report progress (#35475)

* Allow mqtt update entity to report progress

* Add default for `in_progress`

* correct type

* Type null replacement

* Remove none as type

* Address typo

* Typo

* Text improvements

* Document display_precision

* Abbreviation

* Update source/_integrations/update.mqtt.markdown

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Jan Bouwhuis 2024-10-31 08:13:13 +01:00 committed by GitHub
parent 5b6f279a08
commit d86ab50c80
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 100 additions and 2 deletions

View File

@ -698,6 +698,7 @@ support_url:
'dir_cmd_tpl': 'direction_command_template',
'dir_stat_t': 'direction_state_topic',
'dir_val_tpl': 'direction_value_template',
'dsp_prc': 'display_precision',
'e': 'encoding',
'en': 'enabled_by_default',
'ent_cat': 'entity_category',

View File

@ -120,6 +120,11 @@ device_class:
description: The [type/class](/integrations/update/#device-classes) of the update to set the icon in the frontend. The `device_class` can be `null`.
required: false
type: device_class
display_precision:
description: Number of decimal digits for display of update progress.
required: false
type: integer
default: 0
enabled_by_default:
description: Flag which defines if the entity should be enabled when first added.
required: false
@ -239,7 +244,7 @@ mqtt:
{% endraw %}
JSON can also be used as `state_topic` payload.
JSON can also be used as `state_topic` payload. Note that this feature also allows to process and show live progress information.
{% raw %}
@ -256,7 +261,99 @@ JSON can also be used as `state_topic` payload.
{% endraw %}
For the above JSON payload, the `update` entity configuration should look like this:
Simple progress state update example:
{% raw %}
```json
{
"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
}
```
{% endraw %}
Update percentage state update example:
{% raw %}
```json
{
"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
}
```
{% endraw %}
Publish `null` to reset the update percentage state update's:
{% raw %}
```json
{
"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
}
```
{% endraw %}
The values in the JSON are optional but must be valid within the following schema:
{% configuration %}
installed_version:
description: The software or firmware version installed.
required: false
type: string
latest_version:
description: The latest software or firmware version available.
required: false
type: string
title:
description: Title of the software or firmware update available.
required: false
type: string
release_summary:
description: Summary of the software or firmware update available.
required: false
type: string
release_url:
description: URL pointing to the software release notes.
required: false
type: string
entity_picture:
description: URL pointing to an image of the update to be applied as entity picture.
required: false
type: string
in_progress:
description: Boolean to report an update is in progress or not.
required: false
default: false
type: boolean
update_percentage:
description: Number between 0 and 100 to report the update process. A `null` value resets the in-progress state.
required: false
type: ["integer", "float"]
{% endconfiguration %}
For the above JSON payload examples, the `update` entity configuration should look like this:
{% raw %}