modbus 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5559848be6158b9fdf9c0d2a8d030b08769f181510cfba3a59f90a7a8af9e723
+  data.tar.gz: aade6afbf693c033ccb3bd4b021592d0dc09ceff7247ce4a9f66de3491e0bba2
+SHA512:
+  metadata.gz: 5b2ff3ee1a9dfcc6ce804879ec11158db23c1581ce4e9134d439fbc1035e7d8b150cd65a291d91dac3a6a2e150459768dcf83a10967f6469eb0c07a3fd55c11a
+  data.tar.gz: f2409419ec8923a69dccc82e6d340138e320126befa6f7f9add418419a24aa376ce1147f0b33d4f8f3e7451e905b9ea226b1a21f655628b1c0d8703f97510d5b

data/README.md

@@ -0,0 +1,62 @@
+# Ruby Modbus
+
+Constructs [modbus standard](http://www.modbus.org/specs.php) datagrams that make it easy to communicate with devices on modbus networks.
+It does not implement the transport layer so you can use it with native ruby, eventmachine, celluloid or the like.
+
+[![Build Status](https://travis-ci.org/acaprojects/ruby-modbus.svg?branch=master)](https://travis-ci.org/acaprojects/ruby-modbus)
+
+You'll need a gateway that supports TCP/IP.
+
+
+## Install the gem
+
+Install it with [RubyGems](https://rubygems.org/)
+
+    gem install modbus
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com/):
+
+    gem 'modbus'
+
+
+
+## Usage
+
+```ruby
+require 'modbus'
+
+modbus = Modbus.new
+
+# Reading input obtained from the network
+# The class instance performs buffering and yields complete ADUs
+modbus.read(byte_string) do |adu|
+    adu.header.transaction_identifier # => 32
+
+    # Response PDU returned
+    if adu.exception?
+        puts adu.pdu.exception_code
+    else
+        case adu.function_code
+        when 0x01
+            puts adu.pdu.read.data.bytes
+        end
+    end
+end
+
+
+# You can generate requests like so (writing multipe coils starting from 123)
+request = modbus.write_coils(123, true, true, false)
+byte_string = request.to_binary_s
+
+# Read 4 coils starting from address 123
+request = modbus.read_coils(123, 4)
+byte_string = request.to_binary_s
+
+# Send byte_string to the modbus gateway to execute the request
+
+```
+
+
+## License and copyright
+
+MIT

data/lib/modbus.rb

@@ -0,0 +1,191 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+require 'bindata'
+
+require 'modbus/tcp_header'
+require 'modbus/request'
+require 'modbus/response'
+require 'modbus/exception'
+require 'modbus/adu'
+
+class Modbus
+    CODES = {
+        read_coils: 0x01,
+        read_inputs: 0x02,
+        read_holding_registers: 0x03,
+        read_input_registers: 0x04,
+        write_coil: 0x05,
+        write_register: 0x06,
+        write_multiple_coils: 0x0F,
+        write_multiple_registers: 0x10,
+
+        # Serial only
+        read_exception_status: 0x07,
+        diagnostics: 0x08,
+        get_event_counter: 0x0B,
+        get_event_log: 0x0C,
+        get_server_id: 0x11,
+
+        # unsupported
+        read_file_record: 0x14,
+        write_file_record: 0x15,
+        mask_write_register: 0x16,
+        read_write_registers: 0x17,
+        read_fifo_queue: 0x17,
+        encapsulated_interface_transport: 0x2B,
+        canopen_general_request: 0x0D,
+        read_device_identification: 0x0E
+    }
+    CODES.merge!(CODES.invert)
+    CODES.freeze
+
+    def initialize
+        @transaction = 0
+    end
+
+    # Decodes an ADU from wire format and sets the attributes of this object.
+    #
+    # @param data [String] The bytes to decode.
+    def read(data)
+        @buffer ||= String.new
+        @buffer << data
+
+        error = nil
+
+        loop do
+            # not enough data in buffer to know the length
+            break if @buffer.bytesize < 6
+
+            header = TCPHeader.new
+            header.read(@buffer[0..5])
+
+            # the headers unit identifier is included in the length
+            total_length = header.request_length + 6
+
+            # Extract just the request from the buffer
+            break if @buffer.bytesize < total_length
+            request = @buffer.slice!(0...total_length)
+            function_code = request.getbyte(7)
+
+            # Yield the complete responses
+            begin
+                if function_code <= 0x80
+                    response = ResponsePDU.new
+                    response.read(request[6..-1])
+                else # Error response
+                    response = ExceptionPDU.new
+                    response.read(request[6..-1])
+                    function_code = function_code - 0x80
+                end
+
+                yield ADU.new header, function_code, response
+            rescue => e
+                error = e
+            end
+        end
+
+        raise error if error
+    end
+
+    [:read_coils, :read_inputs, :read_holding_registers, :read_input_registers].each do |function|
+        define_method function do |address, count = 1|
+            adu = request_adu function
+            request = adu.pdu
+            request.get.address = address.to_i
+            request.get.quantity = count.to_i
+            adu
+        end
+    end
+
+    def write_coils(address, *values)
+        values = values.flatten
+
+        if values.length > 1
+            write_multiple_coils(address, *values)
+        else
+            adu = request_adu :write_coil
+            request = adu.pdu
+            request.put.address = address.to_i
+            request.put.data = values.first ? 0xFF00 : 0x0
+            adu
+        end
+    end
+
+    def write_registers(address, *values)
+        values = values.flatten.map! { |value| value.to_i }
+
+        if values.length > 1
+            adu = request_adu :write_multiple_registers
+            request = adu.pdu
+            request.put_multiple.address = address.to_i
+            request.put_multiple.quantity = values.length
+            request.put_multiple.data = values.pack('n*')
+            adu
+        else
+            adu = request_adu :write_register
+            request = adu.pdu
+            request.put.address = address.to_i
+            request.put.data = values.first
+            adu
+        end
+    end
+
+    protected
+
+    def write_multiple_coils(address, *values)
+        size = values.length
+
+        bytes = []
+        byte = 0
+        bit = 0
+        loop do
+            value = values.shift
+            if value
+                byte = byte | (1 << bit)
+            end
+            break if values.empty?
+            bit += 1
+            if bit >= 8
+                bytes << byte
+                byte = 0
+                bit = 0
+            end
+        end
+        bytes << byte
+
+        adu = request_adu :write_multiple_coils
+        request = adu.pdu
+        request.put_multiple.address = address.to_i
+        request.put_multiple.quantity = size
+        request.put_multiple.data = bytes.pack('C*')
+        adu
+    end
+
+    def next_id
+        id = @transaction
+        @transaction += 1
+        @transaction = 0 if @transaction > 0xFFFF
+        id
+    end
+
+    def new_header
+        header = TCPHeader.new
+        header.transaction_identifier = next_id
+        header.protocol_identifier = 0
+        header
+    end
+
+    def request_pdu(code)
+        request = RequestPDU.new
+        # This seems to be the default
+        request.unit_identifier = 0xFF
+        request.function_code = code
+        request
+    end
+
+    def request_adu(function)
+        code = CODES[function]
+        ADU.new(new_header, code, request_pdu(code))
+    end
+end

data/lib/modbus/adu.rb

@@ -0,0 +1,48 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+class Modbus
+    # TCP ADU are sent via TCP to registered port 502
+    Modbus::ADU = Struct.new :header, :function_code, :pdu do
+        def exception?
+            pdu.is_a?(ExceptionPDU)
+        end
+
+        def to_binary_s
+            data = pdu.to_binary_s
+            header.request_length = data.bytesize
+            "#{header.to_binary_s}#{data}"
+        end
+
+        def function_name
+            CODES[function_code]
+        end
+
+        def value
+            return EXCEPTIONS[pdu.exception_code] || "unknown error 0x#{pdu.exception_code.to_s(16)}" if exception?
+            return nil unless pdu.is_a?(ResponsePDU) && READ_CODES.include?(function_code)
+
+            bytes = pdu.get.data_length
+            bin_str = pdu.get.data
+
+            case function_name
+            when :read_coils, :read_inputs
+                values = []
+
+                # extract the bits and return an array of true / false values
+                bin_str.each_byte do |byte|
+                    bit = 0
+                    loop do
+                        values << ((byte & (1 << bit)) > 0)
+                        bit += 1
+                        break if bit >= 8
+                    end
+                end
+                values
+            when :read_holding_registers, :read_input_registers
+                # these are all 16bit integers
+                bin_str.unpack('n*')
+            end
+        end
+    end
+end

data/lib/modbus/exception.rb

@@ -0,0 +1,24 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+class Modbus
+    EXCEPTIONS = {
+        0x01 => 'illegal function',
+        0x02 => 'illegal data address',
+        0x03 => 'illegal data value',
+        0x04 => 'server device failure',
+        0x05 => 'acknowledge', # processing will take some time, no need to retry
+        0x06 => 'server device busy',
+        0x08 => 'memory parity error',
+        0x0A => 'gateway path unavailable',
+        0x0B => 'gateway device failed to respond'
+    }
+
+    class ExceptionPDU < BinData::Record
+        endian :big
+
+        uint8 :unit_identifier
+        uint8 :function_code
+        uint8 :exception_code
+    end
+end

data/lib/modbus/request.rb

@@ -0,0 +1,34 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+class Modbus
+    READ_CODES = [0x01, 0x02, 0x03, 0x04].freeze
+    WRITE_CODES = [0x05, 0x06].freeze
+    MULTIPLE_CODES = [0x0F, 0x10].freeze
+
+    class RequestPDU < BinData::Record
+        endian :big
+
+        # This field is used for intra-system routing purpose (default to 0xFF)
+        uint8 :unit_identifier
+        uint8 :function_code
+
+        struct :get, onlyif: -> { READ_CODES.include? function_code } do
+            uint16 :address
+            uint16 :quantity
+        end
+
+        struct :put, onlyif: -> { WRITE_CODES.include? function_code } do
+            uint16 :address
+            uint16 :data
+        end
+
+        struct :put_multiple, onlyif: -> { MULTIPLE_CODES.include? function_code } do
+            uint16 :address
+            uint16 :quantity
+
+            uint8 :data_length, value: -> { put_multiple.data.bytesize }
+            string :data, read_length: -> { put_multiple.data_length }
+        end
+    end
+end

data/lib/modbus/response.rb

@@ -0,0 +1,22 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+class Modbus
+    class ResponsePDU < BinData::Record
+        endian :big
+
+        # This field is used for intra-system routing purpose (default to 0xFF)
+        uint8 :unit_identifier
+        uint8 :function_code
+
+        struct :get, onlyif: -> { READ_CODES.include? function_code } do
+            uint8 :data_length, value: -> { get.data.bytesize }
+            string :data, read_length: -> { get.data_length }
+        end
+
+        struct :put, onlyif: -> { WRITE_CODES.include?(function_code) || MULTIPLE_CODES.include?(function_code) } do
+            uint16 :address
+            uint16 :data
+        end
+    end
+end

data/lib/modbus/tcp_header.rb

@@ -0,0 +1,18 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+class Modbus
+    # TCP ADU are sent via TCP to registered port 502
+    class TCPHeader < BinData::Record
+        endian :big
+
+        # used for transaction pairing
+        uint16 :transaction_identifier
+
+        # The MODBUS protocol is identified by the value 0.
+        uint16 :protocol_identifier
+
+        # byte count of the following fields, including the Unit Identifier and data fields.
+        uint16 :request_length
+    end
+end

data/modbus.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true, encoding: ASCII-8BIT
+
+Gem::Specification.new do |s|
+    s.name        = "modbus"
+    s.version     = '1.0.0'
+    s.authors     = ["Stephen von Takach"]
+    s.email       = ["steve@aca.im"]
+    s.licenses    = ["MIT"]
+    s.homepage    = "https://github.com/acaprojects/ruby-modbus"
+    s.summary     = "Modbus protocol on Ruby"
+    s.description = <<-EOF
+        Constructs Modbus standard datagrams that make it easy to communicate with devices on Modbus networks
+    EOF
+
+
+    s.add_dependency 'bindata', '~> 2.3'
+
+    s.add_development_dependency 'rspec', '~> 3.5'
+    s.add_development_dependency 'rake',  '~> 12'
+
+
+    s.files = Dir["{lib}/**/*"] + %w(modbus.gemspec README.md)
+    s.test_files = Dir["spec/**/*"]
+    s.extra_rdoc_files = ["README.md"]
+
+    s.require_paths = ["lib"]
+end

data/spec/modbus_spec.rb

@@ -0,0 +1,73 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+require 'modbus'
+
+# Example captures
+# http://www.pcapr.net/browse?q=modbus
+
+describe 'modbus protocol helper' do
+    before :each do
+        @modbus = Modbus.new
+        @response = nil
+    end
+
+    it "should parse and generate the same string" do
+        data = "\x0\x0\x0\x0\x0\x4\x1\x1\x1\x1"
+        @modbus.read(data) { |adu| @response = adu }
+        expect(@response.to_binary_s).to eq(data)
+        @response = nil
+
+        data = "\x0\x0\x0\x0\x0\x4\x1\x2\x1\x1"
+        @modbus.read(data) { |adu| @response = adu }
+        expect(@response.to_binary_s).to eq(data)
+        @response = nil
+    end
+
+    it "should generate a read coil request" do
+        data = @modbus.read_coils(0).to_binary_s
+        expect(data).to eq("\x0\x0\x0\x0\x0\x6\xFF\x1\x0\x0\x0\x1")
+    end
+
+    it "should generate a read inputs request" do
+        data = @modbus.read_inputs(0).to_binary_s
+        expect(data).to eq("\x0\x0\x0\x0\x0\x6\xFF\x2\x0\x0\x0\x1")
+    end
+
+    it "should generate a write coils request" do
+        data = @modbus.write_coils(4, true).to_binary_s
+        expect(data).to eq("\x00\x00\x00\x00\x00\x06\xFF\x05\x00\x04\xFF\x00")
+
+        data = @modbus.write_coils(3, false).to_binary_s
+        expect(data).to eq("\x00\x01\x00\x00\x00\x06\xFF\x05\x00\x03\x00\x00")
+
+        data = @modbus.write_coils(4, true, true).to_binary_s
+        expect(data).to eq("\x00\x02\x00\x00\x00\x08\xFF\x0F\x00\x04\x00\x02\x1\x3")
+
+        data = @modbus.write_coils(4, false, true).to_binary_s
+        expect(data).to eq("\x00\x03\x00\x00\x00\x08\xFF\x0F\x00\x04\x00\x02\x1\x2")
+
+        data = @modbus.write_coils(4, true, true, true, true, true, true, true, true, false, true).to_binary_s
+        expect(data).to eq("\x00\x04\x00\x00\x00\x09\xFF\x0F\x00\x04\x00\x0A\x2\xFF\x2")
+    end
+
+    it "should generate a write registers request" do
+        data = @modbus.write_registers(5, [1, 2, 3, 4]).to_binary_s
+        expect(data).to eq("\x00\x00\x00\x00\x00\x0F\xFF\x10\x00\x05\x00\x04\x8\x00\x01\x00\x02\x00\x03\x00\x04")
+
+        data = @modbus.write_registers(5, 4).to_binary_s
+        expect(data).to eq("\x00\x01\x00\x00\x00\x06\xFF\x06\x00\x05\x00\x04")
+    end
+
+    it "should return the response values" do
+        data = "\x00\x00\x00\x00\x00\x04\xFF\x01\x1\x3"
+        @modbus.read(data) { |adu| @response = adu }
+        expect(@response.value).to eq([true, true, false, false, false, false, false, false])
+        expect(@response.function_name).to eq(:read_coils)
+
+        data = "\x00\x00\x00\x00\x00\x07\xFF\x03\x4\x0\x3\x1\x00"
+        @modbus.read(data) { |adu| @response = adu }
+        expect(@response.value).to eq([3, 256])
+        expect(@response.function_name).to eq(:read_holding_registers)
+    end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: modbus
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Stephen von Takach
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12'
+description: "        Constructs Modbus standard datagrams that make it easy to communicate
+  with devices on Modbus networks\n"
+email:
+- steve@aca.im
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/modbus.rb
+- lib/modbus/adu.rb
+- lib/modbus/exception.rb
+- lib/modbus/request.rb
+- lib/modbus/response.rb
+- lib/modbus/tcp_header.rb
+- modbus.gemspec
+- spec/modbus_spec.rb
+homepage: https://github.com/acaprojects/ruby-modbus
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Modbus protocol on Ruby
+test_files:
+- spec/modbus_spec.rb