search

zigpy / zigpy-znp

TI CC2531, CC13x2, CC26x2 radio support for Zigpy and ZHA
GNU General Public License v3.0
149 stars 40 forks source link
cc2531 home-assistant python texas-instruments zigbee zigpy

readme

zigpy-znp

Build Status Coverage Status

zigpy-znp is a Python library that adds support for common Texas Instruments ZNP (Zigbee Network Processors) Zigbee radio modules to zigpy, a Python Zigbee stack project.

Together with zigpy and compatible home automation software (namely Home Assistant's ZHA (Zigbee Home Automation) integration component), you can directly control Zigbee devices such as Philips Hue, GE, OSRAM LIGHTIFY, Xiaomi/Aqara, IKEA Tradfri, Samsung SmartThings, and many more.

Installation

Python module

Install the Python module within your virtual environment:

$ virtualenv -p python3.8 venv                                # if you don't already have one
$ source venv/bin/activate
(venv) $ pip install git+https://github.com/zigpy/zigpy-znp/  # latest commit from Git
(venv) $ pip install zigpy-znp                                # or, latest stable from PyPI

Home Assistant

Stable releases of zigpy-znp are automatically installed when you install the ZHA component.

Testing dev with Home Assistant Core

Upgrade the package within your virtual environment (requires git):

(venv) $ pip install git+https://github.com/zigpy/zigpy-znp/

Launch Home Assistant with the --skip-pip command line option to prevent zigpy-znp from being downgraded. Running with this option may prevent newly added integrations from installing required packages.

Testing dev with Home Assistant OS

Configuration

Below are the defaults with the top-level Home Assistant zha: key. You do not need to copy this configuration, it is provided only for reference:

zha:
  zigpy_config:
    znp_config:
      # Only if your stick has a built-in power amplifier (i.e. CC1352P and CC2592)
      # If set, must be between:
      #  * CC1352/2652:  -22 and 19
      #  * CC253x:       -22 and 22
      tx_power:  

      # Only if your stick has a controllable LED (the CC2531)
      # If set, must be one of: off, on, blink, flash, toggle
      led_mode: off

      ### Internal configuration, there's no reason to touch these values

      # Skips the 60s bootloader delay on CC2531 sticks
      skip_bootloader: True

      # Timeout for synchronous requests' responses
      sreq_timeout: 15

      # Timeout for asynchronous requests' callback responses
      arsp_timeout: 30

      # Delay between auto-reconnect attempts in case the device gets disconnected
      auto_reconnect_retry_delay: 5

      # Pin states for skipping the bootloader
      connect_rts_pin_states: [off, on, off]
      connect_dtr_pin_states: [off, off, off]

Tools

Various command line Zigbee utilities are a part of the zigpy-znp package and can be run with python -m zigpy_znp.tools.name_of_tool. More detailed documentation can be found in TOOLS.md but a brief description of each tool is included below:

Hardware requirements

USB-adapters, GPIO-modules, and development-boards flashed with TI's Z-Stack are compatible with zigpy-znp:

Tip! Adapters listed as "Texas Instruments sticks compatible with Zigbee2MQTT" also works with zigpy-znp.

Reference hardware for this project

These specific adapters are used as reference hardware for development and testing by zigpy-znp developers:

Texas Instruments Chip Part Numbers

Texas Instruments (TI) has quite a few different wireless MCU chips and they are all used/mentioned in open-source Zigbee world which can be daunting if you are just starting out. Here is a quick summary of part numbers and key features.

Supported newer generation TI chips

2.4GHz frequency only chips

Multi frequency chips

Supported older generation TI chips

Auxiliary TI chips

Releases via PyPI

Tagged versions will also be released via PyPI

External documentation and reference

How to contribute

If you are looking to make a code or documentation contribution to this project we suggest that you follow the steps in these guides:

Related projects

Zigpy

zigpy is Zigbee protocol stack integration project to implement the Zigbee Home Automation standard as a Python library. Zigbee Home Automation integration with zigpy allows you to connect one of many off-the-shelf Zigbee adapters using one of the available Zigbee radio library modules compatible with zigpy to control Zigbee devices. There is currently support for controlling Zigbee device types such as binary sensors (e.g. motion and door sensors), analog sensors (e.g. temperature sensors), lightbulbs, switches, and fans. Zigpy is tightly integrated with Home Assistant's ZHA component and provides a user-friendly interface for working with a Zigbee network.