Z-Stack Linux Gateway - User's Guide

This document provides directions on how to use the gateway, gateway application, and web application.

Purpose

The Z-Stack™ Linux Gateway is a complete software development suite which can be used to develop a Zigbee-to-IP gateway solution. It features an abstracted socket API for application developers to access the Zigbee functionality, implemented through a set of Linux-based servers. The targeted product SW architecture consists of a Linux host SW component (running on a Linux machine) and Zigbee Network Processor (ZNP) firmware, running on one of TI's SimpleLink™ CC13x2/26x2 wireless MCUs. The software designed to run on the Linux host is a collection of server applications that accomplish two key goals:

Gateway Block Diagram

Getting Started

To get started, please see the Z-Stack Linux Gateway - Quick Start Guide, which details the required hardware/software and how to set them up to use the out of box Z-Stack Linux Gateway.

Installation Contents

This section will describe what the directories in this installation include.

Project Directory

This section will detail the contents of the Project directory.

Configuring the Gateway Servers

Often a user might want to have more control over the network that is created by the servers, or over the local Gateway device itself. Configuration files are available that allow certain parameters to be tweaked to achieve this. Discussed below are some of the more common things that a user might want to tweak through these files. See more configurables here.

Zigbee Network Parameters

A Zigbee network is created when the servers are run via the zigbeeHAgw script. This script individually brings up all the servers in the correct order, and also supplies them configuration files that they read upon startup. config.ini is the configuration file read by the Z-Stack ZNP server that provides the core Zigbee stack interface (Application Framework and Zigbee Device Object layers). This file contains parameters that let you configure the network created with the Z-Stack device. The user could change the channel the network uses via the parameter DEFAULT_CHANLIST, or it could provide a PAN ID that it wants the network to use via ZDAPP_CONFIG_PAN_ID. Proper Gateway operation requires the local Gateway device to act as the network Coordinator, so DEVICE_TYPE should be left as is (set to 0). If you would like the network to be open for joining devices on start up, you can tweak the parameter PERMIT_JOIN. If the devices that need to join the network will require an install code to join, the BDB_DEFAULT_JOIN_USES_INSTALL_CODE_KEY should be set to 0. More information on config.ini can be found here. All the above parameters in config.ini are read at startup, and will be read again if a hard reset is issued to the network manager via the NWK_ZIGBEE_SYSTEM_RESET_REQ command (Z-Stack Linux Gateway API document, section 8.1.1).

Defining Endpoints on the Gateway device

The local device that acts as the coordinator of the network is also a Zigbee node and can support Zigbee endpoints and clusters. This allows the local device to 'act' like a Zigbee device and communicate with the endpoints on other devices in the network. All messages sent by other devices to this endpoint would be received by the application.

An interesting use-case for defining endpoints would be if a Zigbee device in the network needed to control a non-Zigbee device. For instance, if we had a Wi-Fi Light that we wanted to control via a Zigbee switch in our network, we could represent that light via an endpoint defined on our local device. Binding the Zigbee switch with this local light endpoint, could allow the application to receive messages whenever the switch is operated. The application would typically receive this message as an incoming ZCL frame GW_ZCL_FRAME_RECEIVE_IND (Z-Stack Linux Gateway API document, Section 9.3.12) . This message could then be translated by the application into a Wi-Fi message that the switch understands.

The gateway endpoints can be defined in a configuration file called gateway_config.tlg that the Gateway server reads at startup. The file is re-read every time the application issues a reset via the NWK_ZIGBEE_SYSTEM_RESET_REQ command. Details of this configuration file, and an example of how to create some endpoints is provided here. The NWK_GET_LOCAL_DEVICE_INFO_REQ (Z-Stack Linux Gateway API document, Section 8.1.6) command can be used to query the gateway device for a list of registered endpoints and their descriptors. This API can be used by the application to display this information for the end-user as required. Z-Stack Linux Gateway API document, Section 9.3 has more Gateway APIs that can be leveraged to keep track of or bridge-over the attribute-values on local Gateway device endpoints.

