Introduction
The Zigbee Linux Gateway is a complete software development suite of software and tools which can be used to develop a Zigbee-to-IP gateway solution.
The intention of this lab is to help developers get started in creating their own Zigbee-to-IP gateway solution by using the software and example applications provided within the Zigbee Linux Gateway. All tasks in this lab are targeted to be completed within a 2-3 hour time frame.
Task 0: Install the Zigbee Linux Gateway
Task 1: Program the Zigbee Network Processor (ZNP) and any other Zigbee devices you wish to connect to your Zigbee network
Task 2: Setup BeagleBone Black Linux Embedded Host platform
Task 3: Prepare the Zigbee Linux Gateway environment and begin running the Zigbee Linux Gateway servers
Task 4: Running and using the different Zigbee Gateway Sample Applications
Technical support
For any questions you may have, please refer to the TI Zigbee & Thread E2E Forum.
Prerequisites
Background Knowledge
- Intermediate knowledge of the C programming language
- Basic CCS knowledge
- Basic understanding of embedded software development
- Familiar with working in a Linux environment
Software
- Code Composer Studio (latest version) with support for CC13xx/CC26xx devices
- Zigbee Linux Gateway
- UniFlash
- Etcher SD Card Image Burner Software
- Debian Image for the BeagleBone, tested with v9.3
- PuTTy or any other equivalent terminal program
- WinSCP Used for transferring files from Windows PC to the BeagleBone Black
Hardware
- 2 or more Zigbee-capable SimpleLink LaunchPads for running ZNP and sample applications, review the SDK Release Notes for more information.
- Internet access for the Linux Host platform to install node modules and other required packages
- Local network for Linux Host platform and other devices to interact with the Sensor-to-Cloud gateway
- Linux Embedded Host platform:
- BeagleBone Black or BeagleBone Black Wireless
- Either one of the following:
- 5V, 2A AC/DC power supply for BeagleBone Black
- Ethernet Cable (if not using BeagleBone Black Wireless version)
- A-Male to Mini-B USB Cable
- A Windows PC for running UniFlash to program the LaunchPads and for installing the Zigbee Linux Gateway
Two Host Platform Options
The Zigbee Linux Gateway is compatible out-of-box with both Embedded Host (BeagleBone Black) and 32-bit Linux OS support.
However, using the BeagleBone as a Host provides a more realistic environment, closer to the embedded target product, and is what will be used in this lab.
Recommended Reading
- Z-Stack Linux Gateway Quick Start Guide
- Z-Stack Linux Gateway User's Guide
- Z-Stack Linux Gateway Developer's Guide
Note
This lab can be performed using any Zigbee-compatible SimpleLink LaunchPad. The training material is based on the LAUNCHXL-CC26X2R1, so if using a different device, all references to the CC2652R in text and screenshots should be referred to as your particular board.
At the time of writing this, the prebuilt firmware images provided in the Zigbee Linux Gateway are built for Rev E silicon. If using Rev C or older silicon, please build the ZNP and sample applications from a compatible SDK. See this FAQ for more details.
Background
The Zigbee Linux Gateway
TI's Zigbee 3.0 Linux Gateway includes the source code for Zigbee Linux Gateway servers, pre-built ZNP and Zigbee sample application firmware images, and two different Linux Gateway Sample Applications in order to help developers create a Zigbee 3.0 ultra-low power, long-range, mesh network gateway solution.
The following block diagram shows a high level overview of the key components included as part of the Zigbee Linux Gateway.
The Gateway Application is the user application, which is implemented as a socket client. This application is what interacts with the Zigbee Linux Gateway servers. There are two different sample Gateway Applications provided in the Zigbee Linux Gateway installation.
Local Sample Application: A local C-based sample application which displays a GUI in the terminal. This application can only be interacted with locally, and provides a large variety of different Zigbee functionalities which can be performed. For a detailed guide on interacting with this application and how to use more advanced features, see the Z-Stack Linux Gateway User's Guide.
Node.js Web Application: This application example is implemented using the Node.js framework, and is a Zigbee Sensor-to-Cloud complete solution for interfacing a Z-Stack network with any Cloud infrastructure; allowing full remote control, monitoring, and interaction from anywhere in the world. For a guide on interacting with this application and details of its architecture, see the Z-Stack Linux Gateway Developer's Guide.
The Zigbee Gateway Subsystem is the set of servers, implemented as a C-based application, run on a Linux ARM or x86 host machine. These servers act as a middleman between the ZNP and the Gateway Application to communicate serially with the ZNP device to manage the entire Zigbee network. To find more information on the Linux Gateway, see the Z-Stack Linux Gateway Developer's Guide.
Zigbee Network Processor
The Zigbee Network Processor (ZNP) is a low power solution, providing the full Zigbee functionality with minimal development efforts required. The purpose of ZNP is to split the application and the Z-Stack, so the Z-Stack runs on the SoC (i.e. the CC2652R) and the application runs on an external microcontroller, such as the BeagleBone Black. Z-Stack handles all Zigbee protocol tasks, and leaves the microcontroller to handle all the resources required by the application. The ZNP interfaces to any microcontroller through UART or USB. The figure below shows the ZNP Configuration interfacing with the CC2652R and the external microcontroller.
You can read more about the ZNP in the Zigbee Network Processor (ZNP) Interface section from the TI Z-Stack User's Guide. If you desire to create a custom ZNP image, then you can sample from the ZNP project inside of the SimpleLink CC13xx / CC26xx SDK. The most common change is enabling MTO and increasing the source routing capabilities:
#define CONCENTRATOR_ENABLE true
#define CONCENTRATOR_DISCOVERY_TIME 60
#define CONCENTRATOR_ROUTE_CACHE true
zglobals.h
#define MAX_RTG_SRC_ENTRIES 200
#define SRC_RTG_EXPIRY_TIME 255
nwk_globals.h
Task 0: Install Zigbee Linux Gateway
The following task discusses host installation requirements and the steps required to install the Zigbee Linux Gateway.
The installer is an x86 executable which is able to be installed on either a Windows PC or a Linux machine. This SDK provides pre-built firmware images for the ZNP as well as Z-Stack sample applications, such as a Doorlock, Light, Switch, Temperature Sensor, and Thermostat. All of these Zigbee projects and more come as part of the SimpleLink CC13XX/CC26XX SDK, where you may make modifications and rebuild these projects as you wish.
Download Zigbee Linux Gateway to your Windows PC. Later in the lab, the necessary files in this installation will be transferred onto the Host platform.
Important Notice
Please note the installer is unable to be run on a BeagleBone Black, due to architecture restrictions. The installer must be run on a Windows or Linux x86 machine. Also, the Zigbee Linux Gateway v1.0.1 release includes SimpleLink CC13X2/CC26X2 SDK v3.10 prebuilt firmware images.
Run the Zigbee Linux Gateway installer. All files will be installed in the default directory (
C:/ti
for Windows,~/ti
for Linux).
Task 1: Programming LaunchPads
Zigbee Linux Gateway requires a ZNP connected serially to the Host platform to set the device up as a Zigbee Coordinator. This lab will use two LaunchPads, one as a ZNP and the other as a Zigbee End Device (ZED) Light to join the Zigbee network and interact with the Gateway Application. The ZED Light pre-built firmware, and other Zigbee sample application firmware, are included in the Zigbee Linux Gateway, found in Firmware/cc26x2_sampleapps
.
It is assumed you already have installed the Zigbee Linux Gateway installed from Task 0. If not, please install it now.
Program the Zigbee Network Processor
Connect the LaunchPad designated as the ZNP, which will be configured as the Zigbee Coordinator, to the Windows PC.
Run UniFlash, and perform the following steps:
a. UniFlash will automatically find any LaunchPads connected to the PC:
UniFlash Unable to Autodetect LaunchPad?
If you have more than one LaunchPad connected to the PC, ensure you select the correct LaunchPad when flashing the ZNP firmware. You can compare the XDS Device ID to the Serial Number field displayed in UniFlash. You can find the XDS Device ID by running the
xdsdfu
tool provided with CCS. The tool can be found inc:\ti\ccs920\ccs\ccs_base\common\xds110\xdsdfu.exe
.b. Make sure that the flash memory has been completely erased on each of your LaunchPads before flashing any new Zigbee application on a LaunchPad. To do so, start the session with the connected LaunchPad, then go to
Settings & Utilities
tab in UniFlash and perform a Manual Erase on the entire flash.c. In the
Program
tab under Flash Image(s), browse to the pre-built ZNP hex file for your particular device. All hex files for supported devices (CC2530/CC2531/CC2538/CC2652R1/CC1352R1/CC1352P2) can be found inside theFirmware/znp/
directory within the Zigbee Linux Gateway installation.d. Make sure to first Load Image, then Verify Image afterwards.
Program Additional Zigbee Devices
Program your additional LAUNCHXL-CC26X2R1 LaunchPads by following the same steps above, using the provided Zigbee sample applications firmware (Found in the
Firmware/cc26x2_sampleapps
directory) instead of the ZNP firmware. For this lab, the ZED Light example (zed_light_cc26x2lp.hex
) will be used.Note
To build your own Zigbee sample applications, you need to start with the SimpleLink CC13xx / CC26xx SDK examples. The Zigbee Linux Gateway sample applications have the channel default set to 13. Building and running the Z-Stack sample applications are out of scope for this lab. You can refer to the Developing Zigbee Applications section in the TI Z-Stack User's Guide for more detailed information.
Task 2: Setup BeagleBone Black
For a detailed guide on connecting your BeagleBone to a Windows PC to interact with, you can follow BeagleBoard's Getting Started page here: https://beagleboard.org/getting-started.
SD Card Setup
These steps will ensure you get your SD card set up on your Embedded Host with the latest linux distribution for your Zigbee Linux Gateway.
Download the latest Linux Debian image (or tested version 9.3) for your specific BeagleBone found here: https://beagleboard.org/latest-images/. This lab will be using the Stretch IoT (without graphical desktop) image.
Once finished, open Etcher (or whichever SD card image burner you will be using) and connect SD card to your computer.
Write the image to your SD card by clicking Flash!.
When Etcher notifies you that the image was written successfully, eject the now programmed SD card and insert the SD card into your (powered-down) BeagleBone.
Starting and Connecting to BeagleBone
The steps below will get your BeagleBone turned on, booting from the formatted SD card, and connected to your Windows PC over PuTTy.
With your SD card inserted into the BeagleBone, hold down the USER/BOOT/S2 button and apply power, either by a USB cable or 5V adapter. Hold the button down for about 5-10 seconds.
You'll see the power (PWR or ON) LED lit, and within a minute, you should see the other LEDs blinking in their default configuration. If connected via USB, a network adapter should show up on your computer. Your BeagleBone will run a DHCP server that provides your computer with an IP address of 192.168.7.1 (or 192.168.6.1 for Mac OS and Linux) and the BeagleBone will assign itself the IP address 192.168.7.2 (or 192.168.6.2 accordingly). To see when the BeagleBone is ready, you can run the following command with Command Prompt:
ping 192.168.7.2 -t
. Within a couple of minutes you should see replies from the BeagleBone, and you will then be ready to connect to the BeagleBone.Patience
The first boot from a freshly formatted SD card takes about 1 to 2 minutes longer than normal, as the BBB Debian Linux distribution performs some one-time-only steps.
Once the BeagleBone is powered on, open PuTTy and type in your BeagleBone's assigned IP address while making sure the Connection Type is SSH, then press Open.
When logged in, you should see a similar screen as shown in the figure below.
Note
The default credentials for the BeagleBone Debian image provided:
- user:
debian
- password:
temppwd
- user:
If you are using a BeagleBone black-wireless device, you will need to setup the wifi before proceeding further, otherwise you can move on to the next section. Please follow the instuctions on one of these external resources before moving forward:
Updating and Installing All Required Packages
Update and install all required packages. Note that running these steps requires an internet connection on your Host platform.
First, run the following commands on the BeagleBone inside PuTTy to update and upgrade all installed packages. If you haven't changed the default credentials, the password is the same as noted in the steps above.
sudo apt-get update sudo apt-get upgrade
Now install the required killall and dos2unix packages by running the following commands:
sudo apt-get install psmisc tofrodos dos2unix sudo ln -s /usr/bin/fromdos /usr/bin/dos2unix
After following these steps, you will have a fresh, newly setup Embedded Host platform environment which will soon be ready to start running the Zigbee Linux Gateway.
Task 3. Setup and Run Zigbee Linux Gateway Servers
Preparing the Zigbee Linux Gateway
The following steps will cover getting the Zigbee Gateway applications and servers set up on the Host platform. These steps may also be found in the Z-Stack Linux Gateway Quick Start Guide.
Transfer necessary Gateway files to your Host platform by following the steps below.
In order to securely transfer the Linux Gateway and sample application files from your Windows PC, which the Zigbee Linux Gateway was installed on, to the BeagleBone, use a program such as WinSCP, listed in the Software Requirements section.
a. Open WinSCP and enter in the BeagleBone's credentials to connect.
b. Navigate to the Zigbee Linux Gateway installation directory (
C:\ti\Zigbee_3_0_Linux_Gateway_1_0_1
) and copy the entiresource/
folder into the BeagleBone's home directory (/home/debian
) using drag-and-drop in the WinSCP interface. Once all files have finished copying, close WinSCP to terminate the connection to the BeagleBone.On the Host platform, run the Linux Gateway setup script to automatically convert all files to Unix line endings, delete and rebuild the source Linux Gateway, extract binaries, make file executables, and install all Node.js modules. Note that this step requires internet access to download all required Node.js modules. To run the script, enter the following commands on the Host platform:
cd source/ sudo dos2unix setup.sh sudo chmod +x setup.sh sudo ./setup.sh
Run Linux Gateway Setup Script
Note
If you are using a Ubuntu PC host as your Host platform, run the following command to gain access to the serial port used for communicating with the LaunchPad:
sudo adduser $USER dialout
. For this command to take full effect, restart the Ubuntu PC after executing. This does not apply for Embedded Host platforms such as the BeagleBone Black.
Connecting the ZNP to the Host
Connect your ZNP LaunchPad to the Host Platform using a USB cable, such as the one provided with your LaunchPad.
You can verify the Host platform is enumerating the device successfully by running the command below. You should see output similar as shown.
debian@beaglebone:~/source$ ls -l /dev/ttyACM* crw-rw---- 1 root dialout 166, 0 Nov 2 14:08 /dev/ttyACM0 crw-rw---- 1 root dialout 166, 0 Nov 2 14:08 /dev/ttyACM1
Not Working?
If you do not see any serial ports enumerated after plugging in your LaunchPad flashed with the ZNP image, first ensure that the green LED on the left side of the LaunchPad is ON. This indicates the LaunchPad is receiving power. If there is no LED lit, unplug the LaunchPad from the BeagleBone side and plug it back in, then wait a few seconds.
It is also possible that the LaunchPad has enumerated using different serial device names (e.g. /dev/ttyACM3). If this is the case, you must update the gateway configuration file, which assumes /dev/ttyACM0 by default. Do this by opening the NPI Gateway configuration file insidesource/out/Precompiled/servers/NPI_Gateway.cfg
. You are able to change the device path string (devPath), as well as other configuration parameters about the ZNP here. Note that the LaunchPad enumerates as two separate serial devices. Choose the lower-numbered suffix. If this fails, try the other serial device name instead.
Starting the Zigbee Linux Gateway Servers
Before running the Gateway sample applications, the Zigbee Linux Gateway servers need to be running in the background first. The sample application acts as a socket client and therefore needs the servers, which act as socket servers, to be running before the Gateway application can connect and run properly.
Ensure all of the tasks above were followed and the ZNP is plugged into the Host platform properly.
Navigate to the web application directory and start the Linux Zigbee Gateway servers by running the following commands:
cd ~/source/Projects/node sudo ./start_gateway.sh &
Start the Zigbee Linux Gateway servers
This PuTTy terminal will show logs for how all Zigbee Gateway servers communicate between each other from the ZNP up to the sample application and vice versa.
Terminating Servers
To kill all currently running Zigbee Linux Gateway servers, run the following command inside the node directory:
sudo ./end.sh
. You may have to be patient as this can take up to a minute for all of the processes to end.
Task 4. Running and Using the Gateway Applications
Running Node.js Web Application
Starting the Node.js Web Application
After completing the tasks above, you are now ready to start running the Zigbee Gateway Sensor-to-Cloud web application on your Host platform. The steps below describe how to begin running the Sensor-to-Cloud sample application for an interactive Zigbee-to-IP network.
Ensure all of the prior tasks were followed and the ZNP is plugged into the BeagleBone.
Follow one of the two ways to start the Node.js web application:
If you have not started the Zigbee Linux Gateway servers, you may start both the servers and the web application with the following commands.
cd ~/source/Projects/node sudo ./start_local.sh
Start the Linux Gateway servers and web application
Start up sequence fails?
First try to reset the LaunchPad through the on-board reset push button. If this does not immediatly resolve the issue, then terminate the startup sequence, unplug and replug the LaunchPad back into the host platfrom, and then rerun the commands.
If server startup continues to fail, go into source/out/Precompiled/source/servers and edit the zigbeeHAgw file to either define SOC_RESET_REQUIRED=0 in setup_for_arm or remove execution of soc_reset_hold and soc_reset_release in hw_reset_soc, and also remove the soc_reset_hold and soc_reset_release files located in thesource/out/Precompiled/tools
folder. Then terminate the startup sequence, unplug and repulg the LaunchPad back into the host platfrom, and rerun the commands.To start just the web application, navigate to the main Node.js web application directory, then start the web application by running the following commands.
cd ~/source/Projects/node/nodejs_zb_gateway node main.js &
Start local Node.js web application in the background
Note
You can run this command in the same PuTTy terminal as the Zigbee Linux Gateway servers, or in a separate PuTTy terminal window if you wish to keep the server logs separate. If you attempt to run the
start_local.sh
script with the Zigbee Linux Gateway servers already running, you will encounter errors.
You should see the output
webserver: Server running on http://192.168.7.2:5000/
when the local Sensor-to-Cloud web application is running. Note your Host platform's IP address and port may vary in the output.The integrated local web server should now be accessible via your Host platform's IP address on port 5000 (e.g.
http://192.168.7.2:5000/
). Open a web browser on any machine connected to the same local network as the Host platform. When you've navigated to your Host platform's Sensor-to-Cloud address in your browser, you should be presented with a similar screen as pictured below.
Note
To get the Zigbee Sensor-to-Cloud application to run on the IBM Cloud and be accessible for full remote control, monitoring, and interaction from anywhere in the world, refer to the Z-Stack Linux Gateway User's Guide. The instructions in this lab above will setup the Sensor-to-Cloud application to be accessible only within the Host platform's local network.
Basic Web Application Usage
The Sensor-to-Cloud web interface allows the user to control different aspects of the Zigbee Network as well as view and control the Zigbee devices in the network.
Drop-Down Menu Features
The first element you will notice in the Sensor-to-Cloud web interface is the drop-down menu, which can be opened by clicking the three horizontal lines in the right hand corrner of the interface.
The drop-down menu displays the current network information, such as the channel which the ZNP Zigbee Coordinator is operating on (Default is 13). The PAN ID (Personal Area Network ID) is displayed below which represents the unique identifier of the current Zigbee network. Below the network information is three buttons to control the ZNP.
The Open/Close Network button allows the user to toggle the ability to allow devices to join the network. Pressing Open Network will send a command to the Linux Gateway to open the Zigbee network for devices to join for 180 seconds. Pressing Close Network will send a command to the Linux Gateway to close the network, disallowing devices to join the Zigbee network.
The Soft System Reset button sends a command to the Linux Gateway to perform a soft system reset, resetting all the Linux Gateway servers. The ZNP and all devices joined in the network will remain connected to the network, and the Device Cards will persist on the web interface.
The Hard System Reset button sends a command to the Linux Gateway to perform a hard system reset, resetting all the Linux Gateway servers, the ZNP device, clearing all devices previously on the network, and clearing all Device Cards on the web interface.
Device Cards
Device Cards represent a device which has joined the Gateway network and are displayed on the Sensor-to-Cloud web interface. They function to create an organized list of all devices which are joined in the network, displaying controls and data which can be customized for each device type.
Each card contains a few common elements such as the Device Type description, the IEEE address beside the Device Type, and the End Point number of the device appended to the end of the IEEE address string. Pressing the "X" button in the upper right corner of the Device Card causes the ZNP to send a Leave Request to the ZED as well as removes the Device Card from the web interface. For more information about the different Device Card types and their functions, refer to the Z-Stack Linux Gateway User's Guide.
Adding Additional Devices to the Web Application
When the Gateway Sensor-to-Cloud web application starts for the first time, no devices will be present in the list and the network will be closed, meaning the Zigbee network will not accept any new device connections.
For adding additional Zigbee devices to your Zigbee Gateway network, you can program the pre-built Zigbee sample applications on additional LaunchPads. Follow the steps in Task 1 for programming your Zigbee devices.
Connect your additional Zigbee device(s) to an available powered USB port, or USB power adapter to power on your LaunchPad(s).
Open the drop-down menu in the top right corner of the Sensor-to-Cloud web interface, and press the Open Network button to open the Zigbee network for Zigbee devices to join, as shown in the figure below. The Zigbee network will stay open for a default of 180 seconds as defined in the Zigbee specification.
After opening the network, press BTN-1 on the ZED Light LaunchPad, which will automatically start the Zigbee Network Steering process, joining the now open Zigbee network. If the ZED light is able to join successfully, the Sensor-to-Cloud web interface should update, showing the Zigbee Light device card.
Running Gateway Local Sample Application
The following gives a brief introduction on how to run the Gateway local sample application on the Host platform. For further instructions on all the various functions this application provides, refer to the Z-Stack Linux Gateway User's Guide.
Starting the Gateway Local Sample Application
After completing the tasks above, you are now ready to start running the Zigbee Gateway local sample application on your Host platform. The steps below describe how to begin running the Zigbee Gateway local sample application which displays an interactive GUI for the user to directly interact with on the terminal which is connected to the Host platform. It is recommended to run this application in a PuTTy terminal separate from the PuTTy terminal running the Gateway servers in order to see all of the server logs alongside the Gateway application.
Ensure all of the previous tasks were completed and the ZNP is plugged into the BeagleBone.
Navigate to the main Linux Zigbee Gateway server directory and then start the local sample application in a fullscreen PuTTy terminal.
cd ~/source/out/Precompiled/servers sudo ./start_application
Start local sample application
Adding Additional Devices to the Local Sample Application
When the Gateway local sample application starts for the first time, no devices, excluding the ZNP Zigbee Coordinator, will be present in the list, and the network will be closed, meaning the Zigbee network will not accept any new device connections.
For adding additional Zigbee devices to your Zigbee Gateway network, you can program the pre-built Zigbee sample applications on additional LaunchPads. Follow the steps in Task 1 for programming your Zigbee devices.
Connect your additional Zigbee device(s) to an available powered USB port, or USB power adapter to power on your LaunchPad(s).
Press J in your local sample application window to start the Finding and Binding process, which opens the Zigbee network for other Zigbee devices to join. The Zigbee network will stay open for a default of 180 seconds as defined in the Zigbee specification.
After opening the network, press BTN-1 on the ZED Light LaunchPad, which will automatically start the Zigbee Network Steering process, joining the open Zigbee network. If the ZED light is able to join successfully, the local sample application should update the Devices list, showing the new Zigbee device with its IEEE Address, the short address, and End Point information.
Final notes
Network information and network state is saved in Non-Volatile memory by both the ZNP (using the host file system) and the Zigbee devices connected (using the internal flash memory). This ensures that all Zigbee devices are able to securely re-join the network following a power-cycle. If you wish to repeat Task 4 from scratch, starting a completely new Zigbee network, you will need to reset both the ZNP and other connected Zigbee devices to Factory New defaults. You can perform a Hard System Reset in the Sensor-to-Cloud web application for the ZNP and Reset Factory New via the Common User Interface (CUI) in PuTTy for other Zigbee devices. Holding down BTN-2 on the LaunchPad while restarting the device through a power cycle or reset pin toggle will also perform a factory reset for application projects. The ZNP however must perform a SYS_OSAL_NV_WRITE MT command to NV ID 0x03 at value 0x03 followed by a SYS_RESET to clear NV memory.
Want to Get Deeper?
This lab is based on pre-built binaries of the Zigbee Linux Gateway servers and applications. To modify and build the sample applications from the source, please refer to the Firmware/README.html
.
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.