Z-Stack Linux Gateway - Quick Start Guide

This document aims to help the user quickly evaluate what the Z-Stack Linux Gateway offers.

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 Zigbee 3.0 profile is used. The CC13x2/CC26x2 MCUs and the corresponding SimpleLink™ CC13x2/CC26x2 SDK (from 3.10 and onwards) are R22 certified. The CC253x MCUs, TI's legacy Zigbee platform, are R21 certified.

Setting Up

This section will walk through all of the hardware and software setup.

Hardware Prerequisites The following hardware is required:

Software Prerequisites The following software/tools is required:

BeagleBone Black Setup:

This section will detail how to setup the BBB as the host.

  1. Download the Linux Debian Image for BeagleBone Black using the link above.
  2. Burn the Debian image to the microSD card using Etcher.
  3. With the BeagleBone Black powered down, insert the microSD card into the BeagleBone Black microSD port.
  4. Connect an Ethernet cable between the BeagleBone Black and an internet connected router.
  5. On the BeagleBone Black, press and hold down the Boot Button (S2) and insert the 5V power plug.
  6. Keep holding down the Boot Button until the LEDS start blinking (about 5-15 seconds).
  7. Make sure you have the latest BeagleBone Black USB drivers installed on your PC (follow instructions from http://beagleboard.org/getting-started for more information).
  8. Wait for the BeableBone Black to finish booting. You can tell when it's finished booting when you can open an SSH session (with Host Name/IP address as 192.168.7.2) with PuTTY.
  9. The default login is "debian", and the default password is "temppwd".
  10. Update and upgrade all packages.
    • sudo apt-get update
    • sudo apt-get upgrade
  11. Install killall tools.
    • sudo apt-get install psmisc
  12. Install dos2unix package.
    • sudo apt-get install dos2unix
  13. Ensure that the source/scripts/package_builder script has TARGET_PLATFORM set to "BEAGLEBONE_BLACK" (ie. export TARGET_PLATFORM="BEAGLEBONE_BLACK") .
  14. If you are planning on updating Protobuf files please install Protobuf by following the steps below. NOTE: this is not required for initial setup or to try the included sample application
    • sudo apt-get install autoconf automake libtool curl make g++ unzip
    • apt-get install protobuf-c-compiler
    • git clone https://github.com/google/protobuf.git
    • cd protobuf
    • ./autogen.sh
    • ./configure
    • make
    • make check
    • sudo make install
    • sudo ldconfig # refresh shared library cache.

Linux OS setup:

This section will detail how to setup a Linux OS (32-bit or 64-bit) as the host. (This has been tested with Ubuntu 18.0.4 64-bit.)

  1. Update and upgrade all packages.
    • sudo apt-get update
    • sudo apt-get upgrade
  2. Install killall tools (if not already).
    • sudo apt-get install psmisc
  3. Install dos2unix package (if not already).
    • sudo apt-get install dos2unix
  4. Install libprotobuf-c 32-bit libraries and cross compiler.
    • sudo apt-get install libprotobuf-c-dev
    • sudo apt-get install libprotobuf-c-dev:i386
    • sudo apt-get install gcc-multilib
      Note: The 32-bit libraries and cross compiler are installed because the Gateway servers were designed for (and thus assume) a 32-bit machine.
  5. Copy libprotobuf-c libraries to the gateway's protobuf library directory:
    • Navigate to gateway installation home directory (eg. Zigbee_3_0_Linux_Gateway_1_0_0)
    • cp /usr/lib/i386-linux-gnu/libprotobuf-c.a source/Projects/zstack/linux/protobuf-c/lib/x86
    • cp /usr/lib/i386-linux-gnu/libprotobuf-c.la source/Projects/zstack/linux/protobuf-c/lib/x86
    • cp /usr/lib/i386-linux-gnu/libprotobuf-c.so.1 source/Projects/zstack/linux/protobuf-c/lib/x86
    • cp /usr/lib/i386-linux-gnu/libprotobuf-c.so.1.0.0 source/Projects/zstack/linux/protobuf-c/lib/x86
  6. Ensure that source/scripts/package_builder script has TARGET_PLATFORM set to "x86" (ie. export TARGET_PLATFORM="x86").

Linux Gateway Setup: The following instructions will cover setting up the Zigbee Gateway project.

  1. Using WinSCP, connect to the BeagleBone Black. (Skip this step if using Linux OS machine.)
    • Copy the source/ folder to the BeagleBone Black home directory.
  2. On the host, navigate to the source/ directory.
    • cd source/
  3. Convert the setup script to Unix line endings and make executable. Then run the setup script. This will convert all necessary scripts to Unix line endings, will delete (if applicable) and rebuild the source Linux Gateway code, extract binaries, make files executable and install all Node Modules:
    • sudo dos2unix setup.sh
    • sudo chmod +x setup.sh
    • sudo ./setup.sh

ZNP Setup: The following instructions will assist in programming one of the LaunchPads (LAUNCHXL-CC1352P, LAUNCHXL-CC1352R1, or LAUNCHXL-CC26X2R1) with a ZNP hex image. Please see the Firmware README for how the images were built, what Zigbee channel the ZNP uses, etc.

  1. Connect the LaunchPad to your PC.
  2. Open Flash Programmer 2 (or UniFlash).
  3. Erase all flash sections on the LaunchPad.
  4. Select the appropriate image for the Launchpad:
    • ZNP images are located in Firmware/znp/
    • For example, a CC26x2R1 Launchpad will use CC2652R1LP_GW_ZNP_UART.hex
  5. Flash this image to the LaunchPad.
  6. When flashed successfully, connect the LaunchPad to the host, using the A-Male to Mini-Male USB Cable.

Running Gateway Out-of-Box

The local gateway sample application may be used to create and manage a Zigbee network on the host processor itself.

  1. To start the gateway:
    • Open a new terminal accessing the host (eg PuTTY for BeagleBone Black, Terminal for Linux OS machine)
    • cd ~/source/out/Precompiled/servers
    • sudo ./zigbeeHAgw
    • This will start and monitor the following servers:
      • NPI_lnx
      • ZLSZNP
      • NWKMGR_SRVR
      • GATEWAY_SRVR
      • OTA_SRVR
  2. To start the sample gateway application
    • cd ~/source/out/Precompiled/servers
    • sudo ./start_application
  3. You will see the following screen:

Local Gateway Application

For further instructions on how to use this user interface, please refer to the User Interface section of the User's Guide.

Running the Web Application

A web application may be hosted on the local host platform to control the Zigbee network.

  1. If you have already started the Zigbee Linux Gateway servers, start the web application with the following commands:
    • cd ~/source/Projects/node/nodejs_zb_gateway
    • node main.js &
  2. 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
  3. Wait for the Gateway to start. An IP Address will be printed out in the terminal indicating where the local web application is being hosted. On your PC in a web browser, navigate to the IP address of your BeagleBone Black, followed by port 5000.
    • For example: http://192.168.7.2:5000/
    • Note your Host platform's IP address and port may vary in the output.
  4. 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.

Web application

For further instructions on how to use the web app, please refer to the Web Application section of the User's Guide.