The ability to define endpoints on the Gateway device is a very powerful feature that can be leveraged to create a host of interesting features in the user's gateway application. The sample application also demonstrates this feature by allowing the user to record a single-command macro and associate with a gateway endpoint. This macro will now be recalled whenever a message is sent to the Gateway endpoint. Details of this feature, and instructions on using it, are here.

More Configurables

Some of the servers that are part of this release have certain configuration parameters that allow the network to be tuned per the requirements of the end-user application. These parameters are read once at init-time and are used throughout the length of operation of the servers. These servers are associated with some configuration files that indicate the current/default values assigned to these parameters Provided below is a brief description of some of the important configuration parameters that can be tuned for some of these servers. More details and default values can be found in the configuration files included with the installer.

NPI Server

The NPI Server can be configured by modifying parameters in the NPI_Gateway.cfg file. This file contains parameters pertaining to the hardware configuration of the board and the serial interface used to connect to the network processor.

ZSTACK ZNP SERVER

config.ini contains parameters pertaining to the configuration of the network created with the Z-Stack device as coordinator. Here are some brief descriptions of these parameters:

GATEWAY MANAGER SERVER

The Gateway Manager Server contains a Gateway Endpoint Configuration file named gateway_config.tlg that allows a user to define endpoints and clusters on the Gateway device itself. Other devices can then potentially bind to the end points to this Gateway device, and also send it commands that the end-user application then receives.

For example, an "ON/OFF/TOGGLE Light" endpoint may be defined in the gateway_config.tlg file as follows:

// endpoint { ID, EndpointDef, AttrDef }
endpoint { 3, OnOffLightEpDef, OnOffAttrList }

where the EndpointDef onOffLightEpDef is defined (in the same file) as follows:

endpointdef OnOffLightEpDef { ha_profile, ha_onofflight, 0, OnOffInputClusters, OnOffOutputClusters }

Please refer to the gateway_config.tlg file for more examples and explanation of how to define endpoints. Note: Some endpoint IDs are reserved and must not be used as user-defined endpoint ids. Endpoint numbers 0 (Zigbee Device Object) 2 (Gateway endpoint),14 (OTA upgrade endpoint) and 242 (Green Power endpoint) are reserved.

Using the Local Gateway Sample Application

User Interface Sections

Local Gateway Application

