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.
Releases-Notes and Downloads
Visit the download page for the release notes and downloading a release.
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:
- Z357PA30-USB-P-NC-N-X: this is the ZigBee HA (HomeAutomation) version. Recommended as future extensions are probably only supported by this type.
- Z357PA22-USB-P-TC-N-C: this is the ZigBee SE (SmartEnergy) version.
are WERE available from a distributor like Avnet. Unfortunately, the supported dongles are discontinued by MMB, I'll check if there is a compatible replacement (when I have plenty of time to do so...). Please send me a note if you're in the need for an update, Thanks.
Operating SystemsThe tool was tested with the following operating systems (* marks tests of the current release):
- Mac OS X 13.1 (Ventura, M1 Chipset) (*)
- Windows 7 (64 Bit)
- Windows 8.1
- Windows 10
- Windows 11 (*)
- Ubuntu 22.04
- Raspberry Pi 2 with Raspberry Pi OS
- Raspberry Pi 2 with Ubuntu (*)
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/11 64 Bit
- Download the latest release of the ZigBee Survey Tool (the binaries, not the sources) build, extract it to a location of your choice. Windows users should use a short root path (e.g. "C:\zigbee") as there are issues with Windows Explorer: the length of the folder structure exceeds 255 characters.
- Install the drivers obtained from MMB Networks webpage for the USB dongle and attach it.
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 Homemade build (Mac, Linux and Windows)TooTallNates node-gyp page for the tools needed for your operating system before running
Raspberry Pi NotesInstall 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
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)
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.
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:
- PAN ID ('Personal Area Network' ID), a 16 bit long identifier which is unique for each ZigBee channel.
- Extended PAN ID, the 'MAC-Address' of the ZigBee device. The first few bytes identify the manufacturer of the device.
- Permit association: flag whether new devices can join a network or not.
- ZigBee Protocol and stack information
- Routing and Coordinator capabilities
- ... and many things more, see the screenshot below
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
Customize this tool
The ZigBee Site Survey tool can be customized with own CSS rules and about dialog. Just follow the instructionsin the Customizing ReadMe file.
Feel free to add your logo and styles. But if you supply this tool to your customers, please also supply asupport hotline for them as I won't be able to spend time for this. Thanks.
See settings.js for the options available.
The MIT License (MIT)Copyright © 2015-2023 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.