rmodbus 1.3.3 → 2.1.3

data/lib/rmodbus/client/slave.rb

@@ -0,0 +1,333 @@
+# -*- coding: ascii
+# frozen_string_literal: true
+
+require "timeout"
+
+module ModBus
+  class Client
+    class Slave
+      include Errors
+      include Debug
+      include Options
+      # Number of times to retry on read and read timeouts
+      attr_accessor :uid
+
+      EXCEPTIONS = {
+        1 => IllegalFunction,
+        2 => IllegalDataAddress,
+        3 => IllegalDataValue,
+        4 => SlaveDeviceFailure,
+        5 => Acknowledge,
+        6 => SlaveDeviceBus,
+        8 => MemoryParityError
+      }.freeze
+      def initialize(uid, io)
+        @uid = uid
+        @io = io
+      end
+
+      # Returns a ModBus::ReadWriteProxy hash interface for coils
+      #
+      # @example
+      #  coils[addr] => [1]
+      #  coils[addr1..addr2] => [1, 0, ..-1]
+      #  coils[addr] = 0 => [0]
+      #  coils[addr1..addr2] = [1, 0, ..-1] => [1, 0, ..-1]
+      #
+      # @return [ReadWriteProxy] proxy object
+      def coils
+        ModBus::ReadWriteProxy.new(self, :coil)
+      end
+
+      # Read coils
+      #
+      # @example
+      #  read_coils(addr, ncoils) => [1, 0, ..-1]
+      #
+      # @param [Integer] addr address first coil
+      # @param [Integer] ncoils number coils
+      # @return [Array] coils
+      def read_coils(addr, ncoils = 1)
+        query("\x01#{addr.to_word}#{ncoils.to_word}").unpack_bits[0..ncoils - 1]
+      end
+
+      def read_coil(addr)
+        read_coils(addr, 1).first
+      end
+
+      # Write a single coil
+      #
+      # @example
+      #  write_single_coil(1, 0) => self
+      #
+      # @param [Integer] addr address coil
+      # @param [Integer] val value coil (0 or other)
+      # @return self
+      def write_single_coil(addr, val)
+        if [0, false].include?(val)
+          query("\x05#{addr.to_word}\x00\x00")
+        else
+          query("\x05#{addr.to_word}\xff\x00")
+        end
+        self
+      end
+      alias_method :write_coil, :write_single_coil
+
+      # Write multiple coils
+      #
+      # @example
+      #  write_multiple_coils(1, [0,1,0,1]) => self
+      #
+      # @param [Integer] addr address first coil
+      # @param [Array] vals written coils
+      def write_multiple_coils(addr, vals)
+        nbyte = ((vals.size - 1) >> 3) + 1
+        sum = 0
+        (vals.size - 1).downto(0) do |i|
+          sum <<= 1
+          sum |= 1 if vals[i].positive?
+        end
+
+        s_val = +""
+        nbyte.times do
+          s_val << (sum & 0xff).chr
+          sum >>= 8
+        end
+
+        query("\x0f#{addr.to_word}#{vals.size.to_word}#{nbyte.chr}#{s_val}")
+        self
+      end
+      alias_method :write_coils, :write_multiple_coils
+
+      # Returns a ModBus::ReadOnlyProxy hash interface for discrete inputs
+      #
+      # @example
+      #  discrete_inputs[addr] => [1]
+      #  discrete_inputs[addr1..addr2] => [1, 0, ..-1]
+      #
+      # @return [ReadOnlyProxy] proxy object
+      def discrete_inputs
+        ModBus::ReadOnlyProxy.new(self, :discrete_input)
+      end
+
+      # Read discrete inputs
+      #
+      # @example
+      #  read_discrete_inputs(addr, ninputs) => [1, 0, ..-1]
+      #
+      # @param [Integer] addr address first input
+      # @param[Integer] ninputs number inputs
+      # @return [Array] inputs
+      def read_discrete_inputs(addr, ninputs = 1)
+        query("\x02#{addr.to_word}#{ninputs.to_word}").unpack_bits[0..ninputs - 1]
+      end
+
+      def read_discrete_input(addr)
+        read_discrete_inputs(addr, 1).first
+      end
+
+      # Returns a read/write ModBus::ReadOnlyProxy hash interface for coils
+      #
+      # @example
+      #  input_registers[addr] => [1]
+      #  input_registers[addr1..addr2] => [1, 0, ..-1]
+      #
+      # @return [ReadOnlyProxy] proxy object
+      def input_registers
+        ModBus::ReadOnlyProxy.new(self, :input_register)
+      end
+
+      # Read input registers
+      #
+      # @example
+      #  read_input_registers(1, 5) => [1, 0, ..-1]
+      #
+      # @param [Integer] addr address first registers
+      # @param [Integer] nregs number registers
+      # @return [Array] registers
+      def read_input_registers(addr, nregs = 1)
+        query("\x04#{addr.to_word}#{nregs.to_word}").unpack("n*")
+      end
+
+      def read_input_register(addr)
+        read_input_registers(addr, 1).first
+      end
+
+      # Returns a ModBus::ReadWriteProxy hash interface for holding registers
+      #
+      # @example
+      #  holding_registers[addr] => [123]
+      #  holding_registers[addr1..addr2] => [123, 234, ..-1]
+      #  holding_registers[addr] = 123 => 123
+      #  holding_registers[addr1..addr2] = [234, 345, ..-1] => [234, 345, ..-1]
+      #
+      # @return [ReadWriteProxy] proxy object
+      def holding_registers
+        ModBus::ReadWriteProxy.new(self, :holding_register)
+      end
+
+      # Read holding registers
+      #
+      # @example
+      #  read_holding_registers(1, 5) => [1, 0, ..-1]
+      #
+      # @param [Integer] addr address first registers
+      # @param [Integer] nregs number registers
+      # @return [Array] registers
+      def read_holding_registers(addr, nregs = 1)
+        query("\x03#{addr.to_word}#{nregs.to_word}").unpack("n*")
+      end
+
+      def read_holding_register(addr)
+        read_holding_registers(addr, 1).first
+      end
+
+      # Write a single holding register
+      #
+      # @example
+      #  write_single_register(1, 0xaa) => self
+      #
+      # @param [Integer] addr address registers
+      # @param [Integer] val written to register
+      # @return self
+      def write_single_register(addr, val)
+        query("\x06#{addr.to_word}#{val.to_word}")
+        self
+      end
+      alias_method :write_holding_register, :write_single_register
+
+      # Write multiple holding registers
+      #
+      # @example
+      #  write_multiple_registers(1, [0xaa, 0]) => self
+      #
+      # @param [Integer] addr address first registers
+      # @param [Array] val written registers
+      # @return self
+      def write_multiple_registers(addr, vals)
+        s_val = vals.map(&:to_word).join
+
+        query("\x10#{addr.to_word}#{vals.size.to_word}#{(vals.size * 2).chr}#{s_val}")
+        self
+      end
+      alias_method :write_holding_registers, :write_multiple_registers
+
+      # Mask a holding register
+      #
+      # @example
+      #   mask_write_register(1, 0xAAAA, 0x00FF) => self
+      # @param [Integer] addr address registers
+      # @param [Integer] and_mask mask for AND operation
+      # @param [Integer] or_mask mask for OR operation
+      def mask_write_register(addr, and_mask, or_mask)
+        query("\x16#{addr.to_word}#{and_mask.to_word}#{or_mask.to_word}")
+        self
+      end
+
+      # Read/write multiple holding registers
+      #
+      # @example
+      #  read_write_multiple_registers(1, 5, 1, [0xaa, 0]) => [1, 0, ..-1]
+      #
+      # @param [Integer] addr_r address first registers to read
+      # @param [Integer] nregs number registers to read
+      # @param [Integer] addr_w address first registers to write
+      # @param [Array] vals written registers
+      # @return [Array] registers
+      def read_write_multiple_registers(addr_r, nregs, addr_w, vals)
+        s_val = vals.map(&:to_word).join
+
+        query("\x17#{addr_r.to_word}#{nregs.to_word}#{addr_w.to_word}" \
+              "#{vals.size.to_word}#{(vals.size * 2).chr}#{s_val}")
+          .unpack("n*")
+      end
+      alias_method :read_write_holding_registers, :read_write_multiple_registers
+
+      # rubocop:disable Layout/LineLength
+
+      # Request pdu to slave device
+      #
+      # @param [String] pdu request to slave
+      # @return [String] received data
+      #
+      # @raise [ResponseMismatch] the received echo response differs from the request
+      # @raise [ModBusTimeout] timed out during read attempt
+      # @raise [ModBusException] unknown error
+      # @raise [IllegalFunction] function code received in the query is not an allowable action for the server
+      # @raise [IllegalDataAddress] data address received in the query is not an allowable address for the server
+      # @raise [IllegalDataValue] value contained in the query data field is not an allowable value for server
+      # @raise [SlaveDeviceFailure] unrecoverable error occurred while the server was attempting to perform the requested action
+      # @raise [Acknowledge] server has accepted the request and is processing it, but a long duration of time will be required to do so
+      # @raise [SlaveDeviceBus] server is engaged in processing a long duration program command
+      # @raise [MemoryParityError] extended file area failed to pass a consistency check
+      def query(request)
+        tried = 0
+        response = ""
+        begin
+          ::Timeout.timeout(@read_retry_timeout, ModBusTimeout) do
+            send_pdu(request)
+            response = read_pdu unless uid.zero?
+          end
+        rescue ModBusTimeout
+          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 response.empty?
+
+        read_func = response.getbyte(0)
+        if read_func >= 0x80
+          exc_id = response.getbyte(1)
+          raise EXCEPTIONS[exc_id] unless EXCEPTIONS[exc_id].nil?
+
+          raise ModBusException.new, "Unknown error"
+        end
+
+        check_response_mismatch(request, response) if raise_exception_on_mismatch
+        response[2..-1]
+      end
+      # rubocop:enable Layout/LineLength
+
+      private
+
+      def check_response_mismatch(request, response)
+        read_func = response.getbyte(0)
+        data = response[2..-1]
+        # Mismatch functional code
+        send_func = request.getbyte(0)
+        msg = "Function code is mismatch (expected #{send_func}, got #{read_func})" if read_func != send_func
+
+        case read_func
+        when 1, 2
+          bc = (request.getword(3) / 8) + 1
+          msg = "Byte count is mismatch (expected #{bc}, got #{data.size} bytes)" if data.size != bc
+        when 3, 4
+          rc = request.getword(3)
+          msg = "Register count is mismatch (expected #{rc}, got #{data.size / 2} regs)" if data.size / 2 != rc
+        when 5, 6
+          exp_addr = request.getword(1)
+          got_addr = response.getword(1)
+          msg = "Address is mismatch (expected #{exp_addr}, got #{got_addr})" if exp_addr != got_addr
+
+          exp_val = request.getword(3)
+          got_val = response.getword(3)
+          msg = "Value is mismatch (expected 0x#{exp_val.to_s(16)}, got 0x#{got_val.to_s(16)})" if exp_val != got_val
+        when 15, 16
+          exp_addr = request.getword(1)
+          got_addr = response.getword(1)
+          msg = "Address is mismatch (expected #{exp_addr}, got #{got_addr})" if exp_addr != got_addr
+
+          exp_quant = request.getword(3)
+          got_quant = response.getword(3)
+          msg = "Quantity is mismatch (expected #{exp_quant}, got #{got_quant})" if exp_quant != got_quant
+        else
+          warn "Function (#{read_func}) is not supported raising response mismatch"
+        end
+
+        raise ResponseMismatch.new(msg, request, response) if msg
+      end
+    end
+  end
+end

