zigpy
Zigpy application examples
Hi, guys. Are there some examples like?:
- Device enumeration: list all connected devices to my zigbee-adapter
- Data reading from devices
- Device command sending
+1 here
It will be extra useful to get some examples of basic flow when using as separate library (without HA and/or even quirks).
Unfortunatly, no one has written application examples or documentation than what is in zigpy wiki and CONTRIBUTING.md file:
https://github.com/zigpy/zigpy/wiki
https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md
Currently, best zigpy use reference is instead Home Assistant's zha component integration as Zigbee gateway implementation:
https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha
Perhaps some independent developers are willing to extend/improve the zigpy API documentation in CONTRIBUTING.md via PRs?
https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md
zigpy also have the zigpy wiki which is a wiki so anyone can add or change to contribute informaton and examples:
https://github.com/zigpy/zigpy/wiki
Anyway, zigpy libraries are for low-level Zigbee use so you really need to read up on ZCL (Zigbee Cluster Library) and the Zigbee protocol as a primer in order to get deeper knowledge about how Zigbee works in order to develop new applications with zigpy.
Currently the zigpy API is only documented here -> https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md#the-zigpy-api
Unfortunately, no one has yet written a guide on how to make an application with zigpy or provided examples for all use cases.
This is a free and open source project that is maintained by volunteers in their spare time, so you can actually help here too!
If you post a direct specific and narrow question then I am sure that some zigpy developer(s) can try to help give a code example.
Note! Be aware that many tools from zigpy radio libraries are deprecated as have instead been moved to zigpy-cli instead:
https://github.com/zigpy/zigpy-cli
Perhaps with help from independent developers like yourself, zigpy-cli could someday become a high-level tool, but needs to be extended with more commands (so submit patches to zigpy-cli to extend its functionality) -> https://github.com/zigpy/zigpy-cli
Also, you need to go to application and command examples previously posted as replies to direct questions -> https://github.com/zigpy/zigpy/issues/1087
Today there are only larger/full Zigbee gateway implementations such as ZHA integration component for Home Assistant, the Zigbee Plugin for Domoticz, and the Zigbee Plugin for Jeedom (competing open-source home automation software, where in the case of the Zigbee Plugin for Jeedom you, unfortunately, need to buy and install Jeedom and that plugin to get its code).
-
https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha
-
https://github.com/zigbeefordomoticz/Domoticz-Zigbee
Also check out zha-toolkit -> https://github.com/mdeweerd/zha-toolkit/ it however depends on the zha component integration services -> https://www.home-assistant.io/integrations/zha#services
As for zigpy API documentation there is unfortunately only some basic info available here:
https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md
(And the ZHA Device Handlers /Quirks documentation -> https://github.com/zigpy/zha-device-handlers/edit/dev/README.md ).
Also see this pull request "Documenting zigpy API a kind of developer guide" that was only partially copied to above document:
https://github.com/zigpy/zigpy/pull/477
and
https://github.com/zigpy/zigpy/pull/470
Maybe you could improve API documation and try to submit another pull request to update API docs in CONTRIBUTING.md or post info in wiki? -> https://github.com/zigpy/zigpy/wiki
(Perhaps for additional inspiration also look at https://github.com/Koenkk/zigbee-herdsman#api-documentation ?).
There no other docs but also check through issues and discussions as some pointers have been given to others who asked, as ex:
https://github.com/zigpy/zigpy/discussions/709
https://github.com/zigpy/zigpy-znp/issues/108
https://github.com/zigpy/zigpy-znp/issues/77
https://github.com/zigpy/zigpy-znp/issues/152
https://github.com/zigpy/zigpy-znp/issues/25
https://github.com/zigpy/zigpy-znp/issues/166
https://github.com/zigpy/zigpy-znp/issues/192
https://github.com/zigpy/zigpy/issues/452
https://github.com/zigpy/zigpy/issues/469
https://github.com/zigpy/zigpy/pull/470
https://github.com/zigpy/zigpy/issues/471
https://github.com/zigpy/zigpy/issues/715
https://github.com/zigpy/zigpy/issues/7
https://github.com/zigpy/zigpy-znp/issues/166
https://github.com/zigpy/zigpy/discussions/595
https://github.com/zigpy/zigpy/discussions/709
https://github.com/zigpy/zigpy/discussions/865
https://github.com/zigpy/bellows/issues/431
as well as existing articles in the zigpy wiki:
https://github.com/zigpy/zigpy/wiki
Other than using the ZHA integration component code for Home Assistant as reference might also want to look at the code of the Zigbee Plugin for Domoticz and the Zigbee Plugin for Jeedom (competing open-source home automation software) which both partially implements zigpy libraries as dependencies:
https://github.com/zigbeefordomoticz/Domoticz-Zigbee/ (dev https://github.com/zigbeefordomoticz/Domoticz-Zigbee/tree/dev).
Again, also check out zha-toolkit -> https://github.com/mdeweerd/zha-toolkit/ it however depends on the zha component integration services -> https://www.home-assistant.io/integrations/zha#services
- https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha
PS: zigpy developers also generally recommend read primer on Zigbee / ZCL is also needed as prior knowledge and reference:
- https://github.com/zigpy/zigpy/discussions/595
- Zigbee Boot Camp
- Zigbee Protocol Specification (also known as "Zigbee Pro" specifications)
- Zigbee Cluster Library Specification
- Zigbee Base Device Behavior Specification (V1.0)
- Zigbee Lighting & Occupancy Device Specification (V1.0)
- ZigBee Smart Energy Standard (v1.2a)
PPS: In addition, you can also reference third-party and manufacturer-specific documentation:
Oh, by the way, other than zigpy-cli be sure to also check out the code for zha-toolkit for low-level Zigbee commands using zigpy:
https://github.com/zigpy/zigpy-cli
https://github.com/mdeweerd/zha-toolkit/
FYI, dmulcahey also began working on a web socket client–server model design but it looks like he at least paused that it for now:
https://github.com/zigpy/zigpy/discussions/1207
https://github.com/zigpy/zha-websocket-server/
https://github.com/zigpy/zhaws-addon
https://github.com/dmulcahey/home-assistant/tree/dm/zha-ws
https://github.com/dmulcahey/home-assistant/tree/dm/zha-ws/homeassistant/components/zhaws
Believe needs both zhaws-addon + zhaws from fork of Home Assistant core with ZHA WS implementation as custom component.
Again, perhaps some independent developers be willing to extend/improve the zigpy API documentation in CONTRIBUTING.md?
https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md#the-zigpy-api
Also see this related suggestion/idea of adding some kind of Automatic API Documentation Generation for zigpy Python libraries:
https://github.com/zigpy/zigpy/issues/1105
If need inspiration suggest to check out matter.js and com.zsmartsystems.zigbee as a few examples of summarizing API concepts:
https://github.com/project-chip/matter.js/blob/main/packages/matter.js/API.md
https://github.com/zsmartsystems/com.zsmartsystems.zigbee/blob/master/README.md
I'd be willing to write some stand-alone examples (not HA related) and even get documentation started if I could get some help to ramp up my understanding...
I'd be willing to write some stand-alone examples (not HA related) and even get documentation started if I could get some help to ramp up my understanding...
@garrethcain FYI, probably not up to date but @pipiche38 did start to write a zigpy_api.md a few years ago, check out:
https://github.com/zigpy/zigpy/pull/477
https://github.com/zigpy/zigpy/issues/471
IMHO best approach to begin today might be to just start writing one or more short stand-alone examples as a small "draft" pull request in a new section for the CONTRIBUTING.md file as then you can get feedback to that pull reuqest from zigpy developers:
https://github.com/zigpy/zigpy/blob/dev/CONTRIBUTING.md
Then once you get started with a format that is acceptable to existing zigpy developers then you could submit new pull requests.
This specific issue/tracker and the application-level questions in it should now maybe/probably be moved to the repository for the new zha (zha gateway) library:
- https://github.com/zigpy/zha
- https://github.com/zigpy/zha/issues
The zigpy library is a low-level library, while the new zha library is a high-level library that is event based and has a simpler API.
- https://github.com/zigpy/zha/blob/dev/zha/application/gateway.py
Readme is still pending:
- https://github.com/zigpy/zha/pull/131
- https://github.com/zigpy/zha/pull/131/commits/b761767a35db649d0ba621b077351ff7551587de
Packages of tagged versions are also released via the "zha" project on PyPI
- https://pypi.org/project/zha/
- https://pypi.org/project/zha/#history
- https://pypi.org/project/zha/#files
This new zha library still depends on the zigpy project + other libraries from the zigpy organization on GitHub:
- https://github.com/zigpy
The new zha library is meant to be used by application-level implementations such as the Zigbee Home Automation integration) in Home Assistant, howevers others (like yourselves) could potentially also use it to create stand-alone Zigbee Gateway applications or externally by other types of Zigbee host applications.
That new zha library is actually parts of Home Assistant's ZHA component that have been split/broken-out as an stand-alone library, which is now what the ZHA integration in Home Assistant now depends on to use as an external Zigbee Gateway library so that code there could potentially be used as a reference implementation:
- https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha