View on GitHub

ZigBee Site Survey Tool

A node.js based tool for ZigBee measurements

Download this project as a .zip fileDownload this project as a tar.gz file

ZigBee Site Survey tool

A node.js tool for ZigBee range measurements using a RapidConnect USB stick from MMB Networks. This tool was just a proof-of-concept and there were no intentions to maintain it for a long time. But whenever you create something others consider as useful, you can't hide...

Using this tool you can scan the RSSI/LQI values for all ZigBee networks in your area (you don't have to join them, just being in range is enough) and log the RSSI/LQI values for a specific network. This is very helpful if you experience connectivity problems with your ZigBee network.

Screenshots

The main screen, displaying all networks found
Scanning one specific network over the time

Releases-Notes and Downloads

Visit the download page for the release notes and downloading a release.

Installation

Prerequisites

This tool requires a current node.js release (node 4 and higher, the LTS version 4 is recommended and the only tested version) and a ready to operate RapidConnect USB dongle. There are two different dongles available:

The dongles are available from a distributor like Avnet.

Operating Systems

The tool was tested with the following operating systems:

It runs best using the Google Chrome browser but other modern browsers like Firefox or Opera should work as well. Some people also state that the tool works with the Internet Explorer, but using this browser is not recommended anyway.

Installation for Mac OS X and Windows 7/8/10 64 Bit

Homemade build (Mac, Linux and Windows)

If you want to build the tool on your own, you need some additional development tools on your machine in order to compile the native sources. Check TooTallNates node-gyp page for the tools needed for your operating system before runningnpm install.

Raspberry Pi Notes

Install libudev-dev before running npm install:sudo apt-get install libudev-dev. The USB dongle does not need a driver for the Raspberry Pi. Connect the Raspberry Pi with the network and connect to the webserver using a tablet or smartphone.

See my blog entry for more details.

Run the tool

Just start the tool using the command line

node server.js

If the environment variable SIMULATOR is set to true, simple simulated data is used. This mode enables debugging the UI without a ZigBee network or hardware.

Open the URL supplied in the console in your web browser (defaults: simulator: http://localhost:2999, real:http://localhost:2998)

Usage

The first page shows all networks in range, updating the list continuously. If you select a network by clicking on its extended PAN-ID, the second page opens with detailed data about the selected network.

Use the log field to enter some data (e.g. 'Room 201') and press the button right of the input. This logs the measurement and adds it to the list.

After finishing your survey, print the page (generate a PDF) and return to the main page. The other networks are not scanned while analyzing a specific one.

Technical information

The tool sends periodically a 'Beacon Request', which is a broadcast targeting all active devices on the channel. This includes ZigBee coordinators and routers. When such a device receives the beacon request, it responses with a 'Beacon' (or as some say, with a 'Beacon Response'). This response contains the following information:

The software on the USB dongle gets the signal strength of the received beacon response which is displayed then in the tool.

Captured frames of a Beacon Request and Beacon

A Beacon Request
A Beacon response from a coordinator

Customize this tool

The ZigBee Site Survey tool can be customized with own CSS rules and about dialog. Just follow the instructions in the Customizing ReadMe file.

Feel free to add your logo and styles. But if you supply this tool to your customers, please also supply a support hotline for them as I won't be able to spend time for this. Thanks.

Configuration options

See settings.js for the options available.

License

The MIT License (MIT)

Copyright © 2015 Christian Kuster, CH-8342 Wernetshausen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.