jgillick-ruby-serialgps

= Ruby GPSSerial This library provides an easy way to get GPS data from your serial GPS unit.

== Description Uses ruby-serialport to connect to a standard serial GPS unit and parses the NMEA sentences into an easy to use hash.

=== NMEA Sentences Currently it only parses the following NMEA sentences:

• $GPGGA
• $GPRMC
• $GPGLL
• $GPRMA
• $GPGSA
• $GPGSV
• $GPHDT
• $GPZDA

=== GPS Data Hash Calling read or get_data will return a hash with some or all of the keys listed below. Each time you call one of those methods, more NMEA sentences will be parsed and added to the hash. You may have to call read multiple times in a loop until your data is available.

get_data is a wrapper function that will call read in a loop until at least the $GPGGA and $GPRMC sentences are read.

last_nmea:: The last NMEA sentence name (without "$GP") parsed with the read method. quality:: 0 = invalid, 1 = GPS fix, 2 = DGPS fix validity:: A = ok, V = invalid latitude:: Latitude lat_ref:: North/South (N/S) longitude:: Longitude long_ref:: East/West (E/W) altitude:: Current altitude alt_unit:: Altitude height unit of measure (i.e. M = Meters) speed:: Speed over ground in knots heading:: Heading, in degrees course:: Course over ground in degrees time:: Current time formated as HHMMSS.SS -- use date_time to get the parsed version date:: Current date formated as DDMMYY -- use date_time to get the parsed version local_hour_offset:: Local zone description, 00 to +/- 13 hours local_minute_offset:: Local zone minutes description (same sign as hours) num_sat:: The number of satellites in view satellites:: An array with id, elevation, azimuth and SNR for each satellite height_geoid:: Height of geoid above WGS84 ellipsoid height_geoid_unit:: Unit of measure (i.e. M = Meters) last_dgps:: Time since last DGPS update dgps:: DGPS reference station id mode:: M = Manual (forced to operate in 2D or 3D) A = Automatic (3D/2D) mode_dimension:: 1 = Fix not available, 2 = 2D, 3 = 3D hdop:: Horizontal Dilution of Precision pdop:: Positional Dilution of Precision vdop:: Vertical Dilution of Precision msg_count:: Total number of messages of this type in this cycle msg_num:: Message number variation:: Magnetic variation var_direction:: Magnetic variation direction (i.e E = East)

== Date and Time GPS modules provide the current time and date (UTC) strings in the following format:

Time: HHMMSS.SS

Date: DDMMYY

Instead of parsing these yourself, the date_time method will convert these strings into a DateTime object with the timezone set to UTC. require "serialgps"

gps = SerialGPS.new("/dev/ttyUSB0")

...

puts gps.date_time

== Install

=== Remotely You need RubyGems 1.2.0 to install it remotely from the GitHub repository.

gem sources -a http://gems.github.com gem install jgillick-ruby-serialgps

=== Locally After downloading ruby-serialgps.gem

gem install ruby-serialgps.gem

== Examples Here's a simple example of

=== Simple GPS dump This uses the internal live_gps_dump method to show live GPS data in the console

require "serialgps"

device = "/dev/ttyUSB0" gps = SerialGPS.new(device) gps.live_gps_dump

=== Print Latitude and Longitude A program that prints latitude and longitude data to the console as soon as it's available.

require "serialgps"

device = "/dev/ttyUSB0" gps = SerialGPS.new(device)

puts "Your current position:" while true data = gps.read if data.key?(:latitude) puts "Latitude: #{data[:latitude]}#{data[:lat_ref]}\t" puts "Longitude: #{data[:longitude]}#{data[:long_ref]}\n" end end