rmodbus 0.5.0 → 1.0.0

data/lib/rmodbus/client.rb

@@ -1,6 +1,6 @@
 # RModBus - free implementation of ModBus protocol on Ruby.
 #
-# Copyright (C) 2008  Timin Aleksey
+# Copyright (C) 2008-2011  Timin Aleksey
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -12,202 +12,80 @@
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 
-require 'rmodbus/common'
-require 'rmodbus/exceptions'
-require 'rmodbus/ext'
-
-
 module ModBus
+  # @abstract
   class Client
     include Errors
-    include Common
-    # Number of times to retry on connection and read timeouts
-    attr_accessor :read_retries, :read_retry_timeout
-
-    def connection_retries
-      warn "[DEPRECATION] `connection_retries` is deprecated.  Please don't use it."
-      @connection_retries
-    end
-
-    def connection_retries=(value)
-      warn "[DEPRECATION] `connection_retries=` is deprecated.  Please don't use it."
-      @connection_retries = value
-    end
-
 
-    Exceptions = { 
-          1 => IllegalFunction.new("The function code received in the query is not an allowable action for the server"),
-          2 => IllegalDataAddress.new("The data address received in the query is not an allowable address for the server"),
-          3 => IllegalDataValue.new("A value contained in the query data field is not an allowable value for server"),
-          4 => SlaveDeviceFailure.new("An unrecoverable error occurred while the server was attempting to perform the requested action"),
-          5 => Acknowledge.new("The server has accepted the request and is processing it, but a long duration of time will be required to do so"),
-          6 => SlaveDeviceBus.new("The server is engaged in processing a long duration program command"),
-          8 => MemoryParityError.new("The extended file area failed to pass a consistency check")
-    }
-    def initialize
-      @connection_retries = 10
-      @read_retries = 10
-      @read_retry_timeout = 1
-    end
-    # Read value *ncoils* coils starting with *addr*
-    #
-    # Return array of their values
-    def read_coils(addr, ncoils)
-      query("\x1" + addr.to_word + ncoils.to_word).unpack_bits[0..ncoils-1]
-    end
-
-    # Read value *ncoils* discrete inputs starting with *addr*
-    #
-    # Return array of their values
-    def read_discrete_inputs(addr, ncoils)
-      query("\x2" + addr.to_word + ncoils.to_word).unpack_bits[0..ncoils-1]
-    end
-
-    # Deprecated version of read_discrete_inputs
-    def read_discret_inputs(addr, ncoils)
-      #warn "[DEPRECATION] `read_discret_inputs` is deprecated.  Please use `read_discrete_inputs` instead."
-      read_discrete_inputs(addr, ncoils)
-    end
-
-    # Read value *nreg* holding registers starting with *addr*
-    #
-    # Return array of their values
-    def read_holding_registers(addr, nreg) 
-      query("\x3" + addr.to_word + nreg.to_word).unpack('n*')
-    end
-
-    # Read value *nreg* input registers starting with *addr*
-    #
-    # Return array of their values
-    def read_input_registers(addr, nreg)
-      query("\x4" + addr.to_word + nreg.to_word).unpack('n*')
-    end
-
-    # Write *val* in *addr* coil 
-    #
-    # if *val* lager 0 write 1
-    #
-    # Return self
-    def write_single_coil(addr, val)
-      if val == 0
-        query("\x5" + addr.to_word + 0.to_word)
+    # Initialized client (alias :connect)
+    # @example
+    #   Client.new(any_args) do |client|
+    #     client.closed? #=> false
+    #   end
+    # @param *args depends on implementation
+    # @yield return client object and close it before exit
+    # @return [Client] client object
+    def initialize(*args, &block)
+      @io = open_connection(*args)
+      if block_given?
+        yield self
+        close
       else
-        query("\x5" + addr.to_word + 0xff00.to_word) 
+        self
       end
-      self
     end
 
-    # Write *val* in *addr* register
-    #
-    # Return self
-    def write_single_register(addr, val)
-      query("\x6" + addr.to_word + val.to_word)
-      self
+    class << self
+      alias_method :connect, :new
     end
 
