Overview

This project aims to provide a ZigBee compatible framework written in Java and compatible with Android. It provides a ZigBee Cluster Library implementation, and network management functions, aiming to provide a full featured ZigBee framework that can be implemented within end systems. This repository aims to provide a high quality framework, with quality documentation and a thorough set of test cases to ensure against regression.

Packages are broken down to provide the main ZigBee framework, separate packages for dongles, and a console application that allows full use of the framework. The bundles include OSGi headers for use within an OSGi framework.

Minimum Android support is currently API19, Android 4.4 (KitKat). It is highly recommended to move to Android 8 as this may become the minimum requirement in the future to allow the framework to use the newer classes available from API26. Note that more modern language features are incorporated into the library and this may require Android users to use a modern version of Android Studio.

Features

Features include -:

• ZigBee Cluster Library
• Over-The-Air firmware upgrade
• Device information data store

ZigBee Cluster Library

The framework includes a ZigBee Cluster Library that is auto-generated from an XML definition file.

The following clusters are currently supported -:

Packages

The framework implements a package structure that allows efficient use of re-usable components in a number of different applications.

Testing

The framework incorporates a lot of unit testing, ensuring real data received from devices can be correctly decoded. When an error is detected following operation with real devices, a test case is normally added to reproduce the error and then it is fixed.

Logging

A log viewer to decode the logs and present them in a usable format is available here. This provides filtering of data at different levels and filtering by node address.

ZigBee Stack

The framework implements a ZigBee stack, currently employing a single endpoint. The default profile, device type and supported clusters can all be configured.

The supported clusters must be configured or the framework will not process any received frames. Likewise, the framework will not respond to messages sent to any endpoints other than endpoint 1.

To add support for local clusters, use the ZigBeeNetworkManager methods addSupportedClientCluster and addSupportedServerCluster. Note that any configuration required in the transport layer (dongle dependant) will also need to be configured consistently.

Dongles

Silicon Labs Ember EM35x / EFR32

The library supports the Silicon Labs EZSP (EmberZNet Serial Protocol) APIs for EM35x and EFR32 SoCs using ASH or SPI protocols over a serial interface. The implementation of the SPI protocol assumes that the SPI provides a TTY-like software interface to the application, or is otherwise abstracted via the ZigBeePort interface.

It is worth noting that EM3588 devices that have an embedded USB core will likely work with any baud rate, where dongles using external USB interface (eg CP2102 used with an EM3581) will likely require a specific baud rate.

Silabs did use to provide two main NCP images pre-build with firmware for EM35x, one image supported hardware flow control with a baud rate of 115200 and the other image supported software flow control with a rate of 57600.

Silicon Labs no longer provide pre-build firmware images, so now you have to build and compile firmware with their Simplicity Studio SDK for EmberZNet PRO Zigbee Protocol Stack Software. Simplicity Studio is a free download but building and compiling EmberZNet PRO Zigbee firmware images required that you have the serialnumber of an official Zigbee devkit registered to your Silicon Labs user account.

Ember NCP configuration

The library provide a standard set of configuration constants to configure the NCP for use as a coordinator. There are two methods available in the Ember driver to manipulate the configuration maps updateDefaultConfiguration and updateDefaultPolicy. The configuration is sent to the NCP during the initialisation sequence which is performed when calling the ZigBeeNetworkManager.initialize() method, so any changes to configuration must be performed prior to this.

The Ember dongle driver includes a public method getEmberNcp() which returns a EmberNcp class. This class provides high level methods for interacting directly with the NCP.

Ember Reset

By default the library uses the ASH Reset command to reset the NCP when the framework starts. Silabs have stated that this is not reliable due to possible communication problems between the NCP and the host. Where possible the user should implement a hardware reset to reset the NCP. Since this is application specific, the framework provides an interface for the application to implement this reset. The user should implement the EmberNcpResetProvider interface, and set this during NCP initialisation with the ZigBeeDongleEzsp.setEmberNcpResetProvider() method.

Ember MfgLib use

The library provides access to the mfglib functions in the NCP to facilitate device testing. To use this function, create the ZigBeeDongleEzsp and then call the getEmberMfglib(EmberMfglibListener) method to get the EmberMfglib class and also set the callback listener. The EmberMfglib class provides access to the mfglib functions.

Note that this can only be used if the dongle is not configured for use in the network (ie initialize has not been called).

The com.zsmartsystems.zigbee.sniffer project is an example of the use of these features to provide a network sniffer to route frames to Wireshark.

Texas Instruments CC2531

The library supports the Texas Instruments ZNP protocol over a serial interface.

Telegesis ETRX3

The library supports the Telegesis AT protocol over a serial interface. Currently implemented against R309C. Note that some dongles such as the Qivicon Funkstick may use PID/VID codes that require special drivers or they will not be detected as a serial port.

Under Linux you can add the Qivicon dongle without a custom made kernel with the following command -:

echo 10c4 89fb > /sys/bus/usb-serial/drivers/cp210x/new_id

ConBee / RaspBee

The library supports the Dresden Electronics RaspBee and ConBee dongles. Note that this requires some further work.

XBee

The XBee S2C XStick is supported.

Tested Hardware

The framework has been tested against many different devices - many lights, motion sensors, temperature/humidity/light sensors, plug sockets...

ZigBee Dongles and Chipsets

The following table provides a summary of some of the dongles / chipsets that are available on the market and their support within the library. Receive sensitivity and transmit power are the main parameters affecting RF performance - it should be noted that regulations may reduce transmit power in some areas of the world and other factors can also impact performance.

• Receive: Defines the typical receive performance. A lower number is best.
• Transmit: Defines the maximum output power. A higher number is best.

Device Data-Store

The framework implements a data store to serialise device information to and from disk to ensure network information is persisted across restarts. This is implemented via the ZigBeeNetworkDataStore interface, and the implementation of this interface is set in the ZigBeeNetworkManager with the setNetworkDataStore(ZigBeeNetworkDataStore) method.

While optional, it is highly recommended that this data store be implemented as it will greatly enhance performance across system restarts.

Application Extensions

The framework includes optional functional applications to support higher layer functionality. Extensions implement the ZigBeeNetworkExtension interface and are registered with the network manager with the ZigBeeNetworkManager.addExtension() method. Extensions provide the top level network manager functionality and are normally augmented with lower level client/server functions associated with specific clusters. These client/server applications implement the ZigBeeApplication interface and are registered with the endpoint with the ZigBeeEndpoint.addApplication() method.

Currently implemented extensions include -:

• Discovery Extension (ZigBeeDiscoveryExtension)
• Network Mesh Monitor Extension (ZigBeeDiscoveryExtension)
• IAS CIE client (ZigBeeIasCieExtension)
• OTA Upgrade Server (ZigBeeOtaUpgradeExtension)
• Basic Cluster Server (ZigBeeBasicServerExtension)

These provide basic functionality and can be extended as required to meet the application needs.

It should be noted that extensions to the framework should be performed by linking to the ZclCluster through the ZclCommandListener notifications. This ensures that processing of DefaultResponse commands is handled correctly as the framework will automatically handle sending of these responses if there is no response sent. Calls to the handleCommand method must return true if the method has sent a response, or false if no response is sent to ensure that the framework correctly handles the DefaultResponse notifications. If all handlers return a false response, then the framework will send a DefaultResponse with UNSUP_CLUSTER_COMMAND, UNSUP_GENERAL_COMMAND, UNSUP_MANUF_CLUSTER_COMMAND or UNSUP_MANUF_GENERAL_COMMAND, as appropriate.

Overview

Extensions may provide different levels of functionality - an extension may be as simple as configuring the framework to work with a specific feature, or could provide a detailed application.

