Configuration Utilities for XBee Radios
I purchased two XBee Series 1 Module (Freescale 802.15.4 firmware) from Adafruit. These are manufactured by Digi and are low-power module with wire antenna (XB24-AWI-001). They have a 250 kbps RF data rates and operate at 2.4 GHz. These radios use the IEEE 802.15.4 networking protocol and can perform point-to-multi-point or peer-to-peer networking , but as configured here, they do not mesh. The Digi models that handle meshing are Digimesh, ZNet2.5 and Zigbee (ZB). Digimesh is a version of firmware that runs on Series 1 hardware. So, if you choose to, you can upgrade these modules to Digimesh firmware to get meshing.
Xbee Adapter Board
Along with the XBee radios, I purchased adapter boards designed to make it easier to work with the radios. The adopter provides on-board 3.3V regulator power from a 5 volt source, voltage level shifting circuitry so you can connect 5V circuitry to the XBee, commonly used pins are brought out along the edge (making it easy to breadboard), and engineered to be interface via FTDI cable to a computer via USB.
- 3V pin – This is either an input power pin (if 5V is not provided) or an output from the 250mA regulator if 5V is provided
- DTR – “Data terminal ready” is a flow control pin used to tell the XBee that the microcontroller or computer host is ready to communicate.
- RST – “Reset” pin can be used to reset the XBee. By default it is pulled high by the 10K resistor under the module. To reset, pull this pin low.’
- Ground – common ground for power and signal
- CTS – “Clear to Send” this is a flow control pin that can be used to determine if there is data in the XBee input buffer ready to be read
- 5V – This is the power input pin into the 3.3V regulator. Provide up to 6V that will be linearly converted into 3.3V
- RX – “Receive Data” is the XBee’s serial recieve pin. Serial data is sent on this pin into the XBee to be transmitted wirelessly
- TX – “Transmit Data” is the XBee’s serial transmit pin. Serial data is sent on this pin out of the XBee, after it has been transmitted wirelessly from another module
- RTS – “Ready to Send” is a flow control pin that can be used to tell the XBee to signal that the computer or microcontroller needs a break from reading serial data.
- see pin #1
The DTR, RTS, RST and RX pins (going into the XBee) pass through a level converter chip that brings the levels to 3.3V. Adafruit claims you can use pretty much anywhere between 2.7 to 5.5V data to communicate with the XBee. The breakout pins on the bottom of the board are not level shifted and you should try to keep data going directly into the XBee pin under 3.3V
XBee Initial Configuration and Testing
You need a way to communicate withe the Xbee, via it adapter, to set it up. This can be done via Adafruit’s USB FTDI TTL-232 Cable, and the Digi X-CTU serial terminal program. By the way, the X-CTU user guide describes the many more things it can do beyond the configuration shown here.
- Plug in the USB FTDI TTL-232 Cable into a PC USB port. If drivers are not installed automatically (it didn’t for me), follow the steps at the FTDI site.
- Download the X-CTU, double click on the executable file, and follow the instructions to install the program.
- Now connect the USB FTDI TTL-232 Cable to the Xbee Adapter as shown in the picture to the right and insert the USB end of the cable to you PC. Start the X-CTU.
- To connect, configure and upgrading the Xbee, follow the Adafruit instructions for the Xbee Adapter board. Note that if you follow the instructions (I didn’t – I kept it at 9600 baud), the modem’s serial interface is now set to 19,200 baud, not the default 9600 used by X-CTU. Remember this next time you use X-CTU with this Xbee.
- If your instructed by X-CTU to reset the Xbee, you can do this by shorting the reset pin, RST pin, to ground.
The configuration can be touchy, it can go badly, or not at all. In my case, I seem to have one Xbee Adapter that can reliably perform a firmware upgrade but the other one took some time due to a lose fitting between the Adaptor and Xbee. If you run into configuration problems, check out these sites: Using XCTU to Invoke the Bootloader, The Unofficial XBee FAQ, How to recover from a failed firmware upgrade.
Quickly Getting the Xbee’s Communicating
The next step for me was just do a basic test of getting two XBee device communicating with each other. This is just a sanity test to see evidence of communication between the devices. Basically, I just followed the instructions provided by Adafruit.
- Using the X-CTU, set the PAN ID to the same value on the two Xbee’s.
- Select an Ardunio that has been programmed to send repeated brief messages to its serial port. I used the standard LED Blinking sketch but put in some write statements in the loop.
- Using an Arduino and breadboard, connect +5V and ground to provide power. Make sure the XBee’s LED is blinking.
- Connect the RX line (input) of the XBee to the TX line (output) of the Arduino. Connect the RX line (input) of the Arduino to the TX line (output) of the Xbee. Plug the Arduino into your PC’s serial port.
- Now take the second Xbee and connect the USB FTDI TTL-232 Cable to the Xbee and the PC. The cable is doing nothing but appling power to the Xbee.
- Now you should see the receive LED periodically light on the USB FTDI TTL-232 Cable tethered Xbee.
- You now got proof that the two Xbee’s are communicating. The Arduino connected Xbee is sending data to its serial port and the USB FTDI TTL-232 Cable tethered Xbee is receiving it.
Above you’ll find a picture of the configuration, and below is the Arduino sketch I used.
Installing XBee Python Tools for the RPi
While the MS Windows based Digi X-CTU tool is just fine, I want to use the RPi’s and Python to access the XBee serial communication API, and its advanced features, for one or more XBee devices. I prefer simple utilities, that can be scripted within the Linux shell. Call me a Linux snob if you wish, but I don’t care for MS Windows!
In my post “Selecting XBee Radios and Supporting Software Tools“, I referenced a Python package that could be used to create my utilitiesd, call python-xbee, and I will be using it here. It claims to provides a semi-complete implementation of the XBee binary API protocol and allows a developer to send and receive the information they desire without dealing with the raw communication details. It also claims the library is compatible with both XBee 802.15.4 (Series 1) and XBee ZigBee (Series 2) modules, normal and PRO.
First, we need to load some additional required Python Packages, that being pySerial and Nose. pySerial extends python’s capabilities to include interacting with a serial port and Nose is a package providing a very easy way to build tests, based on the Python class unittest. (Don’t let this all scare you away, these are necessary but your not going to use them directly). To load these package:
sudo pip install pySerial
sudo pip install nose
Download the python-xbee tools from Google Code or Python Org and place them into the RPi’s $HOME/src. The README file provides installation instructions. It states that the following command automatically test and install the package for you:
sudo python setup.py install
There is a simple to use RPi platform tool that I have modified for my needs, that is a XBee serial command shell for interacting with XBee radios. It performs the core functions of the official configuration tool, X-CTU, which only runs on Windows. (There happens to be a cross-platform version of X-CTU called moltosenso Network Manager but I don’t need all this horse power.) I’ll use this X-CTU-alternative to configure the individual XBee radios. With the X-CTU, you can update firmware, etc. but most of the time you need the program to do simple configuration tasks. You could use Linux’s
minicom, but I prefer a simpler tool which can be scripted so I can configure several XBee radios identically. I found much of what I wanted in an existing Python XBee tools for configuration. I made some modification/improvements,
The XBeeTerm.py module imports functions from the pretty.py package, specifically to colorize the output for xterm on the Raspberry Pi.
Identifying the RPi USB device used by the XBee
Since the python-xbee library wants to talk to the via a Linux serial devices, I’m using the USB FTDI TTL-232 Cable (FTDI is the USB chip manufacturer) used in the XBee configuration step done earlier. I connected the cable to the RPi USB port and then we need to find the serial tty the cable is associated with. To do this, it takes a bit of detective work. Run the commands:
dmesg | grep Manufacturer
dmesg | grep FTDI
A better command might be (but I’m not sure it will work every time):
dmesg | grep -i usb | grep -i tty
The interpretation of the output tells us the cable is attached to serial device
For more detail: Configuration Utilities for XBee Radios