Building an Advanced Site Survey Tool
Overview
MMB's Site Survey tool provides the following data for each network that is within range of the tool:
- Channel
- Short PAN ID
- Extended PAN ID
- Permitting Joining (or not)
- Stack Profile
- LQI
- RSSI
There are some use cases where users may want to receive additional information as a part of a scan. In these cases, it's possible to use the Manufacturing Library frames in RapidConnect in such a way that more information can be pulled from the Zigbee beacon messages. The beacon messages contain additional information such as:
- Router / Coordinator Node ID
- Router Capacity - a boolean indicating if the device is capable of accepting join requests from routers
- Device Depth - how many hops from the coordinator the device is. If this value is 0x00, then the device is a coordinator
- End Device Capacity - a boolean indicating if the device is capable of accepting join requests from end devices (sleepy or not)
- Network Update ID - the network setting snapshot against which the device is operating
Procedure
The following procedure allows the device to request and observe beacons from a specific channel:
Setup
- Create a serial connection to the RapidConnect radio using the appropriate serial parameters for the firmware in question.
- Send a Manufacturing Library Start frame.
Channel-Specific Scan
- Send a Manufacturing Library Set Channel frame to select the appropriate channel.
- Send a Manufacturing Library Set Power frame to select the appropriate power level.
- Send a Manufacturing Library Set Rx Packet Enable frame to enable the receipt of packets.
Send a Manufacturing Library Tx Packet frame with repeat count: 1, packet payload:
03 08 <sequence> ff ff ff ff 07
Receive each Manufacturing Library Rx Packet frame for a user-selected period of time. The existing network scan frames allow this value to range from 31ms to 998ms. Upon receipt, these responses should be processed as per the following section.
Send a Manufacturing Library Set Rx Packet Enable frame to disable the receipt of packets.
Teardown
- Send a Manufacturing Library Stop frame to exit the manufacturing mode.
Frame Interpretation
To interpret the frame, we need to look at 3 layers of protocol. These layers are the 802.15.4 layer, the 802.15.4 Beacon layer, the Zigbee Beacon layer. The data is processed in network order.
802.15.4 Layer
The 802.15.4 layer is comprised of the fields described below. The Frame Control field is described below and indicates what the content of each of the fields means.
| Frame Control | Sequence Number | Destination PAN Identifier | Destination Address | Source PAN Identifier | Source Address | Auxiliary Security Header | |
|---|---|---|---|---|---|---|---|
| Octets | 2 | 1 | 0/2 | 0/2/8 | 0/2 | 0/2/8 | 0/5/6/10/14 |
Frame Control
The frame control field is defined as follows:
| Frame Type | Not Applicable | Reserved | Destination Addressing Mode | Frame Version | Source Addressing Mode | |
|---|---|---|---|---|---|---|
| bits | 0-2 | 3-6 | 7-9 | 10-11 | 12-13 | 14-15 |
| fixed value | 0 | 0 | 0 | 0 | 0 | 2 |
Source Addressing Mode
For a beacon, the Frame Type must be 2 to indicate that short addressing is in use.
Destination PAN Identifier
The Destination PAN identifier is not included for a Zigbee beacon.
Destination Address
The Destination Address is not included for a Zigbee beacon.
Source PAN Identifier
The Source PAN Identifier is included in a Zigbee beacon.
Source Address
The Source Address is included and the size is based on the source addressing mode specified in the Frame Control field.
Auxiliary Security Header
The Auxiliary Security Header is not included in Zigbee beacons.
802.15.4 Beacon Layer
The 802.15.4 Beacon layer is comprised of the fields descibed below. The Superframe Specification field is described below and indicates what the content of each of the fields means.
| Superframe Specification | GTS Specification | GTS fields | Pending Address Specification | Pending | |
|---|---|---|---|---|---|
| Octets | 2 | 1 | variable | 1 | variable |
Superframe Specification
The Superframe Specification is defined as follows:
| Beacon Order | Superframe Order | Final CAP Slot | Battery Life Extension (BLE) | Reserved | PAN Coordinator | Association Permit | |
|---|---|---|---|---|---|---|---|
| Bits | 0-3 | 4-7 | 8-11 | 12 | 13 | 14 | 15 |
| Fixed Value | 0xF | 0xF | 0xF | 0 | 0 | <variable> | <variable> |
PAN Coordinator
For a beacon, this set to 1 for beacons sent but the coordinator of the network. Otherwise this is set to 0.
Association Permit
For a beacon, this is set to 1 if the network is currently permitting join. Otherwise this is set to 0.
GTS Specification
The GTS Specification should be 0 which indicates there are no GTS Fields for a zigbee beacon.
GTS fields
A beacon should not contain GTS fields.
Pending Address Specification
The pending address specification should be 0, and specifies the number of pending address fields that are included. The format is as follows:
| Number of Short Addresses Pending | Reserved | Numbed of Extended Addresses Pending | Reserved | |
|---|---|---|---|---|
| Bits | 0-2 | 3 | 4-6 | 7 |
| Fixed Value | 0 | 0 |
Pending Address Fields
The Pending Addresses fields are a list of short and long addresses as specified in the Pending Address Specification. Short Addresses are 2 octets in length while Extended Addresses are 8 octets in length. The Short Addresses are included first.
Zigbee Beacon Layer
The Zigbee Beacon layer is composed of the fields descibed below:
| Protocol Id | Stack Profile | nwkProtocolVersion | Reserved | Router Capacity | Device Depth | End Device Capacity | nwkExtendedPanId | TX Offset | NwkUpdateId | |
|---|---|---|---|---|---|---|---|---|---|---|
| bits | 0-7 | 8-11 | 12-15 | 16-17 | 18 | 19-22 | 23 | 24-87 | 88-111 | 112-119 |
| octet offset | 0 | 1 | 1 | 2 | 2 | 2 | 2 | 3-10 | 11-13 | 14 |
| fixed value | 0 | 0 |
Protocol ID
The Protocol ID is required to be set to 0 for a Zigbee network.
Stack Profile
The Stack Profile identifier. Typically this is set to 2 which indicates Zigbee PRO.
nwkProtocolVersion
This indicates the version of the Zigbee network protocol.
Router Capacity
This indicates if the device has room in its tables, etc. to support another router connected through it (or as a neighbour).
Device Depth
This indicates the distance from the coordinator, but is only required to be updated during the join.
End Device Capacity
This indicates if the device has any room for children in its various tables, etc.
nwkExtendedPanId
The Extended PAN ID of the network. This is intended to be globally unique per network.
TX Offset
The TX offset indicates the number of symbols between beacons on a beaconed network. For beaconless networks (like Zigbee PRO), this gets set to 0xFFFFFF
NwkUpdateId
The NwkUpdateId indicates which version of the network information the device is using.
Supported Firmware
- RapidConnect 3
Legal Notices
Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.