Home > Support > Knowledge Base > Knowledge Base Article

Programming Xbee modules in Linux using Ruby::XBee


Ruby::XBee (open source) allows you to configure and access Digi XBee RF devices using ruby classes and ruby-based command line utilities.


Not all XBee Series 1 features are supported, though many are.

No provision is made to flash new device firmware into the XBee from Ruby::XBee classes or utilities.

Intel architecture only.

Quick Start

Install ruby 1.8.7 for your platform (see www.ruby-lang.org)

Download the ruby-xbee tarball http://www.esawdust.com/ruby-xbee/releases/ruby-xbee-1.0/ruby-xbee-1.0.tar.gz. Extract the bundle into its permanent directory:

tar xvfz ruby-xbee-.tar.gz

Create a symbolic link for serial-port-0.6:

ln -s ruby-serial-port-0.6-linux-intel ruby-serialport-0.6

determine your /dev string and add it to the conf/xbeeconfig.rb file.

Once the XBIB-U-DEV USB device is plugged into the USB port on the Linux host, the in-kernelftdi driver should automatically load and create the associated device. It is usually /dev/ttyUSB0 for the first USB host port, with additional ports incrementing (i.e. /dev/ttyUSB1, /dev/ttyUSB2). The first host serial port is typically labeled /dev/ttyS0, with additional ports incrementing (i.e. /dev/ttyS1, /dev/ttyS2, etc...).

Sample entry for the USB XBIB-U-DEV device:

# this is the monitor port device # your device will be different than this #@xbee_usbdev_str = "/dev/tty.KeySerial1" @xbee_usbdev_str = "/dev/ttyUSB0"


Sample entry for the Serial XBIB-R-DEV:


# this is the monitor port device
# your device will be different than this

#@xbee_usbdev_str = "/dev/tty.KeySerial1"

@xbee_usbdev_str = "/dev/ttyS0"



Test communication:





If everything is configured correctly you will see output from xbeeinfo similar to this (your output will vary):




$ ./xbeeinfo.rb Attention: OK Firmware: 10CD Hardware: 180B Baud: 9600 Parity: None Neighbors: [{:NI="BMW528", :MY="2", :SH="13A200", :SL="4008A642", :DB=-36}] Node ID: BaseStation Channel: C PAN ID: 1 MY: 1 SH: 13A200 SL: 4008A64E DH: 0 DL: 2 Last received signal strength (dBm): -36 Port 0: Disabled Port 1: DI Port 2: Disabled Port 3: Disabled Port 4: Disabled Port 5: Associated_Indicator Port 6: Disabled Port 7: CTS Port 8: Disabled





Configuring an XBee using Ruby and the Ruby::XBee class

Syntax ./xbeeconfigure.rb [options]


Command line help




./xbeeconfigure.rb --help xbeeconfigure.rb [options] Options: [--panid new_pan_id] [-p new_pan_id] sets the XBee PAN ID [--channel new_channel] [-c new_channel] sets the new channel number for XBee RF [--mysrc new_address] [-M new_address] sets MY 16-bit source address (0-0xffff) [--nodeid new_node_id] [-n new_node_id] sets the text for the XBee node ID [--desthigh highaaddress] [-H highaddress] sets the high portion of the destination address [--destlow low_address] [-L low_address] sets the low portion of the destination address [--parity [NEOMS]] [-P [NEOMS]] sets new parity, N = 8bit no-parity, E = 8bit even, O = 8bit odd, M = 8bit mark, S = 8bit space [--newbaud baud_rate] [-B baud_rate] sets a new baud rate in XBee to take effect after configuration is complete [--dev device] [-d device] use this device to talk to XBee (ie: /dev/tty.usb-791jdas) [--baud baud_rate] [-b baud_rate] use this baud rate for configuring the device [--save] [-s] write new configuration to XBee flash when finished; default is: configuration is not flashed [--help] print this command help message





Example usage:


./xbeeconfigure.rb --nodeid BaseStation --panid 01 --mysrc 01 -H0 -L 2 -s








The command above configures an XBee with a human readable node ID of BaseStation, a PAN ID of 1, sets the devices MY 16-bit source address to 1, sets the destination to point to an XBee in a 16-bit addressing mode with a low address of 2 (-L 2) and a high of 0 which determines this is a 16-bit address.) Finally, the -s causes the new configuration to be saved in XBee flash when the configuration is completed. The BaseStation node id is reported as one of the attributes from neighboring nodes.

Since there are both long and short versions of the same options, an equivalent, shorter command line is:



./xbeeconfigure.rb -n BaseStation -M 01 -M 01 -H0 -L 2 -s







Learn More:

You can learn more about Ruby::XBee and other projects at: http://www.esawdust.com/blog/EaglePCB/ruby-xbee_files/ruby-xbee-release1.html

Contact a Digi expert and get started today! CONTACT US

Desktop Site