Configuring XBees for API Mode

XBee are popular wireless modules used by hobbyists and DIYers.  These wireless modules come in variety of styles and power ratings (distance ranges).  There are several tutorials even instructables for configuring XBees for point-point (P2P) communication.  P2P communication is restricted between two end-points and this is all you need if you only have two wireless devices in your setup.  What do you if you have multiple devices...say a network?  Perhaps we should start with a simpler set up.  

In this instructable, I will show you how to configure XBees for a point-to-multipoint mesh.  In this configuration, there will be one central COORDINATOR and multiple END DEVICES.  The END DEVICES will send and receive messages from the COORDINATOR and the COORDINATOR will have to sort which wireless packets came from which END DEVICE and send packets to the appropriate END DEVICE as well.  

The XBee modules can be configured in two ways: Transparent Mode (AT) and API Mode (API). In AT mode you are limited to point-to-point communication between two XBees. In API mode, we can trivally send and receive from both the COORDINATOR and many many XBees out in the world.  Additionally, API mode will expose a variety of additional information encoded in each packet. 

In a point-to-multipoint wireless configuration (see picture 1), multiple nodes (Router/End Devices) pictured in blue, send to and receive from a central coordinator (red).

Andrew Rapp wrote a great XBee Java API which can be found here: http://code.google.com/p/xbee-api/

Andrew also provides detailed instructions for integrating the XBee API with the popular IDE Eclipse. For my project (and for unknown reasons) I decided on using the Swing JAVA GUI library which, for me, was a little easier to develop for using NetBeans. Therefore, I will also provided instructions on how to setup the XBee JAVA API using Netbeans. But first we need configure the firmware on the XBee. 

The only way I know of to initially configure XBees is to use XCTU. This is a free program available from Digi, the makers of the XBee. XCTU runs only on Windows, however, I have been successful at configuring XBees using XCTU running under Wine. In fact, I have even been successful configuring an XBee on a MacBook, with Debian installed on a virtual Machine and WINE running XCTU. So you can configure your XBee no matter what OS you are running! 

Using a macbook, I first installed VirtualBox then downloaded and installed the Debian Network ISO. After installation of the OS, I download XCTU from the download link and installed wine through aptitude (Debian package manager).

After everything has downloaded, run WINE and the XCTU executable downloaded from DIGI. (See Pic 1). Once installed you will need to create a symbolic link between /dev/ttyUSBx (x: 0,1,2,3) and COM0x (x: 0,1,2,3). Don't worry if they don't exist now. /dev/ttyUSBx will exist after you connect your fdti-usb chip to the XBee.
cd ~/.wine/dosdevices
ln -s /dev/ttyUSB0 COM00
See Pic 2
(The following assume you have connect your XBee to your computer using a usb interface. This can be accomplished with a variety of XBee breakout boards.)

Next you will need to update XCTU (I know, we haven't even run XCTU yet!). I have not been able to update XCTU from a virtual machine. Luckily, I found someone with a windows machine and asked them to update the config files for XCTU.  They the packaged the updates for all of our convenience. Copy the updated files to ".wine/drive_c/Program Files/Digi/XCTU/update/" (if you need help with update files please message me)

Now we can finally run XCTU. See Pic 3. After a successful launch, plug in your XBee and allow the virtual machine access to your usb device. Under VirutalBox, this accomplished by clicking on Devices->USB Device->FTDI (my usb device). Check to see if your device was added by typing on the command line 'ls /dev/ttyUSB*'.  You should see a listing.

In XCTU, click on Network Interface in the bottom half and add the link name that is pointing to the listed /dev/ttyUSBx . In my case /dev/ttyUSB0 is listed and therefore I added COM00 (See Pic 4). After clicking "Add" select the name and click on Test / Query. You should see successful communication (Pic 5) 

Now that XCTU is running we need to reconfigure the device for API mode. First Click on Modem Configuration (Top Right Tab) and click on the Read button (Pic 1). From the drop down menu select ZNET 2.5 ROUTER/END DEVICE API (Pic 2). Click on Write and wait until writing finishes. A dialog box may pop-up and ask to reset the device. If this is the case and you are using an XBee LilyPad Breakout, simply connect the MINUS pin to the RST pin and release.  After reconfiguring, click on the Test / Query button to confirm that the XBee has been reconfigure (Pic 3)

Now that we can configure XBees for API mode let's switch gears to setting up the JAVA environment.

If you are going to use the Eclipse IDE, I would suggest following Andrew Rapp's instructions found here: http://code.google.com/p/xbee-api/wiki/GettingStartedWithEclipse

If you choose to use the Netbeans IDE do the following:
Downlod NetBeans and install.
Select: New Project->Java->Java Project with Existing Sources  (Below are my settings)

Project Name: TestXBeeJavaAPI
Project Folder: /Users/benzaitlen/NetBeansProjects/TestXBeeJavaAPI
Click Next
Add Folder for Source Package and select the src folder in the XBee Java Api folder
Click Next
Then click Finish

If you have a red exclamation point in your list of files, you probably need to add the log4j and/or RXTX JARS. Luckily, Andrew packaged both of these with his source files. Right Click on Libraries in the Navigation window and navigate to the API folder->lib->log4j.jar

If you receive the following error: log4j:ERROR Could not read configuration file [log4j.properties], then make sure log4j.properties is located in your netbeans project folder. (The log4j.properties file also is provided by Andrew Rapp's JAVA package)

RXTX has some problems on OSX. You can try the binaries or source code from http://rxtx.qbang.org/wiki/index.php/Download . If you try compiling the source, make sure you download the most updated Java Developer Package from developer.apple.com. If you are getting frustrated with OSX, then use the already setup ubuntu/debian virtual machine!

Once you have established that you can use the JAVA API, program two XBees. One should be ZNET 2.5 ROUTER/ENDDEVICE API 1347 and the other should be ZNET 2.5 COORDINATOR API 1147. At this point, I would strongly suggest labeling the two XBee with some masking tape.

Homestretch!

Now that the XBees are in API mode. We have to get the Arduino to also use the XBee API. Again, Adnrew has already done the heavy lifting for us. Download the Arduino API ZIP file from: http://code.google.com/p/xbee-arduino/

Extract and copy the XBee folder to ARDUINO_HOME/hardware/libraries or create a folder 'libraries', wherever you store your sketches, and unpack there. If you are upgrading from a previous version, be sure to delete XBee.o

Once installed I would suggest playing with the JAVA and Arduino API to make sure you can send and receive messages.  There are plenty of examples provided in both libraries. Assuming you have an arduino+xbee and an XBee connected to your computer, try setting up the following: ArduinoReceiveTest.java (Computer Side) and Series2_Tx.pde (Arduino Side).

For an an instructable that relies on the XBee API mode click here

This material is based upon work supported by the National Science Foundation under Grant No. 0855886 to Kylie A. Peppler. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.