14 July

This post deals with Xbee/Zigbee firmware with non-windows software for editing the Xbee parameters from the command line. There's also a trick for re-flashing and Xbee in an Arduino shield. Below, I explain the different kinds of hardware and software.

Contents: my application, XBee hardware versions (confusing!), firmware versions, non-Windows programming software (Mac OS X, Linux, etc.)

My application

Last weekend I implemented a GPS broadcasting system using Xbee (Zigbee) modules from Digi International. These are small wireless networking nodes that can be connected using a serial line. The Funnel IO variant of the Arduino open source CPU module directly supports the Xbee hardware, and also provides a lithium-polymer charging circuit, so it seemed just right for my needs. (FunnelIO is very nice, but poorly documented.) The idea was to receive GPS data on one module and transmit it to another one (that was in a location where direct GPS reception was impossible: i.e. inside our robot). While everything seemed pretty straightforward in principle, I had few problems.

XBee rear
(click to zoom)

I programmed the Arduino to pull in GPS data on a software serial port, and then retransmit the data on the hardware serial driver connected to the Xbee. I also wrote some diagnostic code to verify the GPS data was solid, to check the fix and do some housekeeping. This worked well, and I was even able to deploy the GPS receiver at the end of a 10 meter cable. When I tried to relay the data across the Zigbee link, however, I encountered all kinds of data losses. These looked like buffer overflows which led to lost data.


On the whole, I found the terminology and variety of options pretty confusing, partly because terms have changed and there are both obsolete and even misleading documents widely readily available on the net. Also, non-windows support, and even Windows Vista/7 support, was poor. Hence this page.

Firmware and device families

[ Sorry, this part of the story is almost assured to confuse you on the first reading. That's because the mish-mash of names and models is just a mess. Just ahead to the more readable part on "Reflashing in an Arduino shield" is you start to feel sea sick. ]

Now these xbee modules can work in either point-to-point mode, or via broadcast. My first attempt was with broadcast using ZB firmware since that was easier to configure. Well, broadcast mode automatically retransmits packets multiple times (since acknowledgements can;t be sent in a broadcast context). I figured I'd try point-to--point mode. I could never get this to work.

My observations and inferences about the Xbee line:

-- There are at least 4 main families of the hardware, and several variants of the firmware for each hardware family. All the modules on a network should have the same hardware and firmware. (In addition, within each family there may be different modules with alternative antennas, but I'll ignore those little differences since they don't impinge on functionality at a software level.)

-- There are 2 different hardware "series": Series 1 and Series 2, and each has a Pro (and non-Pro) variation. This makes for 4 classes of hardware: Series 1 non-pro, Series 1 Pro, Series 2 non-pro, Series 2 Pro. These different variations differ at a hardware level. You cannot reprogram one to become another.

XBee series 2 indication
(click to zoom)

-- Confusing names: Series 1 is now officially called "XBee 802.15.4." Series 2 was renamed "XBee ZNet 2.5" which is really confusing since this names also seems to be used for one of the types of firmware for these devices.

These two series (1 and 2) are also known as Freescale and Ember respectively, based on the different hardware makers for the 802.15.4-protocol networking chip. The Freescale MC13213 is an integrated radio transceiver and a 8-bit 689S08A microcontroller. The Ember EM250 is a radio and a 16-bit XAP2b RISC microcontroller with AES encryption support and 128kB of flash memory. Series 1 and Series 2 differences are described in this document from Digi.

Firmware versions (4 types)

-- ZNet 2.5 firmware is based on the "EmberZNet 2.5" radio networking software. (This equivalence and terminology is indicated in the Firmware Revision History, although a Digi employee I spoke to disputed some details.)

-- ZB firmware is also known as Zigbee, or more correctly as "ZigBee PRO" since that is the name of the protocol specification it adheres to. It is based on the Ember "EmberZNet 3.x" rio-networking software. Thus, ZB is newer than ZNet 2.5, but for me ZNet 2.5 worked better.

-- Devices running ZNet 2.5 firmware cannot talk to devices running the ZB firmware, even though they are used in very similar ways and with similar commands.

-- Another firmware called 802.15.4 for Series 1 modules also exists, as well as DigiMesh. This makes for 4 different firmware families, and they should all be considered incompatible with one another. Note that 802.15.4 appears the name of one of the firmwares, but it is ALSO the name of the networking protocol. This 802.15.4 has two different meanings: the firmware and a IEEE standard protocol. (Yes, this is bewildering.)

-- The Zigbee networking protocol is defined by an organization called the Zigbee alliance. They have two key variations of the Zigbee protocol: the original Zigbee (Zigbee 2006) and a new protocol called Zigbee Pro based on Zigbee 2007. This "Pro" suffix is unrelated to the word Pro in the name of the "Xbee Pro" module family, where refers to modules with high power output. Also, both these Zigbee protocols are built upon the lower-level IEEE 802.15.4-2003 standard.

-- "XBee Pro" modules operate at higher RF power levels, 50 or 100 milliwatts. Same pinout, slightly longer chip housing for the Pro models. The regular (non-pro) units work at 1 or 2 milliwatts. (It is possible they inter-operate with non-pro, but I have not tried.) Regular XBee devices have serial numbers starting with "XB" (e.g. XB24-B) while Pro devices start with XBP.

Using the "DD" command, you can read the pre-loaded device family code.

The Xbee's using I purchased came with "Zigbee" firmware pre-installed. I believe this is what they suggest for new customers. I could never get point-to-point (non-broadcast) communications to work with or without a coordinator, so I tried another firmware. When I eventually decided to download and burn in the "ZNET 2.5" firmware instead of the Zigbee firmware, everything worked. Point-to-point worked, but I am pretty sure the throughput was so much better that broadcast would have worked fine also. My morale: use the ZNet 2.5 software on the Xbee if you can.

Firmware versions -- details
Using the VL command, you can query the currently-loaded firmware version. It is a 4-digit number (ABCD), but if the last digit is zero it might appear in the form ABC. The digits have the following interpretations:

  • A: seems to be 1 for ZNet 2.5 release firmware, 2 for Zigbee firmware and 8 for beta-test code.

  • B: the "variant". 0 for coordinator in AT mode (one of two possible command languages used for the modules). 2 for end device code. 1 and 3 are for API command mode.

  • C: seems to identify the version of the code. New releases have bigger values.

  • D: revision number of the version.

Thus my XBee Series 2 node in coordinator mode currently uses firmware version 1047.

See also Digi's firmware documentation, the list series 2 firmware releases.

Reflashing in an Arduino shield

To reflash the Xbee firmware you need to use the XCTU program. My Xbee was in an Arduino "shield" (which provides a USB interface). To directly control the Xbee, you need to remove the microcontroller from the Arduino CPU board (as described here). This is great for accessing the Xbee serial interface from a computer, but to use XCTU you will also need to reset the Xbee a couple of times and no such button it provided on the shield. With a small section of wire, you can do this the "hard core" way. Just touch the wire between pin 5 and pin 10 of the Xbee (or the solder pads beside it). Pin five is the reset pin and pin 10 (at the corner of the module) is the ground pin. Pulling the reset pin low (to ground) does the reset. This is pretty easy and works reliably.

XBee reset using jumper
(click to zoom)

Python-based XCTU replacement

I rarely use Windows and thus I also wrote a python-based program to allow the parameters of the Xbee to be queried and set. This allowed me to configure the Xbee from OS X and (later) from other software systems. This is command-line based. I've tested it on Apple's OS X and it is likely to work on Linux. On Windows I have no idea, but Windows supports XCTU which in the vendor supported solution. On the other hand, since as of this date XCTU does not seem to support either Windows Vista or Windows 7, this might be useful even there. If you try this on Windows, let me know what happens. This software does not support re-flashing the firmware, so to switch from Zigbee to ZNet you still need to use XCTU from Digi.

My Python program called "xbee-gdxctu.py" is available for download. Version 2.10 was put in place Feb. 2011, but it might have been updated since (e.g. it was update to v2.1 on Dec 1 2012). This link provides the current version ID.

Note that my program requires the pyserial module that you might also need to download.

This software is is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.Creative Commons License

If you find problems of have suggestions, please let me know. An example session is given below.

Here is an example of what you get when you run the code. By default, it prints some of the key XBee parameters, and then lets you do manual queries. I have also added some comments on the "ND Discover all other nodes" command output (where it detected another node that I had activated).

python xbee-gdxctu.py
Here is an example of what you get when you run the code. By default, it prints some of the key XBee parameters, and then lets you do manual queries. I have also added some comments on the "ND Discover all other nodes" command output (where it detected another node that I had activated).

python xbee-gdxctu.py

xbee-gdxctu XBee configuration tool. 2.1 Copyright Gregory Dudek (c) 2009.
xbee-gdxctu.py using /dev/tty.usbserial-A5002WY6
Try 19200 got: 'OK'
Firmware: 1047
Non-Beacon Enabled 802.15.4 Code
>> %V Vcc Voltage (multiply by 0.001173; thus 0x8FE means 2.70v)
%V AE8 equal to 3.275016 V
>> BD baud code (2:4800, 3:9600, 4:19200, 5:38400, 6:57600 )
BD 4 => 19200 baud
>> CH Addressing: The channel of the module
CH 17
>> DB Received Signal Strength [in dB] of last good packet (see RC)
DB 41
>> DH Addressing: destination address for wireless communication (hi word)
DH 0
>> DL Addressing: destination address for wireless communication (lo word)
>> ID Addressing: The network ID (default 0x1234)
ID 1234
>> MY 16-bit address of the spefic module
MY 0
>> ND Discover all other nodes (takes NT*100 ms). MY/SH/SL/DB/NI

[Article posted 2009/11/24, revisions: July 14 2010, Feb 26,2011,Dec. 1,2012 ]

By Gregory Dudek at | Read (7) or Leave a comment |    
Re: Xbee Znet and gps

I've just ordered some XBee modules and I am in early stage of research on them. Thank you for your detailed information about firmware variants of these modules. I'm sure they'll help me a lot.

[ You are welcome, I'm glad it was useful. -gd ]

Posted by: Mani at November 24,2009 13:30
Re: Xbee Znet and gps

I am trying to work with the XBees on a mac. Found this python program. It calls for importing the modules: serial,os,sys,time and re.

Where can I find these?
Thank you.

[ Perhaps only "serial" is missing since the rest of the libraries are very standard. See http://pyserial.sourceforge.net/
The rest of the modules are commonplace. They are all standard Python libraries. In many cases they should be installed with Python by default; I thought they are always installed on OS X by default. See: http://www.python.org for information about python, and see the downloads page for specific instructions.
You can also try macports for a more generic methods for installing all kinds of things on OS X. --gd ]

Posted by: hve at December 12,2009 23:25
Re: Xbee Znet and gps

Aha- after battling with trying to 'upgrade' my ZNets to ZBs for a couple of hours, and getting little to no communication at all, I stumbled upon your post. I 'downgraded' one of the ZBs to ZNet instead and instantly I had communication back. What's up with the ZBs?

[ As you saw in my post, I was not happy with the ZB software either. I am glad this was of some assistance. -Greg ]

Posted by: anonymous at March 17,2010 21:45
Re: Xbee Znet and gps

Nice article on XBee devices http://t413.com/news/fast-2-way-xbee-series-2-data

Posted by: anonymous at June 17,2010 19:59

I have been having trouble getting xctu to recognize and write to my xbee chips. Thanks for writing such a useful program!

[ You're welcome! -gd ]

Posted by: Craig at September 30,2011 14:02
Re: Xbee Znet and gps

Great article. Have been programming off and on these XBee S2 chips for past few months and some aspects of it drive me nuts. Especially the inconsistencies with data transmission. Being optimistic (and realistic) I always suspected that it was programmer error (i.e. I didnt know enough). This article very helpful. Thanks for sharing and thank you for sharing the python code.....it was on my to-do list !

Posted by: anonymous at July 26,2012 03:17
Re: Xbee Znet and gps


I got an error:

Try 9600 baud
Traceback (most recent call last):
File "./xbee-gdxctu.py", line 441, in
s = ser.readline(eol='\r')
TypeError: readline() takes no keyword arguments

What's all that about? It should work!

[ Thanks for pointing this out. The code had been
updated as described in the text below (as well as some other small

It seems this is due to a change in python 2.6 and onwards.
As a short term fix:
1) If your version of readline does not take an end-of-line argument,
you might try simply deleting that argument so that the line reads:
s = ser.readline()
which will work for many people I think.
2) A cleaner solution which I have inserted is as follows:
a) up top, add
import io
b) below, after ser is opened, add
ser = io.TextIOWrapper(io.BufferedRWPair(ser, ser))

More details at http://pyserial.sourceforge.net/shortintro.html

-gd ]