data/lib/rmodbus/client.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module ModBus
   # @abstract
   class Client
+    autoload :Slave, "rmodbus/client/slave"
+
     include Errors
     include Debug
     include Options
@@ -13,12 +17,12 @@ module ModBus
     # @param *args depends on implementation
     # @yield return client object and close it before exit
     # @return [Client] client object
-    def initialize(*args, &block)
+    def initialize(*args)
       # Defaults
-      @debug = false
+      @logger = nil
       @raise_exception_on_mismatch = false
       @read_retry_timeout = 1
-      @read_retries = 10
+      @read_retries = 1
 
       @io = open_connection(*args)
       if block_given?
@@ -45,9 +49,9 @@ module ModBus
     #
     # @param [Integer, #read] uid slave devise
     # @return [Slave] slave object
-    def with_slave(uid, &block)
+    def with_slave(uid)
       slave = get_slave(uid, @io)
-      slave.debug = debug
+      slave.logger = logger
       slave.raise_exception_on_mismatch = raise_exception_on_mismatch
       slave.read_retries = read_retries
       slave.read_retry_timeout = read_retry_timeout
@@ -70,22 +74,23 @@ module ModBus
     end
 
     protected
-    def open_connection(*args)
-      #Stub conn object
+
+    def open_connection(*)
+      # Stub conn object
       @io = Object.new
 
-      @io.instance_eval """
+      @io.instance_eval <<~RUBY, __FILE__, __LINE__ + 1
         def close
         end
 
         def closed?
           true
         end
-        """
+      RUBY
       @io
     end
 
-    def get_slave(uid,io)
+    def get_slave(uid, io)
       Slave.new(uid, io)
     end
   end

data/lib/rmodbus/debug.rb

@@ -1,14 +1,20 @@
+# frozen_string_literal: true
+
+require "time"
+
 module ModBus
   module Debug
-    attr_accessor :debug, :raise_exception_on_mismatch,
-                  :read_retries, :read_retry_timeout
-
+    attr_accessor :raise_exception_on_mismatch,
+                  :read_retries,
+                  :read_retry_timeout,
+                  :logger
 
     private
-    # Put log message on standart output
+
+    # Put log message on standard output
     # @param [String] msg message for log
     def log(msg)
-      $stdout.puts msg if @debug
+      logger&.debug(msg)
     end
 
     # Convert string of byte to string for log
@@ -17,16 +23,7 @@ module ModBus
     # @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
+      msg.unpack1("H*").gsub(/\X{2}/, "[\\0]")
     end
   end
 end

data/lib/rmodbus/errors.rb

@@ -1,30 +1,53 @@
+# frozen_string_literal: true
+
 module ModBus
   module Errors