-    # Write *val* in coils starting with *addr*
+    # Given slave object
+    # @example
+    #   cl = Client.new
+    #   cl.with_slave(1) do |slave|
+    #     slave.holding_registers[0..100]
+    #   end
     #
-    # *val* it is array of bits
-    #
-    # Return self
-    def write_multiple_coils(addr, val)
-      nbyte = ((val.size-1) >> 3) + 1
-      sum = 0
-      (val.size - 1).downto(0) do |i|
-        sum = sum << 1
-        sum |= 1 if val[i] > 0
-      end
-   
-      s_val = ""
-      nbyte.times do
-        s_val << (sum & 0xff).chr
-        sum >>= 8 
-      end
-
-      query("\xf" + addr.to_word + val.size.to_word + nbyte.chr + s_val)
-      self
-    end
-
-    # Write *val* in registers starting with *addr*
-    #
-    # *val* it is array of integer
-    #
-    # Return self
-    def write_multiple_registers(addr, val)
-      s_val = ""
-      val.each do |reg|
-        s_val << reg.to_word
+    # @param [Integer, #read] uid slave devise
+    # @return [Slave] slave object
+    def with_slave(uid, &block)
+      slave = get_slave(uid, @io)
+      if block_given?
+        yield slave
+      else
+        slave
       end
-
-      query("\x10" + addr.to_word + val.size.to_word + (val.size * 2).chr + s_val)
-      self
     end
 
-    # Write *current value & and_mask | or mask in *addr* register
-    #
-    # Return self
-    def mask_write_register(addr, and_mask, or_mask)
-      query("\x16" + addr.to_word + and_mask.to_word + or_mask.to_word)
-      self  
+    # Check connections
+    # @return [Boolean]
+    def closed?
+      @io.closed?
     end
 
-    def query(pdu)    
-      tried = 0
-      begin
-        timeout(@read_retry_timeout, ModBusTimeout) do 
-          send_pdu(pdu)
-          pdu = read_pdu
-        end
-      rescue ModBusTimeout => err
-        log "Timeout of read operation: (#{@read_retries - tried})"
-        tried += 1
-        retry unless tried >= @read_retries
-        raise ModBusTimeout.new, "Timed out during read attempt"
-      end
-    
-      return nil if pdu.size == 0
-
-      if pdu.getbyte(0) >= 0x80
-        exc_id = pdu.getbyte(1)
-        raise Exceptions[exc_id] unless Exceptions[exc_id].nil?
-
-        raise ModBusException.new, "Unknown error"
-      end
-      pdu[2..-1]
+    # Close connections
+    def close
+      @io.close unless @io.closed?
     end
 
     protected
+    def open_connection(*args)
+      #Stub conn object
+      @io = Object.new
 
-    def send_pdu(pdu)
-    end
-
-    def read_pdu
-    end
+      @io.instance_eval """
+        def close
+        end
 
-    def close
+        def closed?
+          true
+        end
+        """
+      @io
     end
 
-	# We have to read specific amounts of numbers of bytes from the network depending on the function code and content
-    def read_rtu_response(io)
-	  # Read the slave_id and function code
-	  msg = io.read(2) 
-      function_code = msg.getbyte(1)
-      case function_code
-        when 1,2,3,4 then
-          # read the third byte to find out how much more 
-          # we need to read + CRC
-          msg += io.read(1)
-          msg += io.read(msg.getbyte(2)+2)
-        when 5,6,15,16 then
-          # We just read in an additional 6 bytes
-          msg += io.read(6)
-        when 22 then
-          msg += io.read(8)
-        when 0x80..0xff then
-          msg += io.read(4)
-        else
-          raise ModBus::Errors::IllegalFunction, "Illegal function: #{function_code}"
-      end
+    def get_slave(uid,io)
+      Slave.new(uid, io)
     end
   end
 end

data/lib/rmodbus/common.rb

@@ -1,23 +1,50 @@
+# RModBus - free implementation of ModBus protocol in Ruby.
+#
+# Copyright (C) 2010  Timin Aleksey
+# Copyright (C) 2010  Kelley Reynolds
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
 module ModBus
-	module Common
+  module Common
+    # @return [Boolean] debug mode
+    # default false
+    attr_accessor :debug
+
+    @debug = false
 
