Troubleshooting Zigbee Communications

= Tools = When troubleshooting communications between modules, you will want the following tools and techniques. If contacting us for advanced support questions please try using the tools below - they will make both our lives easier.

Debug Serial Output
There are multiple ways of reading out variables in an embedded application, including halting the processor and reading memory locations, or outputting the value over a serial port, or logging the data for later use. When doing wireless communications there are many time critical tasks and it makes it difficult to halt the processor each time you want to access a value. For that reason and to make it easy to use the module drivers have a compile option to output various information to a debug port, using printf. These are used extensively in the examples and make it much easier to troubleshoot any issues that arise. We highly recommend having a serial debug port on any wireless device; it greatly speeds development and debugging. If you are using a slow processor then you can speed things up by using a Circular Buffer to queue the data going out the serial port and not hold up the processor. We have included the Hello World example to help you verify that your serial output is working correctly.

Once your code starts the module it is useful to read out the status of the module. We include a few functions in module.c to do this:
 * displayNetworkConfigurationParameters - displays the module's configuration parameters as set by ZB_WRITE_CONFIGURATION, including:
 * PANID mask
 * Channel List
 * Security Settings
 * displayDeviceInformation or displayBasicDeviceInformation - the former is the verbose version, the latter is more concise. These display the settings that the module is currently using, including:
 * MAC Address
 * Short Address
 * Channel
 * PANID

The module drivers have optional compile flags to output even more information. These are specific to each driver file. For example, in module.c you would need to #define MODULE_INTERFACE_VERBOSE, or in af.c you would need to #define AF_VERBOSE. Use of these is not recommended during production as they may slow down normal operations if you're not using a buffered serial port.

Logic Analyzer
The next step is to attach a logic analyzer to the bus between the module and the host processor. This normally isn't needed but if you're porting to another processor then you will want to have one handy to ensure that you configured the SPI correctly. We have several Logic Analyzer Traces showing correct module operation which you can use as a reference.

Packet Sniffer
In a few rare occasions we had to use a packet sniffer to troubleshoot the issue. TI offers a free Packet Sniffer that can be used with their $50 CC2531EMK which is a little USB stick with a Zigbee radio. This packet sniffer is good enough for basic troubleshooting, but as of August 2013 it cannot decrypt packets. I have also used Ubilogix packet sniffer from Ubiqua; it is more powerful and can decrypt packets. It's also much easier to use. There is a free 30 day trial available or it may be purchased for $999.

Network Explorer
The Network Explorer is an example that runs on a LaunchPad with BoosterPack. It can act as a known good node when developing communications between two nodes. The Network Explorer can be configured to act as a Zigbee Coordinator, Router, or End Device and can send and receive messages. When developing your product, first get your device to work with the Network Explorer. That will ease development since you have a reference platform for one side.

= Anatomy of Correct Communications = Assuming the modules started up successfully, the following is an outline of what happens when Device A sends a message to Device B by calling afSendData in af.c. First we will assume that we are using standard ACKing (aka MAC ACKs)
 * 1) Device A application processor sends an AF_DATA_REQUEST to the module.
 * 2) Device A module immediately sends back a response to the application processor since this is a Synchronous Request Message.
 * 3) Device A module sends the message to Device B module.
 * 4) Device B module sends an ACK message back to Device A module to indicate that it received a message.
 * 5) Device B module attempts to decrypt the message. If so then it sends the message to Device B application processor.

Now, if Application level acknowledgments (aka APS ACK) are used then the process is fairly similar but the difference is when the ACK gets sent:
 * 1) Device A application processor sends an AF_DATA_REQUEST to the module.
 * 2) Device A module immediately sends back a response to the application processor since this is a Synchronous Request Message.
 * 3) Device A module sends the message to Device B module.
 * 4) Device B module attempts to decrypt the message. If so then it sends the message to Device B application processor AND Device B module sends an ACK message back to Device A module to indicate that it received a message.

= Issues = We have helped numerous clients with their applications and have incorporated that knowledge into this wiki. Below are a few specific issues and ways to resolve them.

Modules Unable to Communicate with Each Other
In one application the customer was developing their product, which consisted of a small keyfob which would function as a Zigbee End Device and an adapter that would function as a Zigbee Coordinator. They were having problems getting the devices to communicate. Specifically, messages could be successfully sent from ED to Coordinator but not from Coordinator to ED. The following is a list of steps to take for similar issues:


 * 1) Start with the Basics.  You should already have basic functionality working; specifically:
 * 2) Hello World - verify that serial output works
 * 3) Get MAC Address - verify SPI communications with the Module
 * 4) Divide and Conquer.  Use the Network Explorer to function as one node while you develop the other. Then do the opposite. This will reduce the number of variables.
 * 5) Router before End Device.  Although the final product will be a Zigbee End Device, it is much easier to start as a Router since the Routers listen continually. The End Devices only wakeup periodically (2000mSec is default but can be changed) to check for new data. Even if your product will end up being an End Device, first get it working as a Router.
 * 6) Verify Module Startup.  Use a Logic Analyzer to compare your module startup with the reference logic analyzer traces.
 * 7) Display the Network Information.  Use the Serial Debug Port to display information about the network once the startup is complete. Look at this and verify:
 * 8) Both devices are using the same PANID and Channel
 * 9) Both devices have the same security settings
 * 10) The Router's Extended MAC Address is the Coordinator's MAC Address
 * 11) Ensure the Devices are Close.  The devices should be no further than a few yards from each other, and no closer than a foot or so. If they are too close then the radios can get saturated and have a difficult time communicating.
 * 12) Use both ACK modes to help troubleshoot.  If you are receiving MAC ACKs but not APS ACKs then it means that the module received the message, but can't understand it.
 * 13) Check security settings
 * 14) Use a packet sniffer to view the APS security settings. This turned out the be the cause of the problem; the ED had security=1 but the Coordinator had security=0.