zha_toolkit is a custom component providing useful features for ZHA that helps
fix, configure or analyze your zigbee devices.
zha_toolkit also helps with automations (e.g., store a zigbee attribute to a state).
About 2% of the ZHA installs use zha_toolkit.
In order, my top favorite features are:
- Write values that were retrieved from a Zigbee read directly to a state;
- Read Zigbee values from ZHA’s internal cache;
- Go beyond the bindings offered by HA’s UI;
- Finetune and check reporting configurations;
- Perform a scan of the device to get a more detailed picture of what it offers (when the device allows it);
- Write any value to any HA state (not zha-related, but a service offered by the toolkit).
A presumed popular feature is that it provides “online” backups of the Coordinator hardware (which has been validated for the ZNP radios (TI based key) but awaiting confirmation for bellows). (Now ZHA handles backups by itself).
HA2023.7 with zigpy 0.56.0 has breaking changes, you need to update to zha-toolkit v0.9.4
zha-toolkit is more technical than most integrations.
For example, you can check the bindings a device has and remove all of these binding (when the binding table is full for instance), or change reporting configurations - even for sleepy devices and different from the default ones (for example, a thermometer).
zha_toolkit is a fork of zha_custom and has facilitated getting data back from the events, easier access to the commands, documentation and new commands, read/write/read functionnality, backup, getting the device list, scanning the capabilities of a device, update/create Home Assistant states, writing data to CSV, read attributes from cache, … .
You can add this using HACS - it’s in the default repository list.
After adding the componant using HACS, you still need to update your configuration.yaml so that it is loaded after restart:
zha_toolkit:
This is an example of the options available for writing an attribute (there is zha_toolkit.attr_write as well for this):
service: zha_toolkit.attr_write
data:
ieee: 5c:02:72:ff:fe:92:c2:5d
# The endpoint is optional - when missing tries to find endpoint matching the cluster
endpoint: 11
cluster: 0x1706
attribute: 0x0000
attr_type: 0x41
# Example of octet strings (the length is added because of attr_type)
attr_val: [41,33,8,45,52,46,50,191,55,57,136,60,100,102,63]
# Optional manufacturer Id
manf: 0x1021
# Optional, state to write the read value to
state_id: sensor.test
# Optional, state attribute to write the value to, when missing: writes state itself
state_attr: option
# Optional, when true, allows creating the state (if not the state must exist)
allow_create: True
# The manufacturer should be set only for manufacturer attributes
manf: 0x1202
# You can set the next events to use as a trigger.
# The event data has the result of the command (currently attr_read, attr_write)
event_success: my_write_success_trigger_event
event_fail: my_write_fail_trigger_event
event_done: my_write_done_trigger_event
# Settings for attr_write
# Read attribute before writing it (defaults to True)
read_before_write: True
# Read attribute after writing it (defaults to True)
read_after_write: True
# Write attribute when the read value matches (defaults to False)
write_if_equal: False
After updating zha-toolkit, most of the time you do NOT need to restart HA.
If you want to “hack” a few functions, just change the code on your platform and call the service - your code will be used - or you’ll see the error which you can fix and retry the service again.
As Developer Tools>Services is searchable, just typing part of the command will quickly lead to the right one and the leading icon (emojii) helps identify a zha-toolkit service.
Note: this head post has been heavily edited since its initial version.
.