Merge pull request #186 from mdeweerd/dev

Response data - Doc and example.

.pre-commit-config.yaml

@@ -64,6 +64,14 @@ repos:
     rev: v6.2.1
     hooks:
       - id: beautysh
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.9.0.5
+    hooks:
+      - id: shellcheck
+        files: ^[^\.].*\.sh$
+        # Change the entry to make this work on cygwin
+        args: [-x,-e,SC2086,-e,SC2004,-e,SC2207,-e,SC2002,-e,SC2116]
+        # args: ["--severity=warning"]  # Optionally only show errors and warnings
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1
     hooks:

README.md

@@ -226,6 +226,17 @@ the entity. You can switch back and forth!
 There are several examples below for different commands. You can copy/paste
 them to start from.
 
+The services now provide the data as
+[response data](https://www.home-assistant.io/blog/2023/07/05/release-20237/#services-can-now-respond)
+\- they are still provided as event_data.\
+Adding
+`response_variable: VAR_NAME` to a `zha_toolkit` service call will make the
+result of that call available under `VAR_NAME`.\
+You can verify what the
+service returns interactively. Example of an attribute read:
+
+![Service Response Example](ServiceResponse.png)
+
 Not all available commands are documented. The undocumented ones were in
 the original repository.\
 Some of these undocumented commands seem to be
@@ -1734,6 +1745,12 @@ tap_action:
 See [script_use_zha_devices.yaml](examples/script_use_zha_devices.yaml) to
 see how you can loop over the device list provided in the event data.
 
+See
+[script_use_zha_devices_response.yaml](examples/script_use_zha_devices_response.yaml)
+shows how a new method available since Home Assistant 2023.7 that allows us
+to avoid the complexity of event_data by using the response from the
+zha-toolkit service.
+
 ### `register_services`: Reregister ZHA-Toolkit services
 
 The services may have evolved after an update of the code and calling

STATS.md

@@ -1,6 +1,8 @@
 # Badges showing number of downloads per version
 
 - ![badge latest](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/latest/total.svg)
+- ![badge v0.9.7](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.9.7/total.svg)
+- ![badge v0.9.6](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.9.6/total.svg)
 - ![badge v0.9.5](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.9.5/total.svg)
 - ![badge v0.9.4](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.9.4/total.svg)
 - ![badge v0.9.3](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.9.3/total.svg)

custom_components/zha_toolkit/__init__.py

@@ -644,7 +644,7 @@ def register_services(hass):  # noqa: C901
     is_response_data_supported = u.is_ha_ge("2023.7.0")
 
     if is_response_data_supported:
-        from home_assistant.core import ServiceCall
+        from homeassistant.core import SupportsResponse
 
     async def toolkit_service(service):
         """Run command from toolkit module."""
@@ -811,7 +811,7 @@ async def toolkit_service(service):
                 key,
                 toolkit_service,
                 schema=value,
-                supports_response=ServiceCall.OPTIONAL,  # type:ignore[undefined-variable]
+                supports_response=SupportsResponse.OPTIONAL,  # type:ignore[undefined-variable]
             )
         else:
             hass.services.async_register(

examples/fetchOTAfw.sh

@@ -29,9 +29,10 @@
 
 # List all FW files that were already downloaded.
 # The files usually have the FW version in their name, making them unique.
-ls *.ZIGBEE *.OTA *.sbl-ota *.bin *.ota *.zigbee > existing.list
+ls -- *.ZIGBEE *.OTA *.sbl-ota *.bin *.ota *.zigbee > existing.list
 
 # Get and filter the list from Koenk's list, download the files
+# shellcheck disable=SC2016
 curl https://raw.githubusercontent.com/Koenkk/zigbee-OTA/master/index.json |\
     jq -r '.[] |.url' |\
     grep -v -f existing.list |\

examples/script_use_zha_devices_response.yaml

@@ -0,0 +1,34 @@
+---
+alias: Loop over zha_devices, extract some device data.  For HA>=2023.7
+sequence:
+  - service: zha_toolkit.zha_devices
+    data:
+    response_variable: dev_data
+  - service: system_log.write
+    data:
+      logger: zha_devices
+      level: error
+      message: '{{ "Got device_data %s" % ( dev_data.devices ) }}'
+  - service: system_log.write
+    alias: List unavailable only
+    data:
+      logger: zha_devices
+      level: error
+      message: >
+        {% set ns = namespace(names=[]) %}
+        {% for item in dev_data.devices if not item.available %}
+          {% set ns.names = ns.names + [ "'%s'" % (item.name) ] %}
+        {% endfor %}
+        Items: {{ ns.names | join(', ') }}
+  - repeat:
+      for_each: '{{ dev_data.devices }}'
+      sequence:
+        - service: system_log.write
+          data:
+            logger: zha_devices
+            level: error
+            message: >-
+              {{ "Item '%s' Power: %s dBm Available: %s" % (
+                repeat.item.name, repeat.item.rssi, repeat.item.available
+              ) }}
+mode: single

scripts/installNoHacsFromZip.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # To update / install :
-cd config
+cd config || exit
 (
     mkdir -p custom_components/zha_toolkit
-    cd custom_components/zha_toolkit
+    cd custom_components/zha_toolkit || exit
     rm zha-toolkit.zip >& /dev/null
     curl -s https://api.github.com/repos/mdeweerd/zha-toolkit/releases/latest \
         | grep "browser_download_url.*/zha-toolkit.zip" \

scripts/installNoHacsWithGit.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
-cd config/
+cd config/ || exit
 (
     git clone -n --depth=1 --filter=tree:0 https://github.com/mdeweerd/zha-toolkit.git
-    cd zha-toolkit
+    cd zha-toolkit || exit
     git sparse-checkout set --no-cone custom_components
     git checkout
 )
@@ -11,6 +11,6 @@ cd config/
 )
 # To update:
 (
-    cd zha-toolkit
+    cd zha-toolkit || exit
     git pull
 )