Skip to content

Latest commit

 

History

History
429 lines (310 loc) · 89 KB

README.md

File metadata and controls

429 lines (310 loc) · 89 KB

Travis Build Status Maven Central CLA Assistant Badge Total alerts

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 -:

ID Cluster Description
0000 BASIC This cluster supports an interface to the node or physical device. It provides attributes and commands for determining basic information, setting user information such as location, and resetting to factory defaults.
0001 POWER_CONFIGURATION Attributes for determining detailed information about a device’s power source(s), and for configuring under/over voltage alarms.
0003 IDENTIFY Attributes and commands to put a device into an Identification mode (e.g. flashing a light), that indicates to an observer – e.g. an installer - which of several devices it is, also to request any device that is identifying itself to respond to the initiator.
0004 GROUPS The ZigBee specification provides the capability for group addressing. That is, any endpoint on any device may be assigned to one or more groups, each labeled with a 16-bit identifier (0x0001 – 0xfff7), which acts for all intents and purposes like a network address. Once a group is established, frames, sent using the APSDE-DATA.request primitive and having a DstAddrMode of 0x01, denoting group addressing, will be delivered to every endpoint assigned to the group address named in the DstAddr parameter of the outgoing APSDE-DATA.request primitive on every device in the network for which there are such endpoints.
0005 SCENES The scenes cluster provides attributes and commands for setting up and recalling scenes. Each scene corresponds to a set of stored values of specified attributes for one or more clusters on the same end point as the scenes cluster.
0006 ON_OFF Attributes and commands for switching devices between ‘On’ and ‘Off’ states.
0007 ON_OFF_SWITCH_CONFIGURATION Attributes and commands for configuring On/Off switching devices
0008 LEVEL_CONTROL This cluster provides an interface for controlling a characteristic of a device that can be set to a level, for example the brightness of a light, the degree of closure of a door, or the power output of a heater.
0009 ALARMS Attributes and commands for sending alarm notifications and configuring alarm functionality.
000A TIME This cluster provides a basic interface to a real-time clock. The clock time MAY be read and also written, in order to synchronize the clock (as close as practical) to a time standard. This time standard is the number of seconds since 0 hrs 0 mins 0 sec on 1st January 2000 UTC (Universal Coordinated Time).
000B RSSI_LOCATION This cluster provides a means for exchanging Received Signal Strength Indication (RSSI) information among one hop devices as well as messages to report RSSI data to a centralized device that collects all the RSSI data in the network.
000C ANALOG_INPUT_BASIC The Analog Input (Basic) cluster provides an interface for reading the value of an analog measurement and accessing various characteristics of that measurement. The cluster is typically used to implement a sensor that measures an analog physical quantity.
000F BINARY_INPUT_BASIC The Binary Input (Basic) cluster provides an interface for reading the value of a binary measurement and accessing various characteristics of that measurement. The cluster is typically used to implement a sensor that measures a two-state physical quantity.
0012 MULTISTATE_INPUT_BASIC The Multistate Input (Basic) cluster provides an interface for reading the value of a multistate measurement and accessing various characteristics of that measurement. The cluster is typically used to implement a sensor that measures a physical quantity that can take on one of a number of discrete states.
0013 MULTISTATE_OUTPUT_BASIC The Multistate Output (Basic) cluster provides an interface for setting the value of an output that can take one of a number of discrete values, and accessing characteristics of that value.
0014 MULTISTATE_VALUE_BASIC The Multistate Value (Basic) cluster provides an interface for setting a multistate value, typically used as a control system parameter, and accessing characteristics of that value.
0015 COMMISSIONING This cluster provides attributes and commands pertaining to the commissioning and management of ZigBee devices operating in a network.
0019 OTA_UPGRADE The cluster provides a standard way to upgrade devices in the network via OTA messages. Thus the upgrade process MAY be performed between two devices from different manufacturers. Devices are required to have application bootloader and additional memory space in order to successfully implement the cluster.
0020 POLL_CONTROL This cluster provides a mechanism for the management of an end device’s MAC Data Request rate. For the purposes of this cluster, the term “poll” always refers to the sending of a MAC Data Request from the end device to the end device’s parent. This cluster can be used for instance by a configuration device to make an end device responsive for a certain period of time so that the device can be managed by the controller. This cluster is composed of a client and server. The end device implements the server side of this cluster. The server side contains several attributes related to the MAC Data Request rate for the device. The client side implements commands used to manage the poll rate for the device. The end device which implements the server side of this cluster sends a query to the client on a predetermined interval to see if the client would like to manage the poll period of the end device in question. When the client side of the cluster hears from the server it has the opportunity to respond with configuration data to either put the end device in a short poll mode or let the end device continue to function normally.
0021 GREEN_POWER The Green Power cluster defines the format of the commands exchanged when handling GPDs.
0101 DOOR_LOCK The door lock cluster provides an interface to a generic way to secure a door. The physical object that provides the locking functionality is abstracted from the cluster. The cluster has a small list of mandatory attributes and functions and a list of optional features.
0102 WINDOW_COVERING Provides an interface for controlling and adjusting automatic window coverings.
0201 THERMOSTAT This cluster provides an interface to the functionality of a thermostat.
0202 FAN_CONTROL This cluster specifies an interface to control the speed of a fan as part of a heating / cooling system.
0203 DEHUMIDIFICATION_CONTROL This cluster provides an interface to dehumidification functionality.
0204 THERMOSTAT_USER_INTERFACE_CONFIGURATION This cluster provides an interface to allow configuration of the user interface for a thermostat, or a thermostat controller device, that supports a keypad and LCD screen.
0300 COLOR_CONTROL This cluster provides an interface for changing the color of a light. Color is specified according to the Commission Internationale de l'Éclairage (CIE) specification CIE 1931 Color Space. Color control is carried out in terms of x,y values, as defined by this specification.
0400 ILLUMINANCE_MEASUREMENT The cluster provides an interface to illuminance measurement functionality, including configuration and provision of notifications of illuminance measurements.
0401 ILLUMINANCE_LEVEL_SENSING The cluster provides an interface to illuminance level sensing functionality, including configuration and provision of notifications of whether the illuminance is within, above or below a target band.
0402 TEMPERATURE_MEASUREMENT The server cluster provides an interface to temperature measurement functionality, including configuration and provision of notifications of temperature measurements.
0403 PRESSURE_MEASUREMENT The cluster provides an interface to pressure measurement functionality, including configuration and provision of notifications of pressure measurements.
0404 FLOW_MEASUREMENT The server cluster provides an interface to flow measurement functionality, including configuration and provision of notifications of flow measurements.
0405 RELATIVE_HUMIDITY_MEASUREMENT The server cluster provides an interface to relative humidity measurement functionality, including configuration and provision of notifications of relative humidity measurements.
0406 OCCUPANCY_SENSING The cluster provides an interface to occupancy sensing functionality, including configuration and provision of notifications of occupancy status.
0407 LEAF_WETNESS_MEASUREMENT The server cluster provides an interface to read the percentage of water on the leaves of plants.
0408 SOIL_MOISTURE_MEASUREMENT The server cluster provides an interface to soil moisture measurement functionality, including configuration and provision of notifications of soil moisture measurements.
0500 IAS_ZONE The IAS Zone cluster defines an interface to the functionality of an IAS security zone device. IAS Zone supports up to two alarm types per zone, low battery reports and supervision of the IAS network.
0501 IAS_ACE The IAS ACE cluster defines an interface to the functionality of any Ancillary Control Equipment of the IAS system. Using this cluster, a ZigBee enabled ACE device can access a IAS CIE device and manipulate the IAS system, on behalf of a level-2 user.
0502 IAS_WD The IAS WD cluster provides an interface to the functionality of any Warning Device equipment of the IAS system. Using this cluster, a ZigBee enabled CIE device can access a ZigBee enabled IAS WD device and issue alarm warning indications (siren, strobe lighting, etc.) when a system alarm condition is detected.
0700 PRICE The Price Cluster provides the mechanism for communicating Gas, Energy, or Water pricing information within the premises. This pricing information is distributed to the ESI from either the utilities or from regional energy providers. The ESI conveys the information (via the Price Cluster mechanisms) to other Smart Energy devices.
0701 DEMAND_RESPONSE_AND_LOAD_CONTROL This cluster provides an interface to the functionality of Smart Energy Demand Response and Load Control. Devices targeted by this cluster include thermostats and devices that support load control.
0702 METERING The Metering Cluster provides a mechanism to retrieve usage information from Electric, Gas, Water, and potentially Thermal metering devices. These devices can operate on either battery or mains power, and can have a wide variety of sophistication. The Metering Cluster is designed to provide flexibility while limiting capabilities to a set number of metered information types. More advanced forms or data sets from metering devices will be supported in the Smart Energy Tunneling Cluster
0703 MESSAGING This cluster provides an interface for passing text messages between ZigBee devices. Messages are expected to be delivered via the ESI and then unicast to all individually registered devices implementing the Messaging Cluster on the ZigBee network, or just made available to all devices for later pickup. Nested and overlapping messages are not allowed. The current active message will be replaced if a new message is received by the ESI.
0704 SMART_ENERGY_TUNNELING The tunneling cluster provides an interface for tunneling protocols. It is comprised of commands and attributes required to transport any existing metering communication protocol within the payload of standard ZigBee frames (including the handling of issues such as addressing, fragmentation and flow control). Examples for such protocols are DLMS/COSEM, IEC61107, ANSI C12, M-Bus, ClimateTalk etc.
0705 PREPAYMENT The Prepayment Cluster provides the facility to pass messages relating to the accounting functionality of a meter between devices on the HAN. It allows for the implementation of a system conforming to the set of standards relating to Payment Electricity Meters (IEC 62055) and also for the case where the accounting function is remote from the meter. Prepayment is used in situations where the supply of a service may be interrupted or enabled under the control of the meter or system in relation to a payment tariff. The accounting process may be within the meter or elsewhere in the system. The amount of available credit is decremented as the service is consumed and is incremented through payments made by the consumer. Such a system allows the consumer to better manage their energy consumption and reduces the risk of bad debt owing to the supplier.
0800 KEY_ESTABLISHMENT This cluster provides attributes and commands to perform mutual authentication and establish keys between two ZigBee devices.
0B01 METER_IDENTIFICATION This cluster provides attributes and commands for determining advanced information about utility metering device.
0B04 ELECTRICAL_MEASUREMENT This cluster provides a mechanism for querying data about the electrical properties as measured by the device. This cluster may be implemented on any device type and be implemented on a per-endpoint basis. For example, a power strip device could represent each outlet on a different endpoint and report electrical information for each individual outlet. The only caveat is that if you implement an attribute that has an associated multiplier and divisor, then you must implement the associated multiplier and divisor attributes. For example if you implement DCVoltage, you must also implement DCVoltageMultiplier and DCVoltageDivisor.
0B05 DIAGNOSTICS The diagnostics cluster provides access to information regarding the operation of the ZigBee stack over time. This information is useful to installers and other network administrators who wish to know how a particular device is functioning on the network.

