Justin DeWind and I recently started working on a project involving XBee radios. These little devices are fun to work with and more capable than their small size lets on. A lot of questions have come up as we’ve worked through a technical spike using the devices, some with difficult-to-find answers. The following are a few notes that, hopefully, will save you time and frustration when adding a little bit of XBee to your projects.
Know your series
There are two different series of XBee radio — Series 1 and Series 2. They are not compatible with each other. If you have a device that contains an XBee radio but don’t know which series, look for the FCC registration ID on the outside of the device. Short of taking it apart, that’s probably the easiest way to identify the XBee radio series.
The FCC has a site where you can look up the ID: http://transition.fcc.gov/oet/ea/fccid/. Be sure to include the dash in the Product Code field — the search will fail without it (e.g., Grantee Code: OUR, Product Code: –XBEEPRO).
Series 2 XBee radios have an FCC ID of OUR–XBEE2, while the Series 1 radios are either OUR–XBEE or OUR–XBEEPRO. Ours were series 1, but much of what follows will apply to either type.
Get connected
We ordered our XBee radios and XBee Explorer USB boards from SparkFun. The Explorer USB boards made it very easy to plug in to our MacBook Pros and get up and running quickly. An XBee Arduino shield would have worked well once we concluded we needed a microcontroller involved, but they are relatively simple to wire up without one.
Download the appropriate FTDI drivers for your operating system, then plug it in and get going.
GNU screen for configuration
The GNU screen utility has proved extremely useful for communicating with XBee radios once they are live on the /dev filesystem. However, it can also elicit a wide variety of explitives from the uninitiated. Much like our beloved Vim, learning your way around screen takes patience but is well worth at least a small investment of your time.
To start screen and interact with your XBee, you will need to know the baud rate of the serial device. Ours came configured at 9600 baud and showed up as /dev/tty.usbserial-A900fs0v. The command to start screen is then:
$> screen /dev/tty.usbserial-A900fs0v 9600
Your terminal window will then go blank. These commands will help as you start interacting more with the XBee.
- Ctrl+a, Shift+c — clear the terminal window.
- Beware: Ctrl+a, Ctrl+c will open a new terminal session window within the screen session. This can quickly become as strange as an episode of Lost if you try to launch a screen session to your XBee radio again from this bizarro terminal session. Ctrl+a, k will get you out.
- Ctrl+a, Ctrl+\ — exit screen
- Ctrl+a, k — kill the current window
- Ctrl+a, : — enter command mode. A lot like typing colon in Vim.
- In command mode, type help to bring up the built-in help information.
Now start issuing commands to your XBee radio. You will need to enter command mode for these commands to work; type +++ and wait for the OK acknowledgement. Note that you should not press return after typing +++, unlike the commands below. There is a timeout for command mode and it is very short by default (10 seconds). If you want it to be longer you can set it using the CT command.
- atct190 — Set the command mode timeout to 400 × 100ms.
- atid — Display the current network id. XBee radios must be on the same network to communicate. Append a new ID to the command to set it. (default: 3332)
- atwr — write the configuration to non-volatile memory
Note: If you’re working on an ARM system that doesn’t have screen, like we were, you can find static binaries here.
Poorly documented commands
There are a few commands I noticed on other blogs, but the reference manuals make no mention of. They appeared to be important to our cause — we wanted to use a digital IO pin to light an LED — and I had a hard time tracking down descriptions for them. It appears this may not be as much of a problem for those using the Windows-only X-CTU application because I ultimately found the answers in screenshots of the application.
- IU — I/O Output Enable. Enables I/O data received to be sent out UART.
- 1 means status updates will be published on the serial channel as well as the appropriate digital I/O pins if configured appropriately.
- 0 means the status updates will not be published on the serial channel.
- IA — I/O Input Address (or, I/O input line passing input address)
- FFF will match any address
- Or, set a specific address
Of course, learning what those commands are will only help you if your ambitions are possible in the first place. That brings us to my final point.
What you can and can’t do with the digital IO pins
We wanted to send a message to an XBee radio and cause one of the digital I/O pins, configured as a digital output, to go high or low. It sounded possible based on descriptions I skimmed of using the XBee devices without a microcontroller, but in the end no amount of configuration appeared to allow it. And as far as I understand it doesn’t work quite that way.
The digital I/O pins are present for two primary purposes:
- As inputs, to be sampled and the values sent to another XBee radio.
- As outputs, to mirror the values of input pins received from another XBee radio.
I suppose we could probably send a packet that looks like an input reading from another XBee and, given the configuration is correct, get the digital output to reflect the desired value. But it was much simpler to attach an Arduino and program it to work its digital I/O pin magic when it received specific data via the attached XBee radio. This is also more likely to reflect our real use case as the devices we’ll be communicating with are not bare XBee radios.
We’re still working out some of the details with our configuration, but hopefully this helped save you a little time.