An example of a simple extension is the ZigBeeOtaUpgradeExtension which simply listens for new devices on the network, and adds the ZclOtaUpgradeServer to the endpoint.

A more complex extension could for example handle the CIE IAS zones, providing a cross device implementation to coordinate the allocation of zones and handling of alarms.

The lifecycle of an extension is as follows -:

• extensionInitialize is called when the extension is first registered
• extensionStartup is called when the network is online and the extension may run operationally.
• extensionShutdown is called when the extension is closed. The framework will do this when it is shutting down.

Extensions should normally register as a ZigBeeNetworkNodeListener to get notified when a node is discovered or removed from the network so that they can add support to the node. The extension will then register a client or server application with the endpoint. The client/server application may register for callbacks with the endpoint (or node).

Extension may want to register a supported cluster with the ZigBeeNetworkManager.addSupportedServerCluster() and ZigBeeNetworkManager.addSupportedClientCluster() methods so that the services provided are discoverable.

Client/Server implementations will normally be linked to a specific cluster and provide the application logic for the cluster. The client/server implementation class should be named with the same name as the cluster, but exchanging Cluster for Client or Server (eg a server supporting the ZclOtaUpgradeCluster would be named ZclOtaUpgradeServer).

Console Application

A console application is provided as part of the package. This application allows full use and testing of the framework. It can be used to test any new functionality without the added complexity of application level integration, or may be used as a stand-alone ZigBee configuration tool.

All commands implement the ZigBeeConsoleCommand interface, providing an easily extendible command system.

The command handlers used in the console application are in the package com.zsmartsystems.zigbee.console. This is separate from the main console application, and this allows the command handlers to be incorporated into other frameworks.

Command handlers for commands specific to each dongle implementation are in the package com.zsmartsystems.zigbee.console.abc (where abc is the name of the dongle). These commands allow access to non standard API relating solely to each dongle.

Command handlers take a set of arguments as provided by the user and will throw IllegalArgumentException if there are any errors with arguments, or IllegalStateException if there are any issues with the network state that prevent the command execution.

Starting the Console

The console application takes the following parameters -:

| Option | Description | | ---------------------------- | -------------------------------------------------------- | -------- | --------- | ------ | ----- | | -?,--help | Print usage information | | -a,--pan | Set the ZigBee PAN ID | | -b,--baud | Set the port baud rate | | -c,--channel | Set the ZigBee channel ID | | -d,--dongle | Set the dongle type to use (EMBER | CC2531 | TELEGESIS | CONBEE | XBEE) | | -e,--epan | Set the ZigBee EPAN ID | | -f,--flow | Set the flow control (NONE | HARDWARE | SOFTWARE) | | -h,--profile | Set the default profile ID | | -l,--linkkey | Set the ZigBee Link key (defaults to well known ZHA key) | | -n,--nwkkey | Set the ZigBee Network key (defaults to randon value) | | -o,--nwkkeyoutcnt | Set the ZigBee Network key outgoing frame counter | | -p,--port | Set the port | | -t,--linkkeyoutcnt | Set the ZigBee Link key outgoing frame counter | | -r,--reset | Reset the ZigBee dongle |

The -dongle and -port options are always required. Most dongles will also require -baud, and may require -flow, although this may be hard coded for dongles that do not have this option.

If -reset is used, you should normally also set the -channel, -pan, -epan and -nwkkey options. If not set, defaults will be used to allow the system to start, however these may be random and may not allow you to use a network sniffer or other tools where some of this information may be required. The -linkkey may also be set, but will default to the well known ZHA ZigBeeAlliance09 key if not set.

Decimal configuration values such as pan may be specified in decimal, or hexadecimal by prepending 0x to the value (eg 0x2000).

Example -:

-dongle EMBER -port /dev/tty.usbserial-FTD6C0AF -baud 115200 -flow software -channel 11 -pan 0x2000 -epan 987654321 -nwkkey AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -reset

Console Commands