-    class ProxyException < StandardError
+    class ProxyException < RuntimeError
     end
 
-    class ModBusException < StandardError
+    class ModBusException < RuntimeError
     end
 
     class IllegalFunction < ModBusException
+      def initialize(msg = nil)
+        super(msg || "The function code received in the query is not an allowable action for the server")
+      end
     end
 
     class IllegalDataAddress < ModBusException
+      def initialize
+        super("The data address received in the query is not an allowable address for the server")
+      end
     end
 
     class IllegalDataValue < ModBusException
+      def initialize
+        super("A value contained in the query data field is not an allowable value for server")
+      end
     end
 
     class SlaveDeviceFailure < ModBusException
+      def initialize
+        super("An unrecoverable error occurred while the server was attempting to perform the requested action")
+      end
     end
 
     class Acknowledge < ModBusException
+      def initialize
+        super("The server has accepted the request and is processing it, but a long duration of time will be required to do so") # rubocop:disable Layout/LineLength
+      end
     end
 
     class SlaveDeviceBus < ModBusException
+      def initialize
+        super("The server is engaged in processing a long duration program command")
+      end
     end
 
     class MemoryParityError < ModBusException
+      def initialize
+        super("The extended file area failed to pass a consistency check")
+      end
     end
 
     class ModBusTimeout < ModBusException
@@ -32,6 +55,7 @@ module ModBus
 
     class ResponseMismatch < ModBusException
       attr_reader :request, :response
+
       def initialize(msg, request, response)
         super(msg)
         @request = request

data/lib/rmodbus/ext.rb

@@ -1,85 +1,106 @@
-class String
-
-  if RUBY_VERSION < "1.9"
-    def getbyte(index)
-      self[index].to_i
-    end
-  end
+# frozen_string_literal: true
 
+class String
+  # unpack a string of bytes into an array of integers (0 or 1)
+  # representing the bits in those bytes, according to how the
+  # ModBus protocol represents coils.
   def unpack_bits
-    array_bit = []
-    self.unpack('b*')[0].each_char do |c|
-        array_bit << c.to_i
+    result = []
+    each_byte do |b|
+      8.times do
+        # least significant bits first within each byte
+        result << (b & 0x01)
+        b >>= 1
+      end
     end
