nmea_plus 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dd8de99b8dfe9e24e6177dd8da3ded4bb1ee4ec8
-  data.tar.gz: 3908a6334549db1c32e5e5a778d072bed59705f3
+  metadata.gz: 14b78eb70f5197e702eda48e3b297cfa9e6aed78
+  data.tar.gz: cc2f08b71f5841d8436f2e53baca38745aa67169
 SHA512:
-  metadata.gz: d99daa0ad0e7157a3325a5dd7f4f8e60a7588b28f83605b1f8b44649cbb69a541f9a781e54f8a85122ad6da1a0a66454ac561b1fc2f9165565646f753b65bb96
-  data.tar.gz: 54e1b1b32580ff94b291bde5249b2302301d244da2d770501d69cd9ab63439f8281c879ee570ad045c96a35ae498dc0d3eb2ffea23d1dc5f3f7d47e5945e6305
+  metadata.gz: f2db86ca89249ba01692b2cd4251eede675e1550defbb0bb80b486fad391e6ed2b1dbcfe9ef08c20b9854d8454510ba429cdb1f56c318d99f62d6e19a41ca2e8
+  data.tar.gz: 33a427ee981915f75cfdbf3f4143ddc2d6349db562f03fb59884f5f7562660c3f59d5f2e781b03addd7f33c1768750aa42fcf6430b39543a8594f02d4e1f2cfe

data/README.md

@@ -0,0 +1,116 @@
+# NMEA Ruby Gem (nmea_plus)
+
+[![Gem Version](https://badge.fury.io/rb/nmea_plus.svg)](https://rubygems.org/gems/nmea_plus)
+[![Build Status](https://travis-ci.org/ifreecarve/nmea_plus.svg)](https://travis-ci.org/ifreecarve/nmea_plus)
+
+[NMEA Plus](https://github.com/ifreecarve/nmea_plus) is a Ruby gem for parsing and decoding "GPS" messages: NMEA, AIS, and any other similar formats of short messaging typically used by marine equipment.  It provides convenient access (by name) to the fields of each message type, and a stream reader designed for use with Ruby Blocks.
+
+
+## Install
+
+`gem install nmea_plus`
+
+## Example
+
+In its most basic use, you can decode messages as follows:
+
+```ruby
+require 'nmea_plus'
+
+decoder = NMEAPlus::Decoder.new
+message = decoder.parse("$GPGLL,4916.45,N,12311.12,W,225444,A*00")
+# message data -- specific to this message type
+puts message.latitude     # prints 49.27416666666666666666
+puts message.longitude    # prints -123.18533333333333333
+puts message.fix_time     # prints <today's date> 22:54:44 <your local time zone offset>
+puts message.valid?       # prints true
+puts message.faa_mode     # prints nil
+
+# metadata
+puts message.checksum_ok? # prints false -- because this checksum is made up
+puts message.original     # prints "$GPGLL,4916.45,N,12311.12,W,225444,A*00"
+puts message.data_type    # prints "GPGLL" -- what was specified in the message
+puts message.interpreted_data_type  # prints "GLL" -- the actual container used
+
+# metadata that applies to multipart messages (also works for single messages)
+puts message.all_messages_received? # prints true
+puts message.all_checksums_ok?      # prints false -- checksum is still made up
+
+# safer way to do what we did above
+if "GPGLL" == message.data_type     # Alternately, if "GLL" == message.interpreted_data_type
+  puts message.latitude     # prints 49.27416666666666666666
+  puts message.longitude    # prints -123.18533333333333333
+  puts message.fix_time     # prints <today's date> 22:54:44 <your local time zone offset>
+  puts message.valid?       # prints true
+  puts message.faa_mode     # prints nil
+end
+```
+
+
+Of course, decoding in practice is more complex than that.  Some messages can have multiple parts, and AIS messages have their own complicated payload.  NMEAPlus provides a SourceDecoder object that operates on IO objects (anything with `each_line` support) -- a File, SerialPort, etc.  You can iterate over each message (literally `each_message`), or receive only fully assembled multipart messages by iterating over `each_complete_message`.
+
+```ruby
+require 'nmea_plus'
+
+input1 = "!AIVDM,2,1,0,A,58wt8Ui`g??r21`7S=:22058<v05Htp000000015>8OA;0sk,0*7B"
+input2 = "!AIVDM,2,2,0,A,eQ8823mDm3kP00000000000,2*5D"
+io_source = StringIO.new("#{input1}\n#{input2}")  # source decoder works on any IO object
+
+source_decoder = NMEAPlus::SourceDecoder.new(io_source)
+source_decoder.each_complete_message do |message|
+  puts message_all_checksums_ok?                  # prints true -- the full message set has good checksums
+  puts message_all_messages_received?             # prints true -- taken care of by each_complete_message
+  if "AIVDM" == message.data_type
+    puts message.ais.message_type                   # prints 5
+    puts message.ais.repeat_indicator               # prints 0
+    puts message.ais.source_mmsi                    # prints 603916439
+    puts message.ais.ais_version                    # prints 0
+    puts message.ais.imo_number                     # prints 439303422
+    puts message.ais.callsign.strip                 # prints "ZA83R"
+    puts message.ais.name.strip                     # prints "ARCO AVON"
+    puts message.ais.ship_cargo_type                # prints 69
+    puts message.ais.ship_dimension_to_bow          # prints 113
+    puts message.ais.ship_dimension_to_stern        # prints 31
+    puts message.ais.ship_dimension_to_port         # prints 17
+    puts message.ais.ship_dimension_to_starboard    # prints 11
+    puts message.ais.epfd_type                      # prints 0
+    puts message.ais.eta                            # prints <this year>-03-23 19:45:00 <your local time zone offset>
+    puts message.ais.static_draught                 # prints 13.2
+    puts message.ais.destination.strip              # prints "HOUSTON"
+    puts message.ais.dte?                           # prints false
+  end
+end
+
+```
+
+## Design documents
+
+This gem was coded to accept the standard NMEA messages defined in the unoffical spec found here:
+http://www.catb.org/gpsd/NMEA.txt
+
+Because the message types are standard, if no override is found for a particular talker ID then the message will parse according to the command (the last 3 characters) of the data type.  In other words, $GPGLL will use the general GLL message type.  Currently, the following standard message types are supported:
+
+> AAM, ALM, APA, APB, BOD, BWC, BWR, BWW, DBK, DBS, DBT, DCN, DPT, DTM, FSI, GBS, GGA, GLC, GLL, GNS, GRS, GSA, GST, GSV, GTD, GXA, HDG, HDM, HDT, HFB, HSC, ITS, LCD, MSK, MSS, MTW, MWV, OLN, OSD, R00, RMA, RMB, RMC, ROT, RPM, RSA, RSD, RTE, SFI, STN, TDS, TFI, TPC, TPR, TPT, TRF, TTM, VBW, VDR, VHW, VLW, VPW, VTG, VWR, WCV, WNC, WPL, XDR, XTE, XTR, ZDA, ZFO, ZTG
+
+
+Additionally, AIS message type definitions were implemented from the unofficial spec found here:
+http://catb.org/gpsd/AIVDM.html
+
+> Currently AIVDM messages types 1, 2, 3, 5, and 8 are implemented.
+
+Support for proprietary messages is also possible.  PASHR is included as proof-of-concept.
+
+
+## Disclaimer
+
+This module was written from information scraped together on the web, not from testing on actual devices.  Please don't entrust your life or the safety of your ship to this code without doing your own rigorous testing.
+
+
+## Author
+
+This gem was written by Ian Katz (ifreecarve@gmail.com) in 2015.  It's released under the Apache 2.0 license.
+
+
+## See Also
+
+* [Contributing](CONTRIBUTING.md)

data/{gem/lib → lib}/nmea_plus.rb

@@ -3,11 +3,22 @@ require 'nmea_plus/version'
 require 'nmea_plus/generated_parser/parser'
 require 'nmea_plus/generated_parser/tokenizer'
 
+# NMEAPlus contains classes for parsing and decoding NMEA and AIS messages.
+# @author Ian Katz
 module NMEAPlus
+
+  # The NMEA source decoder wraps an IO object, converting each_line functionality
+  # to {#each_message} or {#each_complete_message}
   class SourceDecoder
+    # False by default.
+    # @return [bool] whether to throw an exception on lines that don't properly parse
     attr_accessor :throw_on_parse_fail
-    attr_accessor :throw_on_unrecognized_type  # typically for development
 
+    # False by default. Typically for development.
+    # @return [bool] whether to throw an exception on message types that aren't supported
+    attr_accessor :throw_on_unrecognized_type
+
+    # @param line_reader [IO] The source stream for messages
     def initialize(line_reader)
       unless line_reader.respond_to? :each_line
         fail ArgumentError, "line_reader must inherit from type IO (or implement each_line)"
@@ -17,7 +28,9 @@ module NMEAPlus
       @decoder = NMEAPlus::Decoder.new
     end
 
-    # return each parsed message
+    # Executes the block for every valid NMEA message in the source stream
+    # @yield [NMEAPlus::Message] A parsed message
+    # @return [void]
     def each_message
       @source.each_line do |line|
         if @throw_on_parse_fail
@@ -34,7 +47,10 @@ module NMEAPlus
       end
     end
 
-    # return messages grouped into multipart chains as required
+    # Executes the block for every valid NMEA message in the source stream, attempting to
+    # group multipart messages into message chains.
+    # @yield [NMEAPlus::Message] A parsed message that may contain subsequent parts
+    # @return [void]
     def each_complete_message
       partials = {}
       each_message do |msg|

data/lib/nmea_plus/ais_message_factory.rb

@@ -0,0 +1,23 @@
+
+require_relative 'message_factory'
+
+require_relative 'message/ais/vdm'
+
+module NMEAPlus
+
+  # Defines a factory for AIS messages, which will all use {NMEAPlus::Message::AIS::AISMessage} as their base
+  class AISMessageFactory < MessageFactory
+    # @return [String] The name of the parent module: AIS
+    def self.parent_module
+      "AIS"
+    end
+
+    # Match all AIS messages as their generic counterparts.  AIVDM becomes VDM, etc.
+    # @param data_type [String] The data_type of the AIS message (e.g. the AIVDM of "$AIVDM,12,3,,4,5*00")
+    # @return [String] The data_type that we will attempt to use in decoding the message (e.g. VDM)
+    def self.alternate_data_type(data_type)
+      # match last 3 digits (get rid of talker)
+      data_type[2..4]
+    end
+  end
+end

data/{gem/lib → lib}/nmea_plus/generated_parser/tokenizer.rb

@@ -6,7 +6,7 @@
 
 
 module NMEAPlus
-class Decoder < Parser  # not indented due to constraints of .rex format
+class Decoder < Parser  # This file is in .rex format, so no indenting.  And yard docs are impossible.
   require 'strscan'
 
   class ScanError < StandardError ; end

data/{gem/lib → lib}/nmea_plus/message/ais/vdm.rb

@@ -1,9 +1,5 @@
 require_relative "base_ais"
 
-require_relative "vdm_payload/vdm_msg1"
-require_relative "vdm_payload/vdm_msg5"
-require_relative "vdm_payload/vdm_msg8"
-
 =begin boilerplate for vdm payload objects
 require_relative 'vdm_msg'
 
@@ -21,6 +17,11 @@ end
 
 =end
 
+require_relative "vdm_payload/vdm_msg1"
+require_relative "vdm_payload/vdm_msg5"
+require_relative "vdm_payload/vdm_msg8"
+
+
 module NMEAPlus
   module Message
     module AIS

data/lib/nmea_plus/message/base.rb

@@ -0,0 +1,235 @@
+
+module NMEAPlus
+
+  # The module containing all parsed message types.
+  # @see NMEAPlus::Message::Base
+  module Message
+
+    # The base message type, from which all others inherit
+    # @abstract
+    class Base
+      # make our own shortcut syntax for message attribute accessors
+      # @param name [String] What the accessor will be called
+      # @param field_num [Integer] The index of the field in the payload
+      # @param formatter [Symbol] The symbol for the formatting function to apply to the field (optional)
+      # @!macro [attach] field_reader
+      #   @method $1
+      #   @return field $2 of the payload, formatted with the function {#$3}
+      def self.field_reader(name, field_num, formatter = nil)
+        if formatter.nil?
+          self.class_eval("def #{name};@fields[#{field_num}];end")
+        else
+          self.class_eval("def #{name};#{formatter}(@fields[#{field_num}]);end")
+        end
+      end
+
+      # @return [String] The single character prefix for this NMEA 0183 message type
+      attr_accessor :prefix
+
+      # @return [String] The unprocessed payload of the message
+      attr_reader :payload
+
+      # @return [Array<String>] The payload of the message, split into fields
+      attr_reader :fields
+
+      # @return [String] The two-character checksum of the message
+      attr_accessor :checksum
+
+      # @return [String] The data type used by the {MessageFactory} to parse this message
+      attr_accessor :interpreted_data_type
+
+      # @return [NMEAPlus::Message] The next part of a multipart message, if available
+      attr_accessor :next_part
+
+      field_reader :data_type, 0, nil
+
+      # @!parse attr_reader :original
+      # @return [String] The original message
+      def original
+        "#{prefix}#{payload}*#{checksum}"
+      end
+
+      # @!parse attr_accessor :payload
+      def payload=(val)
+        @payload = val
+        @fields = val.split(',', -1)
+      end
+
+      # @return [bool] Whether the checksum calculated from the payload matches the checksum given in the message
+      def checksum_ok?
+        calculated_checksum.upcase == checksum.upcase
+      end
+
+      # return [bool] Whether the checksums for all available message parts are OK
+      def all_checksums_ok?
+        return false unless checksum_ok?
+        return true if @next_part.nil?
+        @next_part.all_checksums_ok?
+      end
+
+      # return [String] The calculated checksum for this payload as a two-character string
+      def calculated_checksum
+        "%02x" % @payload.each_byte.map(&:ord).reduce(:^)
+      end
+
+      # @!parse attr_reader :total_messages
+      # @abstract
+      # @see #message_number
+      # @return [Integer] The number of parts to this message
+      def total_messages
+        1
+      end
+
+      # @!parse attr_reader :message_number
+      # @abstract
+      # @see #total_messages
+      # @return [Integer] The ordinal number of this message in its sequence
+      def message_number
+        1
+      end
+
+      # Create a linked list of messages by appending a new message to the end of the chain that starts
+      # with this message.  (O(n) implementation; message parts assumed to be < 10)
+      # @param msg [NMEAPlus::Message] The latest message in the chain
+      # @return [void]
+      def add_message_part(msg)
+        if @next_part.nil?
+          @next_part = msg
+        else
+          @next_part.add_message_part(msg)
+        end
+      end
+
+      # @return [bool] Whether all messages in a multipart message have been received.
+      def all_messages_received?
+        total_messages == highest_contiguous_index
+      end
+
+      # @return [Integer] The highest contiguous sequence number of linked message parts
+      # @see #message_number
+      # @see #_highest_contiguous_index
+      def highest_contiguous_index
+        _highest_contiguous_index(0)
+      end
+
+      # Helper function to calculate the contiguous index
+      # @param last_index [Integer] the index of the starting message
+      # @see #highest_contiguous_index
+      # @return [Integer] The highest contiguous sequence number of linked message parts
+      def _highest_contiguous_index(last_index)
+        mn = message_number # just in case this is expensive to compute
+        return last_index if mn - last_index != 1      # indicating a skip or restart
+        return mn if @next_part.nil?                   # indicating we're the last message
+        @next_part._highest_contiguous_index(mn)       # recurse down
+      end
+
+      ######################### Conversion functions
+
+      # Convert A string latitude or longitude as fields into a signed number
+      # @param dm_string [String] An angular measurement in the form DDMM.MMM
+      # @param sign_letter [String] can be N,S,E,W
+      # @return [Float] A signed latitude or longitude
+      def _degrees_minutes_to_decimal(dm_string, sign_letter = "")
+        return nil if dm_string.nil? || dm_string.empty?
+        r = /(\d+)(\d{2}\.\d+)/  # (some number of digits) (2 digits for minutes).(decimal minutes)
+        m = r.match(dm_string)
+        raw = m.values_at(1)[0].to_f + (m.values_at(2)[0].to_f / 60)
+        _nsew_signed_float(raw, sign_letter)
+      end
+
+      # Use cardinal directions to assign positive or negative to mixed_val.
+      # Of possible directions NSEW (sign_letter) treat N/E as + and S/W as -
+      # @param mixed_val [String] input value, can be string or float
+      # @param sign_letter [String] can be N,S,E,W, or empty
+      # @return [Float] The input value signed as per the sign letter.
+      def _nsew_signed_float(mixed_val, sign_letter = "")
+        value = mixed_val.to_f
+        value *= -1 if !sign_letter.empty? && "SW".include?(sign_letter.upcase)
+        value
+      end
+
+      # integer or nil
+      # @param field [String] the field index to check
+      # @return [Integer] The value in the field or nil
+      def _integer(field)
+        return nil if field.nil? || field.empty?
+        field.to_i
+      end
+
+      # float or nil
+      # @param field [String] the field index to check
+      # @return [Float] The value in the field or nil
+      def _float(field)
+        return nil if field.nil? || field.empty?
+        field.to_f
+      end
+
+      # string or nil
+      # @param field [String] the field index to check
+      # @return [String] The value in the field or nil
+      def _string(field)
+        return nil if field.nil? || field.empty?
+        field
+      end
+
+      # hex to int or nil
+      # @param field [String] the field index to check
+      # @return [Integer] The value in the field or nil
+      def _hex_to_integer(field)
+        return nil if field.nil? || field.empty?
+        field.hex
+      end
+
+      # utc time or nil (HHMMSS or HHMMSS.SS)
+      # @param field [String] the field index to check
+      # @return [Time] The value in the field or nil
+      def _utctime_hms(field)
+        return nil if field.nil? || field.empty?
+        re_format = /(\d{2})(\d{2})(\d{2}(\.\d+)?)/
+        now = Time.now
+        begin
+          hms = re_format.match(field)
+          Time.new(now.year, now.month, now.day, hms[1].to_i, hms[2].to_i, hms[3].to_f)
+        rescue
+          nil
+        end
+      end
+
+      # time interval or nil (HHMMSS or HHMMSS.SS)
+      # @param field [String] the field index to check
+      # @return [Time] The value in the field or nil
+      def _interval_hms(field)
+        return nil if field.nil? || field.empty?
+        re_format = /(\d{2})(\d{2})(\d{2}(\.\d+)?)/
+        begin
+          hms = re_format.match(field)
+          Time.new(0, 0, 0, hms[1].to_i, hms[2].to_i, hms[3].to_f)
+        rescue
+          nil
+        end
+      end
+
+      # @param d_field [String] the date field index to check
+      # @param t_field [String] the time field index to check
+      # @return [Time] The value in the fields, or nil if either is not provided
+      def _utc_date_time(d_field, t_field)
+        return nil if t_field.nil? || t_field.empty?
+        return nil if d_field.nil? || d_field.empty?
+
+        # get formats and time
+        time_format = /(\d{2})(\d{2})(\d{2}(\.\d+)?)/
+        date_format = /(\d{2})(\d{2})(\d{2})/
+
+        # crunch numbers
+        begin
+          dmy = date_format.match(d_field)
+          hms = time_format.match(t_field)
+          Time.new(2000 + dmy[3].to_i, dmy[2].to_i, dmy[1].to_i, hms[1].to_i, hms[2].to_i, hms[3].to_f)
+        rescue
+          nil
+        end
+      end
+
+    end
+  end
+end