Zigpy application examples #1087
Comments
|
+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 -> #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). 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: and 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: 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 PS: zigpy developers also generally recommend read primer on Zigbee / ZCL is also needed as prior knowledge and reference:
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/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: 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... |
@garrethcain FYI, probably not up to date but @pipiche38 did start to write a 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 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: 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. Readme is still pending: Packages of tagged versions are also released via the "zha" project on PyPI This new zha library still depends on the zigpy project + other libraries from the zigpy organization on GitHub: 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: |
Hi, guys. Are there some examples like?:
The text was updated successfully, but these errors were encountered: