rmodbus 1.0.0-java

data/NEWS.md

@@ -0,0 +1,52 @@
+Release 1.0.0
+=====================================
+New API for client part of library
+---------------------------------------
+
+Example:
+
+    require 'rmodbus'
+
+    ModBus::TCPClient.new('127.0.0.1', 8502) do |cl|
+      cl.with_slave(1) do |slave|
+        # Read a single holding register at address 16
+        slave.holding_registers[16]
+
+        # Write a single holding register at address 16
+        slave.holding_registers[16] = 123
+
+        # Read holding registers 16 through 20
+        slave.holding_registers[16..20]
+
+        # Write holding registers 16 through 20 with some values
+        slave.holding_registers[16..20] = [1, 2, 3, 4, 5]
+      end
+    end
+
+for more information [see](http://rdoc.info/gems/rmodbus/1.0.0/frames)
+
+Conversion to/from 32bit registers
+-----------------------------------
+
+Some modbus devices use two registers to store 32bit values.
+RModbus provides some helper functions to go back and forth between these two things when reading/writing.
+The built-in examples assume registers in a particular order but it's trivial to change.
+
+    # Reading values in multiple registers (you can read more than 2 and convert them all so long as they are in multiples of 2)
+    res = slave.holding_registers[0..1]
+    res.inspect => [20342, 17344]
+    res.to_32i => [1136676726]
+    res.to_32f => [384.620788574219]
+
+    # Writing 32b values to multiple registers
+    cl.holding_registers[0..1] = [1136676726].from_32i
+    cl.holding_registers[0..1] => [20342, 17344]
+    cl.holding_registers[2..3] = [384.620788574219].from_32f
+    cl.holding_registers[2..3] => [20342, 17344]
+
+Support JRuby
+--------------------------------------
+Now you could use RModBus on JRuby without RTU implementation.
+
+RTU classes requires gem [serialport](https://github.com/hparra/ruby-serialport) which
+currently not compatible with JRuby

data/README.md

@@ -0,0 +1,87 @@
+RModBus
+==========================
+
+**RModBus** - free implementation of protocol ModBus.
+
+Features
+---------------------------
+  - Ruby 1.8, Ruby 1.9, JRuby (without serial ModBus RTU)
+  - TCP, RTU, RTU over TCP protocols
+  - Client(master) and server(slave)
+  - 16, 32 -bit and float registers
+
+Support functions
+---------------------------
+  * Read Coils (0x01)
+  * Read Discrete Inputs (0x02)
+  * Read Holding Registers (0x03)
+  * Read Input Registers (0x04)
+  * Write Single Coil (0x05)
+  * Write Single Register (0x06)
+  * Write Multiple Coils (0x0F)
+  * Write Multiple registers (0x10)
+  * Mask Write register (0x16)
+
+Installation
+------------------------------------
+
+Download and install RModBus with the following
+
+**$ gem install rmodbus**
+
+Example
+------------------------------------
+
+    require 'rmodbus'
+
+    ModBus::TCPClient.new('127.0.0.1', 8502) do |cl|
+      cl.with_slave(1) do |slave|
+        # Read a single holding register at address 16
+        slave.holding_registers[16]
+
+        # Write a single holding register at address 16
+        slave.holding_registers[16] = 123
+
+        # Read holding registers 16 through 20
+        slave.holding_registers[16..20]
+
+        # Write holding registers 16 through 20 with some values
+        slave.holding_registers[16..20] = [1, 2, 3, 4, 5]
+      end
+    end
+
+
+Conversion to/from 32bit registers
+-----------------------------------
+
+Some modbus devices use two registers to store 32bit values.
+RModbus provides some helper functions to go back and forth between these two things when reading/writing.
+The built-in examples assume registers in a particular order but it's trivial to change.
+
+    # Reading values in multiple registers (you can read more than 2 and convert them all so long as they are in multiples of 2)
+    res = slave.holding_registers[0..1]
+    res.inspect => [20342, 17344]
+    res.to_32i => [1136676726]
+    res.to_32f => [384.620788574219]
+
+    # Writing 32b values to multiple registers
+    cl.holding_registers[0..1] = [1136676726].from_32i
+    cl.holding_registers[0..1] => [20342, 17344]
+    cl.holding_registers[2..3] = [384.620788574219].from_32f
+    cl.holding_registers[2..3] => [20342, 17344]
+
+GitHub
+----------------------------------
+
+You can checkout source code from GitHub repositry
+
+**$ git clone git://github.com/flipback/RModBus.git**
+
+Reference
+----------------------------------
+
+Home page: http://rmodbus.heroku.com
+
+RModBud on GitHub: http://github.com/flipback/RModBus
+
+ModBus community: http://www.modbus-ida.org

data/Rakefile

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+  if RUBY_PLATFORM == "java"
+    spec.pattern.exclude("spec/rtu_client_spec.rb", "spec/rtu_server_spec.rb")
+  end
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/examples/perfomance_rtu.rb

@@ -0,0 +1,56 @@
+$:.unshift File.join(File.dirname(__FILE__),'../lib')
+
+require 'rmodbus'
+require 'benchmark'
+
+include ModBus
+
+BAUD = 9600 
+TIMES = 100
+
+srv = RTUServer.new 'com3', BAUD 
+srv.coils = [0,1]  * 50
+srv.discrete_inputs = [1,0]  * 50
+srv.holding_registers = [0,1,2,3,4,5,6,7,8,9]  * 10
+srv.input_registers = [0,1,2,3,4,5,6,7,8,9]  * 10
+srv.start
+
+
+cl = RTUClient.new('com4', BAUD)
+cl.with_slave(1) do |slave|
+  Benchmark.bmbm do |x|
+    x.report('Read coils') do
+      TIMES.times { slave.read_coils 0, 100 }
+    end
+      
+    x.report('Read discrete inputs') do
+      TIMES.times { slave.read_discrete_inputs 0, 100 }
+    end
+    
+    x.report('Read holding registers') do
+      TIMES.times { slave.read_holding_registers 0, 100 } 
+    end
+    
+    x.report('Read input registers') do
+      TIMES.times { slave.read_input_registers 0, 100 }
+    end
+    
+    x.report('Write single coil') do
+      TIMES.times { slave.write_single_coil 0, 1 }
+    end
+    
+    x.report('Write single register') do
+      TIMES.times { slave.write_single_register 100, 0xAAAA }
+    end
+    
+    x.report('Write multiple coils') do
+      TIMES.times { slave.write_multiple_coils 0, [1,0] * 50 }
+    end
+    
+    x.report('Write multiple registers') do
+      TIMES.times { slave.write_multiple_registers 0, [0,1,2,3,4,5,6,7,8,9] * 10  }
+    end
+  end
+end
+srv.stop
+cl.close

data/examples/perfomance_tcp.rb

@@ -0,0 +1,55 @@
+$:.unshift File.join(File.dirname(__FILE__),'../lib')
+
+require 'rmodbus'
+require 'benchmark'
+
+include ModBus
+
+TIMES = 1000
+
+srv = ModBus::TCPServer.new 1502 
+srv.coils = [0,1]  * 50
+srv.discrete_inputs = [1,0]  * 50
+srv.holding_registers = [0,1,2,3,4,5,6,7,8,9]  * 10
+srv.input_registers = [0,1,2,3,4,5,6,7,8,9]  * 10
+srv.start
+
+
+cl = TCPClient.new('127.0.0.1', 1502)
+cl.with_slave(1) do |slave|
+  Benchmark.bmbm do |x|
+    x.report('Read coils') do
+      TIMES.times { slave.read_coils 0, 100 }
+    end
+    
+    x.report('Read discrete inputs') do
+      TIMES.times { slave.read_discrete_inputs 0, 100 }
+    end
+    
+    x.report('Read holding registers') do
+      TIMES.times { slave.read_holding_registers 0, 100 } 
+    end
+    
+    x.report('Read input registers') do
+      TIMES.times { slave.read_input_registers 0, 100 }
+    end
+    
+    x.report('Write single coil') do
+      TIMES.times { slave.write_single_coil 0, 1 }
+    end
+    
+    x.report('Write single register') do
+      TIMES.times { slave.write_single_register 100, 0xAAAA }
+    end
+    
+    x.report('Write multiple coils') do
+      TIMES.times { slave.write_multiple_coils 0, [1,0] * 50 }
+    end    
+    
+    x.report('Write multiple registers') do
+      TIMES.times { slave.write_multiple_registers 0, [0,1,2,3,4,5,6,7,8,9] * 10  }
+    end
+  end
+end
+cl.close
+srv.stop

data/examples/use_rtu_via_tcp_modbus.rb

@@ -0,0 +1,22 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib/')
+require 'rmodbus'
+
+srv = ModBus::RTUViaTCPServer.new(10002,1)
+srv.coils = [1,0,1,1]
+srv.discrete_inputs = [1,1,0,0]
+srv.holding_registers = [1,2,3,4]
+srv.input_registers = [1,2,3,4]
+srv.debug = true
+srv.start
+
+ModBus::RTUViaTCPClient.connect('127.0.0.1', 10002) do |cl|
+  cl.with_slave(1) do |slave|
+    slave.debug = true
+    regs = slave.holding_registers
+  	puts regs[0..3]
+  	regs[0..3] = [2,0,1,1]
+  	puts regs[0..3]
+  end
+end
+
+srv.shutdown

data/examples/use_tcp_modbus.rb

@@ -0,0 +1,23 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib/')
+require 'rmodbus'
+
+srv = ModBus::TCPServer.new(8502,1)
+srv.coils = [1,0,1,1]
+srv.discrete_inputs = [1,1,0,0]
+srv.holding_registers = [1,2,3,4]
+srv.input_registers = [1,2,3,4]
+srv.debug = true
+srv.audit = true
+srv.start
+
+ModBus::TCPClient.connect('127.0.0.1', 8502) do |cl|
+  cl.with_slave(1) do |slave|
+    slave.debug = true
+    regs = slave.holding_registers
+  	puts regs[0..3]
+  	regs[0..3] = [2,0,1,1]
+  	puts regs[0..3]
+  end
+end
+
+srv.stop

data/lib/rmodbus/client.rb

@@ -0,0 +1,91 @@
+# RModBus - free implementation of ModBus protocol on Ruby.
+#
+# 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
+# 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
+  # @abstract
+  class Client
+    include Errors
+
+    # 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
+        self
+      end
+    end
+
+    class << self
+      alias_method :connect, :new
+    end
+
+    # Given slave object
+    # @example
+    #   cl = Client.new
+    #   cl.with_slave(1) do |slave|
+    #     slave.holding_registers[0..100]
+    #   end
+    #
+    # @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
+    end
+
+    # Check connections
+    # @return [Boolean]
+    def closed?
+      @io.closed?
+    end
+
+    # Close connections
+    def close
+      @io.close unless @io.closed?
+    end
+
+    protected
+    def open_connection(*args)
+      #Stub conn object
+      @io = Object.new
+
+      @io.instance_eval """
+        def close
+        end
+
+        def closed?
+          true
+        end
+        """
+      @io
+    end
+
+    def get_slave(uid,io)
+      Slave.new(uid, io)
+    end
+  end
+end

data/lib/rmodbus/common.rb

@@ -0,0 +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
+    # @return [Boolean] debug mode
+    # default false
+    attr_accessor :debug
+
+    @debug = false
+
+    private
+    # Put log message on standart output
+    # @param [String] msg message for log
+    def log(msg)
+      $stdout.puts msg if @debug
+    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/errors.rb

@@ -0,0 +1,50 @@
+# RModBus - free implementation of ModBus protocol on Ruby.
+#
+# Copyright (C) 2008  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
+# 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 Errors
+
+    class ProxyException < StandardError
+    end
+
+    class ModBusException < StandardError
+    end
+
+    class IllegalFunction < ModBusException
+    end
+
+    class IllegalDataAddress < ModBusException
+    end
+
+    class IllegalDataValue < ModBusException
+    end
+
+    class SlaveDeviceFailure < ModBusException
+    end
+
+    class Acknowledge < ModBusException
+    end
+
+    class SlaveDeviceBus < ModBusException
+    end
+
+    class MemoryParityError < ModBusException
+    end
+
+    class ModBusTimeout < ModBusException
+    end
+
+  end
+
+end

data/lib/rmodbus/ext.rb

@@ -0,0 +1,88 @@
+# RModBus - free implementation of ModBus protocol on Ruby.
+#
+# Copyright (C) 2009  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
+# 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.
+
+class String
+
+  unless RUBY_VERSION =~ /^1\.9/
+    def getbyte(index)
+      self[index].to_i
+    end
+  end
+
+  def unpack_bits
+    array_bit = []
+    self.unpack('b*')[0].each_char do |c|
+        array_bit << c.to_i
+    end
+    array_bit
+  end
+  
+end
+
+class Integer
+
+  # Shortcut or turning an integer into a word
+  def to_word
+    [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 = ""
+    mask = 0x01
+
+    self.each do |bit| 
+      word |= mask if bit > 0
+      mask <<= 1
+      if mask  == 0x100
+        mask = 0x01
+        s << word.chr
+        word = 0
+      end
+    end
+    unless mask == 0x01
+      s << word.chr
+    else
+      s
+    end
+  end
+
+end
+

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