gps 0.0.1

data/Manifest.txt

@@ -0,0 +1,24 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/gps.rb
+lib/gps/fix.rb
+lib/gps/receiver.rb
+lib/gps/receivers/gpsd.rb
+lib/gps/version.rb
+script/destroy
+script/generate
+setup.rb
+spec/fix_spec.rb
+spec/gpsd_spec.rb
+spec/receiver_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake

data/README.txt

@@ -0,0 +1,97 @@
+= 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.
+
+== 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
+
+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)

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,67 @@
+require 'gps/version'
+
+AUTHOR = "Nolan Darilek"  # can also be an array of Authors
+EMAIL = "nolan@thewordnerd.info"
+DESCRIPTION = "An interface to GPS receivers"
+GEM_NAME = "gps"
+RUBYFORGE_PROJECT = "hermes" # The unix name for your project
+HOMEPATH = "http://hermes-gps.info/"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+REV = ENV["SNAPSHOT"]? ".#{`bzr revno`.chomp}": ""
+VERS = Gps::VERSION::STRING+REV
+
+RDOC_OPTS = ['--quiet', '--title', 'gps documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = "This library provides an elegant interface to data from GPS receivers. An extensible architecture simplifies adding new receiver types, with a GPSD receiver already written. Additionally, the API supports registering callbacks triggered on change of position, course, altitude and visible satellites."
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\\n\\n")
+  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'gps'

data/lib/gps.rb

@@ -0,0 +1,21 @@
+$:.unshift File.dirname(__FILE__)
+
+module Gps
+end
+
+begin
+	require "rubygems"
+rescue LoadError
+end
+
+if Object.const_defined?("Gem")
+	begin
+		require "gem_plugin"
+	rescue LoadError
+	end
+end
+require "gps/fix"
+require "gps/receiver"
+require "gps/receivers/gpsd"
+
+GemPlugin::Manager.instance.load "gps" => GemPlugin::INCLUDE if Object.const_defined?("GemPlugin")

data/lib/gps/fix.rb

@@ -0,0 +1,13 @@
+# Module representing all data in a GPS fix.
+module Gps::Fix
+	attr_reader :last_tag, :timestamp, :timestamp_error_estimate, :latitude, :longitude, :altitude, :horizontal_error_estimate, :vertical_error_estimate, :course, :speed, :climb, :course_error_estimate, :speed_error_estimate, :climb_error_estimate, :satellites
+
+	def initialize(*args)
+		@altitude = 0
+		@latitude = 0
+		@longitude = 0
+		@speed = 0
+		@course = 0
+		@satellites = 0
+	end
+end

data/lib/gps/receiver.rb

@@ -0,0 +1,112 @@
+# Represents a provider of GPS fixes and a dispatcher of event callbacks for applications needing 
+# such fixes.
+module Gps
+	class Receiver
+		include Fix
+
+		def initialize(options = {})
+			super
+			@last_latitude = @last_longitude = 0
+			@position_change_threshold = 0
+			@last_speed = 0
+			@last_course = 0
+			@last_altitude = 0
+			@last_satellites = 0
+		end
+
+		# Factory for creating a +Receiver+.
+		# Accepts an implementation and a hash of options, both optional. If no 
+		# implementation is provided, the first is used by default. Implementations are in 
+		# the module +Gps::Receivers+.
+		def self.create(arg = nil, args = {})
+			implementation = arg.respond_to?(:capitalize)? Receivers.const_get(arg.capitalize): Receivers.const_get(Receivers.constants[0])
+			options = arg.kind_of?(Hash)? arg: args
+			implementation.new(options)
+		end
+
+		# Sets the position from an array of the form [latitude, longitude], calling the 
+		# _on_position_change_ callback if necessary.
+		def position=(value)
+			@latitude = value[0]
+			@longitude = value[1]
+			call_position_change_if_necessary
+		end
+
+		# Called on position change, but only if the change is greater than +threshold+ degrees.
+		# The block receives the amount of change in degrees.
+		def on_position_change(threshold = 0, &block)
+			@position_change_threshold = threshold
+			@on_position_change = block
+		end
+
+		# Called on speed change.
+		def on_speed_change(&block)
+			@on_speed_change = block
+		end
+
+		# Called on course change.
+		def on_course_change(&block)
+			@on_course_change = block
+		end
+
+		# Called when the altitude changes.
+		def on_altitude_change(&block)
+			@on_altitude_change = block
+		end
+
+		# Called when the number of visible satellites changes.
+		def on_satellites_change(&block)
+			@on_satellites_change = block
+		end
+
+		# Override this in children. Opens the connection, device, etc.
+		def start
+			@thread = Thread.new do
+				while true
+					update
+				end
+			end
+		end
+
+		# Override this in children. Closes the device, connection, etc. and stops updating.
+		def stop
+			@thread.kill if @thread
+			@thread = nil
+		end
+
+		# Returns _true_ if started, _false_ otherwise.
+		def started?
+			!@thread.nil? && @thread.alive?
+		end
+
+		# Override this in children, setting fix variables from the GPS receiver.
+		# Here we dispatch to callbacks if necessary.
+		def update
+			call_position_change_if_necessary
+			@on_speed_change.call if @on_speed_change and @speed != @last_speed
+			@last_speed = @speed
+			@on_course_change.call if @on_course_change and @course != @last_course
+			@last_course = @course
+			@on_altitude_change.call if @on_altitude_change and @altitude != @last_altitude
+			@last_altitude = @altitude
+			@on_satellites_change.call if @on_satellites_change and @satellites != @last_satellites
+			@last_satellites = @satellites
+		end
+
+		private
+		def call_position_change_if_necessary
+			if position_change > @position_change_threshold
+				@on_position_change.call(position_change) if @on_position_change
+				@last_latitude = @latitude
+				@last_longitude = @longitude
+			end
+		end
+
+		def position_change
+			(@latitude-@last_latitude).abs+(@longitude-@last_longitude).abs
+		end
+	end
+
+	module Receivers
+	end
+end

data/lib/gps/receivers/gpsd.rb

@@ -0,0 +1,69 @@
+require "socket"
+
+# Represents a +Receiver+ that obtains information from GPSD.
+module Gps::Receivers
+	class Gpsd < Gps::Receiver
+		attr_reader :host, :port
+
+		# Accepts an options +Hash+ consisting of the following:
+		# * _:host_: The host to which to connect
+		# * _:port_: The port to which to connect
+		def initialize(options = {})
+			super
+			@host ||= options[:host] ||= "localhost"
+			@port = options[:port] ||= 2947
+		end
+
+		def start
+			@socket = TCPSocket.new(@host, @port)
+			@socket.puts("w+")
+			super
+		end
+
+		def update
+			line = @socket.gets.chomp.split(",")[1]
+			return if !line
+			types = []
+			data = []
+			line.split(",").each do |sentence|
+				sentence.split("=").each_with_index  do |d, i|
+					if i%2 == 0
+						types << d
+					else
+						data << d
+					end
+				end
+			end
+			types.each_with_index do |type, i|
+				begin
+					send("parse_#{type.downcase}", data[i])
+				rescue NoMethodError
+				end
+			end
+			super
+		end
+
+		private
+		def parse_o(data)
+			params = data.split
+			@last_tag = params[0]
+			@timestamp = params[1].to_f
+			@timestamp_error_estimate = params[2].to_f
+			@latitude = params[3].to_f
+			@longitude = params[4].to_f
+			@altitude = params[5].to_f
+			@horizontal_error_estimate = params[6].to_f
+			@vertical_error_estimate = params[7].to_f
+			@course = params[8].to_f
+			@speed = params[9].to_f
+			@climb = params[10].to_f
+			@course_error_estimate = params[11].to_f
+			@speed_error_estimate = params[12].to_f
+			@climb_error_estimate = params[13].to_f
+		end
+
+		def parse_y(data)
+			@satellites = data.split(":")[0].split[-1].to_i
+		end
+	end
+end

data/lib/gps/version.rb

@@ -0,0 +1,9 @@
+module Gps #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)