ruby-xbee

Coverage Status Dependency Status

Ruby::XBee - What is it?

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

Current host platforms supported:

What is an XBee?

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/

Why use Ruby::XBee?

Ruby::XBee Documentation

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

Quick Start

  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

Detailed Quick Start

clone the ruby-xbee repository.

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

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

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.

Build and install the RubyGem

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

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

Try xbeeinfo.rb

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

Troubleshooting

XBee won’t respond:

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

Google is your friend.

Limitations

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

See Also

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

Contact and Contribute

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

Synopsis

Ruby::XBee - Configure and access XBee using Ruby

Current host platforms supported:

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

Release Notes

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

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

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.

Bugs

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.

Feature Requests

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.

Generating Ruby::XBee RDoc

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

Accessing/Obtaining earlier versions of Ruby::XBee

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.