[SUGGESTION] Zigpy developer guide #471
Comments
|
@dmulcahey also already written a very nice guide on how to build a quirk for ZHA Device Handlers which has good info too: https://github.com/zigpy/zha-device-handlers/blob/dev/CONTRIBUTING.md @puddly and @Adminiuga also posted some examples in #452 which could maybe together with the parts of the work @pipiche38 publisged in his https://github.com/pipiche38/Domoticz-Zigpy project to make some kind of a small example application which only has the very bare minimum needed in a small standalone Zigbee gateway application? For reference, in regards to this, you can to a degree compare the zigpy library to the OpenZWave library, which even though is written in C++ and is meant for Z-Wave instead Zigbee looks at least in an overview on paper to in essence have the exact same concept as the zigpy libary. They too have a "Getting Started" introduction which includes both online Developers documentation (generated from source comments by Doxygen) as well as such minimum example of a standalone application called "MinOZW" (short for 'Minimum OpenZWave') which is based on the library, and the idea is that they use this example application in their guides. https://github.com/OpenZWave/open-zwave/blob/master/README.md Getting StartedThere is an example application based on the library, it is called MinOZW and it is part of the open-zwave repository. This currently offers a minimal example. There are also plenty of other examples on the Internet that you can research. On Linux, macOS, BSD run "make" to build the library and MinOZW. Optionally, run "make install" to install the library, header and config files system-wide. Run "BUILD=DEBUG make" to make a debug build. Online Developers documentation is generated from source comments by Doxygen. If you do "make install" and have Doxygen on your system, a description of the api will be in open-zwave/docs/api/html/index.html On Windows, install "Visual Studio" then open "open-zwave/cpp/build/windows/vs2010/OpenZWave.sln" to build the library or "open-zwave/cpp/examples/windows/MinOZW/vs2010/MinOZW.sln" to build both library and sample application. |
|
I might be wrong, but from what I read from the zha-device-handers is much more oriented on developing a quirk rather than an application using the full stack. Again, pointing to existing application is good, but this doesn't give the perspective and the general design, and required to understand and take time to read. I'm convinced that all the knowledge is there, the point is just to extract it and put it in a user guide. And this is not about automatic documentation as here I agree reading the code is the best. But you need to get the main principles , the general design and architecture to be able to navigate to the code and the all library |
|
FYI, showcasing importance of getting started guidance see the introduction on the homepage of OpenZWave listing its features:
With the exception of those missing two points they list the homepage of OpenZWave only basically the same features zigpy have: Introduction Our goal is to create free software library that interfaces with selected Z-Wave PC controllers, allowing anyone to create applications that manipulate and respond to devices on a Z-Wave network, without requiring in-depth knowledge of the Z-Wave protocol. This software is currently aimed at Application Developers who wish to incorporate Z-Wave functionality into their applications. If you are a looking for applications to control your Z-Wave devices, please consult this page which lists applications that utilize OpenZWave. Features
|
|
Here is a starting file feel free to add/comment |
See that submitted a PR with this file to zigpy now in #477 so have something all can build on. Thank you @pipiche38 That is great! |
|
@pipiche38 please also see the somewhat related replies from @puddly to @Mopele in zigpy/zigpy-znp#25 |
|
There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved with the latest updates. Please make sure to update to the latest version and check if that solves the issue. Let us know if that works for you by adding a comment 👍 This issue has now been marked as stale and will be closed if no further activity occurs. Thank you for your contributions. |
|
Perhaps best to keep this open? And instead close #715 which looks to maybe be a duplicate? |
Here is the summary of a refection I had after trying to build a poc for Domoticz. This is not about documenting the code itself, but more how to start.
Maybe it is just about creating the file, and then having everyone contributing to it.
I would be more than happy to handle and challenge the content.
As a library you need to provide some guide on how-to use such library. I tried with #470, but I don't think we understand each other.
Just have a look to https://www.domoticz.com/wiki/Developing_a_Python_plugin which describe the steps on how to develop a plugin in Domoticz.
What I would expect from a Zigpy Developer Guide are:
1- Concepts
2- My first App using zigpy
3- API list
4- How to deal with errors
The text was updated successfully, but these errors were encountered: