ruby-xbee¶ ↑

<img src=“https://travis-ci.org/exsilium/ruby-xbee.png” /> <img src=“https://coveralls.io/repos/exsilium/ruby-xbee/badge.png” alt=“Coverage Status” /> <img src=“https://gemnasium.com/exsilium/ruby-xbee.png” alt=“Dependency Status” /> <img src=“https://codeclimate.com/github/exsilium/ruby-xbee.png” />

Ruby::XBee lets you configure and access Digi XBee RF devices using ruby classes and ruby-based command line utilities.

Current host platforms supported:

• Linux (Intel)

• Mac OS X (PPC or Intel)

XBee devices are handy, low-cost RF data radios often used in embedded applications for communicating with microcontrollers and sensors. The distance an XBee covers ranges from a few hundred feet to 15 miles line of sight depending upon the XBee device type, frequency, antenna type, and power ratings.

Some XBees can be configured to support the ZigBee standard. Other XBees support various forms of proprietary mesh networking especially suited to scaling sensor networks.

To learn more about Digi’s XBee modules, see Digi’s web site at: www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/zigbee-mesh-module/

• Ruby::XBee is a convenient way to script the configuration of XBee especially if you have a lot of XBees to program.

• Ruby::XBee lends itself to building command line applications and deploying XBee networks.

• Ruby::XBee is a quick way to experiment with functionality of XBees.

• Ruby::XBee can alleviate the need to memorize lots of AT modem commands and their parameters.

• Since Digi has no configuration host support for Linux or OS X, if these are your native or preferred environments, Ruby::XBee may be for you.

• Ruby::XBee is open source and contributions are welcome.

See doc/index.html from the downloaded bundle for detailed documentation on Ruby XBee class and utilities. This documentation is primarily RDoc generated from the actual code, so it should be complete and accurate. If documentation mistakes are found, please report errors to landon att 360vl com.

Not all of the many XBee features are supported by Ruby::XBee, but many of the most common ones are. New features will be supported as this software evolves. Complete XBee feature coverage represents a main project goal and is a significant area of solicited contributions.

Example use of the core XBee ruby class can be found in the utilities themselves: xbeeinfo.rb, xbeeconfigure.rb, xbeedio.rb, xbeelisten.rb, xbeesend.rb

1. install ruby 1.9.3 or 2.0.0 for your platform (see www.ruby-lang.org)

2. download the ruby-xbee ( git clone github.com/exsilium/ruby-xbee )

3. install the dependencies ‘bundle install`

4. determine your /dev string and configure that in bin/ruby-xbee.rb

5. try ./bin/xbeeinfo.rb

git clone https://github.com/exsilium/ruby-xbee

When you plug in your XBee using an USB explorer board such as the Sparkfun XBee explorer:

www.sparkfun.com/products/8687

a new device will appear in the /dev directory of your Mac or Linux machine. As a hint, look for a device such as /dev/tty.usb* or /dev/ttyUSB*

If you use the Sparkfun XBee explorer board mentioned above as an example, you will see a device such as:

ls -l /dev/tty.usbserial*- 
crw-rw-rw-  1 root  wheel   10,  14 Jan  2 11:03 /dev/tty.usbserial-A80081sF

Each USB device has a unique tag so your device will not be named exactly the same as this example.

Once you determine the device name, edit the ruby-xbee/bin/ruby-xbee.rb file and modify the @xbee_usbdev_str to match your device. Example:

@xbee_usbdev_str = "/dev/tty.usbserial-A80081sF"

save the ruby-xbee.rb file.

If you are relying on rvm, please set the appropriate gemset prior

gem build ruby-xbee.gemspec
gem install ruby-xbee-<version>.gem

Once the RubyGem is properly installed you can try to call one of the distributed scripts.

Insure your XBee device is plugged into your host and the device is enumerated in /dev according to Step 2 above.

xbeeinfo.rb

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

cooper:ruby-xbee lcox$ ./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

XBee won’t respond:

• Refer to: www.faludi.com/projects/common-xbee-mistakes/

• Insure your XBee has the latest firmware flashed into the device (use Digi X-CTU)

• Insure your device’s USB driver is enumerated in the /dev directory when you plug in USB

• Insure your XBee device and Ruby::XBee baud rate configuration is identical

• Digi’s XBee development boards do not have USB drivers for OS X or Linux. I recommend using SparkFun USB XBee Explorer board: www.sparkfun.com/products/8687 This board supports drivers that are compatible with OS X and Linux operating systems. This board can be used with Digi’s X-CTU windows configuration utility as well, so it’s a great board to have if you’re working with XBee on various platforms.

• Insure your full device path is configured in conf/xbeeconfig.rb

• Insure you can “talk” to your device with Digi X-CTU on Windows

  • make sure the device itself can be contacted before trying again with Ruby::XBee

• Try the Linux or OS X ‘screen’ command to contact the device:

  screen /dev/tty.usbserial-A80081sF 9600

  where you would replace the /dev/ string in the example above with the one for your USB XBee device. When you plug in a USB serial device, Linux and OS X will enumerate that device automatically by adding a new entry into the /dev directory.

• When you make contact with the device using ‘screen’, issue a +++ and wait for a second or two for an OK response

• Contact Digi. See: www.digi.com/support/productdetail?pid=3257 (S1) or www.digi.com/support/productdetail?pid=3430 (S2)

Other than these suggestions, sorry, I have no time to support connectivity problems to the XBee itself.

Google is your friend.

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

• New efforts are mostly aimed towards supporting Series 2. Efforts are made not to break Series 1

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

Reflashing firmware requires using Digi’s X-CTU windows program. Code contributions in this area are welcome.

There are several other utilties included with Ruby::XBee. See also:

• xbeedio.rb - A Ruby utility for configuring and manipulating XBee DIO ports

• xbeeinfo.rb - A Ruby utility for extracting XBee setup information using xbee ruby class (Ruby::XBee)

• xbeelisten.rb - A ruby utility for listening to data output from an XBee

• xbeesend.rb - A ruby utility for sending raw data to and through an XBee

Please feel to Fork the repository and create pull requests back.

Ruby::XBee - Configure and access XBee using Ruby

Current host platforms supported:

Linux (Intel)
Mac OS X (PPC or Intel)

2014-03-09 Ruby::XBee Version 1.1 - Requirements: Ruby 1.9.3; serialport 1.1.0

2009-01-02 Ruby::XBee Version 1.0 - Requirements: Ruby 1.8.7; ruby-serialport

• Prerequisites - SerialPort

A platform-specific version of the SerialPort is a prerequisite for Ruby::XBee. Please refer to Rubygems ( rubygems.org/gems/serialport ) for package information.

• Prerequisites - Ruby 1.9.3

To date, all testing has been done using Ruby 1.9.3 (p194) & 2.0.0. There has been extensive changes introduced to Ruby after 1.8.x branch and backwards compatibility is not esnured. Please refer to earlier versions of this software.

I’m sure there are bugs. Please test and submit a detailed report to github issues. Better yet, please submit a patch for a fix. Thanks.

Original author can be reached by checking www.esawdust.com/blog/ for updates and sending feature requests to landon att 360vl com

Current maintainer can be reached by sending e-mail to exile att chamber ee or filing a issue via github.

Ruby::XBee uses RDoc and the Hanna template. To generate documentation yourself, you need to do a one-time install of the hanna template and dependencies:

sudo gem install hanna-nouveau

Then from within the ruby-xbee install directory run:

rdoc -f hanna

Original version of Ruby::XBee can be downloaded: www.esawdust.com/ruby-xbee/releases/ruby-xbee-1.0/ruby-xbee-1.0.tar.gz (2013-02-25 MD5 checksum MD5 (ruby-xbee-1.0.tar.gz) = 5f01b6af4cfc8719b601f354c627b6e8)

Mike Ashmore’s version can be obtained via GitHub: github.com/motomike/ruby-xbee

Copyright © 2008-2009 360VL, Inc. and Landon Cox Copyright © 2009 Mike Ashmore Copyright © 2013-2014 Sten Feldman

See LICENSE for details.