nmea_plus 1.0.7 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0eca727afdb573f7ffede6594fc3d7acda16a48
-  data.tar.gz: 6ad4878023b3743d36954b020c8f08d97ea2ec62
+  metadata.gz: ad7de05d0b6299139bf89734517185b1056c2055
+  data.tar.gz: d77eced056aac4fb30998039e41fc9bcdc02e5a5
 SHA512:
-  metadata.gz: 9ab5c817f001fb525e698b1e3588690bfbcf7952fd85faebe27df6e1c214cceecb5502ec0aedc39e74f33a0e1255524fe172059f1d9b870f1fec9eb245b526b1
-  data.tar.gz: 9338e0e75eae30e96717ffa45053ae7fbd03383f49b22793a0b4b87ddfcfb17d508ae6197490093a6aab7e859a67426d329731907949b992a334ecee765a71b7
+  metadata.gz: 337635824791c01b604b2e8027db96711375ad5fe521568953d3c5daac1e9df5605b79434b54ce90b474ff683fd5c532a18ac969585f9cf6a3dc3fc1ae2e42be
+  data.tar.gz: 91dd8c299619df14559f74120e56141d790d413557cd2d8be038f2b0f4df55b21fb42e78561d865b0d4b3a04c13ddd76278fc2cfb535399a33084ce72ee3f4ab

data/README.md

@@ -2,7 +2,7 @@
 
 [![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)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/nmea_plus/1.0.7)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/nmea_plus/1.0.8)
 
 [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.
 
@@ -48,7 +48,7 @@ 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`.
+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` class 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'
@@ -86,6 +86,8 @@ end
 
 ## Design documents
 
+### NMEA
+
 This gem was coded to accept the standard NMEA messages defined in the unoffical spec found here:
 http://www.catb.org/gpsd/NMEA.txt
 
@@ -93,18 +95,23 @@ Because the message types are standard, if no override is found for a particular
 
 > 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
 
+Support for proprietary NMEA messages is also possible.  PASHR is included as proof-of-concept.
+
+### AIS
 
-Additionally, AIS message type definitions were implemented from the unofficial spec found here:
+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, 4, 5, 8, 9, 12, 14, 18, 19, 20, 21, and 24 are implemented.
+Currently, the following AIVDM message types are supported:
+
+> 1, 2, 3, 4, 5, 8, 9, 12, 14, 18, 19, 20, 21, 24, 27
+> Type 8 subtypes for DAC/FID: 1/31, 366/56, 366/57
 
-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.
+This module was written from information scraped together on the web, not from testing on actual devices.  A lack of test cases -- especially for more obscure message types -- is a barrier to completeness.  Please don't entrust your life or the safety of a ship to this code without doing your own rigorous testing.
 
 
 ## Author

data/lib/nmea_plus/message/ais/vdm.rb

@@ -28,6 +28,7 @@ require_relative "vdm_payload/vdm_msg18" # also includes 19
 require_relative "vdm_payload/vdm_msg20"
 require_relative "vdm_payload/vdm_msg21"
 require_relative "vdm_payload/vdm_msg24"
+require_relative "vdm_payload/vdm_msg27"
 
 module NMEAPlus
   module Message

data/lib/nmea_plus/message/ais/vdm_payload/payload.rb

@@ -0,0 +1,198 @@
+
+module NMEAPlus
+  module Message
+    module AIS
+      module VDMPayload
+        # Basic tools for interpreting the armored payload encoding
+        class Payload
+
+          def initialize; end
+
+          # @return [String] The raw "armored payload" in the original message
+          attr_accessor :payload_bitstring
+
+          # @return [Integer] The number of padding characters required to bring the payload to a 6 bit boundary
+          attr_accessor :fill_bits
+
+          # make our own shortcut syntax for payload attributes
+          # @param name [String] What the accessor will be called
+          # @param start_bit [Integer] The index of first bit of this field in the payload
+          # @param length [Integer] The number of bits in this field
+          # @param formatter [Symbol] The symbol for the formatting function to apply to the field (optional)
+          # @param fmt_arg Any argument necessary for the formatting function
+          # @param fmt_arg2 Any other argument necessary for the formatting function
+          # @param fmt_arg3 Any other argument necessary for the formatting function
+          # @macro [attach] payload_reader
+          #   @!attribute [r] $1
+          #   @return The field defined by the $3 bits starting at payload bit $2, formatted with the function {#$4}($5, $6, $7)
+          def self.payload_reader(name, start_bit, length, formatter, fmt_arg = nil, fmt_arg2 = nil, fmt_arg3 = nil)
+            args = [start_bit, length]
+            args << fmt_arg unless fmt_arg.nil?
+            args << fmt_arg2 unless fmt_arg2.nil?
+            args << fmt_arg3 unless fmt_arg3.nil?
+            self.class_eval("def #{name};#{formatter}(#{args.join(', ')});end")
+          end
+
+          # Convert 6-bit ascii to a character, according to http://catb.org/gpsd/AIVDM.html#_ais_payload_data_types
+          # @param ord [Integer] The 6-bit ascii code
+          # @return [String] the character for that code
+          def _6b_ascii(ord)
+            '@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_ !"#$%&\'()*+,-./0123456789:;<=>?'[ord]
+          end
+
+          # Access part of the payload.  If there aren't bytes, there, return nil
+          # else execute a block
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return Nil or whatever is yielded by the block
+          # @yield [String] A binary coded string ("010010101" etc)
+          def _access(start, length)
+            part = @payload_bitstring[start, length]
+            return nil if part.nil? || part.empty?
+            yield part
+          end
+
+          # pull out 6b chunks from the payload, then convert those to their more familar characters
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return [String]
+          def _6b_string(start, length)
+            _bit_slices(start, length, 6).to_a.map(&:join).map { |x| _6b_ascii(x.to_i(2)) }.join
+          end
+
+          # pull out 8b chunks from the payload, then convert those to their more familar characters
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return [String]
+          def _8b_data_string(start, length)
+            _bit_slices(start, length, 8).to_a.map(&:join).map { |x| x.to_i(2).chr }.join
+          end
+
+          # Slice a part of the payload into binary chunks of a given size
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return [Array<String>] Strings representing binary ("01010101" etc) for each slice
+          def _bit_slices(start, length, chunk_size)
+            _access(start, length) { |bits| bits.chars.each_slice(chunk_size) }
+          end
+
+          # convert a 6b string but trim off the 0s ('@')
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return [String]
+          def _6b_string_nullterminated(start, length)
+            _6b_string(start, length).split("@", 2)[0]
+          end
+
+          # directly convert a string to a binary number as you'd read it
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an unsigned integer value
+          def _6b_unsigned_integer(start, length, equiv_nil = nil)
+            ret = _access(start, length) { |bits| bits.to_i(2) }
+            return nil if ret == equiv_nil
+            ret
+          end
+
+          # perform a twos complement operation on part of the payload
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an integer value
+          def _6b_integer(start, length, equiv_nil = nil)
+            case @payload_bitstring[start]
+            when "0"
+              _6b_unsigned_integer(start, length, equiv_nil)
+            when "1"
+              # MSB is 1 for negative
+              # two's complement: flip bits, then add 1
+              ret = _access(start, length) { |bits| (bits.tr("01", "10").to_i(2) + 1) * -1 }
+              return nil if ret == equiv_nil
+              ret
+            end
+          end
+
+          # scale an integer by dividing it by a denominator
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param denominator [Integer] The divisor to use in scaling down the result
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an integer value
+          def _6b_integer_scaled(start, length, denominator, equiv_nil = nil)
+            ret = _6b_integer(start, length, equiv_nil)
+            return nil if ret.nil?
+            ret.to_f / denominator
+          end
+
+          # scale an unsigned integer by dividing it by a denominator
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param denominator [Integer] The divisor to use in scaling down the result
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an integer value
+          def _6b_unsigned_integer_scaled(start, length, denominator, equiv_nil = nil)
+            ret = _6b_unsigned_integer(start, length, equiv_nil)
+            return nil if ret.nil?
+            ret.to_f / denominator
+          end
+
+          # scale an integer by dividing it by a denominator
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param denominator [Integer] The divisor to use in scaling down the result
+          # @param shift [Float] the amount to shift (up) the result by
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an integer value
+          def _6b_integer_scaled_shifted(start, length, denominator, shift, equiv_nil = nil)
+            ret = _6b_integer_scaled(start, length, denominator, equiv_nil)
+            return nil if ret.nil?
+            ret + shift
+          end
+
+          # scale an unsigned integer by dividing it by a denominator
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @param denominator [Integer] The divisor to use in scaling down the result
+          # @param shift [Float] the amount to shift (up) the result by
+          # @param equiv_nil [Integer] If applicable, the value for this field that would indicate nil
+          # @return [Integer] an integer value
+          def _6b_unsigned_integer_scaled_shifted(start, length, denominator, shift, equiv_nil = nil)
+            ret = _6b_unsigned_integer_scaled(start, length, denominator, equiv_nil)
+            return nil if ret.nil?
+            ret + shift
+          end
+
+          # Get the value of a bit in the payload
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param _ [Integer] Doesn't matter.  Here so signatures match; we hard-code 1 because it's 1 bit.
+          # @return [bool]
+          def _6b_boolean(start, _)
+            _access(start, 1) { |bits| bits.to_i == 1 }
+          end
+
+          # Return a string representing binary
+          # @param start [Integer] The index of the first bit in the payload field
+          # @param length [Integer] The number of bits in the payload field
+          # @return [String] e.g. "0101010101011000"
+          def _2b_data_string(start, length)
+            _access(start, length)
+          end
+
+          # use shorthand for data types as defined in http://catb.org/gpsd/AIVDM.html
+          alias_method :_u, :_6b_unsigned_integer
+          alias_method :_U, :_6b_unsigned_integer_scaled
+          alias_method :_i, :_6b_integer
+          alias_method :_I, :_6b_integer_scaled
+          alias_method :_b, :_6b_boolean
+          alias_method :_e, :_6b_unsigned_integer
+          alias_method :_t, :_6b_string_nullterminated
+          alias_method :_d, :_2b_data_string
+          alias_method :_UU, :_6b_unsigned_integer_scaled_shifted
+          alias_method :_II, :_6b_integer_scaled_shifted
+
+        end
+      end
+    end
+  end
+end

data/lib/nmea_plus/message/ais/vdm_payload/vdm_msg.rb

@@ -1,3 +1,4 @@
+require_relative "payload"
 
 module NMEAPlus
   module Message
@@ -5,158 +6,12 @@ module NMEAPlus
       # There are many VDM payload types, and this is their container.  See {VDMMsg}.
       module VDMPayload
         # The base class for the AIS payload (of {NMEAPlus::Message::AIS::VDM}), which uses its own encoding for its own subtypes
-        class VDMMsg
-
-          def initialize; end
-
-          # @return [String] The raw "armored payload" in the original message
-          attr_accessor :payload_bitstring
-
-          # @return [Integer] The number of padding characters required to bring the payload to a 6 bit boundary
-          attr_accessor :fill_bits
-
-          # make our own shortcut syntax for payload attributes
-          # @param name [String] What the accessor will be called
-          # @param start_bit [Integer] The index of first bit of this field in the payload
-          # @param length [Integer] The number of bits in this field
-          # @param formatter [Symbol] The symbol for the formatting function to apply to the field (optional)
-          # @param formatter_arg Any argument necessary for the formatting function
-          # @macro [attach] payload_reader
-          #   @!attribute [r] $1
-          #   @return The field defined by $3 bits starting at bit $2 of the payload, formatted with the function {#$4}($5)
-          def self.payload_reader(name, start_bit, length, formatter, formatter_arg = nil)
-            if formatter_arg.nil?
-              self.class_eval("def #{name};#{formatter}(#{start_bit}, #{length});end")
-            else
-              self.class_eval("def #{name};#{formatter}(#{start_bit}, #{length}, #{formatter_arg});end")
-            end
-          end
+        class VDMMsg < NMEAPlus::Message::AIS::VDMPayload::Payload
 
           payload_reader :message_type, 0, 6, :_u
           payload_reader :repeat_indicator, 6, 2, :_u
           payload_reader :source_mmsi, 8, 30, :_u
 
-          # Convert 6-bit ascii to a character, according to http://catb.org/gpsd/AIVDM.html#_ais_payload_data_types
-          # @param ord [Integer] The 6-bit ascii code
-          # @return [String] the character for that code
-          def _6b_ascii(ord)
-            '@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_ !"#$%&\'()*+,-./0123456789:;<=>?'[ord]
-          end
-
-          # Access part of the payload.  If there aren't bytes, there, return nil
-          # else execute a block
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return Nil or whatever is yielded by the block
-          # @yield [String] A binary coded string ("010010101" etc)
-          def _access(start, length)
-            part = @payload_bitstring[start, length]
-            return nil if part.nil? || part.empty?
-            yield part
-          end
-
-          # pull out 6b chunks from the payload, then convert those to their more familar characters
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [String]
-          def _6b_string(start, length)
-            _bit_slices(start, length, 6).to_a.map(&:join).map { |x| _6b_ascii(x.to_i(2)) }.join
-          end
-
-          # pull out 8b chunks from the payload, then convert those to their more familar characters
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [String]
-          def _8b_data_string(start, length)
-            _bit_slices(start, length, 8).to_a.map(&:join).map { |x| x.to_i(2).chr }.join
-          end
-
-          # Slice a part of the payload into binary chunks of a given size
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [Array<String>] Strings representing binary ("01010101" etc) for each slice
-          def _bit_slices(start, length, chunk_size)
-            _access(start, length) { |bits| bits.chars.each_slice(chunk_size) }
-          end
-
-          # convert a 6b string but trim off the 0s ('@')
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [String]
-          def _6b_string_nullterminated(start, length)
-            _6b_string(start, length).split("@", 2)[0]
-          end
-
-          # directly convert a string to a binary number as you'd read it
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [Integer] an unsigned integer value
-          def _6b_unsigned_integer(start, length)
-            _access(start, length) { |bits| bits.to_i(2) }
-          end
-
-          # perform a twos complement operation on part of the payload
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [Integer] an integer value
-          def _6b_twoscomplement(start, length)
-            # two's complement: flip bits, then add 1
-            _access(start, length) { |bits| bits.tr("01", "10").to_i(2) + 1 }
-          end
-
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [Integer] an integer value
-          def _6b_integer(start, length)
-            # MSB is 1 for negative
-            twoc = _6b_twoscomplement(start, length)
-            twoc && twoc * (@payload_bitstring[start] == 0 ? 1 : -1)
-          end
-
-          # scale an integer by dividing it by 10^decimal_places
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @param decimal_places [Integer] The power of ten to use in scaling down the result
-          # @return [Integer] an integer value
-          def _6b_integer_scaled(start, length, decimal_places)
-            _6b_integer(start, length).to_f / (10 ** decimal_places)
-          end
-
-          # scale an unsigned integer by dividing it by 10^decimal_places
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @param decimal_places [Integer] The power of ten to use in scaling the result
-          # @return [Integer] an integer value
-          def _6b_unsigned_integer_scaled(start, length, decimal_places)
-            _6b_unsigned_integer(start, length).to_f / (10.0 ** decimal_places)
-          end
-
-          # Get the value of a bit in the payload
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param _ [Integer] Doesn't matter.  Here so signatures match; we hard-code 1 because it's 1 bit.
-          # @return [bool]
-          def _6b_boolean(start, _)
-            _access(start, 1) { |bits| bits.to_i == 1 }
-          end
-
-          # Return a string representing binary
-          # @param start [Integer] The index of the first bit in the payload field
-          # @param length [Integer] The number of bits in the payload field
-          # @return [String] e.g. "0101010101011000"
-          def _2b_data_string(start, length)
-            _access(start, length)
-          end
-
-          # use shorthand for data types as defined in http://catb.org/gpsd/AIVDM.html
-          alias_method :_u, :_6b_unsigned_integer
-          alias_method :_U, :_6b_unsigned_integer_scaled
-          alias_method :_i, :_6b_integer
-          alias_method :_I, :_6b_integer_scaled
-          alias_method :_b, :_6b_boolean
-          alias_method :_e, :_6b_unsigned_integer
-          alias_method :_t, :_6b_string_nullterminated
-          alias_method :_d, :_2b_data_string
-
           # The ship cargo type description lookup table
           # @param code [Integer] The cargo type id
           # @return [String] Cargo type description
@@ -231,6 +86,25 @@ module NMEAPlus
             980_000_000 < source_mmsi && source_mmsi < 990_000_000
           end
 
+          # @param code [Integer] The navigational status id
+          # @return [String] Navigational status description
+          def get_navigational_status_description(code)
+            return nil if code.nil?
+            case code
+            when 0 then return "Under way using engine"
+            when 1 then return "At anchor"
+            when 2 then return "Not under command"
+            when 3 then return "Restricted manoeuverability"
+            when 4 then return "Constrained by her draught"
+            when 5 then return "Moored"
+            when 6 then return "Aground"
+            when 7 then return "Engaged in Fishing"
+            when 8 then return "Under way sailing"
+            when 14 then return "AIS-SART active"
+            end
+            "Reserved for future use"
+          end
+
         end
 
         # We haven't defined all the AIS payload types, so this is a catch-all