stën

Programmable XBee in Linux/MacOS/*BSD

Sten Feldman -

Intro

Digi is quite famous for its confusing portfolio of XBee radios that over the years have been featured in numerous DIY projects and are available from many hobby shops. There are literally tons of guides out there to get you started. They usually start by configuring the radios so that the channel works for communication. Continuing from there, the tutorials cover how to hook up an Arduino/Raspberry/[Name-your-board] so that they can "talk" to each other for whatever practical application you may have in mind. There is also an excellent book about Building Wireless Sensor Networks which covers XBee radios in detail as well as Building Wireless Sensor Networks Using Arduino for more specialized usage and scenarios.

This is all great! But what if I told you, you can add logic to certain XBee modules without having any additional boards attached to it. This may or may not be news, but Digi also has a programmable variant of its radio modules, in which they have included an 8-bit HCS08 microcontroller (MC9S08QE32) directly on the XBee module.

From pricing point of view, there's very little difference between the two. For an example:

Model SKU Programmable Price
XBee-PRO ZigBee Through-Hole (Wire Antenna) XBP24CZ7WIT-004 No! 25.83€+VAT
Programmable XBee-PRO ZigBee Through-Hole (Wire Antenna) XBP24CZ7WITB003 Yes! 27.99€+VAT

This looks really really good and competitive, and one might start to wonder why aren't they covered in more detail, until you start looking into what you'd need to develop on it:

  • You'd need a DEV-Kit (XK2-Z7SBE0)! Digi sells one with some SMT version of the modules, interface board and a debugger for 400+€! What if I just need one for blinking some LEDs?
  • Although the excellent configuration tooling called XCTU is a multiplatform offering, the development tools are strictly Windows bound!
  • SDK Documentation and tutorials are all burried into the same Windows based SDK tooling, making accessibility difficult.

Based on this, it's easy to see why the Hobbyist crowd aren't much using these.

But what if I told you, you don't need the DEV-Kit and that you can develop/flash the module at the comfort of your Linux/MacOS/BSD machine!

Development flow and tooling

Time for some warning! Do keep in mind that this solution makes it more challenging to debug your application. Also, it relies on the bootloader to work properly. The bootloader code is designed to protect its memory space not to overwrite itself but I guess it's still possible to end up with a non-functional XBee module. Consider yourself warned!

If you have familiarized yourself with the basic XBee modules, here's what you need with the Programmable variant:

  • An USB XBee Explorer or equivalent with a working Reset button. The Reset button is used frequently to access the module's bootloader for Bypassing the onboard MCU or for flashing application firmware.
  • pxbee-fwup.js - for flashing the built binary.
  • Unless you are on Linux, Docker is required for building the project as the compiler and burner are 32-bit Linux binaries.
  • A Programmable XBee module (duh!)

Building hello world

Start with a boilerplate hello-world project for blinking a LED on your new shiny Programmable S2B or S2C Xbee module. For that check-out the pxbee-blink-led project.

git clone https://github.com/exsilium/pxbee-blink-led.git
cd pxbee-blink-led

If you are using a S2C version of Programmable module, edit the include/xbee_config.h file and change #define CONFIG_XBEE_S2B to #define CONFIG_XBEE_S2CTH. Then build the project:

make all

For nuances about compiling on non 32-bit Linux, please see the above linked Github page but if you have Docker installed the following should work:

make builddocker
make dall

This will produce an HCS08 binary (./obj/blink_led.abs.bin) that you can upload to the XBee module. The application offers very little in functionality - it just turns on/off pin 7 in 125ms intervals. The same pin is by default used for RX signal strength indicator so if your XBee shield has a LED connected to it, you will see a rapidly blinking LED when the application will boot up.

Flashing

The factory shipped modules are all flashed with a bootloader and they do support firmware update over the serial interface. As long as the bootloader works, it's quite safe to upload a new application binary to the module.

For that, we need the help of pxbee-fwup.js project:

git clone https://github.com/exsilium/pxbee-fwup.js.git
cd pxbee-fwup.js
npm install
./fwup.js --help

To flash the binary:

./fwup.js -d /dev/your-serial-port -b 9600 -F ./obj/blink_led.abs.bin

Conclusions

For the DIY crowd on a Linux machine, there is now tooling in place that gives a good opportunity to explore Programmable XBee radios without big investments. Futher more, this will enable you to save power and reduce the footprint of your projects as there is no need for a separate microcontroller board.

Have fun! 🍻😎