Merge pull request #49 from mdeweerd/dev

ota_notify - fetch images & documtation & service definition

README.md

@@ -98,6 +98,7 @@ ZHA Toolkit can also:
     - [`znp_restore`: Restore ZNP network data](#znp_restore-restore-znp-network-data)
   - [Miscellaneous](#miscellaneous)
     - [`backup`: Backup the coordinator](#backup-backup-the-coordinator)
+    - [`ota_notify`](#ota_notify)
     - [`zha_devices`: Device List Information to Event or CSV](#zha_devices-device-list-information-to-event-or-csv)
     - [`register_services`: Reregister ZHA-Toolkit services](#register_services-reregister-zha-toolkit-services)
     - [User method](#user-method)
@@ -402,7 +403,6 @@ commands):
 - `bind_group`
 - `get_routes_and_neighbours`
 - `ieee_ping`
-- `ota_notify`
 - `unbind_group`
 - `zdo_flood_parent_annce`
 - `zdo_update_nwk_id`
@@ -1326,6 +1326,39 @@ data:
   command_data: _20220105
 ```
 
+### `ota_notify`
+
+`OTA` is the acronym for "Over the Air" and we implicitally add "update" or
+"upgrade".
+
+`ota_notify` will indicate to the device that an update is available, which
+will trigger the device to request this update from the coordinator (in
+this case zigpy).
+
+Prior to notifying the device, `ota_notify` will request all image provides
+to update the list of available images. By default this is only done on
+startup, so when you add a new image to your local directory or when a new
+update is available from a third party, you'ld have to restart HA. But with
+`ota_notify` no restart is required.
+
+For details on how to setup your images sources, check the
+[zigpy wiki section](https://github.com/zigpy/zigpy/wiki/OTA-Device-Firmware-Updates#enabling-ota-updates).
+Also read about the possibilities to enable logging, and that some devices
+require to be re-associated.
+
+To trigger the OTA update, use `ota_notify` instead. The debug log is
+useful to check the update progress or indication that no update is
+available.\
+When the update starts, be patient: it can take a while.
+
+```yaml
+service: zha_toolkit.ota_notify
+data:
+  # Reference of the device that should be notified about an update.
+  # Using one of the entity/sensor names is so much easier !
+  ieee: sensor.lixee_zlinky_tic_00000000_electrical_measurement
+```
+
 ### `zha_devices`: Device List Information to Event or CSV
 
 Write information from currently known ZHA devices to a CSV file. You also

custom_components/zha_toolkit/__init__.py

@@ -334,7 +334,11 @@
         extra=vol.ALLOW_EXTRA,
     ),
     S.OTA_NOTIFY: vol.Schema(
-        {},
+        {
+            vol.Required(ATTR_IEEE): vol.Any(
+                cv.entity_id_or_uuid, t.EUI64.convert
+            ),
+        },
         extra=vol.ALLOW_EXTRA,
     ),
     S.REJOIN: vol.Schema(

custom_components/zha_toolkit/ota.py

@@ -3,9 +3,20 @@
 LOGGER = logging.getLogger(__name__)
 
 
+async def ota_update_images(
+    app, listener, ieee, cmd, data, service, params, event_data
+):
+    for _, (ota, _) in app.ota._listeners.items():
+        await ota.refresh_firmware_list()
+
+
 async def ota_notify(
     app, listener, ieee, cmd, data, service, params, event_data
 ):
+    await ota_update_images(
+        app, listener, ieee, cmd, data, service, params, event_data
+    )
+
     if ieee is None:
         LOGGER.error("missing ieee")
         return

custom_components/zha_toolkit/services.yaml

@@ -1256,6 +1256,44 @@ misc_reinitialize:
       selector:
         entity:
           integration: zha
+ota_notify:
+  description: Notify a device that an update is available, after triggering ota image providers to fetch new images.
+  fields:
+    ieee:
+      description: >-
+        Entity name,\ndevice name, or\nIEEE address of the node to execute
+        command
+      example: entity.name_of_zigbee_device
+      required: true
+      selector:
+        entity:
+          integration: zha
+    event_success:
+      description: Event name in case of success
+      example: ota_notify_success
+      selector:
+        text:
+    event_fail:
+      description: Event name in case of failure
+      example: ota_notify_fail
+      selector:
+        text:
+    event_done:
+      description: >-
+        Event name when the images were updated and the device notified (either success
+        or failure).
+      example: ota_notify_done
+      selector:
+        text:
+    fail_exception:
+      description: >-
+        Throw exception when success==False, useful to stop scripts, automations
+      selector:
+        boolean:
+    expect_reply:
+      description: Wait for/expect a reply (not used yet)
+      selector:
+        boolean:
 register_services:
   description: >-
     Reregister zha-toolkit services\nUsefull during development when they