There are 9 different sections of the User Interface display. Below is a brief description of each. The backsingle- quote ( `) can be used to move to Devices, Groups, Scenes, or Install Code. The space bar can be used to move to the actions section.

NETWORK

This section provides informative details of the network that has been created by the servers started by the zigbeeHAgw script. It indicates the External PAN ID (IEEE address of the Gateway device), the local PAN ID, channel number on which the network has been formed, and its current state for devices to join (open/close). It also shows the current state of the Identify timer, displaying "READY" when the timer has ended and it's ready to be set again.

DEVICES

This section provides details on the devices that are part of the network that has been created. At start-up, the only device listed, is the gateway device itself. The fields displayed include its unique IEEE address, network address (always 0x0 for the Coordinator), list of active endpoints, and some other details about the endpoint such as the Device ID and Profile ID that it is associated with (Home Automation i.e., HA). Device ID number is the one assigned by the specific profile specification (or defined by the user, in case of a manufacturer specific profile).

GROUPS

Once you have devices added to the network you can create groups within them and that will allow you to send an "ACTION" to a group rather than to a single device. This section indicates which Group is active.

SCENES

"Scenes" can be used to remember a set of states for a group of devices. For instance, if you have multiple lights in your network, you can change their settings individually or as a group, using the ACTIONS keys. Once you do that, you can save these settings in a Scene, and recall them at will.

INSTALL CODE

This interface allows the user to add an install code to the Gateway (Zigbee Coordinator). The first field Install Code is a 16-byte key to establish the connection between a a joining device and the Trust Center. The second field CRC is a 2-byte error-detecting code that will confirm if the Install Code is correct. The third and final field is the 8-byte IEEE Address of the joining device. All three fields are necessary to properly add the Install Code to the Gateway.

ACTIONS

This provides a list of commands you can send targeting the network, or individual/group of devices. The commands include Light related settings (Off/On, Level, Hue, Saturation), Network related settings (Open the network for devices to join, remove devices from network, bind and/or unbind say a Switch to a Light etc), Group/Scene commands, or Base Device Behavior (Start the finding and binding process for a specific endpoint, Add an Install Code to join a new device).

LOG

This section provides trace information that is generated from the application itself as it processes user-input, and also input from the servers.

APPLICATION STATUS

This section provides information regarding the status of the application. The letters N, G and O in the title-bar refer to the 3 servers that this application is connected to (Network Manager, Gateway Manager and OTA Upgrade). Upper case indicates that the connection has been established and lower case indicates that it has been disconnected. The LOG section will indicate it when an application has established connection.

HELP

This section provides Help. A more detailed Help Guide is available by pressing the "?" key.

User Interactions

Adding Devices:
After you bring up the sample application and it has established connection to all the servers ("NGO" visible in the Application Status and Network Status indicates "ACTIVE"), the network is ready to accept connections from Zigbee devices. In the "ACTIONS" section, use the spacebar to navigate to the "Permit Join" (shortcut key "P") to open the network up for joining devices. You can change the time for which the network remains open by pressing +/- key. The "NETWORK" section will indicate a State of "OPEN" with a countdown timer. At this point you can add other Zigbee devices to the network, by following the respective "Join" instructions in their documentation. Once a device has successfully joined the network, it will be listed in the "DEVICES" section along with all its details.

Light Control:
In the "DEVICES" section, use the up/down arrow keys to navigate to a 'Light' device and use "ON/OFF/TOGGLE" or "LVL/HUE/SAT" from the "ACTIONS" section to observe the Gateway control the 'Light' Device.

Temperature/Humidity Sensor:
Temperature/Humidity Sensors added to the network will register changes automatically and periodically when you press the "A" shortcut key.

Bind and Unbind:
The BIND/UNBIND (shortcut keys "D" and "U") action lets you bind and unbind one or more devices.

For instance, to bind a Switch to a Light, you would follow the steps below:

  1. In the "DEVICES" section, use the up/down arrow keys to navigate to the desired Switch device and press "D". The trace log will confirm that a binding source has been selected. (Pressing "D" again, will unselect your device).
  2. Next navigate to a Light device and press "D" again. The trace log will confirm that a binding destination has been selected.
  3. Trace log will show the messages that are being sent to initiate this bind, and also the final result (successful or unsuccessful). The entries should flash green to indicate that binding has been initiated.
  4. After a successful bind, the Switch should be able to control the light.
    • To Unbind, press "U" for the devices one by one, in the same order.

Groups:
One or more devices (such as lights) can be added to a Group and then a command can be sent to them as a group.

Scenes:
Once a group has been created, you can set each device (individually or as a group) to a particular state and store that as a scene.

OTA Upgrade:
To initiate an "OTA Upgrade" you will need to do the following:

Adding Devices Using Install Codes:
You can also add devices using an extra level of security with an Install Code. Some devices may include a prebuilt-in code and others, like development boards, may have an interface that allows the user to add it manually on run time. To add devices using Install Code you need to set the BDB_DEFAULT_JOIN_USES_INSTALL_CODE_KEY flag to "1" on the config.ini file located on zstack server znp. This boolean flag's default value is 0 and needs to be changed before runtime in order for it to take effect. To add a device using an Install Code to the network through the sample app you need to:

Finding and Binding:
You can automatically create binds between the Gateway and the device in the network using START_FINDING_BINDING on the "ACTIONS" section. You can indicate the endpoint using the [+/-] keys and then pressing [Enter]. This function automatically creates binds by cross checking the input and output clusters of the target devices in the network that also have activated this function.

Other Helpful Features:
There are several other "shortcuts", details of which are provided in the Help menu.

Usage help start -------------------------------------------------
- Either Devices, Groups or Scenes are selectable at a given time.
[`] - toggle between the four sections "DEVICES", "GROUPS", "SCENES" and "INSTALL CODE".
The section title of the current selection mode is highlighted with a brighter white, and
marked with [].
- [UP/DOWN] - select a device,
[LEFT/RIGHT] - select an endpoint/group/scene
- [SPACE] toggles between the available actions,
[+/-] changes the value associated with the action,
[ENTER] performs the selected action.
- Each action has a quick access key associated with it (underlined in the action name);
Press a quick access key to select an action and perform it immidiately.
- To issue a Bind/Unbind the action needs to be executed twice:
First it will select the binding source device. Second it will select the binding destination
and perform the action.
if the selected binding destination is the same as the source, the operation is canceled.
- Actions that requires destination address will use unicast, groupcast or broadcast
addressing,depending on the current addressing mode (binding and device removal
always use unicast)
- [A/a] - Automatically read data from all sensors periodically.
- [x] - Perform a soft reset.
- [X] - Perform a hard reset.
- [K/k] - Shutdown the gateway subsystem.
- [O/o] - Initiate OTA operation.
- [B/b] - Enable/Disable Broadcast addressing. (When enabled, 'B' appears on the actions
title line.)
- [*] - Enable/Disable immediate execution. (When enabled, '*' appears on the actions title
line.)
When immediate execution is enabled, actions will be triggered as soon as [+/-] is
pressed, after the respective value is updated.
- [[] - Record a single-command macro
- []] - Assign a a recorded macro
- [1] - Display less log lines
- [2] - Display more log lines
- [3] - Display less device lines, but more log lines
- [4] - Display more device lines, but less log lines
- [=] - Redraw user interface according to actual terminal dimentions

