In the trenches with XBee: resources and tips

XBee modules are small chips implementing the Zigbee, ZNET, and/or 802.15.4 wireless protocols. I find them very useful for gathering data from sensors spread around an area. The modules have digital and analog I/O pins to which sensors can be connected directly; this removes the need for a micro-controller. The data rate at the radio interface is  250kbit/sec — so the actual data rate, after allowing for protocol headers etc. is smaller. When using them for my projects, I have managed to transmit data up to 100m line of sight in a park and up to 70m line of sight in a tunnel (XBee Digi Series 2, on-chip antenna. XBees with antennae can transmit much farther). By adding more XBees, the distance can be extended as the network configures itself automatically to forward data hop by hop. Regarding the tunnel scenario, if you need to transmit signals around a corner, make sure that either:

  • One Xbee can “see” the two XBees at the sides of the corner
  • The XBees around the curve are not more than 7-10 m apart, with one of them at most 2 m from the corner

Otherwise communication becomes intermittent or impossible.

XBees can be configured either as a simple serial-line replacement (where you don’t have to do anything explicitly to communicate over them), or as uniquely addressable devices, in which case you decide to which XBee each message goes. There are two modes: AT mode (very simple, commands are text-based), and API mode (complicated, binary, but gives you more control). My recommendation is to use AT mode to set up connections and try out quick prototypes, and then use one of the libraries below to implement an API mode advanced version of your device.

Some resources I found useful in my work with XBees are the following:

The data sheet:
Useful for understanding how they work and the commands you need to configure them and to communicate with them.

Another data sheet.:
I find the previous one better, but this is for a different model.
The X-CTU utility for configuring and flashing the XBee if needed: .
A serial terminal works just as well for configuring, but is not as friendly because you’d have to use the command line

The Unofficcial XBee FAQ: For an in-depth look, especially regarding baud-rate mismatches and other details of the electrical/physical layer, have a look at The XBee Cookbook:

The XBee Java API library,, complete with tests and example cases. Doubly useful: it allows you to program true computers to use XBees, and it allows you to debug your communication algorithms and protocols on a real computer before implementing them on a microcontroller (where debugging is more complicated)

The XBee Arduino API library,, written from the same author. Great library, but with a catch: It only uses escaped API mode (parameter AP=2). This means you must make sure your XBees are programmed to use API mode with AP=2 and this is written to their flash memory to survive powering off. As an alternative, your Arduino program should set AP=2 as a first thing. I spent three days trying to debug why my code worked fine in Java with the Java API library above, but not on the Arduino with the Arduino API. Reason: The Java API library sets AP=2 automatically during initialization, in the call. The Arduino library does not.

There is an XBee shield page at Arduino Playground, but I have not yet made much use of it. From a first look it seems to be pretty comprehensive. In my opinion one needs to read the data sheet at some point, so better early than never 😉

Lastly: a debugging checklist, so you can save yourself from ripping your own hair when the XBees don’t accept to talk to each other in API mode 🙂

  1. Write on a paper the model and firmware of your XBee. You can see them from X-CTU, in the “modem-configuration” tab, click READ and write down the content of the drop-down lists at the top. If all goes to hell, you’ll need this info to revive your XBee.
  2. If you use API mode and the Arduino library, the XBees need to be initialized to AP=2. Double check that. Again.
    You can set AP=2 through X-CTU, via a terminal, or in your code. If using a terminal, do not forget to give the ATWR command to save it to flash. In your code, just after xbee.begin(), you need to send an ATCommandRequest with AP=2. Note that  AP will be a char array {‘A’,’P’}, but the 2 in the value is an int, not a char ‘2’.
  3. If that does not work, reset all the XBees to the default AT mode, 9600 bps. Double check that they are all configured as the same protocol, either ZNet, Zigbee, or whatever else is available for your firmware. There must be only one coordinator. Check that all XBees have the same PAN ID. Don’t forget ATWR to write it in flash.
  4. Check that things are working in AT mode. You can do this via a simple terminal, no API library is needed for this. Connect two XBees, type into one, you should be receiving the characters into the other.
  5. Reprogram the end/router nodes (NOT the coordinator!) to API firmware, check that communication via the xbee-api Java library works (just use one of the examples from the library). How you connect from Java to the XBEE depends on what cables and electronic skills you have. You will need a FTDI Cable (Sparkfun or DIY with an Arduino). In both cases you need to connect only GND, VCC, RX, and TX of the XBee module. An XBee kit may be helpful but is in no way a must.
  6. Reprogram the coordinator to API firmware, set AP=2, check that everything is still working. Only use the xbee-api library in Java, with one of the library’s own examples.
  7. In the library, go to “private void doStartupChecks()” in and comment out the part that reads and sets the AP=2 mode. Run and check that everything still works. If communication breaks here, you know you have not set AP=2 in the firmware, or that your code is not setting it explicitly.
  8. If everything is fine up to here, you may start using the xbee-arduino library. Double-check to make sure the serial ports in the Arduino code and in the XBees are set to 9600 bps, 8bits data, no parity. Use a hardware serial port, not a software serial one for this test, to avoid interrupt problems. Hopefully everything should work. If it doesn’t, you might need an oscillator to see what is being sent to the Xbees and compare it with what should be sent. I used this one when I had problems:

During all these tests, it may happen that you “almost” brick your XBee, i.e. that it does not communicate anymore with X-CTU or it cannot be flashed anymore etc. But “almost bricked” is not the same as “bricked”: Try a factory reset following the tips in this post at Sparkfun’s forum. This is where you’ll need the model and firmware you wrote down in step 1 of the debugging list. Right?

  1. Take the XBee out of the adapter/board/whatever it is in. Open X-CTU and connect to the adapter/board/Serial port
  2. In the “modem configuration” tab check “Always update firmware” and select the model and firmware/function set from the drop downs. These are the same you wrote down before.
  3. Click on “Write”. X-CTU will complain it cannot find the XBee. Now, without clicking anything on screen, insert the XBee into the interface board. If the alert dialog does not go away by itself, dismiss it. If X-CTU still does not finish successfully, repeat the process.

Good luck and have fun!