Packages

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

Package Description
com.zsmartsystems.zigbee The main framework and cluster library implementation
com.zsmartsystems.zigbee.autocode Code generator for the ZigBee cluster library classes
com.zsmartsystems.zigbee.dongle.cc2531 Dongle driver for the Texas Instruments ZNP CC2531
com.zsmartsystems.zigbee.dongle.conbee Dongle driver for the Dresden Electronics Conbee
com.zsmartsystems.zigbee.dongle.ember Dongle driver for the Silabs EZSP Network Co-Processor
com.zsmartsystems.zigbee.dongle.ember.autocode Code generator for the Ember NCP dongle commands
com.zsmartsystems.zigbee.dongle.telegesis Dongle driver for the Telegesis dongle
com.zsmartsystems.zigbee.dongle.telegesis.autocode Code generator for the Telegesis dongle commands
com.zsmartsystems.zigbee.dongle.xbee Dongle driver for the Digi XBee dongle
com.zsmartsystems.zigbee.dongle.xbee.autocode Code generator for the XBee dongle commands
com.zsmartsystems.zigbee.console Console commands for the general framework
com.zsmartsystems.zigbee.console.ember Console commands for the Silabs Ember NCP
com.zsmartsystems.zigbee.console.main Main CLI console application
com.zsmartsystems.zigbee.serial Serial driver implementation
com.zsmartsystems.zigbee.test Overall tests and code coverage

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.