-		private
-		def log(msg)
-			$stdout.puts msg if @debug
-		end
+    private
+    # Put log message on standart output
+    # @param [String] msg message for log
+    def log(msg)
+      $stdout.puts msg if @debug
+    end
 
-		def logging_bytes(msg)
-			result = ""
-			msg.each_byte do |c|
-				byte = if c < 16
-					'0' + c.to_s(16)
-				else
-					c.to_s(16)
-				end
-				result << "[#{byte}]"
-			end
-			result
-		end
-	end
+    # Convert string of byte to string for log
+    # @example
+    #   logging_bytes("\x1\xa\x8") => "[01][0a][08]"
+    # @param [String] msg input string
+    # @return [String] readable string of bytes
+    def logging_bytes(msg)
+     result = ""
+     msg.each_byte do |c|
+       byte = if c < 16
+         '0' + c.to_s(16)
+       else
+          c.to_s(16)
+       end
+         result << "[#{byte}]"
+      end
+      result
+    end
+  end
 end
 

data/lib/rmodbus/{exceptions.rb → errors.rb}

@@ -15,6 +15,9 @@ module ModBus
 
   module Errors
 
+    class ProxyException < StandardError
+    end
+
     class ModBusException < StandardError
     end
 

data/lib/rmodbus/ext.rb

@@ -27,19 +27,42 @@ class String
     end
     array_bit
   end
-
+  
 end
 
 class Integer
 
+  # Shortcut or turning an integer into a word
   def to_word
-    (self >> 8).chr + (self & 0xff).chr 
+    [self].pack('n')
   end
 
 end
 
 class Array
 
+  # Given an array of 16bit Fixnum, we turn it into 32bit Int in big-endian order, halving the size
+  def to_32f
+    raise "Array requires an even number of elements to pack to 32bits: was #{self.size}" unless self.size.even?
+    self.each_slice(2).map { |(lsb, msb)| [msb, lsb].pack('n*').unpack('g')[0] }
+  end
+    
+  # Given an array of 32bit Floats, we turn it into an array of 16bit Fixnums, doubling the size
+  def from_32f
+    self.pack('g*').unpack('n*').each_slice(2).map { |arr| arr.reverse }.flatten
+  end
+
+  # Given an array of 16bit Fixnum, we turn it into 32bit Float in big-endian order, halving the size
+  def to_32i
+    raise "Array requires an even number of elements to pack to 32bits: was #{self.size}" unless self.size.even?
+    self.each_slice(2).map { |(lsb, msb)| [msb, lsb].pack('n*').unpack('N')[0] }
+  end
+
+  # Given an array of 32bit Fixnum, we turn it into an array of 16bit fixnums, doubling the size
+  def from_32i
+    self.pack('N*').unpack('n*').each_slice(2).map { |arr| arr.reverse }.flatten
+  end
+
   def pack_to_word
     word = 0
     s = ""

data/lib/rmodbus/proxy.rb

@@ -0,0 +1,54 @@
+# ReadOnly and ReadWrite hash interface for modbus registers and coils
+#
+# Copyright (C) 2010  Kelley Reynolds
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+module ModBus
+  # Given a slave and a type of operation, execute a single or multiple read using hash syntax
+  class ReadOnlyProxy
+    # Initialize a proxy for a slave and a type of operation
+    def initialize(slave, type)
+      @slave, @type = slave, type
+    end
+
+    # Read single or multiple values from a modbus slave depending on whether a Fixnum or a Range was given.
+    # Note that in the case of multiples, a pluralized version of the method is sent to the slave
+    def [](key)
+      if key.instance_of?(Fixnum)
+        @slave.send("read_#{@type}", key, 1)
+      elsif key.instance_of?(Range)
+        @slave.send("read_#{@type}s", key.first, key.count)
+      else
+        raise ProxyException, "Invalid argument, must be integer or range. Was #{key.class}"
+      end
+    end
+  end
+  
+  class ReadWriteProxy < ReadOnlyProxy
+    # Write single or multiple values to a modbus slave depending on whether a Fixnum or a Range was given.
+    # Note that in the case of multiples, a pluralized version of the method is sent to the slave. Also when
+    # writing multiple values, the number of elements must match the number of registers in the range or an exception is raised
+    def []=(key, val)
+      if key.instance_of?(Fixnum)
+        @slave.send("write_#{@type}", key, val)
+      elsif key.instance_of?(Range)
+        if key.count != val.size
+          raise ProxyException, "The size of the range must match the size of the values (#{key.count} != #{val.size})"
+        end
+
+        @slave.send("write_#{@type}s", key.first, val)
+      else
+        raise ProxyException, "Invalid argument, must be integer or range. Was #{key.class}"
+      end
+    end
+  end
+
+end