Where an address is required, endpoints can use the format 123/1 (destination/endpoint), or in hexadecimal (0xed1/1). Group addresses can be subsituted by preceding the address with a # - eg #123 or #0xed1.

General Commands

Note that the console is currently being refactored and this readme only documents the commands that have been migrated. For a full list of commands, use the help command in the console.

Ember NCP Commands

The following commands are available if the transport layer is using the Silabs Ember NCP.

Telegesis Commands

The following commands are available if the transport layer is using the Telegesis dongle.

Contributing

• Code style should use standard naming conventions
• Codacy static testing should pass.
• Run the findBugs goal and check that you have not introduced any bugs into your code. FindBugs reports are generated with the mvn site goal, and reports are located in the target/site/findbugs.html file.
• Please consider raising issues before working on an enhancement to provide some coordination with other contributors.
• Keep PRs short - try and keep a single PR per enhancement. This makes tracking and reviewing easier.
• Contributions must be supported with tests. Ideally, you should aim to acheive full coverage of the code changes. Code coverage reports are located in the com.zsmartsystems.zigbee.test/target/site/jacoco-aggregate folder and opening the index.html file.
• Code must be formatted using the Eclipse code formatter provided in the project.
• Contributions must be your own and you must agree with the license.
• You must sign the PR and commits and must agree to the Contributor License Agreement.

Maven

The library is published directly to the maven central repository, and the following dependency can be specified -:

<dependency>
    <groupId>com.zsmartsystems.zigbee</groupId>
    <artifactId>com.zsmartsystems.zigbee</artifactId>
    <version>1.x.x</version>
    <type>pom</type>
</dependency>

Maven Goals

• To build: mvn clean install
• To prepeare a new release: mvn release:prepare
• To perform a new release: mvn release:perform
• To bump the version: mvn release:update-versions
• To format the license header: mvn license:format
• To produce the findbugs (etc) reports: mvn site

Gradle

gradlew clean build

Gradle build dependencies:

dependencies
{
    compile 'com.zsmartsystems.zigbee:com.zsmartsystems.zigbee:1.x.x'
}

Note:

Change 1.x.x to desired/latest version (24.12.2018 1.x.x -> 1.1.7)

License

The code is licensed under Eclipse Public License. Refer to the license file for further information.

Some parts of this code are from zigbee4java which in turn is derived from ZB4O projects which are licensed under the Apache-2 license. These are being refactored out to ensure the contributions to this reportisory are understood.

ZigBee Documentation

Some documentation used to create parts of this framework is copyright © ZigBee Alliance, Inc. All rights Reserved. The following copyright notice is copied from the ZigBee documentation.

Elements of ZigBee Alliance specifications may be subject to third party intellectual property rights, including without limitation, patent, copyright or trademark rights (such a third party may or may not be a member of ZigBee). ZigBee is not responsible and shall not be held responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights.

No right to use any ZigBee name, logo or trademark is conferred herein. Use of any ZigBee name, logo or trademark requires membership in the ZigBee Alliance and compliance with the ZigBee Logo and Trademark Policy and related ZigBee policies.

This document and the information contained herein are provided on an “AS IS” basis and ZigBee DISCLAIMS ALL WARRANTIES EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO (A) ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OF THIRD PARTIES (INCLUDING WITHOUT LIMITATION ANY INTELLECTUAL PROPERTY RIGHTS INCLUDING PATENT, COPYRIGHT OR TRADEMARK RIGHTS) OR (B) ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NONINFRINGEMENT. IN NO EVENT WILL ZIGBEE BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF BUSINESS, OR FOR ANY OTHER DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND, IN CONTRACT OR IN TORT, IN CONNECTION WITH THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.

All Company, brand and product names may be trademarks that are the sole property of their respective owners.

Dongle Documentation

Some documentation used to implement dongle drivers is copywrite to the respective holders, including Silicon Labs, Texas Instruments, Dresden Electronics, Digi International.