Tutorial just for ZigBee users
The aims of this tutorial are to help the ZigBee user in 2 operations:
- to send data frames from his Waspmote to Meshlium, using the 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 post 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:
Three steps to receive frames on Meshlium
- some explanation on the ZigBee coordinator, MACs, JV parameter, AT mode and PANID parameter
1 – Download the latest version of the Waspmote's API
2 – With the Waspmote's IDE, upload this example on your Waspmote (read the Waspmote's CheckList
if you have not yet):
char* data="Test message!";
// Inits the XBee ZigBee library
// Powers XBee
// Set params to send
xbeeZB.setOriginParams(paq_sent, "5678", MY_TYPE);
xbeeZB.setDestinationParams(paq_sent,"0013A2004071E9DD", data, MAC_TYPE,DATA_ABSOLUTE);
if( !xbeeZB.error_TX )
In your sketch, you should change "0013A2004071E9DD" for 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 Note below. No need to change more data, just the MAC address
NOTE: 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.
N.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.
N.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.
N.3 - Press “Save”. It is mandatory to press "Save", at least in the first time.
3 – Show data on Manager System
3.1 - Connect to Meshlium and open the Manager System. Go to the ZigBee tab.
3.2 - Check that the Capturer is available; the icon should be like this:
3.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.
3B.1 - Connect to Meshlium via SSH.
3B.2 - Stop the daemon called "ZigbeeStorer" by executing this command:
3B.3 - Execute the following command to execute the Capturer:
capturer S0 384000
The data received from Waspmote will be displayed in the shell.
Which is your ZigBee coordinator?
[ all that is in the documentation by Libelium and Digi, and the users should read it, but we are making it explicit here ]
One thing should be clear: an ZigBee, when is powered on for the first time, will look for ZigBee coordinators. The first one it founds is going to be set as its coordinator, forever. Now that the ZigBee knows that it has a "parent", it changes its JV parameter to avoid looking again for new ZigBee coordinators.
This first step is done here at Libelium.
(a) The normal thing is that we take 5 Waspmotes with ZigBee (5 end-devices or routers) and 1 Gateway with ZigBee (1 coordinator). Then, the 5 end-devices are tied 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 in each one of his Waspmotes' ZigBees. The JV parameter indicates to its ZigBee module if he has a "parent" (coordinator) or not. And in the case the ZigBee checks it has no parent, the 1st thing it will do will be to look for a "parent" (remember one coordinator [and only one] is mandatory in any ZigBee network).
How to change the JV parameter?
There are 3 ways:
- with X-CTU (a Gateway is needed)
- with code in the Waspmote's sketch
- with AT commands
Probably, the easiest way to change the JV parameter (and any ZigBee/XBee parameter) is with X-CTU. Please read the Waspmote's Checklist
(chapter 5, "Networking Problems") to know how.
To change each ZigBee parameters with X-CTU, it is needed to use the Gateway. If there is not a Gateway, the (2) option should be performed by uploading and executing this sketch for each Waspmote's ZigBee:
// Inits the XBee ZigBee library
// Powers the ZigBee module
// Sets the ZigBee to be un-matched to any coodinator
// Saves the changes in the ZigBee module's memory
// Blink the LEDs for signaling the process was completed
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 3 methods (1), (2) or (3), 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.
What about the AP mode?
The AP mode decides if one XBee is going to work:
- in "Router API" mode --> mode AP = 2 --> all the Waspmotes must be configured like this
- in "Router AP" 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.
Can I change the PANID?FAQsForming a Network
It stands for P
entifier. This parameter is unique in a certain ZigBee network. That 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 ZigBee network. 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 command:
As said, the rest of the network must have this PANID. The user can check a Waspmote's ZigBee PANID in 3 ways:
- with X-CTU (a Gateway is needed)
- with code in the Waspmote's sketch
- with AT commands
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 for selecting the channel and PAN ID are described in the following sectionsChannel Selection
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. PANID
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. ATEE
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.More information:
1. Networking Guide of Waspmote with ZigBee
2. XBee/XBee-PRP ZigBee Module
3. ZigBee vs 802.15.4