Merge pull request #46 from mdeweerd/dev

Integrate updated README, example and tuya code comments.

.github/scripts/gen_stats.sh

@@ -5,7 +5,7 @@ DEST=$(dirname $0)/../../STATS.md
 TEMPLATE='- ![badge VERSION](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/VERSION/total.svg)'
 
 # Exclude stuff that results in invalid badges
-EXCLUDES="v0.7.9 v0.7.7 v0.7.6 v0.7.5 v0.7.3 v0.7.2 v0.7.1"
+EXCLUDES="v0.7.9 v0.7.7 v0.7.6 v0.7.5 v0.7.3 v0.7.2 v0.7.1 v0.7.23 v0.7.24"
 
 (
     echo '# Badges showing number of downloads per version'

README.md

@@ -4,7 +4,36 @@
 ![Downloads](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/total)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 
-# Highlights
+[ZHA Toolkit](https://github.com/mdeweerd/zha-toolkit) (Zigbee Home
+Assistant Toolkit) is a custom service for "rare" Zigbee operations using
+the
+[ZHA integration component](https://www.home-assistant.io/integrations/zha)
+in [Home Assistant](https://www.home-assistant.io/) (an open source home
+automation software).
+
+You can add ZHA Toolkit as custom service to Home Assistant using
+[HACS (Home Assistant Community Store)](https://hacs.xyz/). ZHA Toolkit is
+already available HACS default repository list.
+
+## Purpose
+
+The purpose of ZHA Toolkit and its Home Assistant 'Services' feature, is to
+provide direct control overi low level zigbee commands provided in ZHA or
+Zigpy that are not otherwise available or too limited for some use cases.
+
+ZHA Toolkit can also:
+
+- Serve as a framework to do local low level coding (the modules are
+  reloaded on each call).
+
+- Provide access to some higher level commands such as ZNP backup (and
+  restore).
+
+- Make it easier to perform one-time operations where (some) Zigbee
+  knowledge is sufficient and avoiding the need to understand the inner
+  workings of ZHA or Zigpy (methods, quirks, etc).
+
+### Highlights
 
 - Read Zigbee attributes into Home Assistant attributes
 - Daily ZNP Coordinator backup (See blueprint)
@@ -15,9 +44,9 @@
 
 <!-- mdformat-toc start --slug=github --no-anchors --maxlevel=4 --minlevel=1 -->
 
-- [Highlights](#highlights)
-- [Table of Contents](#table-of-contents)
 - [Purpose](#purpose)
+  - [Highlights](#highlights)
+- [Table of Contents](#table-of-contents)
 - [Setup](#setup)
 - [Automations](#automations)
 - [Using `zha_toolkit`](#using-zha_toolkit)
@@ -81,22 +110,6 @@
 
 <!-- mdformat-toc end -->
 
-# Purpose
-
-Using the Home Assistant 'Services' feature, provide direct control over
-low level zigbee commands provided in ZHA or Zigpy that are not otherwise
-available or too limited for some use cases.
-
-Can also serve as a framework to do local low level coding (the modules are
-reloaded on each call).
-
-Provide access to some higher level commands such as ZNP backup (and
-restore).
-
-Make it easier to perform one-time operations where (some) Zigbee knowledge
-is sufficient and avoiding the need to understand the inner workings of ZHA
-or Zigpy (methods, quirks, etc).
-
 # Setup
 
 The component files needs to be added to your `custom_components` directory
@@ -1402,6 +1415,8 @@ Shame on Tuya to be a
 [member of the Zigbee Alliance](https://zigbeealliance.org/member/tuya-global-inc/)
 and deviate from the Zigbee Specifications.
 
+These commands help fix some of that.
+
 #### `tuya_magic` - Tuya Magic spell
 
 This was labeled the

STATS.md

@@ -1,9 +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.7.26](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.26/total.svg)
 - ![badge v0.7.25](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.25/total.svg)
-- ![badge v0.7.23](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.23/total.svg)
-- ![badge v0.7.24](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.24/total.svg)
 - ![badge v0.7.22](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.22/total.svg)
 - ![badge v0.7.21](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.21/total.svg)
 - ![badge v0.7.20](https://img.shields.io/github/downloads/mdeweerd/zha-toolkit/v0.7.20/total.svg)

custom_components/zha_toolkit/_user.py

@@ -8,6 +8,9 @@
 
 from zigpy import types as t
 
+from custom_components.zha_toolkit import utils as u
+from custom_components.zha_toolkit.params import INTERNAL_PARAMS as p
+
 LOGGER = logging.getLogger(__name__)
 
 
@@ -85,3 +88,30 @@ async def user_zigpy_deconz(
         ["model", "manufacturer"], allow_cache=False
     )
     LOGGER.info("Iris 2nd ep attr read: %s", res)
+
+
+async def user_tuya_magic(
+    app, listener, ieee, cmd, data, service, params, event_data
+):
+    """
+    Send Tuya 'magic spell' sequence to device
+    to try to get 'normal' behavior.
+    """
+
+    dev = app.get_device(ieee)
+    basic_cluster = dev.endpoints[1].in_clusters[0]
+
+    # The magic spell is needed only once.
+    # TODO: Improve by doing this only once (successfully).
+
+    # Magic spell - part 1
+    attr_to_read = [4, 0, 1, 5, 7, 0xFFFE]
+    res = await u.cluster_read_attributes(
+        basic_cluster, attr_to_read, tries=params[p.TRIES]
+    )
+
+    event_data["result"] = res
+
+    # Magic spell - part 2 (skipped - does not seem to be needed)
+    # attr_to_write={0xffde:13}
+    # basic_cluster.write_attributes(attr_to_write, tries=3)

custom_components/zha_toolkit/services.yaml

@@ -48,9 +48,9 @@ execute:
             - remove_from_group
             - remove_group
             - scan_device
+            - tuya_magic
             - unbind_coordinator
             - unbind_group
-            - tuya_magic
             - zcl_cmd
             - zdo_flood_parent_annce
             - zdo_join_with_code

custom_components/zha_toolkit/tuya.py

@@ -5,9 +5,11 @@
 async def tuya_magic(
     app, listener, ieee, cmd, data, service, params, event_data
 ):
+    """
+    Send 'magic spell' sequence to device to try to get 'normal' behavior.
+    """
 
     dev = app.get_device(ieee)
-    """Initialize device so that all endpoints become available."""
     basic_cluster = dev.endpoints[1].in_clusters[0]
 
     # The magic spell is needed only once.