Model Support Receive Transmit Antenna
Xbee XU-Z11 Yes -90dBm +4.5dBm Internal
EM358 Yes (EZSP) -100dBm +8.0dBm Internal
EFR32 Yes (EZSP)
EM358LR Yes (EZSP) -103dBm +20.0dBm Internal
MGM111 Yes (EZSP) -99dBm +10.0dBm Internal
RaspBee Yes (CONBEE) -105dBm +8.7dBm Internal
ConBee Yes (CONBEE) -105dBm +8.7dBm Internal
CC2530 Yes (ZNP) -97dBm +4.5dBm
CC2531 Yes (ZNP) -97dBm +4.5dBm
CC2538 Yes (ZNP) -97dBm +7.0dBm
CC2650 Yes (ZNP) -100dBm +5.0dBm
ATSAMR21 No -99dBm +4.0dBm
JN5169 No -96dBm +10.0dBm
HUSBZB-1 Yes (EZSP) Internal
Telegesis ETRX3 Yes (Telegesis) Internal
Qivicon Funkstick Yes (Telegesis) Internal
  • 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.

Command Description
join Enable or disable network join
leave Remove a node from the network
nodelist Lists the known nodes in the network
node Provides detailed information about a node
endpoint Provides detailed information about an endpoint
info Get basic info about a device
identify Sends the identify command to an endpoint
fingerprint Get detailed information about a device
read Read an attribute
write Write an attribute
bind Binds a device to another device
unbind Unbinds a device from another device
bindtable Reads and displays the binding table from a node
attsupported Check what attributes are supported within a cluster
cmdsupported Check what commanda are supported within a cluster
subscribe Subscribe to attribute reports
unsubscribe Unsubscribe from attribute reports
reportcfg Read the reporting configuration of an attribute
otaupgrade Provides information about device Over The Air upgrade server status
installkey Adds an install key to the dongle
linkkey Sets the link key int the dongle, optionally computing the MMO Hash from the join code
netstart Join or Form a network as a router or coordinator
netbackup Backup or restores the state of the dongle
discovery Gets information on the network discovery tasks
routingtable Gets the routing table from a node
neighbours Gets the neighbour table from a node
on Turns a device on
off Turns a device off
level Sets the level on a level control device
color Sets the color on a color control device
covering Sets the level on a window covering device
group Configures multicast groups
scene Configures scenes
factoryreset Resets a node to factory defaults

Ember NCP Commands

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

Command Description
ncpchildren Gets the NCP child information
ncpaddrtable Manages the NCP address table
ncpconfig Read or write an NCP configuration value
ncpscan Performs a scan, looking for other networks, or energy levels on each channel
ncpcounters Gets the NCP debug counters
ncpstate Gets the NCP network state and optionally brings the network up or down
ncpvalue Read or write an NCP memory value
ncpversion Gets the NCP firmware version
ncpsecuritystate Gets the current NCP security state and configuration
ncptransientkey Adds a transient link key to the NCP
ncpmmohash Uses the NCP to perform the MMO hash
ncprouting Prints the NCP routing tables and information
ncpmcast Read and configure NCP multicast group table
ncppolicy REad and write NCP policies
ncptoken Reads and writes manufacturing tokens in the NCP

Telegesis Commands

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

Command Description
ncpsecuritystate Gets the current NCP security state and configuration

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

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.