Merge pull request #122 from mdeweerd/dev

Update readme, add zha_devices example script
mdeweerd · Jan 11, 2023 · 7cfa6d8 · 7cfa6d8
2 parents 4542c12 + 4cf221a
commit 7cfa6d8
Show file tree

Hide file tree

Showing 2 changed files with 52 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -63,9 +63,9 @@ ZHA Toolkit can also:
   - [Tries](#tries)
 - [Service commands](#service-commands)
   - [`attr_read`: Read an attribute value](#attr_read-read-an-attribute-value)
-    - [Example: read with write to CSV file](#example-read-with-write-to-csv-file)
-    - [Example of CSV output in /config/csv/testcsv.csv (header may be added in](#example-of-csv-output-in-configcsvtestcsvcsv-header-may-be-added-in)
-    - [Example, read value from cache in state](#example-read-value-from-cache-in-state)
+    - [Example: attribute read with write to CSV file](#example-attribute-read-with-write-to-csv-file)
+    - [Example of CSV output](#example-of-csv-output)
+    - [Example, read attribute value from cache in HA state](#example-read-attribute-value-from-cache-in-ha-state)
   - [`attr_write`: Write(/Read) an attribute value](#attr_write-writeread-an-attribute-value)
   - [Binding related](#binding-related)
     - [`bind_ieee`: Bind matching cluster to another device](#bind_ieee-bind-matching-cluster-to-another-device)
@@ -479,22 +479,22 @@ data:
   csvlabel: MyAttributeLabel
 ```
 
-### Example: read with write to CSV file
+### Example: attribute read with write to CSV file
 
 ```yaml
-service: zha_toolkit.execute
+service: zha_toolkit.attr_read
 data:
-  command: attr_read
   ieee: light.texasinstruments_ti_samplelight_d77add01_level_light_color_on_off
   event_done: zha_done
   attribute: 0
   cluster: 0
   csvout: testcsv.csv
 ```
 
-### Example of CSV output in /config/csv/testcsv.csv (header may be added in
+### Example of CSV output
 
-the future)
+Below is the result in `/config/csv/testcsv.csv` produced by the
+`attr_read` shown above.
 
 ```csv
 2022-02-01T00:10:50.202707+00:00,zcl_version,1,0x0000,0x0000,11,00:12:4b:00:01:dd:7a:d7,,0x20
@@ -506,9 +506,9 @@ Fields in this output:
 ISO8601_Timestamp,cluster_name,attribute_name,value,attr_id,cluster_id,endpoint_id,IEEE,manf,attr_type
 ```
 
-### Example, read value from cache in state
+### Example, read attribute value from cache in HA state
 
-This example reads the raw temperature value from cache into a state
+This example reads the raw temperature value from cache into a home state
 attribute value.
 
 The purpose of this example is to get the unrounded reported value from a
@@ -1521,6 +1521,9 @@ tap_action:
   url_path: /local/devices.csv
 ```
 
+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.
+
 ### `register_services`: Reregister ZHA-Toolkit services
 
 The services may have evolved after an update of the code and calling

diff --git a/examples/script_use_zha_devices.yaml b/examples/script_use_zha_devices.yaml
@@ -0,0 +1,39 @@
+---
+alias: Loop over zha_devices, extract some device data
+sequence:
+  - parallel:
+      - sequence:
+          - wait_for_trigger:
+              - platform: event
+                event_type: zha_devices_ready
+          - service: system_log.write
+            data:
+              logger: zha_devices
+              level: error
+              message: '{{ "Got event %s" % ( wait.trigger.event.data.devices ) }}'
+          - service: system_log.write
+            alias: List unavailable only
+            data:
+              logger: zha_devices
+              level: error
+              message: >
+                {% set ns = namespace(names=[]) %}
+                {% for item in wait.trigger.event.data.devices if not item.available %}
+                  {% set ns.names = ns.names + [ "'%s'" % (item.name) ] %}
+                {% endfor %}
+                Items: {{ ns.names | join(', ') }}
+          - repeat:
+              for_each: '{{ wait.trigger.event.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
+                      ) }}
+      - service: zha_toolkit.zha_devices
+        data:
+          event_done: zha_devices_ready
+mode: single