-    array_bit
+    result
   end
 
   # Get word by index
-  # @param [Integer] i index first bytes of word
+  # @param [Integer] index index first bytes of word
   # @return unpacked word
-  def getword(i)
-    self[i,2].unpack('n')[0]
+  def getword(index)
+    self[index, 2].unpack1("n")
   end
 end
 
 class Integer
-
-  # Shortcut or turning an integer into a word
+  # Shortcut for turning an integer into a word
   def to_word
-    [self].pack('n')
+    [self].pack("n")
   end
-
 end
 
 class Array
+  # Swap every pair of elements
+  def byteswap
+    even_elements_check
+    each_slice(2).flat_map(&:reverse)
+  end
+  alias_method :wordswap, :byteswap
 
-  # 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] }
+  # Given an array of 16-bit unsigned integers, turn it into an array of 16-bit signed integers.
+  def to_16i
+    pack("n*").unpack("s>*")
   end
 
-  # Given an array of 16bit Fixnum, we turn it into 32bit Int in little-endian order, halving the size
-  def to_32f_le
-    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)| [lsb, msb].pack('n*').unpack('g')[0] }
+  # Given an array of 16-bit unsigned integers, turn it into an array of 32-bit floats, halving the size.
+  # The pairs of 16-bit elements should be in big endian order.
+  def to_32f
+    even_elements_check
+    pack("n*").unpack("g*")
   end
 
-  # Given an array of 32bit Floats, we turn it into an array of 16bit Fixnums, doubling the size
+  # Given an array of 32-bit floats, turn it into an array of 16-bit unsigned integers, doubling the size.
   def from_32f
-    self.pack('g*').unpack('n*').each_slice(2).map { |arr| arr.reverse }.flatten
+    pack("g*").unpack("n*")
+  end
+
+  # Given an array of 16-bit unsigned integers, turn it into 32-bit unsigned integers, halving the size.
+  # The pairs of 16-bit elements should be in big endian order.
+  def to_32u
+    even_elements_check
+    pack("n*").unpack("N*")
   end
 
-  # Given an array of 16bit Fixnum, we turn it into 32bit Float in big-endian order, halving the size
+  # Given an array of 16-bit unsigned integers, turn it into 32-bit signed integers, halving the size.
+  # The pairs of 16-bit elements should be in big endian order.
   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] }
+    even_elements_check
+    pack("n*").unpack("l>*")
   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
+  # Given an array of 32bit unsigned integers, turn it into an array of 16 bit unsigned integers, doubling the size
+  def from_32u
+    pack("N*").unpack("n*")
   end
 
-  def pack_to_word
-    word = 0
-    s = ""
-    mask = 0x01
+  # Given an array of 32bit signed integers, turn it into an array of 16 bit unsigned integers, doubling the size
+  def from_32i
+    pack("l>*").unpack("n*")
+  end
 
-    self.each do |bit|
-      word |= mask if bit > 0
-      mask <<= 1
-      if mask  == 0x100
-        mask = 0x01
-        s << word.chr
-        word = 0
+  # pack an array of bits into a string of bytes,
+  # as the ModBus protocol dictates for coils
+  def pack_bits
+    # pack each slice of 8 bits per byte,
+    # forward order (bits 0-7 in byte 0, 8-15 in byte 1, etc.)
+    # non-multiples of 8 are just 0-padded
+    each_slice(8).map do |slice|
+      byte = 0
+      # within each byte, bit 0 is the LSB,
+      # and bit 7 is the MSB
+      slice.reverse_each do |bit|
+        byte <<= 1
+        byte |= 1 if bit.positive?
       end
-    end
-    unless mask == 0x01
-      s << word.chr
-    else
-      s
-    end
+      byte
+    end.pack("C*")
   end
 
+  private
+
+  def even_elements_check
+    raise ArgumentError, "Array requires an even number of elements: was #{size}" unless size.even?
+  end
 end

data/lib/rmodbus/options.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module ModBus
   module Options
     attr_accessor :raise_exception_on_mismatch,
-                  :read_retries, :read_retry_timeout
+                  :read_retries,
+                  :read_retry_timeout
   end
 end