voltronic_power_interface 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3a18820cbf50df7c487d5adfc987909141aabdd
+  data.tar.gz: 33b19ddfd04564be7ed903a8171c69aa09427c9b
+SHA512:
+  metadata.gz: 7115f2515c3ff251dfc768da86c70ce24e1699124cbc375dba742e8faddff6893ed0a86f2ec634fe2c0718f511901931e5edd76ce830a745122aaf8281837a2e
+  data.tar.gz: e9f9e3dbb566bdd3abf5a82a97b324b11e412418f9326a812c242fe0aae10651e85be55cbbb9eda4dab82ec12b5f92774dfffaf573e49eb99ac1a2883970c6ed

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Johan van der Vyver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+## Voltronic Power Interface
+A library to communicate with [Voltronic Power](http://www.voltronicpower.com/) inverter/PV products.
+
+**NOTE: The author of this library has no association with the above mentioned company**
+
+Some [public documentation](https://s3-eu-west-1.amazonaws.com/osor62gd45llv5fcg47yijafsz6dcrjn/Infini_RS232_Protocol.pdf) exists of supported commands and how to interpret the output.
+
+Not all commands are supported by all devices
+
+## Use
+
+### SerialPort
+
+**NOTE: Only Ruby Gem ```serialport``` is currently supported**
+
+**Linux/Mac OS X/BSD**
+
+Serial ports are typically found in /dev/tty*
+These devices may require root privilege in which case it is recommended to add a udev rule with less restrictive permissions.
+
+Example udev rule for Prolific devices:
+
+`echo 'ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303", MODE="0666", SYMLINK+="ttyProlific"' > /etc/udev/rules.d/37-prolific.rules`
+
+    require 'voltronic/protocol'
+    # => true
+
+    proto = Voltronic::Protocol.for_serialport('/dev/tty_usbserial')
+    # => Protocol(IO)
+
+    proto.execute 'QPI'
+    #=> '(PI30'
+
+    timeout = 0.5 # 500 milliseconds
+    proto.execute 'QPI', timeout
+    #=> '(PI30'
+
+**Windows**
+
+    require 'voltronic/protocol'
+    # => true
+
+    proto = Voltronic::Protocol.for_serialport('COM1')
+    # => Protocol(IO)
+
+    proto.execute 'QPI'
+    #=> '(PI30'
+
+    timeout = 0.5 # 500 milliseconds
+    proto.execute 'QPI', timeout
+    #=> '(PI30'
+
+### USB
+**The implementation currently only support Linux using HIDRaw**
+
+To avoid running as root, execute the following to add a symlink with less restricted privileges
+
+`echo 'ATTRS{idVendor}=="0665", ATTRS{idProduct}=="5161", SUBSYSTEMS=="usb", ACTION=="add", MODE="0666", GROUP="root", SYMLINK+="hidVoltronic"' > /etc/udev/rules.d/35-voltronic.rules`
+
+    require 'voltronic/protocol'
+    # => true
+
+    proto = Voltronic::Protocol.for_usb('/dev/hidVoltronic')
+    # => Protocol(IO)
+
+    proto.execute 'QPI'
+    #=> '(PI30'
+
+    timeout = 0.5 # 500 milliseconds
+    proto.execute 'QPI', timeout
+    #=> '(PI30'

data/lib/voltronic/digest.rb

@@ -0,0 +1,90 @@
+module ::Voltronic
+  module Digest #:nodoc:
+    def self.parse(input) #:nodoc:
+      input = begin
+        input_bytes = input.to_s.bytes
+        end_index = input_bytes.length
+        while(0 != end_index)
+          if (@@termination_character == input_bytes[(end_index -= 1)])
+            break
+          end
+        end
+        input_bytes[0..end_index]
+      end
+
+      if (3 > input.length)
+        raise MalformedInputError.new 'Input must be at at least 3 bytes in size'
+      end
+
+      input_crc = input[-3..-2]
+      input = input[0..-4].map do |byte|
+        if (128 > byte)
+          byte.chr
+        else
+          raise MalformedInputError.new 'Input contained an unparsable character'
+        end
+      end.join
+
+      calculated_crc = encode(input).to_s.bytes[-3..-2]
+      if (calculated_crc == input_crc)
+        return input
+      end
+
+      raise DigestMismatchError.new ['Device digest [',
+        input_crc.first, ',', input_crc.last, '] != [',
+        calculated_crc.first, ',', calculated_crc.last,
+        '] calculated digest'].join
+    end
+
+    def self.encode(input) #:nodoc:
+      input = input.to_s
+      crc = 0
+      input.bytes.each do |byte|
+        crc = ((@@crc_table[(((crc >> 8) ^ byte) & 0xff)] ^ (crc << 8)) & 0xffff)
+      end
+
+      first_byte = ((crc & 0xff00) >> 8)
+      second_byte = (crc & 0xff)
+
+      if ((0x28 == first_byte) || (0x0d == first_byte) || (0x0a == first_byte))
+        first_byte += 1
+      end
+      if ((0x28 == second_byte) || (0x0d == second_byte) || (0x0a == second_byte))
+        second_byte += 1
+      end
+
+      [input, first_byte.chr, second_byte.chr, @@termination_character.chr].join
+    end
+
+    def self.eos?(input) #:nodoc:
+      input.to_s.bytes.any? { |byte| (@@termination_character == byte) }
+    end
+
+    @@termination_character ||= "\r".bytes.first #:nodoc:
+
+    @@crc_table ||= [ #:nodoc:
+      0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7, 0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c,
+      0xd1ad, 0xe1ce, 0xf1ef, 0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6, 0x9339, 0x8318,
+      0xb37b, 0xa35a, 0xd3bd, 0xc39c, 0xf3ff, 0xe3de, 0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4,
+      0x5485, 0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee, 0xf5cf, 0xc5ac, 0xd58d, 0x3653, 0x2672, 0x1611, 0x0630,
+      0x76d7, 0x66f6, 0x5695, 0x46b4, 0xb75b, 0xa77a, 0x9719, 0x8738, 0xf7df, 0xe7fe, 0xd79d, 0xc7bc, 0x48c4,
+      0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823, 0xc9cc, 0xd9ed, 0xe98e, 0xf9af, 0x8948, 0x9969,
+      0xa90a, 0xb92b, 0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12, 0xdbfd, 0xcbdc, 0xfbbf,
+      0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a, 0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41,
+      0xedae, 0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49, 0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13,
+      0x2e32, 0x1e51, 0x0e70, 0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78, 0x9188, 0x81a9,
+      0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e, 0xe16f, 0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046,
+      0x6067, 0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c, 0xe37f, 0xf35e, 0x02b1, 0x1290, 0x22f3, 0x32d2,
+      0x4235, 0x5214, 0x6277, 0x7256, 0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e, 0xe54f, 0xd52c, 0xc50d, 0x34e2,
+      0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405, 0xa7db, 0xb7fa, 0x8799, 0x97b8, 0xe75f, 0xf77e,
+      0xc71d, 0xd73c, 0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634, 0xd94c, 0xc96d, 0xf90e,
+      0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab, 0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3,
+      0xcb7d, 0xdb5c, 0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a, 0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1,
+      0x1ad0, 0x2ab3, 0x3a92, 0xfd2e, 0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9, 0x7c26, 0x6c07,
+      0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1, 0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9,
+      0x9ff8, 0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1, 0x1ef0 ].freeze
+
+    class DigestMismatchError < RuntimeError; end
+    class MalformedInputError < RuntimeError; end
+  end
+end

data/lib/voltronic/protocol.rb

@@ -0,0 +1,95 @@
+module ::Voltronic
+  module Protocol
+    require 'voltronic/digest'
+
+  ##
+  # Open a connection to the device
+  # - Closes an existing connection, if one exists
+
+    ##
+    # Create a new Protocol object using an input IO object
+    def self.for_io(io)
+      require 'voltronic/protocols/io'
+
+      def self.for_io(io)
+        ::Voltronic::Protocol::IO.method(:new).call(io)
+      end
+
+      for_io(io)
+    end
+
+    ##
+    # Create a new Protocol object for Axpert device connected to a serial port
+    def self.for_serialport(port_or_dev, baud = 2400, data_bits = 8, stop_bits = 1, parity = :none)
+      begin
+        require 'serialport'
+      rescue Exception
+        raise LoadError.new 'RubyGem "serialport" required to make use of Axpert on a Serial Port'
+      end
+
+      def self.for_serialport(port_or_dev, baud = 2400, data_bits = 8, stop_bits = 1, parity = :none)
+        port_or_dev = port_or_dev.to_s.strip
+
+        baud = begin
+          parse = Integer(baud)
+          raise if (1 > parse)
+          parse
+        rescue
+          raise ArgumentError.new "Invalid baud #{baud}"
+        end
+
+        data_bits = begin
+          parse = Integer(data_bits)
+          raise unless ((5 == parse) || (6 == parse) || (7 == parse) || (8 == parse))
+          parse
+        rescue
+          raise ArgumentError.new "Invalid data bits #{data_bits}"
+        end
+
+        stop_bits = begin
+          parse = Integer(stop_bits)
+          raise unless ((1 == parse) || (2 == parse))
+          parse
+        rescue
+          raise ArgumentError.new "Invalid stop bits #{stop_bits}"
+        end
+
+        parity = begin
+          parse = parity.to_s.strip.upcase
+          raise unless (('NONE' == parse) || ('EVEN' == parse) || ('ODD' == parse) || ('MARK' == parse) || ('SPACE' == parse))
+          ::SerialPort.const_get(parse.to_sym)
+        rescue
+          raise ArgumentError.new "Invalid Parity #{parity}"
+        end
+
+        serial_io = ::SerialPort.new(port_or_dev, baud, data_bits, stop_bits, parity)
+        serial_io.read_timeout = -1
+        for_io(serial_io)
+      end
+
+      for_serialport(port_or_dev, baud, data_bits, stop_bits, parity)
+    end
+
+    ##
+    # Create a new Protocol object for Axpert device connected to USB
+    #
+    # Currently only supported on Linux kernels that include HIDRaw
+    def self.for_usb(dev)
+      if !(RUBY_PLATFORM =~ /linux/)
+        raise NotImplementedError.new 'USB is currently only supported in Linux'
+      end
+
+      def self.for_usb(dev)
+        for_io(::File.open(dev.to_s, (::IO::RDWR | ::IO::NONBLOCK)))
+      end
+
+      for_usb(dev)
+    end
+
+    ##
+    # Execute a query on the device
+    def execute(input, timeout = 1.0)
+      raise NotImplementedError.new 'Protocol implementation does not implement execute(..)'
+    end
+  end
+end

data/lib/voltronic/protocols/io.rb

@@ -0,0 +1,145 @@
+require 'voltronic/protocol'
+
+##
+# Implementation of the Protocol for IO objects
+class ::Voltronic::Protocol::IO #:nodoc:
+  require 'time'
+
+  MAXIMUM_RESPONSE_SIZE = 1024
+  READ_BLOCK_SIZE = 8 # USB device report size
+  READ_OPTIONS = { exception: false }.freeze
+  CLEAR_TIMEOUT = 2.0
+
+  def initialize(io) #:nodoc:
+    @io_array = [io].freeze
+
+    @io = begin # Verify input io quacks like an IO
+      begin
+        io.sync = true
+      rescue Exception
+      end
+
+      begin
+        io.binmode = true
+      rescue Exception
+      end
+
+      begin
+        io.read_nonblock(READ_BLOCK_SIZE, nil, READ_OPTIONS)
+      rescue Exception
+        raise ArgumentError.new [io.to_s, ' does not support read_nonblock'].join
+      end
+
+      if !io.respond_to?(:write)
+        raise ArgumentError.new [io.to_s, ' does not support write'].join
+      end
+
+      begin
+        ::IO.select(@io_array, nil, nil, 0)
+      rescue Exception
+        raise ArgumentError.new [io.to_s, ' does not support IO.select(', io.to_s, ')'].join
+      end
+
+      io
+    end
+
+    @support_flush ||= begin # Assert if flush works
+      @io.flush
+      true
+    rescue Exception
+      false
+    end
+
+    clear_read_buffer
+  end
+
+  def execute(input, timeout = 1.0) #:nodoc:
+    timeout = begin
+      parse = Float(timeout)
+      raise if (0 >= parse)
+      parse
+    rescue
+      raise ArgumentError.new ['Invalid timeout ', timeout.to_s].join
+    end
+
+    clear_read_buffer
+    write(input)
+    read(timeout)
+  end
+
+  def to_s #:nodoc:
+    'Protocol(IO)'
+  end
+
+  def inspect #:nodoc:
+    self.to_s
+  end
+
+  def close
+    @io.close
+    true
+  rescue Exception
+    false
+  end
+
+  def closed?
+    @io.closed?
+  end
+
+  private
+
+  def clear_read_buffer #:nodoc:
+    loop_timeout = Time.now.to_f + CLEAR_TIMEOUT
+
+    while(true)
+      if ::IO.select(@io_array, nil, nil, 0).nil?
+        return true
+      end
+
+      @io.read_nonblock(READ_BLOCK_SIZE, nil, READ_OPTIONS)
+
+      if (Time.now.to_f > loop_timeout)
+        raise DeviceError.new 'Device is responding with binary data before a write has been issued'
+      end
+    end
+  end
+
+  def read(timeout) #:nodoc:
+    blocks = ''
+    loop_timeout = Time.now.to_f + timeout
+    while(true)
+      iteration_timeout = (loop_timeout - Time.now.to_f)
+      if (0 >= iteration_timeout)
+        raise TimeoutError.new ['Timeout of ', timeout.to_s, ' seconds reached'].join
+      end
+
+      next if ::IO.select(@io_array, nil, nil, iteration_timeout).nil?
+
+      block = @io.read_nonblock(READ_BLOCK_SIZE, nil, READ_OPTIONS)
+      next if block.nil?
+      blocks << block
+
+      if ::Voltronic::Digest.eos?(block)
+        return ::Voltronic::Digest.parse(blocks)
+      end
+
+      if (blocks.length > MAXIMUM_RESPONSE_SIZE)
+        raise BufferOverflowError.new ['Device response exceeds the maximum of ', MAXIMUM_RESPONSE_SIZE.to_s, ' bytes'].join
+      end
+    end
+  end
+
+  def write(input) #:nodoc:
+    number_of_bytes = @io.write(::Voltronic::Digest.encode(input))
+    if @support_flush
+      @io.flush
+    end
+    number_of_bytes
+  end
+
+  class TimeoutError < RuntimeError; end #:nodoc:
+  class BufferOverflowError < RuntimeError; end #:nodoc:
+  class DeviceError < RuntimeError; end #:nodoc:
+
+  private_class_method :new
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: voltronic_power_interface
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Johan van der Vyver
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-07-09 00:00:00.000000000 Z
+dependencies: []
+description: Ruby library to communicate with Voltronic Power devices
+email: code@johan.vdvyver.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+files:
+- LICENSE
+- README.md
+- lib/voltronic/digest.rb
+- lib/voltronic/protocol.rb
+- lib/voltronic/protocols/io.rb
+homepage: https://github.com/jovandervyver/voltronic_power_interface
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--quiet"
+- "--line-numbers"
+- "--inline-source"
+- "--title"
+- Voltronic Power Interface
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Voltronic Power Interface
+test_files: []