Welcome to pyzigbee’s documentation!¶
Version: 0.1.2
Introduction¶
pyzigbee is a python library that enables to talk to Legrand zigbee devices through gateways.
- Supported gateways are:
- 0 883 28: USB dongle
This library works has been tested on Windows and Linux with Python 2.7, 3.3 and 3.4.
Installation¶
If you only want to install the library:
python setup.py install
or with python installer:
pip install .
Use the python installer to install other dependencies that may be needed to run tests or build documentation:
pip install -r requirements.txt
Specific setup instructions¶
Before playing with real hardware, you may need to run some manual setup. Depending on your hardware the steps may be different. This section maintains instructions for the supported gateways
088328 USB/Zigbee dongle¶
driver¶
This dongle embeds a CP2102 USB to UART transceiver. This driver is included in latest Linux kernels. For Windows users, install the driver first:
configuration¶
- Open or create a Zigbee network on a device (NETW led blinking)
- Press the button on the 088328 USB key (NETW led should start blinking slowly)
- Press the NETW button on the device which has open the network
- All the NETW leds should turn off excepted the one of the device which created the network
Note
For gateways relying on a serial line drive (such as 088328), you can list the available ports of your system by running: python -m serial.tools.list_ports
Code example¶
Here is a simple example of pyzigbee library usage (see: pyzigbee/examples/088328/scan.py)
#!/usr/bin/env python
# -*- coding: utf-8 -*-
from __future__ import print_function
from contextlib import closing
from pyzigbee.gateways.factory import GatewayFactory
def scan():
"""
Scan the network looking for zigbee devices and print the found IDs
"""
# Note that you may need to pass a configuration file to
# the GatewayFactory since your low level device may be different
# from the default one. Please read the 'Configuration' section
# of the documentation
gateway = GatewayFactory().create_gateway(ref="088328")
with closing(gateway.open()) as gateway:
ids = gateway.scan()
print("Zigbee devices on the network:", ids)
if __name__ == '__main__':
scan()
You may need to pass a configuration file (see: Configuration) to the factory to be override some driver arguments. Change gateway creation as following:
gateway = GatewayFactory(conf_filename="my_conf.json").create_gateway(ref="088328")
The gateway is the abstraction you will deal with to talk to zigbee devices.
Shell¶
When installing the pyzgbee library, a shell script called pyzigbeesh is also installed.
You can call it from command line:
pyzigbeesh
To display currenly supported arguments:
pyzigbeesh --help
For example, to activate logs:
pyzigbeesh -d 10
Warning
You may need to gain priviledges on your machine to access the underlying hardware (such as the serial com port). A sudo pyzigbeesh should do the trick.
Configuration¶
The pyzigbee library has a default configuration for each supported gateway. This configuration (mainly driver settings) may be overriden by a JSON config file that can be passed to the shell using the –conf option.
Here is an example of such a conf.json configuration file:
{
"088328": {
"driver": {
"args": {
"port": "/dev/ttyUSB0",
"baudrate": "19200"
}
}
}
}
This configuration file could be changed to the following to work on Windows machines:
{
"088328": {
"driver": {
"args": {
"port": "COM1",
"baudrate": "19200"
}
}
}
}
Architecture¶
The big picture¶
------------------- ----------------- ------------------
| Your host running | || Zigbee Gateway || ))) ((( || Zigbee device #1 ||
| pyzigbee | --- HW bus --- || || ------------------
-------------------- ------------------ ...
--------------------
((( || Zigbee device #N ||
--------------------
The HW (hardware) bus can be a serial line, a SPI line,... or whatever depending on the zigbee gateway. The same way, the protocol used to talk with this gateway over the HW bus can vary.
Some more details¶
To reflect reality, the library has the following classes:
- Drivers: deal with low level communication with the underlying hardware
- Protocols: deal with encoding and decoding frames for given protocols
- Gateways: relying on Drivers and Protocols, they provide an API to talk to Zigbee devices
UML diagram¶
The UML diagram should look like:
___________ _______________
| |------------------------------------------------> | <<interface>> |
| Gateway | _______________ | Protocol |
|___________|-------> | <<interface>> | |_______________|
| Driver | ^ ^ ^
|_______________| | | |____________________
^ ^ ^ ______| |_______ |
| | | _____|______ ______|_________ |
| | | | | | |
| | |_________________ | OpenWebNet | | Dummy protocol | ...etc
________| |________ | |____________| |________________|
______|________ ________|_____ |
| | | |
| Serial Driver | | Dummy driver | ...etc
|_______________| |______________|
Note
The dummy classes are used for testing
The client code (application side) only relies on Gateway objects which are created by the GatewayFactory.
Interfaces¶
A Gateway is composed of two objects: a Driver and a Protocol which are interfaces. Real drivers and protocols must implement those interfaces.
-
class
pyzigbee.drivers.basedriver.BaseDriver(**kwargs)[source]¶ Base driver inherited by all the drivers
-
class
pyzigbee.protocols.baseprotocol.BaseProtocol[source]¶ Base protocol inherited by all the protocols
The Gateway is the abstraction on which rely client code. You may need to inherit from and overload some methods to implement your own gateway.