mm_gps 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f68f04c6955bd3be0fac1c0e6c9f6744efb2463a
-  data.tar.gz: 44d139c72d2ec7fec9eba8a1b9f12c72659bdc5c
+  metadata.gz: d54d7a04b331b5339f0e68b21e903101424a9f9e
+  data.tar.gz: b07d30015c9e27d411154880d00b23f1afd6cb00
 SHA512:
-  metadata.gz: d8c3dc05456bd59a303cae8b5d4cd082e0b51a82c3a8533d0308c4ba0202a7cb67c254fb63cce29f1397e9a1f89961616c20f6f7eb674db5e1b6fdaa1c1311b3
-  data.tar.gz: 51b785d6a816b966cb183f5235346ced4496dc510a020e2472994c7181ed7c6580db6ef6067d4ac1c8fdfa79b6986660dc29dae3fabbf13c5a0db0d0c9ebe07d
+  metadata.gz: c8f837ef92db27cd2a89db5a03c368f301cdcd5003bc7d43d54279407d0a60c433847ad7283826560e66e11ac3535a22d7ec2397ec62914e8b4eb88d563b4d6b
+  data.tar.gz: 86cd9f6dadc96679aaa1712b4620569262954635f29014b3672fdac13b5c115e53db40284854433c2d4b12bc62799b9e5e1273e223fac93f0536fccce2d23546

data/README.md

@@ -32,29 +32,17 @@ BAUD = 115200 # SerialPort class does not support non-standard 500 kbps
 beacon = MmGPS::Beacon.new(PORT, BAUD)
 beacon.trap # installs signal handler for CTRL-C
 
-puts "Syncing..."
-begin
-  beacon.sync # discards any byte until the starting sequence "\xFFG" arrives
-rescue MmGPSError => e
-  puts "Packet Error: #{e.inspect}"
-  p e.data[:packet]
-rescue IOError => e
-  puts "Port closed #{e.inspect}"
-  exit
+ # Standard each loop. Type CTRL-C for interrupting it
+beacon.each do |packet|
+  p packet
 end
 
-puts "Reading..."
-while not beacon.closed? do
-  begin
-    p beacon.get_packet
-  rescue MmGPSError => e
-    puts "Packet Error: #{e.inspect}"
-    p e.data
-  rescue IOError => e
-    puts "Port closed #{e.inspect}"
-    exit
-  end
-end
+ # Use the enumerator:
+beacon.reopen      # Needed, since CTRL-C in previous example also closes the Serialport connection
+enum = beacon.each # gets the Enumerator
+p enum.take 10     # Next 10 packets from enum
+
+puts "Exiting"
 ```
 
 ## Contributing

data/lib/mm_gps.rb

@@ -1,6 +1,7 @@
 require 'serialport'
 require 'mm_gps/version'
 require 'mm_gps/mm_gps_module'
+require 'mm_gps/mm_gps_buffer'
 require 'mm_gps/mm_gps_beacon'
 require 'mm_gps/mm_gps'
 

data/lib/mm_gps/mm_gps_beacon.rb

@@ -2,10 +2,26 @@ module MmGPS
   
   # Main interface. Represents a connection to a MarvelMind beacon/hedgehog. 
   # You may want (and can) to have more than one instance.
+  # 
+  # @example Typical usage:
+  #   beacon = MmGPS::Beacon.new(PORT, BAUD)
+  #   beacon.trap # installs signal handler for CTRL-C
+  #   
+  #   # Standard each loop. Type CTRL-C for interrupting it
+  #   beacon.each do |packet|
+  #     p packet
+  #   end
+  # @example Using the enumerator:
+  #   # Use the enumerator:
+  #   beacon.reopen      # Needed, since CTRL-C in previous example also closes the Serialport connection
+  #   enum = beacon.each # gets the Enumerator
+  #   p enum.take 10     # next 10 packets from enum
+  # 
   class Beacon
-    START_TOKEN = "\xFFG".force_encoding(Encoding::BINARY)
-    EMPTY = ''.force_encoding(Encoding::BINARY)
+    include Enumerable
+    START_TOKEN = "\xFFG"
     attr_reader :last_pkt
+    attr_reader :port, :baud
     
     # Open a new connection on the given serial port. It also encapsulates
     # the underlying SerialPort object instance, setting a read timeout of 1 s
@@ -14,17 +30,15 @@ module MmGPS
     # @param port [String] 'COM1' on Windows, '/dev/ttyNNN' on *nix
     # @param baud [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
-      @last_pkt = ''.force_encoding(Encoding::BINARY)
+      @port, @baud = port, baud
+      self.open
     end
     
-    # Istalls a signal handler for the given signal, default to SIGINT, 
+    # Installs 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'
+    # @param signal [String] the signal to be trapped, default to +'SIGINT'+
     def trap(signal="INT")
       Signal.trap(signal) do
         @sp.close
@@ -33,10 +47,31 @@ module MmGPS
     end
     
     # Close the serialport
+    # 
+    # @return [Beacon] self
     def close
-      @sp.close
+      @sp.close unless (!@sp || @sp.closed?)
+      return self
     end
     
+    # Open the serialport connection with {#port} at {#baud} rate. It also
+    # resets internals to a clean state.
+    # 
+    # @return [Beacon] self
+    def open
+      self.close 
+      @sp = SerialPort.new(@port, "baud" => @baud)
+      @sp.read_timeout = 1000 #1 sec
+      @sp.binmode
+      @last_pkt = ''.force_encoding(Encoding::BINARY)
+      @buffer = Buffer.new(START_TOKEN)
+      @buffer.when_updating do
+        @sp.read(1)
+      end
+      return self
+    end
+    alias :reopen :open
+    
     # Check wether the serialport is closed
     # 
     # @return [Bool] true if closed, false if open
@@ -44,47 +79,58 @@ module MmGPS
       return @sp.closed?
     end
     
-    # Reads and discards incoming bytes until the START_TOKEN marrker is
+    # Reads and discards incoming bytes until the START_TOKEN marker is
     # received. Call this metod immediately after opening the connection
     # and before start reading the data.
+    # 
+    # @return [Beacon] self
+    # @deprecated No more needed, since this version automatically takes care of the incomplete packages.
     def sync
-      buf = EMPTY
-      begin
-        buf << (@sp.read(1) || EMPTY)
-        buf = buf[-2..-1] if buf.size > 2
-      end while buf != START_TOKEN
+      warn "Beacon#sync is deprecated and no more necessary!"
+      return self
+    end
+    
+    # Iterates +block+ to each packet
+    # 
+    # @yield [pkt] the decoded packet
+    # @yieldparam pkt [Hash|Array] the decoded packet as returned by +MmGPS#parse_packet+
+    def each
+      return enum_for(:each) unless block_given?
+      loop do
+        begin
+          yield self.get_packet
+        rescue MmGPSError => e
+          warn "Packet Error: #{e.inspect}, reason: #{e.data[:reason]}"
+          warn "Packet: #{MmGPS.hexify(e.data[:packet])}"
+          if e.data[:reason] == :nocrc then
+            warn "CRC16: #{e.data[:crc]}"
+          end
+        rescue IOError => e
+          warn "Port closed #{e.inspect}"
+          return
+        end
+      end
     end
     
     # Reads a raw packet.
     #
-    #  @return [String] a byte stream encoded with Encoding::BINARY
+    # @return [String] a byte stream encoded with Encoding::BINARY
+    # @raise [MmGPSError] when data are not available, setting +e.data [:reason]+ to +:noavail+
     def get_raw_packet
-      buf = START_TOKEN.dup
-      while true do
-        char = @sp.read(1)
-        unless char
-          raise MmGPSError.new("Data unavailable", 
-            {reason: :noavail, packet:nil}) 
-        else
-          buf << char
-        end
-        break if buf[-2..-1] == START_TOKEN
+      pkt = @buffer.next
+      if pkt.empty? then
+        raise MmGPSError.new("Data unavailable", {reason: :noavail})
       end
-      @last_pkt = buf[0...-2]
+      @last_pkt = pkt
       return @last_pkt
     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`
+    # @return [Hash|Array] typically in the form +%I(ts x y f).zip(payload).to_h+
+    # @raise [MmGPSError] when CRC16 check does not pass, setting +e.data [:reason]+ to +:nocrc+
     def get_packet
       return MmGPS::parse_packet(self.get_raw_packet)
-    rescue MmGPSError => e
-      if e.data[:reason] == :noavail then
-        return nil
-      else 
-        raise e
-      end
     end
     
   end

data/lib/mm_gps/mm_gps_buffer.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+class BufferError < RuntimeError; end
+
+module MmGPS
+  # A general abstraction for dealing with character streams.
+  #
+  # @example Typical usage:
+  #   buffer = Buffer.new(START_TOKEN)
+  #   buffer.when_updating do
+  #     @sp.read(1) # @sp is an IO instance
+  #   end
+  #   # more code...
+  #   pkt = buffer.next
+  # 
+  class Buffer
+    include Enumerable
+    attr_reader :separator, :stop_packet
+    attr_reader :buffer, :fiber
+    
+    def initialize(sep="\xFF")
+      @update = lambda { empty }
+      @encoding = Encoding::BINARY
+      fiber_init
+      self.separator = sep
+      self.clear
+    end
+    
+    # Set the {#separator} bytes sequence, as a String in {#encoding} format.
+    # 
+    # @param s [String] the separator string, automatically converted into {#encoding}
+    def separator=(s)
+      @separator = s.force_encoding(@encoding)
+    end
+    
+    # Clear the {#buffer} and return its last content.
+    # 
+    # @return [String] the last buffer content
+    def clear
+      tmp = @buffer
+      @buffer = empty
+      return tmp
+    end
+    
+    # Sets the block to be executed for updating the {#buffer}. Typically, 
+    # this block must read one single byte and return it. Queuing into the 
+    # {#buffer} is automatically performed.
+    # @example To read from a serialport instance +@sp+:
+    #   buffer.when_updating do
+    #     @sp.read(1)
+    #   end
+    # 
+    # @param block [Proc] the block (with no parameters) that must return a new character every time it is called
+    def when_updating(&block)
+      @update = block
+    end
+    
+    # Call the block set with {#when_updating} and queues its returned byte into {#buffer}
+    def update
+      @buffer << (@update.call || empty)
+    end
+    
+    # Return the next available packet
+    # 
+    # @return [String] the next available packet
+    def next
+      @fiber.resume
+    end
+    
+    # Iterates a block over incoming packets
+    # 
+    # @yield [pkt]
+    # @yieldparam pkt [String] the next packet
+    # @return [Enumerator] an {Enumerator} when called without block
+    def each
+      return enum_for(:each) unless block_given?
+      loop do
+        yield self.next
+      end
+    end
+  
+    private
+    def fiber_init
+      @fiber = Fiber.new do
+        loop do # over packets
+          pkt = empty
+          loop do # over chars
+            begin
+              self.update
+            rescue BufferError
+              Fiber.yield self.clear #yelds @buffer AND clears it!
+            end
+            if @buffer.start_with?(@separator) &&
+               @buffer.end_with?(@separator) && 
+               @buffer != @separator then # end of packet
+              pkt = @buffer.slice!(0...-@separator.length)
+              break
+            elsif @buffer.end_with?(@separator) then # Incomplete packet
+              @buffer.slice!(0...-@separator.length)
+            end
+          end
+          Fiber.yield pkt
+        end
+        warn "Exiting fiber!"
+      end
+    end
+  
+    def empty
+      String.new("", encoding:@encoding)
+    end
+  
+  end
+end
+
+if $0 == __FILE__ then
+  require 'pry'
+  
+  str = "OKjhagshj asjhgOKjhjhg jhgasjdhg aOKjhahg ashg jhgjhaOKstopppp"
+  cb = MmGPS::Buffer.new
+  cb.separator = "OK"
+  cb.when_updating do
+    raise BufferError if str.empty?
+    str.slice!(0...1)
+  end
+  p cb
+  
+  binding.pry
+end

data/lib/mm_gps/mm_gps_module.rb

@@ -51,9 +51,8 @@ module MmGPS
   #   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)
     unless valid_crc16?(buf) then
-      raise MmGPSError.new("Invalid CRC", {reason: :nocrc, packet:buf, crc:crc16(buf)}) 
+      raise MmGPSError.new("Invalid CRC", {reason: :nocrc, packet:buf, crc:("%04X" % crc16(buf[0...-2]))}) 
     end
-    # warn "Invalid CRC" unless valid_crc16?(buf)
     header = buf[0..5].unpack('CCS<C')
     if header[2] == 1 then # Regular GPS Data
       result = {}
@@ -73,7 +72,7 @@ module MmGPS
     else
       unless valid_crc16?(buf) then
         raise MmGPSError.new("Unexpected packet type #{header[2]}",
-          {reason: :notype, packet:buf, crc:crc16(buf), type:header[2]}) 
+          {reason: :notype, packet:buf, crc:("%04X" % crc16(buf[0...-2])), type:header[2]}) 
       end
     end
     return result

data/lib/mm_gps/version.rb

@@ -1,3 +1,3 @@
 module MmGPS
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

data/test.rb

@@ -7,26 +7,15 @@ BAUD = 115200 # SerialPort class does not support non-standard 500 kbps
 beacon = MmGPS::Beacon.new(PORT, BAUD)
 beacon.trap # installs signal handler for CTRL-C
 
-puts "Syncing..."
-begin
-  beacon.sync # discards any byte until the starting sequence "\xFFG" arrives
-rescue MmGPSError => e
-  puts "Packet Error: #{e.inspect}, reason: #{e.data[:reason]}"
-  puts "Packet: #{MmGPS.hexify(e.data[:packet])}"
-rescue IOError => e
-  puts "Port closed #{e.inspect}"
-  exit
+# Standard each loop. Type CTRL-C for interrupting it
+beacon.each do |packet|
+  p packet
 end
 
-puts "Reading..."
-while not beacon.closed? do
-  begin
-    p beacon.get_packet
-  rescue MmGPSError => e
-    puts "Packet Error: #{e.inspect}, reason: #{e.data[:reason]}"
-    puts "Packet: #{MmGPS.hexify(e.data[:packet])}"
-  rescue IOError => e
-    puts "Port closed #{e.inspect}"
-    exit
-  end
-end
+
+# Use the enumerator:
+beacon.reopen      # Needed, since CTRL-C in previous example also closes the Serialport connection
+enum = beacon.each # gets the Enumerator
+p enum.take 10     # Next 10 packets from enum
+
+puts "Exiting"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mm_gps
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Paolo Bosetti
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-19 00:00:00.000000000 Z
+date: 2016-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: serialport
@@ -87,6 +87,7 @@ files:
 - formulas.nb
 - lib/mm_gps.rb
 - lib/mm_gps/mm_gps_beacon.rb
+- lib/mm_gps/mm_gps_buffer.rb
 - lib/mm_gps/mm_gps_module.rb
 - lib/mm_gps/version.rb
 - mm_gps.gemspec