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.

  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!


  1. Thanks for the write-up! This saved me as I didn't have a Windows machine handy. One note: when setting up the COM port link the com name needs to be all caps, ie:
    ln -s /dev/ttyUSB1 ~/.wine/dosdevices/COM5
    or x-ctu can't open the port (at least on my OS, Ubuntu 10.10)

  2. Thanks Tyler, I've updated my post with your corrections.
    Glad this worked out for you!

  3. ... Just as a information, when setting up the COM port soft-link, in the part where COM should be with Cap, I had it the other way around. X-CTU couldn't open the COM port when I used capital-letters. It was first when I used normal letters.

    Michael (Ubuntu 10.10 i686)

  4. can it be done without involving WINE ??
    If yes then please forward a link for the same!

  5. Sadly, there is no linux version for the CTU software to my knowledge.

  6. Hi there,

    First of all thanks for the tutorial, I've been following a book (quite a good one actually), but your straight forward ubuntu tutorial came handy.

    Nevertheless I'm having a problem when I try to test the connection it gives me:

    "Unable to communicate with modem"

    In my case I created a link (after consulting dmesg) for ttyUSB0:
    ln -s /dev/ttyUSB0 /home//.wine/dosdevices/COM10

    Any of you had a similar problem?

    Best regards,

    Carlos Vicente (2.6.24-24-server)

  7. Carlos,

    Thanks for using my tutorial!

    Sounds like ttyUSB0 is mapping to a different device.
    Try plugging and unplugging the XBee module while reading dmesg to see if you are mapping your COM port to the right serial device (ttyUSB#).


  8. Hey Ricardo,

    I've actually been able to get my hands on a WinXP to use X-CTU, just for the initial configurations and firmware, and afterwards, I turned again towards my ubuntu and picocom for some AT commands and it worked fine with the ttyUSB0 (it always assigned the same one).

    I guess I must be doing something else wrong while using X-CTU under wine! :-\



  9. Excellent tutorial. Thank you.

    NOTE that for my system Ubuntu 11.10, you have to write com4 with small letters and not capitals (as your correction suggests) in order to work.

  10. 'moltosenso' can be used in place of X-CTU for Ubuntu..

  11. has anyone been able to read the parameters off the Xbee? It keeps asking to download the newest firmware. I moved the windows update file over...

  12. I read your post on XBee cheat sheet. You gave very interesting information regarding XBee. Use Xbee tutorial for learning XBee module.

  13. Always renew 10year . Don't be like the car dealer that they will only do 5year. They kill it . Like a cancer for the car in 5year. Top of the cost. I have renew all my car and bike 10year . I have keep a few car and bike and they run good. Depend how you take care of them. chauffeur service dubai rent a car with driver in dubai