rs232 0.1.3 → 0.1.4

data/README

@@ -1,34 +1,32 @@
-##
- #  
- #                          RS232
- #    
- #  Ruby interface to Windows Serial Port API
- #  
- #  author      hugo benichi
- #  email       hugo.benichi@m4x.org
- #  copyright   2012 hugo benichi  
- #  version     0.1.3
- #
- ##
- 
-  installation:  
- 
-    run in the root directory
-      rake gem_install
-    
-    it will compile the gem library and produce a .gem package for ruby
-    it will then install the .gem automatically
-    
-  usage: 
-  
+
+
+                          RS232
+
+  Ruby interface to Windows Serial Port API
+
+  author      hugo benichi
+  email       hugo[dot]benichi[at]m4x[dot]org
+  copyright   2012 hugo benichi
+  version     0.1.4
+
+
+  Installation:
+
+    To compile the gem, produce a .gem package and install it automatically, run
+    from the root directory:
+
+    $ rake gem_install
+
+  Usage:
+
     cf test/test_rs232.rb
-    
+
     first, require the gem with
       require 'rs232'
-      
-    then instance an object of RS232, passing an address, and optionally parameters to configure
+
+    then create an RS232 instance, passing an address and optional conf params
       serial_port = RS232.new 'COM1'
-    
+
     the default parameters are
       baud rate: 9600
       8 bits
@@ -37,4 +35,4 @@
       control flow hardware (RTS/CTS)
       delimiters "\r\n"
 
-    you can directly use the RS232 instance with the 'write', 'read', and 'query' commands
+    you can use RS232 instances with 'write', 'read' and 'query' commands

data/lib/rs232.rb

@@ -2,8 +2,10 @@ class RS232
 
   require 'ffi'
   
-  attr_accessor :report, :delimiter
-  attr_reader   :count, :error
+  attr_accessor :report,    # flag set by client, if true reports read/write bits
+                :delimiter  # line delimiter caracters, default: "\r\n"
+  attr_reader   :count,     # number of last read/write bits
+                :error      # last error/status code 
   
   # serial port object constructor
   # also sets the parameters and timeout properties through an hash argument
@@ -27,10 +29,14 @@ class RS232
     share = params[:share] || 0 #Win32::FILE_SHARE_DELETE
     type  = params[:file]  || Win32::OPEN_EXISTING
     attr  = params[:attr]  || Win32::FILE_ATTRIBUTE_NORMAL
+
     @serial = Win32::CreateFileA( address, mode, share, nil, type, attr, nil) 
     @error  = Win32.error_check
+
     puts "RS232 >> got file handle 0x%.8x for com port %s" % [@serial, address]   
-    DCB.new.tap do |p|
+
+    # com port connection configuration with C struct
+    DCB.new.tap do |p|  # check below for DCB struct definition
       p[:dcblength] = DCB::Sizeof  
       Win32::GetCommState @serial, p
       p[:baudrate] = params[:baudrate] || 9600
@@ -40,6 +46,8 @@ class RS232
       Win32::SetCommState @serial, p
       @error = Win32.error_check
     end        
+
+    # com port connection timeouts configuration with C struct
     CommTimeouts.new.tap do |timeouts|
       timeouts[:read_interval_timeout]          = params[:read_interval_timeout]          ||  50 
       timeouts[:read_total_timeout_multiplier]  = params[:read_total_timeout_multiplier]  ||  50
@@ -49,13 +57,15 @@ class RS232
       Win32::SetCommTimeouts @serial, timeouts
       @error = Win32.error_check
     end    
+
     grow_buffer 128
     @count = FFI::MemoryPointer.new :uint, 1
     @report = false
     @delimiter = params[:delimiter] || "\r\n"
   end
   
-  # writes a string to the Serial port and happens the delimiter characters stores in @delimiters
+  # writes a string to the Serial port
+  # automatically appends the delimiter characters stored in @delimiter
   def write string
     command = "%s%s" % [string.chomp, @delimiter]
     grow_buffer command.length
@@ -66,7 +76,7 @@ class RS232
     puts "write count %i" % @count.read_uint32 if @report
   end
   
-  # read a string from the Serial port
+  # reads a string from the Serial port
   def read
     Win32::ReadFile @serial, @buffer, @buflen, @count, nil
     @error = Win32.error_check
@@ -74,27 +84,31 @@ class RS232
     @buffer.read_string.chomp
   end
   
-  # write and read helper method
+  # write + read helper method for queries
   def query string
     write string
     read
   end
   
-  # close the Com port
+  # closes the Com port TODO: sets this as object finilizer
   def stop
     Win32::CloseHandle @serial
     @error = Win32.error_check
   end
   
-  # increase the buffer size for reading and writing
-  def grow_buffer size   
-    @buffer = FFI::MemoryPointer.new :char, @buflen = size if @buffer.nil? || @buflen < size
+  # increases the buffer size for reading and writing
+  def grow_buffer size
+    if @buffer.nil? || @buflen < size
+      @buffer = FFI::MemoryPointer.new :char, @buflen = size
+    end
   end
   
   # wraps the native Windows API functions for file IO and COMM port found in kernel32.dll
   module Win32
+
     extend FFI::Library
     ffi_lib 'kernel32.dll'
+
     [
       [ :GetLastError,    [],  :uint32],
       [ :CreateFileA,     [:pointer, :uint32, :uint32, :pointer, :uint32, :uint32, :pointer],  :pointer],
@@ -110,55 +124,59 @@ class RS232
       [ :GetCommTimeouts, [:pointer, :pointer], :int32],
       [ :SetCommTimeouts, [:pointer, :pointer], :int32],
     ].each{ |sig| attach_function *sig }    
+
     def self.error_code
       err = self::GetLastError()
       "error code: %i | 0x%.8x" % [err,err]
     end
+
     def self.error_check
       self::GetLastError().tap{ |err| puts "error: %i | 0x%.8x" % [err,err] if err != 0 }
     end    
-	  # consts from Windows seven sdk. extract with 
-	  #   grep -i "generic_read" *.h
-	  # from the /Include directory
-	  FILE_SHARE_DELETE = 0x00000004
-	  FILE_SHARE_READ   = 0x00000001
-	  FILE_SHARE_WRITE  = 0x00000002
-	  FILE_SHARE_ALL    = FILE_SHARE_WRITE | FILE_SHARE_READ | FILE_SHARE_DELETE
+
+    # consts from Windows seven sdk. extract with 
+    # grep -i "generic_read" *.h
+    # from the /Include directory
+    FILE_SHARE_DELETE = 0x00000004
+    FILE_SHARE_READ   = 0x00000001
+    FILE_SHARE_WRITE  = 0x00000002
+    FILE_SHARE_ALL    = FILE_SHARE_WRITE | FILE_SHARE_READ | FILE_SHARE_DELETE
     GENERIC_READ  = 0x80000000               
     GENERIC_WRITE = 0x40000000
-	  CREATE_NEW    = 1
-	  CREATE_ALWAYS = 2
+    CREATE_NEW    = 1
+    CREATE_ALWAYS = 2
     OPEN_EXISTING = 3
-	  OPEN_ALWAYS   = 4
+    OPEN_ALWAYS   = 4
     FILE_ATTRIBUTE_NORMAL = 0x00000080
+
   end
   
   # this struct is used by windows to configure the COMM port
   class DCB < FFI::Struct
     layout  :dcblength,   :uint32,
             :baudrate,    :uint32,
