Wednesday, July 21, 2010

How To Configure XBee & XBee Pro Series 1 on Linux

This tutorial will explain how to communicate with XBee modules using the X-CTU Configuration & Test Utility software from Digi.

Requirements
  1. A computer running Linux with at least one available USB port. I'll use Ubuntu in this tutorial because that's the one I've got. Don't use USB powered USB Hubs, since these may not be able to provide enough power for the USB XBee Adapter. You'll need two available USB ports if you are planning to configure and test the XBees simultaneously.
  2. You will need at least two (2) XBee modules Series 1 for any project.
  3. You will need at least one USB XBee Adapter. You can buy them either from SparkFun Electronics or Adafruit Industries. My personal suggestion is that you get two and not one, so that you can configure and test them simultaneously (you can have the X-CTU utility open many times). Assemble the USB XBee Adapter if it doesn't come fully assembled.
    I got myself the Adafruit version (manufactured by Parallax).
  4. You will need at least one USB A To Mini-B Cable. You'll need it to connect the USB XBee Explorer with your computer. Get two if you are planning to configure and test them simultaneously.
  5. You will need the FTDI Virtual COM Port drivers.
    Up-to-date linux kernels (2.6.9 or greater) have FTDI support built-in.
    If that's not the case, get the Virtual COM Port drivers from this link and proceed to install them.
  6. Download and install Wine. Here's a guide for Ubuntu, or just type sudo apt-get install wine on the command line.
  7. Download and install the X-CTU Configuration & Utility software from this link. Make sure Wine is installed before attempting this step.
  8. Obtain the firmware versions for your XBee modules.
    If you fail to do this step, you will have problems trying to read the XBee module settings and firmware using the X-CTU software. These firmware versions go in the update folder in ~/.wine/drive_c/Program\ Files/Digi/XCTU.
    You can get them in a couple of ways:
  1. Download the firmware versions for your XBee modules from this link.
    Extract it in ~/.wine/drive_c/Program\ Files/Digi/XCTU.
  2. Download, install and run X-CTU in Windows (could be inside a Virtual Box).
    Go to Modem Configuration and click in Download new versions (it make take a while).
    After it's done downloading, open the X-CTU installation folder in Program Files\Digi\XCTU, and compress the update folder located inside.
    Transfer the compressed file to ~/.wine/drive_c/Program Files/Digi/XCTU and extract it.
  3. If it asks permissions to overwrite any files, just agree to every file.

Running X-CTU on Linux and testing the XBee module and the USB XBee adapter
  1. If you have already added the COM ports to Wine, skip the next step.
  2. Wine allows us to map serial interfaces to COM ports easily.
    Wine reads COM ports from the "
    dosdevices" folder, which is located in ~/.wine in Ubuntu.
    In Ubuntu, the USB serial ports will appear as
    /dev/ttyUSB0 for the first one, /dev/ttyUSB1 for the second, and so on.
    Open up the terminal, and create a soft link to the
    ttyUSB0 like this:
    ln -s /dev/ttyUSB0 ~/.wine/dosdevices/COM4
    If you are going to connect two USB XBee adapters, you might want to add COM5 too.
    ln -s /dev/ttyUSB1 ~/.wine/dosdevices/COM5
    Make sure you type COM in upper case otherwise Wine won't recognize it as a serial port. (Thanks Tyler for pointing this out)
    This will map the first USB serial port to COM4 and the second to COM5. Remember this, as we will need to type it in later.
  3. You will only need to do this step ONCE, as the soft link will persist.
  4. Insert the XBee module into the USB XBee adapter correctly, if you haven't already.
  5. Connect the USB cable from the USB XBee Adapter to the USB port on your computer.
  6. The USB XBee Adapter power leds should light up.
  7. Open up X-CTU using Wine. In Ubuntu, it will be installed in ~/.wine/drive_c/Program\ Files/Digi/XCTU.
    cd ~/.wine/drive_c/Program Files/Digi/XCTU
    wine X-CTU.exe
  8. In the X-CTU software, go to PC Settings > User Com Ports.
  9. In the "Add User Com Port" field type COM4 and hit the Add button.
    Repeat steps 7 and 8 to add more COM ports.
    You will have to do steps 7 and 8 every time you open the X-CTU, a minor nuisance, in my opinion.
  10. Select the previously added COM port in the list above by clicking it. It should appear as User (COM4).
  11. Hit the Test / Query button to test communication with the XBee module.
  12. Wait a couple of seconds. It should output a window displaying the Modem type and Modem firmware version of the XBee module. For me it was type XBP24 and firmware version 10E6 because I have the XBee Pro 2.4 GHz Series 1 model.
    If you failed to select the COM port in the list, it will tell you that it was unable to open the com port.
  13. And there you go, you have established communication between the X-CTU and the XBee module.
EDIT:  Made some corrections that Tyler pointed out in the comments.


Thanks for reading! And don't forget to share your thoughts in the comments!