IMPORTANT: Tutorial just for ZigBee users
The aim of this tutorial is to help the ZigBee user in 2 operations:
- to send data frames from Waspmote to Meshlium, using ZigBee modules
- to receive those frames on Meshlium
All the information explained here was already available on the documentation, so this is just a summary.
The structure of this tutorial is as follows:
- First, we will shown the steps needed to send ZigBee frames to Meshlium and receive them.
- Last, there is valuable theory information that must be read and studied to be able to build ZigBee projects:
- some explanation on the ZigBee coordinator, MACs, JV parameter, AT mode and PANID parameter
Three steps to receive frames on Meshlium
1 – Download the latest version of the Waspmote’s API
2 – With the Waspmote’s IDE, upload this example on your Waspmote:
IMPORTANT: In your sketch, you should change the MAC address of the ZigBee inside your Meshlium. If you do not know how to get the MAC address of your Meshlium’s ZigBee, please read the next section.
No need to change more data, just the MAC address
3 – How can you know the MAC address of the ZigBee module inside Meshlium?
It is supposed to be the Coordinator, and all the Waspmotes will send frames to it, so it is crucial to know its address.
For that, we will connect to the Manager System and read the Meshlium’s ZigBee module MAC address.
3.1 – Press “Load MAC”:
This operation queries the ZigBee module for getting the MAC address. You should get the MAC address divided in 2 halves.
3.2 – Press “Check status”:
This operation queries the ZigBee module for checking the Node Id and Encryption Mode. You should get 2 green OK’s.
3.3 – Press “Save”. It is mandatory to press “Save”, at least in the first time.
4 – Show data on Manager System
4.1 – Connect to Meshlium and open the Manager System. Go to the ZigBee tab.
4.2 – Check that the Capturer is available; the icon should be like this:
4.3 – Press “Start Scan”:
The data received from Waspmote will be displayed in the Manager System.
Another way (B) to visualize the data received, accessing via SSH.
4B.1 – Connect to Meshlium via SSH.
4B.2 – Stop the daemon called “ZigbeeStorer” by executing this command:
4B.3 – Execute the following command to execute the Capturer:
capturer S0 38400
The data received from Waspmote will be displayed in the shell.
5 – Which is your ZigBee coordinator?
One thing should be clear: when a ZigBee is powered on for the first time, it will look for ZigBee coordinators. When it founds a valid one, this coordinator will be be set as its coordinator.
This first step is done here at Libelium.
(a) The normal thing is that we take 5 Waspmotes with ZigBee (5 routers) and 1 Gateway with ZigBee (1 coordinator). Then, the 5 end-devices are joined to this coordinator in particular. We mean the Gateway’s ZigBee.
(b) Another option is that some client wants 5 Waspmotes with ZigBee but he does not want a Gateway, but 1 Meshlium (with a ZigBee module inside obviously). In that case, the process will be like the (a) one, with the only difference that the 5 Waspmotes’ ZigBees will be tied to the Meshlium’s ZigBee.
You can see that in both cases, all the Waspmotes’ ZigBees are tied down to one ZigBee coordinator in particular. If someone wants to change the coordinator of his Waspmotes’ ZigBees (for example, if he purchases a new Meshlium), he must change the JV parameter to ’1′ in each one of his Waspmotes’ ZigBees. The JV command (join verification) enables the power-on join verification check. If enabled, the XBee will attempt to discover the 64-bit address of the coordinator when it first joins a network. If JV=0, the router will continue operating on its current channel even if a coordinator is not detected.
5.1 – How to change the JV parameter?
There are 2 ways:
- with code in the Waspmote’s sketch
- with X-CTU (a Gateway is needed)
The easiest and safer way to change the JV parameter (or other parameters) is to upload some code to Waspmote, so that Waspmote sends the AT command to the ZigBee module.
To change each ZigBee parameter with X-CTU, it is needed to use the Gateway and study the X-CTU tutorial. Instead of that way, we advice to perform the first method by uploading and executing this sketch for each Waspmote’s ZigBee:
Please take a look at the ZigBee Networking Guide for more information on how to use the function setChannelVerification.
So, after doing some of the 2 methods (1) or (2), the ZigBee module will look for a “parent” (a ZigBee coordinator) since they are un-matched from any other “parent” (in the case they had one). It is recommended to have just one coordinator turned on when a ZigBee must look for a “parent”.
Obviously, 2 different ZigBee modules have 2 different MACs addresses, so if a user is changing the coordinator, he must take into account that the destination MAC must be changed. Also, same channel, same PAN ID or same encryption parameters in all the modules in a network, are basic things to be considered.
5.2 – What about the AP mode?
The AP mode decides if one XBee is going to work:
- in “Router API firmware” mode → mode AP = 2 → all the Waspmotes must be configured like this
- in “Router AT firmware” mode → mode AP = 0 → all the Meshliums must be configured like this
Libelium delivers the material properly configured and the user should not change it.
5.3 – Can I change the PANID?
It stands for Personal Area Network IDentifier. This parameter is unique in a certain ZigBee network. This means that it will be the same in all the related devices, including the Coordinator (Meshlium or Gateway) and the Routers or End Devices (Waspmotes).
The user cannot change the PANID in a established ZigBee network. But it is possible to set the ZigBee modules to create/join exclusively a specific PANID.
The PANID is defined by the Coordinator (Meshlium) in the first phase, when the network is set in an automatic way. Then, the Coordinator transmits the PANID to the rest of the network (to the Routers or End Devices, which are Waspmotes). From this moment, all the devices inside the ZigBee Network have the same PANID.
The user can know the PANID of a Meshlium’s ZigBee with the AT command:
As said, the rest of the network must have this PANID. The user can check a Waspmote’s ZigBee PANID in 2 ways:
- with X-CTU (a Gateway is needed)
- with code in the Waspmote’s sketch
Forming a Network
The coordinator is responsible for selecting the channel, PAN ID (16-bit and 64-bit), security policy, and stack profile for a network. Since a coordinator is the only device type that can start a network, each ZigBee network must have one coordinator. After the coordinator has started a network, it can allow new devices to join the network. It can also route data packets and communicate with other devices on the network.
To ensure the coordinator starts on a good channel and unused PAN ID, the coordinator performs a series of scans to discover any RF activity on different channels (energy scan) and to discover any nearby operating PANs (PAN scan). The process of selecting the channel and PAN ID are described in the following sections.
When starting a network, the coordinator must select a “good” channel for the network to operate on. To do this, it performs an energy scan on multiple channels (frequencies) to detect energy levels on each channel.
Channels with excessive energy levels are removed from its list of potential channels to start on.
PAN ID Selection
After completing the energy scan, the coordinator scans its list of potential channels (remaining channels after the energy scan) to obtain a list of neighboring PANs. To do this, the coordinator sends a beacon request (broadcast) transmission on each potential channel. All nearby coordinators and routers (that have already joined a ZigBee network) will respond to the beacon request by sending a beacon back to the coordinator. The beacon contains information about the PAN the device is on, including the PAN identifiers (16-bit and 64-bit).
This scan (collecting beacons on the potential channels) is typically called an active scan or PAN scan.
After the coordinator completes the channel and PAN scan, it selects a random channel and unused 16-bit PAN ID to start on.
ZigBee networks are called personal area networks or PANs. Each network is defined with a unique PAN identifier (PAN ID). This identifier is common among all devices of the same network. ZigBee devices are either preconfigured with a PAN ID to join, or they can discovery nearby networks and select a PAN ID to join.
ZigBee supports both a 64-bit and a 16-bit PAN ID. Both PAN IDs are used to uniquely identify a network.
Devices on the same ZigBee network must share the same 64-bit and 16-bit PAN IDs. If multiple ZigBee networks are operating within range of each other, each should have unique PAN IDs.
The 16-bit PAN ID is used as a MAC layer addressing field in all RF data transmissions between devices in a network. However, due to the limited addressing space of the 16-bit PAN ID (65,535 possibilities), there is a possibility that multiple ZigBee networks (within range of each other) could use the same 16-bit PAN ID. To resolve potential 16-bit PAN ID conflicts, the ZigBee Alliance created a 64-bit PAN ID.
The 64-bit PAN ID (also called the extended PAN ID), is intended to be a unique, non-duplicated value. When a coordinator starts a network, it can either start a network on a preconfigured 64-bit PAN ID, or it can select a random 64-bit PAN ID. The 64-bit PAN ID is used during joining; if a device has a preconfigured 64-bit PAN ID, it will only join a network with the same 64-bit PAN ID. Otherwise, a device could join any detected PAN and inherit the PAN ID from the network when it joins. The 64-bit PAN ID is included in all ZigBee beacons and is used in 16-bit PAN ID conflict resolution.
Routers and end devices are typically configured to join a network with any 16-bit PAN ID as long as the 64-bit PAN ID is valid. Coordinators typically select a random 16-bit PAN ID for their network.
Since the 16-bit PAN ID only allows up to 65,535 unique values, and since the 16-bit PAN ID is randomly selected, provisions exist in ZigBee to detect if two networks (with different 64-bit PAN IDs) are operating on XBee®/XBee‐PRO® ZB RF Modules© 2012 Digi International, Inc. 35 the same 16-bit PAN ID. If such a conflict is detected, the ZigBee stack can perform PAN ID conflict resolution to change the 16-bit PAN ID of the network in order to resolve the conflict. See the ZigBee specification for details.
To summarize, ZigBee routers and end devices should be configured with the 64-bit PAN ID of the network they want to join. They typically acquire the 16-bit PAN ID when they join a network.
The coordinator must select the network security key for the network. The NK command (write-only) is used to set the network key. If NK=0 (default), a random network key will be selected. (This should suffice for most applications.) Otherwise, if NK is set to a non-zero value, the network security key will use the value specified by NK. NK is only supported on the coordinator.
Routers and end devices with security enabled (ATEE=1) acquire the network key when they join a network. They will receive the network key encrypted with the link key if they share a pre-configured link key with the coordinator (only writable KY command must be the same as the coordinator)