From d86ab50c80c8be7ac3d283704c0f6014a5db376c Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Thu, 31 Oct 2024 08:13:13 +0100
Subject: [PATCH] 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>
---
 source/_integrations/mqtt.markdown        |   1 +
 source/_integrations/update.mqtt.markdown | 101 +++++++++++++++++++++-
 2 files changed, 100 insertions(+), 2 deletions(-)

diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown
index 7b9cb3beff4..16f50d22da9 100644
--- a/source/_integrations/mqtt.markdown
+++ b/source/_integrations/mqtt.markdown
@@ -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',
diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown
index 33c9f7f8793..326b16765c7 100644
--- a/source/_integrations/update.mqtt.markdown
+++ b/source/_integrations/update.mqtt.markdown
@@ -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 %}