data/lib/rmodbus/{crc16.rb → rtu.rb}

@@ -1,6 +1,7 @@
 # RModBus - free implementation of ModBus protocol in Ruby.
 #
-# Copyright (C) 2010  Timin Aleksey
+# Copyright (C) 2010 - 2011  Timin Aleksey
+# Copyright (C) 2010  Kelley Reynolds
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -13,7 +14,75 @@
 # GNU General Public License for more details.
 
 module ModBus
-  module CRC16
+  module RTU
+    private
+
+    # We have to read specific amounts of numbers of bytes from the network depending on the function code and content
+    def read_rtu_response(io)
+	    # Read the slave_id and function code
+	    msg = io.read(2)
+      function_code = msg.getbyte(1)
+      case function_code
+        when 1,2,3,4 then
+          # read the third byte to find out how much more
+          # we need to read + CRC
+          msg += io.read(1)
+          msg += io.read(msg.getbyte(2)+2)
+        when 5,6,15,16 then
+          # We just read in an additional 6 bytes
+          msg += io.read(6)
+        when 22 then
+          msg += io.read(8)
+        when 0x80..0xff then
+          msg += io.read(4)
+        else
+          raise ModBus::Errors::IllegalFunction, "Illegal function: #{function_code}"
+      end
+    end
+
+    def read_rtu_request(io)
+			# Read the slave_id and function code
+			msg = io.read(2)
+
+			# If msg is nil, then our client never sent us anything and it's time to disconnect
+			return if msg.nil?
+
+			function_code = msg.getbyte(1)
+			if [1, 2, 3, 4, 5, 6].include?(function_code)
+				# read 6 more bytes and return the message total message
+				msg += io.read(6)
+			elsif [15, 16].include?(function_code)
+				# Read in first register, register count, and data bytes
+				msg += io.read(5)
+				# Read in however much data we need to + 2 CRC bytes
+				msg += io.read(msg.getbyte(6) + 2)
+			else
+				raise ModBus::Errors::IllegalFunction, "Illegal function: #{function_code}"
+			end
+
+			log "Server RX (#{msg.size} bytes): #{logging_bytes(msg)}"
+
+			msg
+		end
+
+    def serv_rtu_requests(io, &blk)
+      loop do
+        # read the RTU message
+        msg = read_rtu_request(io)
+        # If there is no RTU message, we're done serving this client
+        break if msg.nil?
+
+        if msg.getbyte(0) == @uid and msg[-2,2].unpack('n')[0] == crc16(msg[0..-3])
+          pdu = yield msg
+          resp = @uid.chr + pdu
+          resp << crc16(resp).to_word
+          log "Server TX (#{resp.size} bytes): #{logging_bytes(resp)}"
+          io.write resp
+		    end
+	    end
+    end
+
+    # Calc CRC16 for massage
     def crc16(msg)
       crc_lo = 0xff
       crc_hi = 0xff
@@ -65,5 +134,7 @@ module ModBus
         0x48, 0x49, 0x89, 0x4B, 0x8B, 0x8A, 0x4A, 0x4E, 0x8E, 0x8F, 0x4F, 0x8D, 0x4D, 0x4C, 0x8C,
         0x44, 0x84, 0x85, 0x45, 0x87, 0x47, 0x46, 0x86, 0x82, 0x42, 0x43, 0x83, 0x41, 0x81, 0x80,
         0x40]
+
   end
 end
+

data/lib/rmodbus/rtu_client.rb

@@ -1,6 +1,6 @@
 # RModBus - free implementation of ModBus protocol in Ruby.
 #