Posted by: anonymous at November 30,2012 08:11
Please send trackback to:/blog/180/tbping
בלו ביי - קונים מוכרים - מכירות פומביות, מכירות רגילות, לוחות ובארטרים

[...] This post was mentioned on Twitter by Michael Vallez, iznix. iznix said: Crazy Mikes Apps– iPhone Video App Review iWatch USA[...]

Posted by: בלו ביי - קונים מוכרים - מכירות פומביות, מכירות רגילות, לוחות ובארטרים at December 26,2009 14:05
Post your own response

Each comment is manually screened for the presence of appropriate and substantive content, due to a constant onslaught of comment-spam. This means there may be a delay before your comment appears.

(Some kind of name is required, will be visible)

Required, whatever you enter will be visible to other users.

(Optional, used for "mailto" link)

Your email address is not required, but if you insert it it will be displayed so people can contact you.

Answer this question correctly to demonstrate that you are not a dumb spambot.

The title for your comment.

Your comment goes here. All relevant comments are welcome, except for those that simply promote an irrelevant product or else are used to fraudulently inflate the link count to an irrelevant web page. They appear after moderation. Don't forget to also fill in the captcha below or your text will be rejected automatically!

You must answer this question to prove you are human
What kind of restaurant has waiters, napkins, and pizza (enter a number): 1:Seafood, 2:Drive-through, 3:Pizzeria, 4:Reform school, 5:Roadside hot-dog stand?

Answer this question correctly to demonstrate that you are not a dumb spambot.