UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) RD-0001-0201: Zigbee Wi-Fi/Ethernet Gateway Reference Design and RD-0002-0201: Zigbee USB Virtual Gateway Reference Design are designed to demonstrate Zigbee coordinator functionality with Silicon Labs Zigbee reference designs: * RD-0039-0201: Capacitive Sense Dimmer Switch Reference Design * RD-0030-0201: Contact Sensor Reference Design * RD-0051-0201: Smart Outlet Reference Design * RD-0100-0201: Smart Outlet Reference Design * RD-0078-0201: Occupancy Sensor Reference Design * RD-0099-0201: Occupancy Sensor Reference Design * RD-0020-0601: Lighting Reference Design * RD-0035-0601: Lighting Reference Design * RD-0085-0401: Lighting Reference Design * RD-0098-0401: Lighting Reference Design KEY POINTS * Describes Zigbee gateway reference designs. * Provides step-by-step instructions for the installation and configuration process. * Explains the gateway functionality. * Details the software architecture of the gateway. * Offers troubleshooting solutions and references for common issues. This user's guide refers to Silicon Labs Gateway software release version 2.5.0. silabs.com | Building a more connected world. Rev. 0.7 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Introduction 1. Introduction This section introduces RD-0001-0201: Zigbee Wi-Fi/Ethernet Gateway Reference Design and RD-0002-0201: Zigbee USB Virtual Gateway Reference Design. The software is distributed as three software components: * Z3Gateway Application * NodeJS Server Application * ReactJS Front-End Application The Z3Gateway Application offers three transport options for inter-process and off-gateway communication: * Telnet * CoAP * MQTT The MQTT transport is used for inter-process communication with the NodeJS Server Application. The software binaries are available using the Linux apt package manager, as described in section 2. Installation and Configuration for the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) and 3. Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201). The software source code for the Z3Gateway application is available as a host example application distributed with the EmberZNet PRO 6.2.0 Zigbee stack. For more information on how access the Zigbee stack please see http://www.silabs.com/products/wireless/ mesh-networking/Pages/getting-started-with-mighty-gecko-zigbee.aspx. The software source code for the NodeJS Server Application and ReactJS Front-End Application is available on github at https:// github.com/SiliconLabs/gateway-management-ui and is also installed on the target system at /opt/siliconlabs/zigbeegateway/gateway_management_ui. The kits RD-0001-0201 and RD-0002-0201 are no longer available for purchase from Silicon Labs. Most users found it more convenient to acquire the Raspberry Pi hardware from third-party sources. Throughout this document the part numbers RD-0001-0201 and RD-0002-0201 are used to refer to the kit acquired previously from Silicon Labs or built with components from a third-party. The kits RD-0001-0201 and RD-0002-0201 shipped from Silicon Labs used a CEL USB dongle as the NCP. To improve ease-of-use, the CEL USB dongle is replaced with one of the three wireless starter kit mainboards available with the EFR32 Mighty Gecko Wireless SoC Starter Kit (SLWSTK6000B). Notes are made throughout this document to guide users wishing to continue using their CEL NCP USB dongle and EM35x-DEV end-devices. The WiFi / Ethernet Gateway runs on a Raspberry Pi 2 Model B or Raspberry Pi 3 Model B computer with Raspbian Linux and Zigbee NCP (network co-processor). A Silicon Labs EFR32 Mighty Gecko Wireless Starter Kit such as SLWSTK6000B is required as the NCP. The gateway includes a Wi-Fi soft access point and a web server that presents a user interface to a desktop or mobile web browser. The web browser can run on a device connected via Wi-Fi or wired local area network (LAN). A typical Zigbee system configuration with the Zigbee Wi-Fi/Ethernet Gateway is shown in the following figure. silabs.com | Building a more connected world. Rev. 0.7 | 2 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Introduction Figure 1.1. Typical Zigbee Wi-Fi/Ethernet Gateway Configuration The USB Virtual Gateway runs on Ubuntu Linux 16.04 and Zigbee NCP, and is available for Windows and OSX host operating systems within a Virtualbox virtual machine. A Silicon Labs EFR32 Mighty Gecko Wireless Starter Kit such as SLWSTK6000B is required as the NCP. The gateway uses the host computer Wi-Fi client and includes a web server that presents a user interface to a desktop or mobile web browser. The web browser can run on the Virtualbox virtual machine or on a device connected via the LAN. A typical Zigbee system configuration with the Virtual Gateway is shown in the following figure. Figure 1.2. Typical Zigbee Virtual Gateway Configuration silabs.com | Building a more connected world. Rev. 0.7 | 3 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) 2. Installation and Configuration for the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) The Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) runs on a Raspberry Pi computer. The following instructions describe how to order, set up, and install the Raspbian operating system and gateway software. 2.1 Order a Raspberry Pi Refer to https://www.raspberrypi.org for recommended vendors for each component. * Raspberry Pi 2 Model B or Raspberry Pi 3 Model B * 16 GB MicroSD card * Edimax EW-7811UN USB 2.0 Wireless Adapter (required for Raspberry Pi 2 Model B only) * 5V 2A Power supply 2.2 Set Up the Raspberry Pi 1. Connect the USB Wi-Fi Adapter to one of the Raspberry Pi 2 Model B's USB ports (Raspberry Pi 3 Model B already has built-in WiFi). 2. Connect the Raspberry Pi's Ethernet port to the Internet with an Ethernet cable. 3. Connect one of the Wireless Starter Kit mainboards to the Raspberry Pi with a USB cable. This will become the network co-processor as shown in Figure 1.1 Typical Zigbee Wi-Fi/Ethernet Gateway Configuration on page 3 4. Connect a monitor to the HDMI port and a keyboard to a free USB port. 5. Plug in RaspberryPi's power supply. In the following steps you will power the Zigbee Gateway on and off by connecting and disconnecting its power supply. The red power LED will illuminate on the Zigbee Gateway and the green activity LED will blink until the boot process has completed. The proper procedure for power down is to issue the following command before removing power: $ sudo shutdown -h now silabs.com | Building a more connected world. Rev. 0.7 | 4 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) 2.3 Install the Raspbian OS and Gateway Software 1. Use a host computer to install the Raspbian Stretch Lite operating system on the SD card as described here: https://www.raspberrypi.org/downloads/raspbian/ Note: Latest Silicon Labs Gateway 2.5.0 was verified on the 2017-11-29 Raspbian Stretch Lite image. (This archived version can be download here: http://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2017-12-01/) 2. Install the SD card in the Raspberry Pi and power it on. 3. Login and configure the keyboard layout. The default username is "pi" and password is "raspberry". On the first reboot you are prompted to change the password. Configure the default keyboard layout and optionally enable the ssh server with: $ sudo raspi-conf The keyboard configuration is set with "Localization Options" and the ssh server is enabled with "Interfacing Options." 4. Run the following commands to install the Zigbee Gateway and Wi-Fi soft access point packages: $ $ $ $ $ $ $ $ $ sudo sudo sudo sudo sudo sudo sudo sudo sudo apt-get update apt-get install dirmngr apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 90CE4F77 chmod 666 /etc/apt/sources.list echo deb http://devtools.silabs.com/solutions/apt stretch main >> /etc/apt/sources.list apt-get update apt-get install silabs-zigbee-gateway apt-get install silabs-networking reboot Note: If the keyserver's port is blocked by firewall, use the hkp:// port 80 as below instead: $ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 90CE4F77 silabs.com | Building a more connected world. Rev. 0.7 | 5 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3. Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) The Zigbee USB Virtual Gateway (RD-0002-0201) runs on Ubuntu Linux 16.04 operating system (OS) natively, or runs Ubuntu Linux 16.04 as a guest OS within a VirtualBox virtual machine for Windows or OSX host operating systems. The following instructions describe how to install a VirtualBox virtual machine, Linux 16.04 and the gateway software. 3.1 Preparing to Install 1. Download Ubuntu Linux 16.04 ISO image here: http://www.ubuntu.com/download 2. In a free USB port install the Silicon Labs EFR32 Mighty Gecko Wireless Starter Kit (SLWSTK6000B). If you prefer to run the Zigbee Virtual Gateway natively for Ubuntu Linux 16.04 you may skip to ahead to 3.10 Install the Gateway on Ubuntu Linux 16.04 OS. 3. Download and install VirtualBox here: https://www.virtualbox.org/wiki/Downloads. Accept requests to install drivers. 3.2 Create a Virtual Machine 1. Launch VirtualBox. 2. On the VirtualBox Manager menu, click [New]. 3. Create a virtual machine with the following settings: a. Select Name: Ubuntu Linux 16.04 b. Select Type: Linux. c. Select Version: Ubuntu (64-bit) or Ubuntu (32-bit) depending on your system. d. Select memory size to at least 1024 MB and click [Create]. 4. Create a virtual hard disk. a. Select Create a virtual hard disk now and click [Next]. b. Select VDI and click [Next]. c. Select Dynamically allocated and click [Next]. d. Select 25 GB or greater size and click [Create]. Figure 3.1. VirtualBox Manager Menu silabs.com | Building a more connected world. Rev. 0.7 | 6 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3.3 Configure the Network 1. Select the virtual machine. 2. On the VirtualBox Manager menu, click [Settings]. 3. In the Settings window, select Network. 4. Check Enable Network Adapter. 5. For Attached to: select Bridged Adapter. 6. For Name: select the host adapter. 7. Click [OK]. Figure 3.2. VirtualBox Manager Settings Figure 3.3. Network Settings silabs.com | Building a more connected world. Rev. 0.7 | 7 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3.4 Configure USB Devices 1. Select the virtual machine. 2. On the VirtualBox Manager menu, click [Settings]. 3. In the Settings window, select USB. 4. Insert the Silicon Labs J-Link PRO OB of the EFR32 Mighty Gecko Wireless Starter Kit (SLWSTK6000B) or the Silicon Labs CEL EM3588 Zigbee USB stick into the USB port of the virtual machine host PC. 5. Click the Add new filter icon on the right of the dialog box. 6. Add and check the corresponding NCP to let the virtual machine access that USB NCP device. Note that both NCPs are shown in the following image for demonstration purposes. Your system should only have one of these devices selected. 7. Click [OK]. Figure 3.4. USB Settings silabs.com | Building a more connected world. Rev. 0.7 | 8 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3.5 Install Ubuntu 16.04 1. Select the virtual machine. 2. On the VirtualBox Manager menu, click [Settings]. 3. In the Settings window, select Storage. 4. Select Controller IDE. 5. Click the Add Optical Drive icon. 6. Select the Ubuntu Linux 16.04 ISO image. 7. Click [OK]. 8. On the VirtualBox Manager menu, click [Start]. 9. Select Install Ubuntu and follow installation instructions. Figure 3.5. VirtualBox Manager Start Figure 3.6. Storage Settings 3.6 Configure Guest Additions (Optional) 1. From the virtual machine menu, select Devices >> Insert Guest Additions and follow the installation instructions. 2. Eject the guest additions CD. silabs.com | Building a more connected world. Rev. 0.7 | 9 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3.7 Configure Host / Guest File Sharing (Optional) 1. Select the virtual machine. 2. On the VirtualBox Manager menu, click [Settings]. 3. Click Shared Folders and point to a shared folder on the host OS drive. 4. Click [Automount]. 5. Click [Make Permanent]. 6. Click [OK] twice. 7. From the virtual machine open a terminal and enter the following: $ sudo usermod -a -G vboxsf $ sudo reboot The shared drive will be found in the /media directory in the virtual machine. 3.8 Verify the Network is Connected 1. Confirm the network connection icon is present as shown in the following figure. Figure 3.7. Verify Network Connection 3.9 Verify the USB NCP is Captured 1. From the VirtualBox Manager menu, select Devices >> USB. 2. Confirm the desired USB device is captured (captured devices are indicated with a check) as shown in the following figure. Note that both NCP options are shown for demonstration purposes. Your system should only have one of the options selected. Figure 3.8. Verify USB NCP Device is Captured silabs.com | Building a more connected world. Rev. 0.7 | 10 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201) 3.10 Install the Gateway on Ubuntu Linux 16.04 OS Follow these instructions if you have purchased the Zigbee Virtual Gateway RD-0002-0201. 1. Run the following commands to install the Zigbee Gateway. $ $ $ $ $ sudo sudo sudo sudo sudo add-apt-repository http://devtools.silabs.com/solutions/apt apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 90CE4F77 apt-get update apt-get install silabs-zigbee-gateway reboot Note: If the silabs-zigbee-gateway installation fails due to dependency on nodejs >= 5.12.0, follow this procedure to install a higher version, such as nodejs 8.10.0 LTS, and then re-run sudo apt-get install silabs-zigbee-gateway. $ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash $ sudo apt-get install nodejs silabs.com | Building a more connected world. Rev. 0.7 | 11 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Install the USB Zigbee Adapter NCP Software 4. Install the USB Zigbee Adapter NCP Software The NCP software can be installed or updated in two ways. The first method is to update the NCP with Simplicity Studio. The second method is to update the NCP from the console if a bootloader has been installed. 4.1 Flashing from Simplicity Studio Pre-compiled Zigbee NCP firmware and bootloader files are distributed with the Zigbee Gateway file system. These files may be transferred from the gateway to a host with a utility such as WinSCP or scp. The NCP programming files are available in the Zigbee Gateway file system here: Device NCP Programming File EFR32 /opt/siliconlabs/zigbeegateway/firmware/ncp-uart/efr32mg12p432f1024gl125/ncp-uart-hw.s37 The bootloader files are available in the Zigbee Gateway file system here: Device First and Second Stage Bootloader Files EFR32 /opt/siliconlabs/zigbeegateway/firmware/ncp-uart/efr32mg12p432f1024gl125/first_stage_btl_efx32xg12.s37 /opt/siliconlabs/zigbeegateway/firmware/ncp-uart/efr32mg12p432f1024gl125/bootloader-uart-xmodemefr32mg12p432f1024gl125-brd4161a.s37 Information on how to flash the NCP firmware onto the appropriate chipset can be found in QSG106: Getting Started with EmberZNet PRO. IMPORTANT: The device should be erased before programming. 4.2 Flashing from the Console The NCP software may be updated from the console if a bootloader is installed. Stop the Zigbee Gateway applications, scan to determine the NCP port, and flash the NCP software. Be certain to specify the correct port for the flash operation (/dev/ttyACM0 is used as an example below) as returned by the scan function. There will be no visible indication while firmware is updated. $ $ $ $ $ sudo service siliconlabsgateway stop cd /opt/siliconlabs/zigbeegateway/ sudo python tools/ncp-updater/ncp.py scan sudo python tools/ncp-updater/ncp.py flash -p /dev/ttyACM0 -f firmware/ncp-uart/efr32mg12p432f1024gl125/*.gbl sudo reboot silabs.com | Building a more connected world. Rev. 0.7 | 12 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway 5. Run the Gateway If using the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201), power-up the gateway hardware, use a mobile phone or laptop and connect to the Wi-Fi SSID "Silicon Labs xxxx" using the password "solutions" as shown in the following figure. Then, open a web browser and browse to "192.168.42.1" to access the gateway user interface. If using the Zigbee Virtual USB Gateway (RD-0002-0201), open Virtual Box and start the Ubuntu Virtual Machine. Then, open the web browser and browse to "localhost" to access the gateway user interface. Figure 5.1. Wireless Network Connections (Windows) The following sections describe the gateway user interface tabs and their functions. silabs.com | Building a more connected world. Rev. 0.7 | 13 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway 5.1 Setup In the Network Maintenance section of the Setup tab, confirm that "ZigBee 3.0 Network: Up" is shown, and if not, refer to Section 8. Troubleshooting for possible solutions. On first boot by default the PAN ID is randomly assigned, a clear channel is auto-selected after channel scanning, and the power is set to 20 dBm. All settings are saved and restored on the next boot. All settings are saved and restored on the next boot. The PAN ID is a 16-bit number expressed in hexadecimal format, the channel can be set to any valid Zigbee channel (11-26), and the valid power level range is -20 dBm to 20 dBm. Note that range checking is enforced. Tapping the Reform Zigbee 3.0 Network button as shown in the following figure will re-initialize the Zigbee 3.0 network similar to the first boot. Note that all existing joined devices will be cleared. Tapping the Extended Network Form Settings icon next to Reform ZigBee 3.0 Network allows you to set specific PAN ID, channel, and power levels explicitly, then reinitialize the Zigbee 3.0 network. All existing joined devices will be cleared. Figure 5.2. Network Maintenance Zigbee 3.0 devices should join the Zigbee 3.0 network using install codes, or optionally using the default global Trust Center link key. To enable a Zigbee 3.0 device joining only with an install code, enter the corresponding 16-hexadecimal-digit device EUI and the 16byte (32-hexadecimal-digit) install code in the input boxes shown in the following figure. Turn on the Allow Join Only With Install Code option and then tap [+ ZigBee 3.0 Device (Install Code Only)] to open the network for joining the desired device. Figure 5.3. Install Code To join Zigbee devices using the default global Trust Center link key, simply leave the Device EUI and Install Code input boxes blank and tap [+ ZigBee 3.0 Device] to open the network for the active joining devices. When a Zigbee HA device is joined on a Zigbee 3.0 network, the device will be allowed to join for 180 seconds before being sent a leave request. silabs.com | Building a more connected world. Rev. 0.7 | 14 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway When using Zigbee 3.0 install codes the device EUI and install code entered must match the EUI and install code of the desired device. The EUI is an 8-byte (16-digit number) expressed in hexadecimal format. The install code is 16-byte (32-digit number) expressed in hexadecimal format. Refer to the following for additional information on creating and flashing Silicon Labs reference designs with Zigbee 3.0 installation codes: * http://community.silabs.com/t5/Mesh-Knowledge-Base/Z3-network-join-with-install-code-derived-link-key/ta-p/191924 * http://www.silabs.com/documents/public/application-notes/AN714-SmartEnergyECCEnabledDeviceSetupProcess.pdf To enter join mode for the Silicon Labs lighting reference design press S1 ten times rapidly, for the contact sensor press S1 for more than one second, for the dimmer switch press S3 for more than one second, for the occupancy sensor press S1 for more than one second, and for the outlet press the front button for more than three seconds. Additional information can be found in the user's guide for each device. Devices will appear in the list with their name, endpoint, unique node ID, and state. The name shown is determined by the Zigbee device ID of the endpoint(s) reported by each device and the unique node ID is assigned each time the device joins a Zigbee network. For a device supporting multiple-endpoints, each endpoint will appear as an individual entry in the device list with corresponding name and endpoint. If a device is on a network and communicating with the gateway, its state will be labeled as "joined". A device failing to respond will be labeled "unresponsive". To request a device to leave the network, select the "X" next to the device. The device will be labeled "leave sent" if there is no response from the device. Devices may become unresponsive or indicate leave sent because they are asleep, turned off, or out of range. When the device wakes, turns on, or comes back into range, the unresponsive device will be labeled as "joined" and a device labeled "leave sent" will be removed from the device list. RD-0030-0201: Contact Sensor Reference Design will indicate open/close state, active/alarm state, temperature, and the join/leavesent/unresponsive state. The open/close state is sent by the contact sensor immediately upon change of state to indicate whether the magnet is away (open) or near (closed) the reed switch. The alarm state is sent by the contact sensor immediately upon change of state when the tamper alarm is activated by pressing button S1 for more than four seconds and then releasing. RD-0020-0601, RD-0035-0601, RD-0085-0401, and RD-0098-0401: Lighting Demo Board Reference Designs will present the Toggle Light, Turn On and Turn Off buttons to change the on/off state of the light and indicate the join/leave-sent/unresponsive state. The Toggle Light button sends the ZCL on-off toggle command while the Turn On/Off buttons send the ZCL on-off on and ZCL on-off off command respectively. RD-0039-0201: Capacitive Sense Dimmer Switch Reference Design will show the joined/leave sent/unresponsive state. RD-0078-0201 and RD-0099-0201: Occupancy Sensor Reference Design will indicate occupied or not occupied state, temperature, and the join/leave-sent/unresponsive state. RD-0051-0201 and RD-0100-0201: Smart Outlet Reference Design will present Toggle Power, Turn On, and Turn Off buttons to change the on/off state of the outlet and indicate the join/leave-sent/unresponsive state. The Toggle Power button sends the ZCL on-off toggle command while the Turn On/Off buttons send the ZCL on-off on and ZCL on-off off command respectively. Figure 5.4. Attached Devices The gateway allows the user to create rules to bind one device to another. To create a rule, click [+ Set Rule], choose the desired input node and output node, and click [Bind]. Multiple rules can be set for both input nodes and output nodes. If two input nodes send a silabs.com | Building a more connected world. Rev. 0.7 | 15 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway command to an output node, the commands are executed in the order received. Rules can be either individually removed with the "X" next to the device, or all rules can be removed by clicking [Clear Rules]. Figure 5.5. Device Binding Rules 5.2 Home The home tab duplicates the setup information and offers extended information with the [Enter Identify Mode] and the [Show Extended Info] buttons. A dimmable color light adds brightness, on/off, color temperature, and hue/saturation controls, an occupancy sensor adds light intensity and relative humidity, and an outlet adds on/off, power used, light intensity, relative humidity, temperature, RMS voltage, RMS current, and active power. Tap the [Enter Identify Mode] button to command the device to enter identify mode with device-specific visual indication for 3 minutes. The button label will be toggled to [Exit Identify Mode ]. Tap the button again to exit the identify mode. The consequent behavior may not be triggered immediately during sleeping of a sleepy end-device. The extended information includes: * Node EUI * Endpoint * Gateway EUI * Node State (joined, leave sent, unresponsive) * Firmware Version * Firmware Image type * Manufacturer ID * Device Type * OTA Bytes Sent * Updating Indicator (via OTA) * Available OTA images list Available OTA update images are located here: /opt/siliconlabs/zigbeegateway/ota_staging Note: The OTA update process takes approximately ten minutes for non-sleepy devices and up to several hours for sleepy devices. Only one device should be in the "Attached Device" list before beginning the OTA update process. silabs.com | Building a more connected world. Rev. 0.7 | 16 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway Figure 5.6. Home Tab silabs.com | Building a more connected world. Rev. 0.7 | 17 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Run the Gateway 5.3 Diagnostics The diagnostics tab offers advanced logging options. The server log tab displays all web server command routing. The gateway output tab shows all Zigbee gateway commands and data. The "Console Log Streaming" option enables corresponding log updates to the server log tab and gateway log tab in additional to log file background save functionality. In typical use, displaying this logging information is not necessary, and disabling this option reduces gateway traffic and overhead. The Input CLI Command... inbox box below the gateway output tab can also be used to send command line interface (CLI) commands. The server log file is located here: /opt/siliconlabs/zigbeegateway/logs/server.log The gateway output log file is located here: /opt/siliconlabs/zigbeegateway/logs/gateway.log 5.4 About The About tab shows all versions and displays the web server IPv4 address for the purpose of connecting a mobile handset, tablet, or another computer to the gateway. It also displays the version of the installed gateway application as well as the NCP firmware version. Note: The "Running on IP" address is updated when refreshing the browser window. 5.5 Shutdown To properly close the gateway and virtual gateway, issue the following command at the terminal: $ sudo shutdown -h now silabs.com | Building a more connected world. Rev. 0.7 | 18 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6. Software Components This section contains: * An overview of the Zigbee gateway software architecture * How to obtain, compile and run the software components of the gateway * Details of the application interfaces (APIs) between key software components The gateway reference design developed by Silicon Labs is designed to demonstrate Zigbee gateway functionality with several Silicon Labs Zigbee reference designs. The software platform is designed in a manner that customers can leverage to develop their own gateway applications with minimal customization. The gateway software has the following architecture: Figure 6.1. Software Application Diagram silabs.com | Building a more connected world. Rev. 0.7 | 19 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.1 Getting Started The software is distributed as three software components: * Z3Gateway Application * Node Server Application * ReactJS Front-End Application The software binaries are available using the Linux apt package manager, as described in 2. Installation and Configuration for the Zigbee Wi-Fi/Ethernet Gateway (RD-0001-0201) and 3. Installation and Configuration for the Zigbee USB Virtual Gateway (RD-0002-0201). The software source code for the Z3Gateway application is available as a host example application distributed with the EmberZNet PRO Zigbee stack. For more information on how access the Zigbee stack please see http://www.silabs.com/products/wireless/meshnetworking/Pages/getting-started-with-mighty-gecko-zigbee.aspx. The software source code for the Node Server Application and ReactJS Front-End Application is available on github at https:// github.com/SiliconLabs/gateway-management-ui and is also installed on the target system at /opt/siliconlabs/zigbeegateway/gatewaymanagement-ui. silabs.com | Building a more connected world. Rev. 0.7 | 20 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.1.1 Set Up the Z3Gateway Application and MQTT Broker The following describes how to build and launch the Z3Gateway application in a Linux build and execution environment. These setup instructions assume: * Simplicity Studio Version 4.1.6 or later has been installed * Within Simplicity Studio, Gecko SDK Suite 2.2 and EmberZNet 6.2.0.0 (or above) is installed Perform the following steps: 1. Use Simplicity Studio's Simplicity IDE to generate a gateway project to build. a. Open Simplicity Studio and verify the SDK installation: i. Click the gear icon along the top left corner, or Preferences in the menu tab. ii. In the settings dialog box, select Simplicity Studio SDKs. iii. Verify that Gecko SDK Suite: EmberZNet 6.2.0.0 is installed. If not, refer to QSG106: Getting Started with EmberZNet PRO for installation instructions. Note: Depending on your installation you may see other SDKs along with EmberZNet. b. From the Tools menu, open the Simplicity IDE. c. Select File menu New Project. d. In the New Project dialog, select Silicon Labs AppBuilder Project and click [Next]. e. Select ZCL Application Framework V2, and click [Next]. f. Select EmberZNet 6.2.0.0 GA Host 6.2.0.0, and click [Next]. g. Select Z3Gateway, and click [Next]. h. Rename your project (if desired) and click [Next]. i. Ensure Part input box None has been selected. If not, click its right down-arrow button to select "Node (Compatible)" from the drop-down menu. Click [Finish]. j. Under the General tab, ensure the directory for generated files directory is pointed at this location: C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.2. k. The gateway could be executed with or without communication to an MQTT broker. If MQTT is required, some additional plugins (shown in the following figure) need to be enabled on top of the default. Under the Plugins tab, click the checkboxes of "Paho MQTT", "cJSON", "Gateway Relay Mqtt", and "Gateway MQTT transport" to enable these additional plugins. Two plugins, "device-table" and "command-relay," will be enabled automatically when "Gateway Relay Mqtt" is enabled. Figure 6.2. Additional Plugins for an MQTT Connection l. Click [Generate]. 2. Run make to build the executable binary image: a. In a terminal shell window browse to the sdks/gecko_sdk_suite/v2.2/app/builder/Z3GatewayHost/ directory. silabs.com | Building a more connected world. Rev. 0.7 | 21 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components b. Type make to build the gateway. 3. Launch the Z3Gateway application. a. In terminal shell window browse to the sdks/gecko_sdk_suite/v2.2/app/builder/Z3GatewayHost/build/exe directory b. For the EFR32 Mighty Gecko Wireless Starter Kit: ./Z3GatewayHost -n 0 -p /dev/ttyACM0 For the CEL MeshConnect NCP: ./Z3GatewayHost -n 1 -p /dev/ttyUSB0 c. The Z3Gateway application will publish and subscribe to MQTT messages. 6.1.2 Set Up the Node Server Application The following describes how to install, build and launch the node server application. The source for the Node Server Application is located on the target system at /opt/siliconlabs/zigbeegateway/gateway-management-ui/nodeserver. 1. Open a terminal window in the source directory. 2. Build the project: $ sudo npm install 3. Launch the application. If running this application on the same platform as the Z3Gateway application: $ sudo npm run local Otherwise if the Z3Gateway and this application are on different platforms: $ sudo npm run cloud 6.1.3 Set Up the React Front-end Application The following describes how to build and launch the ReactJS front-end application. The source for the Node Server Application is located on the target system at /opt/siliconlabs/zigbeegateway/gateway-management-ui/reactui. 1. Open a terminal window in the source directory. 2. Build the project: $ sudo npm install gulp $ sudo npm install $ sudo npm run build 3. Launch the static server. Note this is only required if the Node Server is launched with "cloud" option. A static server is launched when the Node Server is launched with the "local" option. This application should reside on the same platform as the Node Server. $ sudo npm run server 6.1.4 Set Up the MQTT Broker This reference design uses Mosquitto MQTT broker. Visit http://mosquitto.org and install and launch the broker that corresponds to the target platform (ex: Ubuntu). 6.1.5 Final Steps 1. Open a web browser on the same machine, browse to this address: http://localhost. 2. The gateway application will render in the browser. 6.2 Z3 Gateway Application with CoAP silabs.com | Building a more connected world. Rev. 0.7 | 22 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.2.1 Overview Three plugins are required to support the ZCL/IP (Zigbee Cluster Library over IP) protocol over CoAP from a Zigbee gateway. These plugins collectively expose Zigbee devices connected to the Z3 gateway as CoAP ports for two-way communication with a ZCL/IP client in the cloud, and provide translation between the ZCL/IP protocol over CoAP and the ZCL protocol on Zigbee. The goal is to provide parity with our current Silicon Labs Thread offering. silabs.com | Building a more connected world. Rev. 0.7 | 23 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.2.2 Architecture Overview Figure 6.3. CoAP Architecture Currently, the Z3 Gateway Reference Design provides a Zigbee host application that allows multiple Zigbee devices to be connected to it and be controlled by it. However, the Z3 Gateway Reference Design does not include any connectivity off network by default. One option for off network connectivity is to leverage the ZCL/IP application layer with the CoAP transport. Three different plugins are required to enable this functionality in the Z3 Gateway: libcoap, CoAP Server, and Gateway Relay CoAP. Libcoap is a snapshot of the publically available libcoap project configured for use with a Linux or similar operating system, with one modification. This modification allows for partial mapping of URI before calling the method callbacks. This facilitates its use with the ZCL/IP protocol where the URI structures are the protocol itself. CoAP Server is a plugin that sits between libcoap and the ZCL/IP translation layers. CoAP Server opens one CoAP channel for each Zigbee device and map this port to the respective Zigbee device on the network. In this way, each device in the Zigbee network has its own unique connection to the outside world. This mirrors what we would expect to see with a Thread network, where each Thread device is individually addressable from the outside world. Incoming messages from the CoAP network are sent to the Gateway Relay CoAP plugin for translation and eventual forwarding to the correct Zigbee device. Incoming messages and responses from the Zigbee network can be forwarded to a client device specified by the Gateway Relay Coap plugin. Note: The CoAP Server code is provided as an alpha test tool. Because it does not implement any security layer, it is not recommended for use in a final product in its current form, as that would be an obvious security risk. Future versions of the plugin will employ security. The Gateway Relay CoAP plugin provides translation between the ZCL/IP and ZCL application layers. It leverages the underlying network stacks to provide connectivity. By design, ZCL/IP messages have a natural translation to ZCL messages, and the translation is straightforward. In a few notable situations the ZCL/IP translation does not behave exactly as a Thread device would. This includes any situation where the ZCL/IP translation plugin requires communicating with a Zigbee device to obtain data (such as a read attribute request). In these cases, the ZCL/IP plugin responds to the initial message with an empty ack, and it then forwards the response as a separate, translated message. The Gateway Relay CoAP plugin includes a simple CBOR encoder/decoder that is limited to the functionality required for the ZCL/IP communication currently implemented. The Gateway Relay CoAP plugin includes a simple CLI interface for setting the client IP address, as well as starting and stopping the heartbeat messages. CLI Command Description plugin gateway-relay-coap set-server Set the IP address of the client to which the gateway will relay all outgoing messages. is an IP address string of the format "192.168.2.1" silabs.com | Building a more connected world. Rev. 0.7 | 24 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components CLI Command Description plugin gateway-relay-coap hbstart Start the heartbeat. is a two-byte integer and is in seconds. plugin gateway-relay-coap hbstop Stop the heartbeat. 6.2.3 Building CoAP into a Gateway Application three plugins are designed to be added to the Z3 Gateway and compiled under a Linux environment. To build a gateway with these CoAP plugins, start by building a Z3 Gateway (File->New->Project, then select Silicon Labs AppBuilder Project). After selecting ZCL Application Framework (V2), and selecting Host applications, you will see the sample application dialog as shown in the following figure. Figure 6.4. Building a Gateway with CoAP Select the Z3 Gateway and click [Finish] to create the project. To enable the CoAP functionality, select the Plugins tab and search for the keyword "coap" to find the three CoAP-related plugins. Figure 6.5. Adding CoAP Plugins You must select all three of these plugins in order to enable the CoAP related functionality in your Zigbee gateway. silabs.com | Building a more connected world. Rev. 0.7 | 25 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.2.4 Controlling Zigbee Devices with zclip.js Zclip.js is a ZCL-over-IP implementation written in JavaScript that is available at https://github.com/SiliconLabs/zclip.js. It provides a library useful for interacting with devices, scripting, and off-mesh development platforms like cloud and mobile. Zclip-cli adds a command line wrapper around zclip.js. It comes with a CLI interface, facilitating the following examples. More information about this library can be found at QSG102: Thread Border Router Add-On Kit Quick Start Guide. This CLI utility is available at https://github.com/SiliconLabs/zclip-cli. These examples assume you are connected to the Z3 gateway enabled with the CoAP functionality and a device containing an On-Off Cluster and Level Control Cluster such as the Z3ColorControlLight has been added to its Zigbee network. 1. Turn the device on and off. $ zcl onOffCluster on 192.168.3.40 -port 5700 $ zcl onOffCluster off 192.168.3.40 -port 5700 2. Set the device level. $ zcl levelControlCluster moveToLevel 192.168.3.40 -port 5700 --level 0 --transitionTime 0 $ zcl levelControlCluster moveToLevel 192.168.3.40 -port 5700 --level 255 --transitionTime 0 silabs.com | Building a more connected world. Rev. 0.7 | 26 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3 Gateway Application with MQTT 6.3.1 Overview Table 6.1. Plugins Supporting the Z3Gateway Application Plugin Name Description Device Table Tracks devices as they join the network Command Relay Forwards incoming Zigbee messages to outgoing Zigbee messages cJSON Open source JSON command parser (https://github.com/DaveGamble/cJSON) Paho MQTT Open source MQTT client (https://github.com/eclipse/paho.mqtt.c) Figure 6.6. Z3Gateway Application Diagram silabs.com | Building a more connected world. Rev. 0.7 | 27 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.2 MQTT Pub/Sub Structure The Z3Gateway application and Node server use MQTT topics and a Mosquitto MQTT broker for inter-process communication. Topics are also split so that information sent to the Z3Gateway application is never published on the same topic as information sent from the Z3Gateway application. All topics associated with the Z3Gateway application have the topic prefix = "gw//" where is equal to the Z3Gateway application's EUI 64 identification. Each MQTT topic contains a JSON payload. See each topic for more details. Table 6.2. MQTT Topic from the Z3Gateway Application MQTT topic Description gw//heartbeat An active ZB3 Gateway sends heartbeats containing its network status, short pan ID, transmit power and transmit channel gw//devices Responds to a request for the currently connected devices gw//relays Communicates current status of the command relay list gw//settings Gateway setting information containing NCP stack version, network status, short pan ID, transmit power, and channel number. gw//devicejoined Published when a node joins gw//deviceleft Published when a node leaves gw//devicestatechange Published when a device changes state gw//otaevent OTA event messages gw//executed Published when a command sent has been executed gw//zclresponse Generic ZCL level response for attribute report responses gw//zdoresponse Generic ZDO level response for binding and reporting table responses gw//apsresponse APS layer message transmission responses Table 6.3. MQTT Topic to the Z3Gateway Application MQTT topic Description gw//commands Commands from the node server to process at the Z3Gateway application gw//publishstate Forces a publish of: gw//devices gw//relays gw//settings gw//updatesettings Supported settings: trafficReporting: true/false. This enables advanced traffic diagnostics. 6.3.3 MQTT Topic / Message Attributes All MQTT topics: * Use JSON format * Publish to TCP port 1883 * Use QoS = 2 silabs.com | Building a more connected world. Rev. 0.7 | 28 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.4 MQTT Topics Published to by the Z3Gateway Application Note: This is information sent from the Z3Gateway application. Table 6.4. Z3Gateway Application Heartbeat MQTT Topic: gw//heartbeat Trigger Event: Published by Z3Gateway application every five seconds Description: An active Z3Gateway application sends heartbeats containing its network status, short pan ID, transmit power and transmit channel. Direction: From Z3Gateway application Payload: { networkUp True or False "networkUp":, "networkPanId": , "radioTxPower": , "radioChannel": } networkPanId formatted "0xXXXX" radioTxPower transmission power setting radioChannel number Table 6.5. Z3Gateway Application Device State MQTT Topic: gw//devices Trigger Event: Response to publish on MQTT channel: gw//publishstate Description: This message is published in response to a request for the currently connected Z3Gateway application devices, and after each new joined device. Direction: From Z3Gateway application Payload: { devices array containing all connected nodes "devices":[{ "nodeId":, "deviceState": , "deviceType":, "timeSinceLastMessage":, "deviceEndpoint":{ "eui64": , "endpoint": , "clusterInfo":[{ "clusterId":, "clusterType": }] }, }] } nodeId the node's 16-bit network ID formatted "0xXXXX" deviceState current status of the node deviceType Zigbee device ID number formatted "0xXXXX" (see ZCLDataTypes.js) timeSinceLastMessage elapsed seconds since last message deviceEndpoint array containing active endpoints eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" endpoint Zigbee endpoint number clusterInfo array containing clusters of the device clusterId Zigbee cluster ID number formatted "0xXXXX" (see Constants.js) clusterType In (server cluster) or Out (client cluster) Payload if no devices exist: { "devices":[ ] } silabs.com | Building a more connected world. Rev. 0.7 | 29 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components Table 6.6. Z3Gateway Application Relays List MQTT Topic: gw//relays Trigger Event: Response to publish on MQTT channel: gw//publishstate Description: This message is published in response to a request for the Z3Gateway application relay list contents. Direction: From Z3Gateway application Payload response when relays are present: { "relays":[{ "inDeviceEndpoint": { "eui64": , "endpoint": , "clusterId": }, "outDeviceEndpoint":{ "eui64": , "endpoint": , "clusterId": } }] } Payload response when no relays are present: relays array contains all the relay connections between device endpoints inDeviceEndpoint structure that contains device endpoint information for the relay source outDeviceEndpoint structure that contains device endpoint information for the relay destination eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" endpoint zigbee endpoint number clusterId Zigbee cluster ID number formatted "0xXXXX" (see Constants.js) { "relays":[ ] } Table 6.7. Z3Gateway Application Gateway Info MQTT Topic: gw//settings Trigger Event: Response to publish on MQTT channel: gw//publishstate Description: This is published in request for logging state from the Z3Gateway application. Direction: From Z3Gateway application Payload: { ncpStackVersion stack version string "ncpStackVersion": , "networkUp": , "networkPanId": , "radioTxPower": , "radioChannel": } networkUp true or false networkPanId network PAN formatted "0xXXXX" radioTxPower Zigbee TX power in decimal radioChannel Zigbee transmit channel in decimal silabs.com | Building a more connected world. Rev. 0.7 | 30 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components Table 6.8. Z3Gateway Application State Change MQTT Topic: gw//devicestatechange Trigger Event: Automatic response to a device changing state. Description: This is published when the Z3Gateway application becomes aware of a change in the network state of a device on the Zigbee network. Direction: From Z3Gateway application Payload: { "eui64": , "deviceState": } eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" deviceState new state code for node ND_JUST_JOINED: 0x00 ND_HAVE_ACTIVE: 0x01 ND_HAVE_EP_DESC: 0x02 ND_JOINED: 0x10 ND_UNRESPONSIVE: 0x11 ND_LEAVE_SENT: 0x20 ND_LEFT: 0x30 ND_UNKNOWN: 0xff Table 6.9. Z3Gateway Application Node Join MQTT Topic: gw//devicejoined Trigger Event: Automatic response to a node joining the Zigbee network. Description: This is published when a node joins the Z3Gateway application. Direction: From Z3Gateway application Payload: { "nodeId": , "deviceState": , "deviceType": , "timeSinceLastMessage": , "deviceEndpoint": { "eui64": , "endpoint": "clusterInfo":[{ "clusterId":, "clusterType": }] }, } nodeId the node's 16-bit network ID formatted "0xXXXX" deviceState current status of the node deviceType Zigbee device ID number formatted timeSinceLastMessage elapsed seconds since last eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" endpoints Zigbee endpoint number clusterInfo array containing clusters of the device clusterId Zigbee cluster ID number formatted "0xXXXX" (see Constants.js) clusterType In (server cluster) or Out (client cluster) silabs.com | Building a more connected world. Rev. 0.7 | 31 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components Table 6.10. Z3Gateway Application Node Left MQTT Topic: gw//deviceleft Trigger Event: Automatic response to a node leaving the network, to tell a node to leave, MQTT publish to message the CLI command zdo leave 1 0 Description: This is published when a node leaves the Z3Gateway application. Direction: From Z3Gateway application Payload: { "eui64": eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" } Table 6.11. Z3Gateway Application OTA Messages MQTT Topic: gw//otaevent Trigger Event: Automatically generated when an OTA event is occurring on the Zigbee network. For more advanced usage on starting an OTA event, see 6.3.9 CLI Command Structure. Description: These messages are published by the Z3Gateway application when an OTA event occurs. Direction: From Z3Gateway application Payload = finished: { "messageType": "otaFinished", "eui64": , "manufacturerId": , "imageTypeId": , "firmwareVersion": } Payload = blocksent: eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" manufacturerId 16-bit manufacturer ID loaded imageTypeId 16-bit image type ID loaded firmwareVersion 32-bit firmware ID loaded { "messageType": "otaBlockSent", "eui64": , "bytesSent": , "manufacturerId":, "imageTypeId": , "firmwareVersion": } eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" bytesSent total number bytes that have been sent manufacturerId 16-bit manufacturer ID loaded imageTypeId 16-bit image type ID loaded firmwareVersion 32-bit firmware ID loaded Payload = started: Payload = failed: { "messageType": "otaStarted", "nodeEui": , "manufacturerId": < String>, "imageTypeId": , "firmwareVersion": } { "messageType": "otaFailed" "eui64": "manufacturerId": "imageTypeId": "firmwareVersion": } silabs.com | Building a more connected world. nodeEui EUI64 string formatted "0xXXXXXXXXXXXXXXXX" manufacturerId 16-bit manufacturer ID loaded imageTypeId 16-bit image type ID loaded firmwareVersion 32-bit firmware ID loaded eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" manufacturerId 16-bit manufacturer ID loaded imageTypeId 16-bit image type ID loaded firmwareVersion 32-bit firmware ID loaded Rev. 0.7 | 32 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.5 Zigbee Cluster Layer Response Table 6.12. Zigbee Cluster Layer Response MQTT Topic: gw//zclresponse Trigger Event: Receipt of any attribute read response, attribute report, IAS zone (security) report or ZCL layer command. If a ZCL layer command was initiated the response payload will follow the command payload format. IAS zone events will follow the IAS zone payload format. All other zclresponses will utilize the attribute payload format. Description: This topic will relay any ZCL layer attribute report, attribute read response, or cluster command from the Z3Gateway application. Note: An extra parsed response for the case of incoming security state update commands is also provided. This is in addition to the generic command update that will also be received. Direction: From Z3Gateway application Command Payload: { clusterId Cluster Id, formatted "0xXXXX" "clusterId": , "commandId": , "commandData": , "clusterSpecific": , "mfgCode": , "deviceEndpoint": { "eui64": , "endpoint": } } commandId Command Id formatted "0xXX" commandData Varying length data formatted "XXXX" clusterSpecific "true" or "false" mfgCode Optional if this is manufacturer specific command. Otherwise, omitted eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" endpoint Zigbee endpoint number Attribute Payload: clusterId Zigbee reported cluster 16-bit ID { "clusterId": , "attributeId": , "attributeBuffer": , "attributeDataType": , "deviceEndpoint": { "eui64": , "endpoint": } } attributeId Zigbee reported attribute 16-bit ID attributeBuffer Zigbee global read buffer response in hex string. This is parsed by the node server. attributeDataType data type for the attribute buffer eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" endpoint Zigbee endpoint number silabs.com | Building a more connected world. Rev. 0.7 | 33 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.6 Zigbee Device Object Response Table 6.13. Zigbee Device Object Response MQTT Topic: gw//zdoresponse Trigger Event: Receipt of binding table or report table responses Description: The gateway will use this topic to report binding table or report table activity, such as update success or table entry values. Direction: From Z3Gateway application Bind Response or Con- { figure Report Re"zdoType": "bindResponse", "eui64": , sponse: "status": } zdoType "bindResponse" or "configureReportResponse" eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" status 0 = success, error code otherwise Bind Table Entry Response": zdoType "bindTableResponse" { "zdoType": , "status": , "eui64": , "bindTable" [{ "sourceDeviceEndpoint": , "addressMode": , "clusterId": , "destDeviceEndpoint": ]} } status 0x00 = success, error code otherwise eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" bindTable list if binding table entries sourceDeviceEndpoint endpoint of the source addressMode short or long address (can be ignored) clusterId cluster ID formatted "0xXXXX" destDeviceEndpoint endpoint of the destination Report Table Entry Response: zclType "reportTableEntry" { "zclType": , "deviceEndpoint": , "status": , "direction": , "clusterId": , "attributeId": , "datatype": , "minInterval": , "maxInterval": , "data": } deviceEndpoint endpoint of the device status 0x00 = success, error code otherwise direction 0 = server-to-client, 1 = client-to-server clusterId cluster ID formatted "0xXXXX" attributeId attribute ID formatted "0xXXXX" datatype Zigbee data type formatted "0xXX". See ZCL spec for details. minInterval seconds, formatted "0xXXXX" maxInterval seconds, formatted "0xXXXX" data variable length data, formatted "XXXX" silabs.com | Building a more connected world. Rev. 0.7 | 34 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.7 Zigbee APS Layer Response Table 6.14. Zigbee APS Layer Response MQTT Topic: gw//apsResponse Trigger Event: Receipt of an APS layer response Description: APS layer responses inform the Z3Gateway application whether a message was received (apsAck), and if it was received whether it was understood (defaultResponse). Direction: From Z3Gateway application Payload: { statusType "apsAck" or "defaultResponse" "statusType": , "eui64": , "status": , "clusterId": , "commandId": } eui64 EUI64 string formatted "0xXXXXXXXXXXXXXXXX" status 0x00 = success, error code otherwise clusterId cluster Id formatted "0xXXXX" commandId command Id formatted "0xXX" silabs.com | Building a more connected world. Rev. 0.7 | 35 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.8 MQTT Topics Subscribed to by the Z3Gateway Application Note: This is information sent to the Z3Gateway application. Table 6.15. ZCL Commands to Z3Gateway Application MQTT Topic: gw//commands Description: The Z3Gateway application can receive commands with this MQTT topic. The Z3Gateway application will acknowledge completion of the command with an executed MQTT topic message. Direction: To Z3Gateway application Payload: { CLI message list sent to Gateway "commands":[{ "command": , "postDelayMs": }] } See section 6.3.9 CLI Command Structure to manually populate this list with commands. Each command is executed sequentially. postDelay is added after a command is run before the next command is processed. Note: If postDelay is omitted, no post delay is added Table 6.16. Message Commands to Z3Gateway Application MQTT Topic: gw//updatesettings Description: This topic updates settings of the Z3Gateway application. Supported settings: measureStatistics. Direction: To Z3Gateway application Payload: { "measureStatistics": true } This command changes measureStatistics to true. Table 6.17. Message Commands to Z3Gateway Application MQTT Topic: gw//publishstate Description: This topic forces a state update. Direction: To Z3Gateway application Payload: { } or NULL silabs.com | Building a more connected world. Rev. 0.7 | 36 UG129: Zigbee(R) Gateway Reference Design User's Guide (RD-0001-0201, RD-0002-0201) Software Components 6.3.9 CLI Command Structure The API for the Z3Gateway application exposes the CLI within the EmberZNet PRO stack. Commands such as form and pjoin (permit joining), as well as methods for building and sending ZCL commands to specific devices on the network, are used within the Z3Gateway application. Sending a Standard ZCL Command To send a ZCL command to a device on the network, one must follow a two-step process. 1. Build up the ZCL command in the outgoing command buffer. 2. Issue the send command which will send the contents of the outgoing command buffer to the intended recipient. Example: Build and send a Zigbee command using standard ZCL commands: zcl on-off on send Example: Build and send a Zigbee command using the device-table plugin: zcl on-off on plugin device-table send See the documentation in the EmberZNet PRO stack install for the full CLI description: $STACK_ROOT/documentation/120-3023-000_AF_V2_API/group__cli.html Table 6.18. Common Zigbee CLI Commands Used Command Description Command Parameters Parameter Description Forming a network network form Channel used to form the network TX power used to form the network Short PAN ID to be used Enable permit joining network pjoin