-# Copyright (C) 2009  Timin Aleksey
+# Copyright (C) 2009-2011  Timin Aleksey
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -11,127 +11,31 @@
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-require 'rmodbus/crc16'
-
-begin
-  require 'rubygems'
-rescue
-end
-require 'serialport'
-
 module ModBus
-  
+  # RTU client implementation
+  # @example
+  #   RTUClient.connect('/dev/ttyS1', 9600) do |cl|
+  #     cl.with_slave(uid) do |slave|
+  #       slave.holding_registers[0..100]
+  #     end
+  #   end
+  #
+  # @see RTUClient#open_connection
+  # @see Client#initialize
   class RTUClient < Client
-
-    include CRC16
-    attr_reader :port, :baud, :slave, :data_bits, :stop_bits, :parity, :read_timeout
-    attr_accessor :debug
-
-    # Connect with RTU server
-    #
-    # port - serial port of connections with RTU server
-    #
-    # baud - rate sp of connections with RTU server
-    #
-    # slaveaddr - slave ID of the RTU server
-    #
-    # Options:
-    #
-    # :data_bits => from 5 to 8
-    #
-    # :stop_bits => 1 or 2
-    #
-    # :parity => NONE, EVEN or ODD
-    #
-    # RTUClient.connect('/dev/port1') do |cl|
-    #
-    #   put cl.read_holding_registers(0, 10)
-    #
-    # end
-    def self.connect(port, baud=9600, slaveaddr=1, options = {})
-      cl = RTUClient.new(port, baud, slaveaddr, options) 
-      yield cl
-      cl.close
-    end
-
-    # Connect with RTU server
-    #
-    # port - serial port of connections with RTU server
-    #
-    # baud - rate sp of connections with RTU server
-    #
-    # data_bits - from 5 to 8
-    #
-    # stop_bits - 1 or 2
-    #
-    # parity - NONE, EVEN or ODD
-    #
-    # slaveaddr - slave ID of the RTU server    # Connect with RTU server
-    #
-    # port - serial port of connections with RTU server
-    #
-    # baud - rate sp of connections with RTU server
-    #
-    # slaveaddr - slave ID of the RTU server
-    #
-    # Options:
-    #
-    # :data_bits => from 5 to 8
-    #
-    # :stop_bits => 1 or 2
-    #
-    # :parity => NONE, EVEN or ODD
-    #
-    # :read_timeout => default 5 ms
-    def initialize(port, baud=9600, slaveaddr=1, options = {})
-      @port, @baud, @slave = port, baud, slaveaddr
-      
-      @data_bits, @stop_bits, @parity, @read_timeout = 8, 1, SerialPort::NONE, 5
-
-      @data_bits = options[:data_bits] unless options[:data_bits].nil?
-      @stop_bits = options[:stop_bits] unless options[:stop_bits].nil?
-      @parity = options[:parity] unless options[:parity].nil?
-      @read_timeout = options[:read_timeout] unless options[:read_timeout].nil?
-
-      @debug = false
-
-      @sp = SerialPort.new(@port, @baud, @data_bits, @stop_bits, @parity)
-      @sp.read_timeout = @read_timeout
-
-      super()
-    end
-
-    def close
-      @sp.close unless @sp.closed?
-    end
-
-    def closed?
-      @sp.closed?
-    end
+    include RTU
+    include SP
 
     protected
-    def send_pdu(pdu)
-      msg = @slave.chr + pdu 
-      msg << crc16(msg).to_word
-      @sp.write msg
-
-      log "Tx (#{msg.size} bytes): " + logging_bytes(msg)
+    # Open serial port
+    # @see SP#open_serial_port
+    def open_connection(port, baud=9600, opts = {})
+      open_serial_port(port, baud, opts)
     end
 
-    def read_pdu
-	  msg = read_rtu_response(@sp)
-
-      log "Rx (#{msg.size} bytes): " + logging_bytes(msg)
-
-      if msg.getbyte(0) == @slave
-        return msg[1..-3] if msg[-2,2].unpack('n')[0] == crc16(msg[0..-3])
-        log "Ignore package: don't match CRC"
-	  else 
-        log "Ignore package: don't match slave ID"
-      end
-      loop do
-        #waite timeout  
-      end
+    # @private
+    def get_slave(uid, io)
+      RTUSlave.new(uid, io)
     end
   end
 end