Using the Web Application

The Zigbee web application allows the user to control various aspects of the Zigbee Network and view/control various devices that are commissioned to the network. This section of the guide will walk through how various tasks can be completed for network control as well as guidelines for all current compatible devices.

Dropdown Menu Features:

The following features can be found when one opens the Dropdown Menu. This can be opened by clicking the three horizontal lines in the upper right hand corner of the web application.

Dropdown Menu

Network Information:

The Dropdown Menu displays the current network information. The Channel is the current channel that the coordinator is operating on. When connecting devices, make sure they have permissions to connect to this channel. The Pan ID (Personal Area Network ID) is the unique identifier of the current Zigbee Network.

Network Information

Open/Close Network:

This option allows the user to toggle the ability to allow devices to join the network. This button can be accessed in the Dropdown Menu, by pressing the three horizontal lines in the upper right hand corner. When a user clicks the green button "Open Network", this will send a command to the Linux Gateway to allow devices to join the Zigbee Network for 180 seconds. When a user clicks the red button "Close Network", this will send a command to the Linux Gateway to not allow devices to join the Zigbee Network.

Open/Close Network

Soft System Reset:

When a user clicks this button, the Linux Gateway will perform a soft system reset. This will reset all the Linux Gateways. The ZNP device and all devices that were previously on the network will remain connected to the network. The device cards on the web interface will remain as well. When a user clicks this button, the Linux Gateway will perform a soft system reset. This will reset all the Linux Gateways. The ZNP device and all devices that were previously on the network will remain connected to the network. The device cards on the web interface will remain as well.

Soft System Reset

Hard System Reset:

When a user clicks this button, the Linux Gateway will perform a hard system reset. This will reset all the Linux Gateways, the ZNP device, clear all devices that were previously on the network, and clear all device cards from the web interface. Once clicked, a popup will appear informing the user to wait until the reset has completed. A separate popup will appear when the reset has been successful. If this second popup does not appear after 1 minute, refresh the page and try to perform the hard reset again.