mm_gps 0.1.2 → 0.1.3

data/lib/mm_gps/mm_gps_beacon.rb

@@ -1,29 +1,50 @@
-module MmGPS  
+module MmGPS
+  
+  # Main interface. Represents a connection to a MarvelMind beacon/hedgehog. 
+  # You may want (and can) to have more than one instance.
   class Beacon
     START_TOKEN = "\xFFG".force_encoding(Encoding::BINARY)
     EMPTY = ''.force_encoding(Encoding::BINARY)
     
+    # Open a new connection on the given serial port. It also encapsulates
+    # the underlying SerialPort object instance, setting a read timeout of 1 s
+    # and enabling the binary mode.
+    # 
+    # @param port [String] 'COM1' on Windows, '/dev/ttyNNN' on *nix
+    # @param baus [Fixnum] baudrate, value must be supported by the platform
     def initialize(port, baud = 115200)
       @sp = SerialPort.new(port, "baud" => baud)
       @sp.read_timeout = 1000 #1 sec
       @sp.binmode
     end
     
-    def trap
-      Signal.trap("INT") do
+    # Istalls a signal handler for the given signal, default to SIGINT, 
+    # which closes the serialport connection. Further readings are likely to
+    # trigger an IOError.
+    # 
+    # @param signal [String] the signal to be trapped, default to 'SIGINT'
+    def trap(signal="INT")
+      Signal.trap(signal) do
         @sp.close
-        puts "Beacon port: #{@sp.inspect}"
+        puts "\nBeacon port: #{@sp.inspect}"
       end
     end
-
+    
+    # Close the serialport
     def close
       @sp.close
     end
     
+    # Check wether the serialport is closed
+    # 
+    # @return [Bool] true if closed, false if open
     def closed?
       return @sp.closed?
     end
     
+    # Reads and discards incoming bytes until the START_TOKEN marrker is
+    # received. Call this metod immediately after opening the connection
+    # and before start reading the data.
     def sync
       buf = EMPTY
       begin
@@ -32,6 +53,9 @@ module MmGPS
       end while buf != START_TOKEN
     end
     
+    # Reads a raw packet.
+    #
+    #  @return [String] a byte stream encoded with Encoding::BINARY
     def get_raw_packet
       buf = START_TOKEN.dup
       while true do
@@ -41,6 +65,9 @@ module MmGPS
       return buf[0...-2]
     end
     
+    # Reads a raw packet, checks its CRC, and returns its contents as a Hash.
+    # 
+    # @return [Hash] typically in the form `%I(ts x y z f).zip(payload).to_h`
     def get_packet
       return MmGPS::parse_packet(self.get_raw_packet)
     end

data/lib/mm_gps/mm_gps_module.rb

@@ -1,12 +1,24 @@
-class GPSException < Exception; end
+# Local Exception class.
+class MmGPSException < Exception; end
 
+# Manage connection and data decoding with a MarvelMind beacon or hedgehog.
 module MmGPS
+  # Checks a sbuffer for valid CRC16.
+  # 
+  # @param str [String] the buffer to be checked
+  # @return [Bool] true if the buffer is self-consistent
   def self.valid_crc16?(str)
     crc16(str) == 0
   end
   
+  # Parse the given buffer according to the MarvelMind protocol.
+  # See http://www.marvelmind.com/pics/marvelmind_beacon_interfaces_v2016_03_07a.pdf
+  #
+  # @param buf [String] the String buffer to be parsed
+  # @return [Hash|Array] if the system is running, return a Hash with
+  #   timestamp, coordinates, and error code (data code 0x0001). Otherwise returns an Array of Hashes for beacons status (data code 0x0002).
   def self.parse_packet(buf)
-    raise GPSException, "Invalid CRC" unless valid_crc16?(buf)
+    raise MmGPSException, "Invalid CRC" unless valid_crc16?(buf)
     # warn "Invalid CRC" unless valid_crc16?(buf)
     header = buf[0..5].unpack('CCS<C')
     if header[2] == 1 then # Regular GPS Data
@@ -25,7 +37,7 @@ module MmGPS
         %I(x y z).each {|k| result.last[k] /= 100.0}
       end
     else
-      raise GPSException, "Unexpected packet type #{header[2]}"
+      raise MmGPSException, "Unexpected packet type #{header[2]}"
     end
     return result
   end

data/lib/mm_gps/version.rb

@@ -1,3 +1,3 @@
 module MmGPS
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/test.rb

@@ -8,16 +8,23 @@ beacon = MmGPS::Beacon.new(PORT, BAUD)
 beacon.trap # installs signal handler for CTRL-C
 
 puts "Syncing..."
-beacon.sync # discards any byte until the starting sequence "\xFFG" arrives
+begin
+  beacon.sync # discards any byte until the starting sequence "\xFFG" arrives
+rescue MmGPSException => e
+  puts "Packet Error: #{e.inspect}"
+rescue IOError => e
+  puts "Port closed #{e.inspect}"
+  exit
+end
 
 puts "Reading..."
 while not beacon.closed? do
   begin
     p beacon.get_packet
-  rescue GPSException => e
+  rescue MmGPSException => e
     puts "Packet Error: #{e.inspect}"
   rescue IOError => e
-    puts "Port closed? #{e.inspect}"
+    puts "Port closed #{e.inspect}"
     exit
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mm_gps
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Paolo Bosetti
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-17 00:00:00.000000000 Z
+date: 2016-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: serialport
@@ -84,6 +84,7 @@ files:
 - ext/mm_gps/extconf.rb
 - ext/mm_gps/mm_gps.c
 - ext/mm_gps/mm_gps.h
+- formulas.nb
 - lib/mm_gps.rb
 - lib/mm_gps/mm_gps_beacon.rb
 - lib/mm_gps/mm_gps_module.rb