[SUGGESTION] Zigpy developer guide

[pipiche38]

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

• What are the zigpy principle. What does it do (from pairing a device, to handling of messages).
• The usage of asyncio and the development consequences
• how to receive messages from devices (flow)
  • receiving attributes values
  • receiving commands
• how to send command to devices (flow)
• the concept of listner
• How to deal with the Zigbee radio sub libraries
• Zigpy radio schema (which affects configuration options ) - see RFC: Zigpy/API/Radio schemas #381
• how to use quirks

2- My first App using zigpy

• create the PersistentDB and open the zigbee radio (BTW, I don't understand what the 2 are linked together; I would expect (i) PersistentDB (ii) Zigbee radio communication)
• Loading the DB and adding listener
• setting the call back methods

3- API list

4- How to deal with errors

[Gamester17]

@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

http://www.openzwave.com/dev/

Getting Started

There 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.

[pipiche38]

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

[Gamester17]

FYI, showcasing importance of getting started guidance see the introduction on the homepage of OpenZWave listing its features:

• Fully Documented Code Base
• Includes simple examples to demonstrate how to interface to the code

http://www.openzwave.net

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

• Developed in C++
• Dotnet wrapper for Windows
• Portable to most Linux, Mac OSX and Windows Platforms
• Works with the multiple ZWave Controllers
• ZWave Protocol is abstracted away hiding a lot of the complexity
• Works with most switches, dimmers, thermostats, energy monitors, motion sensors, appliance modules,key fobs, door/window * sensors etc (see here for a complete list)
• S_ecurity related devices such as Locks are Supported_
• Reverse Engineered the ZWave Protocol
• Easy to add support for new devices
• Fully Documented Code Base
• Includes simple examples to demonstrate how to interface to the code

[pipiche38]

Here is a starting file
https://github.com/pipiche38/Domoticz-Zigpy/blob/master/zigpy_api.md

feel free to add/comment

[Hedda]

Here is a starting file
https://github.com/pipiche38/Domoticz-Zigpy/blob/master/zigpy_api.md

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!

[Hedda]

@pipiche38 please also see the somewhat related replies from @puddly to @Mopele in zigpy/zigpy-znp#25

[github-actions]

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.

[Hedda]

Perhaps best to keep this open? And instead close #715 which looks to maybe be a duplicate?