Skip to content

ndarilek/rb-gps

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

GPS Library for Ruby

This library provides a Ruby interface to GPS receivers. Features include:

  • Support for multiple receivers. Receiver connects to a GPS and obtains all data in a Fix.

  • GPSD Receiver for obtaining data from units supported by GPSD.

  • Event callbacks for position, speed and course change.

  • Plugin architecture. Distribute new Receiver implementations as gems.

This library is part of the [Hermes](hermes-gps.info/) project.

Installation

Simply install via gems with the command:

gem install gps

Or run the included setup.rb like so:

ruby setup.rb config ruby setup.rb install

Example usage

For a working example, see the [included web service sample](examples/gps_service.rb).

There are a few simple steps to using this library, but before doing any of them you must first:

require “gps”

Create the Receiver

A Receiver is created by calling Gps::Receiver.create with an implementation and hash of options. If no implementation is given, the first found implementation is used. In a stock installation without any additional plugins, the following calls are equivalent:

gps = Gps::Receiver.create gps = Gps::Receiver.create(“gpsd”) gps = Gps::Receiver.create(:host => “localhost”, :port => 2947) gps = Gps::Receiver.create(“gpsd”, :host => “localhost”)

The GPSD Receiver supports both :host and :port options which point to a host on which a GPSD instance is running. Receiver options are not standard.

Start the Receiver

The Receiver is now created, but is not yet polling the hardware. To start this process, run:

gps.start

Verify that this has succeeded by running:

gps.started?

Assuming this succeeded, you can now access gps.latitude, gps.longitude, _gps.altitude, gps.course, gps.speed and other variables exposed via Fix.

Callbacks

You can also register callbacks which are triggered on various GPS events like so:

gps.on_position_change { puts “Latitude = #{gps.latitude}, longitude = #{gps.longitude}” } gps.on_course_change { puts “Course = #{gps.course}” } gps.on_speed_change { puts “Speed = #{gps.speed}” }

+Receiver#on_position_change+ supports an additional threshold. Because of GPS drift, positions change often. As such, it is possible to specify a threshold like so:

gps.on_position_change(0.0002) { puts “Latitude = #{gps.latitude}, longitude = #{gps.longitude}” }

The callback will not trigger on position changes of less than 0.0002 degrees since it was last called.

Cleaning up

To close devices or connections and no longer receive GPS updates, call the following method:

gps.stop

Hacking

The GPSD Receiver should be sufficient for most needs. If, however, you wish to parse NMEA data directly, interface with raw serial ports or interact with your GPS hardware on a lower level, a new Receiver implementation is necessary. This section is a quick overview to writing Receiver implementations.

When overriding the below methods, super should be the last method called. Also, as polling happens in a separate thread, Receiver code should be thread-safe.

Use Gps::Receivers

The library looks up Receiver implementations in the Gps::Receivers module. Therefore, all implementations must be defined there.

Override +Receiver#start+

This method should open the device, initiate a connection, etc.

Override +Receiver#stop+, if Necessary

The default stop method simply kills the thread and sets it to nil. If this is sufficient, overriding is unnecessary.

Override +Receiver#update+

This method should read an update from the device, setting the variables exposed by Fix.

Make it a Plugin

If the gem_plugin library is installed, new Receivers distributed as gems can be integrated automatically with a few simple steps.

  1. Distribute your Receiver as a gem that depends on both the gps and gem_plugin gems.

  2. Add the following code to your plugin:

GemPlugin::Manager.instance.create(“/receivers/your_receiver_name”, :optional_option => :value)

About

Ruby interface to GPS hardware

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages