Class: NMEAPlus::Message::Base Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/nmea_plus/message/base.rb

Overview

This class is abstract.

The base NMEA message type, from which all others inherit. Messages have a prefix character, fields, and checksum. This class provides convenience functions for accessing the fields as the appropriate data type, and logic for constructing multipart messages.

Direct Known Subclasses

AIS::AISMessage, NMEA::NMEAMessage

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#checksum ⇒ String

Returns The two-character checksum of the message.

Returns:

  • (String) —

    The two-character checksum of the message



48
49
50
 
# File 'lib/nmea_plus/message/base.rb', line 48

def checksum
  @checksum
end

#data_type ⇒ String (readonly)

Returns:

  • (String) —

    The NMEA data type of this message

  • field 0 of the payload, formatted with the function nil



57
 
# File 'lib/nmea_plus/message/base.rb', line 57

field_reader :data_type, 0, nil

#fields ⇒ Array<String> (readonly)

Returns The payload of the message, split into fields.

Returns:

  • (Array<String>) —

    The payload of the message, split into fields



45
46
47
 
# File 'lib/nmea_plus/message/base.rb', line 45

def fields
  @fields
end

#interpreted_data_type ⇒ String

Returns The data type used by the NMEAPlus::MessageFactory to parse this message.

Returns:



51
52
53
 
# File 'lib/nmea_plus/message/base.rb', line 51

def interpreted_data_type
  @interpreted_data_type
end

#message_number ⇒ Integer (readonly)

This method is abstract.

Returns The ordinal number of this message in its sequence.

Returns:

  • (Integer) —

    The ordinal number of this message in its sequence

See Also:



101
102
103
 
# File 'lib/nmea_plus/message/base.rb', line 101

def message_number
  1
end

#next_part ⇒ NMEAPlus::Message

Returns The next part of a multipart message, if available.

Returns:



54
55
56
 
# File 'lib/nmea_plus/message/base.rb', line 54

def next_part
  @next_part
end

#original ⇒ String (readonly)

Returns The original message.

Returns:

  • (String) —

    The original message



61
62
63
 
# File 'lib/nmea_plus/message/base.rb', line 61

def original
  "#{prefix}#{payload}*#{checksum}"
end

#payload ⇒ String

Returns The unprocessed payload of the message.

Returns:

  • (String) —

    The unprocessed payload of the message



42
43
44
 
# File 'lib/nmea_plus/message/base.rb', line 42

def payload
  @payload
end

#prefix ⇒ String

Returns The single character prefix for this NMEA 0183 message type.

Returns:

  • (String) —

    The single character prefix for this NMEA 0183 message type



39
40
41
 
# File 'lib/nmea_plus/message/base.rb', line 39

def prefix
  @prefix
end

#total_messages ⇒ Integer (readonly)

This method is abstract.

Returns The number of parts to this message.

Returns:

  • (Integer) —

    The number of parts to this message

See Also:



93
94
95
 
# File 'lib/nmea_plus/message/base.rb', line 93

def total_messages
  1
end

Class Method Details

._float(field) ⇒ Float

float or nil. This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (Float) —

    The value in the field or nil



181
182
183
184
185
 
# File 'lib/nmea_plus/message/base.rb', line 181

def self._float(field)
  return nil if field.nil? || field.empty?

  field.to_f
end

._hex_to_integer(field) ⇒ Integer

hex to int or nil. This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (Integer) —

    The value in the field or nil



201
202
203
204
205
 
# File 'lib/nmea_plus/message/base.rb', line 201

def self._hex_to_integer(field)
  return nil if field.nil? || field.empty?

  field.hex
end

._integer(field) ⇒ Integer

integer or nil. This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (Integer) —

    The value in the field or nil



171
172
173
174
175
 
# File 'lib/nmea_plus/message/base.rb', line 171

def self._integer(field)
  return nil if field.nil? || field.empty?

  field.to_i
end

._interval_hms(field) ⇒ Time

time interval or nil (HHMMSS or HHMMSS.SS). This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (Time) —

    The value in the field or nil



228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/nmea_plus/message/base.rb', line 228

def self._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, 1, 1, hms[1].to_i, hms[2].to_i, hms[3].to_f, "+00:00")
  rescue
    nil
  end
end

._string(field) ⇒ String

string or nil. This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (String) —

    The value in the field or nil



191
192
193
194
195
 
# File 'lib/nmea_plus/message/base.rb', line 191

def self._string(field)
  return nil if field.nil? || field.empty?

  field
end

._utc_date_time(d_field, t_field) ⇒ Time

Create a Time object from a date and time field

Parameters:

  • d_field (String) —

    the date value in the field to be checked

  • t_field (String) —

    the time value in the field to be checked

Returns:

  • (Time) —

    The value in the fields, or nil if either is not provided



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/nmea_plus/message/base.rb', line 244

def self._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, "+00:00")
  rescue
    nil
  end
end

._utctime_hms(field) ⇒ Time

utc time or nil (HHMMSS or HHMMSS.SS). This function is meant to be passed as a formatter to field_reader.

Parameters:

  • field (String) —

    the value in the field to be checked

Returns:

  • (Time) —

    The value in the field or nil



211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/nmea_plus/message/base.rb', line 211

def self._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, "+00:00")
  rescue
    nil
  end
end

.degrees_minutes_to_decimal(dm_string, sign_letter = "") ⇒ Float

Convert A string latitude or longitude as fields into a signed number

Parameters:

  • dm_string (String) —

    An angular measurement in the form DDMM.MMM

  • sign_letter (String) (defaults to: "") —

    can be N,S,E,W

Returns:

  • (Float) —

    A signed latitude or longitude



147
148
149
150
151
152
153
154
 
# File 'lib/nmea_plus/message/base.rb', line 147

def self.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

.field_reader(name, field_num, formatter = nil) ⇒ void

This method returns an undefined value.

Enable a shortcut syntax for message attribute accessors, in the style of ‘attr_accessor` metaprogramming. This is used to create a named field pointing to a specific indexed field in the payload, optionally applying a specific formatting function.

The formatting function MUST be a static method on this class.  This is a limitation caused by the desire
to both (1) expose the formatters outside this class, and (2) use them for metaprogramming without the
having to name the entire function.  field_reader is a static method, so if not for the fact that
`self.class.methods.include? formatter` fails to work for class methods in this context (unlike
`self.methods.include?`, which properly finds instance methods), I would allow either one and just
conditionally `define_method` the proper definition

Parameters:

  • name (String) —

    What the accessor will be called

  • field_num (Integer) —

    The index of the field in the payload

  • formatter (Symbol) (defaults to: nil) —

    The symbol for the formatting function to apply to the field (optional)



30
31
32
33
34
35
36
 
# File 'lib/nmea_plus/message/base.rb', line 30

def self.field_reader(name, field_num, formatter = nil)
  if formatter.nil?
    define_method(name) { @fields[field_num] }
  else
    define_method(name) { self.class.send(formatter.to_sym, @fields[field_num]) }
  end
end

.nsew_signed_float(mixed_val, sign_letter = "") ⇒ Float

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 -

Parameters:

  • mixed_val (String) —

    input value, can be string or float

  • sign_letter (String) (defaults to: "") —

    can be N,S,E,W, or empty

Returns:

  • (Float) —

    The input value signed as per the sign letter.



161
162
163
164
165
 
# File 'lib/nmea_plus/message/base.rb', line 161

def self.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

Instance Method Details

#_highest_contiguous_index(last_index) ⇒ Integer

Helper function to calculate the contiguous index

Parameters:

  • last_index (Integer) —

    the index of the starting message

Returns:

  • (Integer) —

    The highest contiguous sequence number of linked message parts

See Also:



133
134
135
136
137
138
139
 
# File 'lib/nmea_plus/message/base.rb', line 133

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

#add_message_part(msg) ⇒ void

This method returns an undefined value.

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)

Parameters:



109
110
111
112
113
114
115
 
# File 'lib/nmea_plus/message/base.rb', line 109

def add_message_part(msg)
  if @next_part.nil?
    @next_part = msg
  else
    @next_part.add_message_part(msg)
  end
end

#all_checksums_ok? ⇒ Boolean

return [bool] Whether the checksums for all available message parts are OK

Returns:

  • (Boolean) 


77
78
79
80
81
82
 
# File 'lib/nmea_plus/message/base.rb', line 77

def all_checksums_ok?
  return false unless checksum_ok?
  return true if @next_part.nil?

  @next_part.all_checksums_ok?
end

#all_messages_received? ⇒ bool

Returns Whether all messages in a multipart message have been received.

Returns:

  • (bool) —

    Whether all messages in a multipart message have been received.



118
119
120
 
# File 'lib/nmea_plus/message/base.rb', line 118

def all_messages_received?
  total_messages == highest_contiguous_index
end

#calculated_checksum ⇒ Object

return [String] The calculated checksum for this payload as a two-character string



85
86
87
 
# File 'lib/nmea_plus/message/base.rb', line 85

def calculated_checksum
  format("%02x", @payload.each_byte.map(&:ord).reduce(:^))
end

#checksum_ok? ⇒ bool

Returns Whether the checksum calculated from the payload matches the checksum given in the message.

Returns:

  • (bool) —

    Whether the checksum calculated from the payload matches the checksum given in the message



72
73
74
 
# File 'lib/nmea_plus/message/base.rb', line 72

def checksum_ok?
  calculated_checksum.casecmp(checksum).zero?
end

#highest_contiguous_index ⇒ Integer

Returns The highest contiguous sequence number of linked message parts.

Returns:

  • (Integer) —

    The highest contiguous sequence number of linked message parts

See Also:



125
126
127
 
# File 'lib/nmea_plus/message/base.rb', line 125

def highest_contiguous_index
  _highest_contiguous_index(0)
end