-            :flags,       :uint32,              # the :flag uint32 is actually a bit fields compound with structure
-            :wreserved,   :uint16,              #   uint32 fBinary :1;
-            :xonlim,      :uint16,              #   uint32 fParity :1;
-            :xofflim,     :uint16,              #   uint32 fParity :1;
-            :bytesize,    :uint8,               #   uint32 fOutxCtsFlow :1;
-            :parity,      :uint8,               #   uint32 fOutxDsrFlow :1;
-            :stopbits,    :uint8,               #   uint32 fDtrControl :2;
-            :xonchar,     :int8,                #   uint32 fDsrSensitivity :1;
-            :xoffchar,    :int8,                #   uint32 fTXContinueOnXoff :1;
-            :errorchar,   :int8,                #   uint32 fOutX :1;
-            :eofchar,     :int8,                #   uint32 fInX :1;
-            :evtchar,     :int8,                #   uint32 fErrorChar :1;
-            :wreserved1,  :uint16               #   uint32 fNull :1;
-                                                #   uint32 fRtsControl :2;
-                                                #   uint32 fAbortOnError :1;
-                                                #   uint32 fDummy2 :17;          
-    Sizeof      = 28 # this is used to tell windows the size of its own struct, not sure why it is necessary (different Windows version)
-    ONESTOPBIT  = 0
+            :flags,       :uint32,    # :flag is actually a bit fields compound:
+            :wreserved,   :uint16,    #   uint32 fBinary :1;
+            :xonlim,      :uint16,    #   uint32 fParity :1;
+            :xofflim,     :uint16,    #   uint32 fParity :1;
+            :bytesize,    :uint8,     #   uint32 fOutxCtsFlow :1;
+            :parity,      :uint8,     #   uint32 fOutxDsrFlow :1;
+            :stopbits,    :uint8,     #   uint32 fDtrControl :2;
+            :xonchar,     :int8,      #   uint32 fDsrSensitivity :1;
+            :xoffchar,    :int8,      #   uint32 fTXContinueOnXoff :1;
+            :errorchar,   :int8,      #   uint32 fOutX :1;
+            :eofchar,     :int8,      #   uint32 fInX :1;
+            :evtchar,     :int8,      #   uint32 fErrorChar :1;
+            :wreserved1,  :uint16     #   uint32 fNull :1;
+                                      #   uint32 fRtsControl :2;
+                                      #   uint32 fAbortOnError :1;
+                                      #   uint32 fDummy2 :17;          
+    Sizeof      = 28 # this is used to tell windows the size of its own struct, 
+    ONESTOPBIT  = 0  #   not sure why necessary (different Windows versions ?)
     NOPARITY    = 0
   end
   
-  # this structure is used to set timeout properties of the opened COM ports
+  # this struct is used to set timeout properties of the opened COM ports
   class CommTimeouts < FFI::Struct
     layout  :read_interval_timeout,           :uint32, 
             :read_total_timeout_multiplier,   :uint32, 

data/rakefile.rb

@@ -1,11 +1,20 @@
-task :test_global do ruby "test/test_rs232.rb" end
-task :test_local  do ruby "-Ilib test/test_rs232.rb" end
+task :test_global do                # test if run after gem install
+  ruby "test/test_rs232.rb"
+end
+
+task :test_local  do                # test if run from gem root dir
+    ruby "-Ilib test/test_rs232.rb"
+end
+
+task :gem_build   do
+  sh "gem build rs232.gemspec"
+end
 
-task :gem_build   do sh "gem build rs232.gemspec" end
 task :gem_install => :gem_build do 
-  gemfile = Dir.new("./").entries.select{ |f| f =~ /rs232-[\d]+\.[\d]+\.[\d]+.gem/ }.sort[-1]
-  puts "installing %s" % gemfile
+  gemfile = Dir.new("./").entries.select{ |f|
+    f =~ /rs232-[\d]+\.[\d]+\.[\d]+.gem/
+  }.sort[-1]
   sh "gem install --local %s" % gemfile
 end
 
-task :default => :test_local
+task :default => :test_local

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rs232
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-24 00:00:00.000000000 Z
+date: 2013-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &16159800 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *16159800
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Allows to script access to the serial port on Windows. Simple read and
   write commands
-email: hugo.benichi@m4x.org
+email: hugo[dot]benichi[at]m4x[dot]org
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -53,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Ruby interface to Windows Serial Port API