axpert_rs232 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: feaf14c95a0bb048162f2de460083f56e1564c9a
+  data.tar.gz: 124bfdfe33531983e742cff13ce5883ca8163d9f
+SHA512:
+  metadata.gz: 4f69247e57e69cd8bee76208639a0fbd55f94743d85b9282fe7f1a300bbc289e85a6c2ae4859d3e55ab5d2417922a88712bd85465d88ff99b85af690bb53e0a7
+  data.tar.gz: cd36a586e15a3f5421abf9260b63bcd5c7d35c0499876bf6b3adcf57212d635792d766d2f8bd1cefc281ff07f6e93465eaac4d6595f19822135302f09e3ed5b7

data/lib/axpert_commands.rb

@@ -0,0 +1,543 @@
+##
+# A list of known commands
+#
+# Commands implemented as constants
+# Each command includes the actual command to be executed and a parser for the results of the command
+#
+# Commands source: http://forums.aeva.asn.au/uploads/293/HS_MS_MSX_RS232_Protocol_20140822_after_current_upgrade.pdf
+#
+# @author: Johan van der Vyver
+module AxpertCommands
+  require 'voltronic_device_operation'
+  OP = ::VoltronicDeviceOperation # :nodoc
+
+  ##
+  # Device protocol ID
+  #
+  # Returns:
+  #    # An Integer specifying the protocol ID
+  #    30 # Example
+  PROTOCOL_ID = OP.new(command: 'QPI', parser: lambda { |r| Integer(r.data[3..-1]) })
+
+  ##
+  # Device serial number
+  #
+  # Returns:
+  #    # A String specifying the device serial number
+  #    "XXXXXXXXXXXXXX" # Example
+  SERIAL_NUMBER = OP.new(command: 'QID', parser: lambda { |r| r.data[1..-1] })
+
+  ##
+  # Main CPU Firmware version
+  #
+  # Returns:
+  #    # A String representing the CPU Firmware as a hexidecimal number
+  #    "124004.10" # Example
+  #
+  MAIN_CPU_FIRMWARE = OP.new(command: 'QVFW', parser: lambda do |r|
+    r.data[8..-1].split('.').map { |s| s.chars.map { |c| Integer(c, 16).to_s }.flatten.join }.join('.').upcase
+  end)
+
+  ##
+  # Other CPU Firmware version
+  #
+  # Returns:
+  #    # A String representing the CPU Firmware as a hexidecimal number
+  #    "124004.10" # Example
+  OTHER_CPU_FIRMWARE = OP.new(command: 'QVFW2', parser: lambda do |r|
+    r.data[8..-1].split('.').map { |s| s.chars.map { |c| Integer(c, 16).to_s }.flatten.join }.join('.').upcase
+  end)
+
+  ##
+  # Device rating information
+  #
+  # Returns:
+  #    # A Hash containing device rating information
+  #    { grid_voltage: 230.5, grid_current: 11.2, .. }
+  DEVICE_RATING = OP.new(command: 'QPIRI', parser: lambda do |r|
+    r = r.data[1..-1].split(' ')
+    { grid_voltage: Float(r[0]),
+      grid_current: Float(r[1]),
+      output_voltage: Float(r[2]),
+      output_frequency: Float(r[3]),
+      output_current: Float(r[4]),
+      output_va: Integer(r[5]),
+      output_watts: Integer(r[6]),
+      battery_voltage: Float(r[7]),
+      battery_recharge_voltage: Float(r[8]),
+      battery_under_voltage: Float(r[9]),
+      battery_bulk_charge_voltage: Float(r[10]),
+      battery_float_charge_voltage: Float(r[11]),
+      battery_type: ::AxpertConstants::BATTERY_TYPE[r[12]],
+      maximum_ac_charge_current: Integer(r[13]),
+      maximum_charge_current: Integer(r[14]),
+      input_voltage_sensitivity: CONS::INPUT_VOLTAGE_SENSITIVITY[r[15]],
+      output_source_priority: CONS::OUTPUT_SOURCE_PRIORITY[r[16]],
+      charger_source_priority: CONS::CHARGER_SOURCE_PRIORITY[r[17]],
+      maximum_parallel_units: Integer(r[18]),
+      device_type: CONS::DEVICE_TYPE[r[19]],
+      device_topology: CONS::DEVICE_TOPOLOGY[r[20]],
+      output_mode: CONS::OUTPUT_MODE[r[21]],
+      battery_redischarge_voltage: Float(r[22]),
+      pv_parallel_ok_mode: CONS::PV_PARALLEL_OK_MODE[r[23]],
+      pv_power_balance_mode: CONS::PV_POWER_BALANCE_MODE[r[24]] }
+  end)
+
+
+  ##
+  # Device flags
+  #
+  # Returns:
+  #    # A Hash containing device flag status as booleans
+  #    {enable_buzzer: true/false, nable_bypass_to_utility_on_overload: true/false, ... }
+  DEVICE_FLAGS = OP.new(command: 'QFLAG', parser: lambda do |r|
+    r = r.data[1..-1]
+    lookup = Hash.new { |_, k| raise "The device did not return the status of the flag '#{k}'" }
+    r.scan(/[E][a-z]*/).first.to_s[1..-1].to_s.chars.each { |e| lookup[e.upcase] = true }
+    r.scan(/[D][a-z]*/).first.to_s[1..-1].to_s.chars.each { |d| lookup[d.upcase] = false }
+    { enable_buzzer: lookup['A'],
+      enable_bypass_to_utility_on_overload: lookup['B'],
+      enable_power_saving: lookup['J'],
+      enable_lcd_timeout_escape_to_default_page: lookup['K'],
+      enable_overload_restart: lookup['U'],
+      enable_over_temperature_restart: lookup['V'],
+      enable_lcd_backlight: lookup['X'],
+      enable_primary_source_interrupt_alarm:  lookup['Y'],
+      enable_fault_code_recording: lookup['Z'] }
+  end)
+
+  ##
+  # The current device status
+  #
+  # Returns:
+  #    # A Hash containing device status information
+  #    { grid_voltage: 230.5, grid_current: 11.2, .. }
+  DEVICE_STATUS = OP.new(command: 'QPIGS', parser: lambda do |r|
+    r = r.data[1..-1].split(' ')
+    status = r[16].chars.map { |c| Boolean(c) }
+    { grid_voltage: Float(r[0]),
+      grid_frequency: Float(r[1]),
+      output_voltage: Float(r[2]),
+      output_frequency: Float(r[3]),
+      output_va: Integer(r[4]),
+      output_watts: Integer(r[5]),
+      output_load_percent: Integer(r[6]),
+      dc_bus_voltage: Integer(r[7]),
+      battery_voltage: Float(r[8]),
+      battery_charge_current: Float(r[9]),
+      battery_capacity_remaining: Integer(r[10]),
+      inverter_heatsink_celsius_temperature: Integer(r[11]),
+      pv_battery_input_current: Integer(r[12]),
+      pv_input_voltage: Float(r[13]),
+      solar_charge_controller_battery_voltage: Float(r[14]),
+      battery_discharge_current: Integer(r[15]),
+      add_sbu_priority_version: status[0],
+      configuration_changed: status[1],
+      solar_charge_controller_firmware_changed: status[2],
+      load_on: status[3],
+      battery_voltage_stable: status[4],
+      charger_enabled: status[5],
+      charging_from_solar_charge_controller: status[6],
+      charging_from_utility: status[7] }
+  end)
+
+  # Device mode
+  #
+  # Returns:
+  #    # A symbol denoting the device mode
+  #    See AxpertConstants::DEVICE_MODE for constants
+  DEVICE_MODE = OP.new(command: 'QMOD', parser: lambda { |r| CONS::DEVICE_MODE[r.data[1..-1].upcase] })
+
+  ##
+  # Device warning status messages
+  #
+  # Returns:
+  #    # An Array of Hashes
+  #    # Each Hash has the format { description: String description, level: :none/:fault/:warning }
+  #    # The level is only :none if a reserved error was returned which may signify an update
+  #    # of the parser is needed
+  #    [{ description: 'Bus voltage is too high', level: :fault}, ..]
+  DEVICE_WARNING_STATUS = OP.new(command: 'QPIWS', parser: lambda do |r|
+    r = r.data[1..-1].chars.map { |s| Boolean(s) }
+    parse = lambda { |desc, lvl = :none| { description: desc, level: lvl } }
+    errors = []
+    errors << parse.yield('Reserved') if r[0]
+    errors << parse.yield('Inverter fault', :fault) if r[1]
+    errors << parse.yield('Bus voltage is too high', :fault) if r[2]
+    errors << parse.yield('Bus voltage is too low', :fault) if r[3]
+    errors << parse.yield('Bus soft start failed ', :fault) if r[4]
+    errors << parse.yield('LINE_FAIL', :warning) if r[5]
+    errors << parse.yield('Output short circuited', :warning) if r[6]
+    errors << parse.yield('Inverter voltage too low', :fault) if r[7]
+    errors << parse.yield('Output voltage is too high', :fault) if r[8]
+    errors << parse.yield('Over temperature', (r[1] ? :fault : :warning)) if r[9]
+    errors << parse.yield('Fan is locked', (r[1] ? :fault : :warning)) if r[10]
+    errors << parse.yield('Battery voltage is too high', (r[1] ? :fault : :warning)) if r[11]
+    errors << parse.yield('Battery voltage is too low', 'Fault') if r[12]
+    errors << parse.yield('Reserved') if r[13]
+    errors << parse.yield('Battery under shutdown', :warning) if r[14]
+    errors << parse.yield('Reserved') if r[15]
+    errors << parse.yield('Overload', (r[1] ? :fault : :warning)) if r[16]
+    errors << parse.yield('EEPROM fault', :warning) if r[17]
+    errors << parse.yield('Inverter over current', :fault) if r[18]
+    errors << parse.yield('Inverter soft start failed', :fault) if r[19]
+    errors << parse.yield('Self test fail', :fault) if r[20]
+    errors << parse.yield('Over voltage on DC output of inverter', :fault) if r[21]
+    errors << parse.yield('Battery connection is open', :fault) if r[22]
+    errors << parse.yield('Current sensor failed ', :fault) if r[23]
+    errors << parse.yield('Battery short', :fault) if r[24]
+    errors << parse.yield('Power limit', :warning) if r[25]
+    errors << parse.yield('PV voltage high', :warning) if r[26]
+    errors << parse.yield('MPPT overload fault', :warning) if r[27]
+    errors << parse.yield('MPPT overload warning', :warning) if r[28]
+    errors << parse.yield('Battery too low to charge', :warning) if r[29]
+    errors << parse.yield('Reserved') if r[30]
+    errors << parse.yield('Reserved') if r[31]
+    errors
+  end)
+
+  ##
+  # The device default settings
+  #
+  # Returns:
+  #    # A Hash containing device defaults
+  #    { grid_voltage: 230.5, grid_current: 11.2, .. }
+  DEFAULT_SETTINGS = OP.new(command: 'QDI', parser: lambda do |r|
+    r = r.data[1..-1].split(' ')
+    { output_voltage: Float(r[0]),
+      output_frequency: Float(r[1]),
+      maximum_ac_charge_current: Integer(r[2]),
+      battery_under_voltage: Float(r[3]),
+      battery_float_charge_voltage: Float(r[4]),
+      battery_bulk_charge_voltage: Float(r[5]),
+      battery_recharge_voltage: Float(r[6]),
+      maximum_charge_current: Integer(r[7]),
+      input_voltage_sensitivity: CONS::INPUT_VOLTAGE_SENSITIVITY[r[8]],
+      output_source_priority: CONS::OUTPUT_SOURCE_PRIORITY[r[9]],
+      charger_source_priority: CONS::CHARGER_SOURCE_PRIORITY[r[10]],
+      battery_type: ::AxpertConstants::BATTERY_TYPE[r[11]],
+      enable_buzzer: !Boolean(r[12]),
+      enable_power_saving: Boolean(r[13]),
+      enable_overload_restart: Boolean(r[14]),
+      enable_over_temperature_restart: Boolean(r[15]),
+      enable_lcd_backlight:  Boolean(r[16]),
+      enable_primary_source_interrupt_alarm: Boolean(r[17]),
+      enable_fault_code_recording: Boolean(r[18]),
+      enable_bypass_to_utility_on_overload: Boolean(r[19]),
+      enable_lcd_timeout_escape_to_default_page: Boolean(r[20]),
+      output_mode: CONS::OUTPUT_MODE[r[21]],
+      battery_redischarge_voltage: Float(r[22]),
+      pv_parallel_ok_mode: CONS::PV_PARALLEL_OK_MODE[r[23]],
+      pv_power_balance_mode: CONS::PV_POWER_BALANCE_MODE[r[24]] }
+  end)
+
+  ##
+  # All the possible input values for the charge current setting
+  #
+  # Returns:
+  #    [10, 20, 30] # => Array of Integers, example given
+  ACCEPTED_CHARGE_CURRENT_VALUES = OP.new(command: 'QMCHGCR', parser: lambda do |r|
+    r.data[1..-1].split(' ').map { |s| Integer(s) }
+  end)
+
+  ##
+  # All the possible input values for the utility charge current setting
+  #
+  # Returns:
+  #    [10, 20, 30] # => Array of Integers, example given
+  ACCEPTED_UTILITY_CHARGE_CURRENT_VALUES = OP.new(command: 'QMUCHGCR', parser: lambda do |r|
+    r.data[1..-1].split(' ').map { |s| Integer(s) }
+  end)
+
+  ##
+  # Has device undergone DSP bootstrap
+  #
+  # Returns:
+  #    # A Boolean indicating if the device has undergone DSP bootstrap
+  #    true # Example
+  DSP_BOOTSTRAP_STATUS = OP.new(command: 'QBOOT', parser: lambda { |r| Boolean(r.data[1..-1]) })
+
+  ##
+  # Device parallel output mode status
+  #
+  # Returns:
+  #    # A symbol denoting the current device parallel output mode
+  #    See AxpertConstants::OUTPUT_MODE for constants
+  OUTPUT_MODE = OP.new(command: 'QOPM', parser: lambda { |r| CONS::OUTPUT_MODE[r.data[2..-1]] })
+
+  ##
+  # Parallel device information
+  #
+  # Input: (OPTIONAL, default = 0)
+  #    # Default of 0 seems to work for single unit mode
+  #    2 # => parallel_machine_number (Parallel mode only)
+  #
+  # Returns:
+  #    # A Hash containing parallel device status information
+  #    { grid_voltage: 230.5, grid_current: 11.2, .. }
+  PARALLEL_DEVICE_STATUS = OP.new(command: lambda { |i = 0| "QPGS#{Integer(i)}" }, parser: lambda do |r|
+    r = r.data[1..-1].split(' ')
+    status = r[19].chars
+    { parallel_number_exists: Boolean(r[0]),
+      serial_number: r[1],
+      device_mode: CONS::DEVICE_MODE[r[2]],
+      fault_code: CONS::FAULT_CODE[r[3]],
+      grid_voltage: Float(r[4]),
+      grid_frequency: Float(r[5]),
+      output_voltage: Float(r[6]),
+      output_frequency: Float(r[7]),
+      output_va: Integer(r[8]),
+      output_watts: Integer(r[9]),
+      load_percentage: Integer(r[10]),
+      battery_voltage: Float(r[11]),
+      battery_charge_current: Integer(r[12]),
+      battery_capacity: Integer(r[13]),
+      pv_input_voltage: Float(r[14]),
+      total_charge_current: Integer(r[15]),
+      total_output_va:  Integer(r[16]),
+      total_output_watt:  Integer(r[17]),
+      total_load_percentage: Integer(r[18]),
+      solar_charge_controller_enabled: Boolean(status[0]),
+      charging_from_utility: Boolean(status[1]),
+      charging_from_solar_charge_controller: Boolean(status[2]),
+      battery_status: [:normal, :under, :open][Integer("#{status[3]}#{status[4]}")],
+      line_status_ok: !Boolean(status[5]),
+      load_on: Boolean(status[6]),
+      configuration_changed: Boolean(status[7]),
+      output_mode:  CONS::OUTPUT_MODE[r[20]],
+      charger_source_priority: CONS::CHARGER_SOURCE_PRIORITY[r[21]],
+      maximum_charge_current: Integer(r[22]),
+      device_maximum_charge_current: Integer(r[23]),
+      pv_input_current: Integer(r[24]),
+      battery_discharge_current: Integer(r[25]) }
+  end)
+
+  ##
+  # Reset device to factory defaults
+  #
+  # Returns:
+  #    # A Boolean indicating if the device has reset to defaults succesfully
+  #    true # Example
+  RESET_TO_DEFAULT = OP.new(command: 'PF', error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device output frequency
+  #
+  # Input:
+  #    50 # => Any integer is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the frequency was set succesfully
+  #    true # Example
+  SET_OUTPUT_FREQUENCY = OP.new(command: lambda { |input| "F#{Integer(input).to_s.rjust(2, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device output source priority
+  #
+  # Input:
+  #    # A symbol donating the output source priority setting
+  #    See AxpertConstants::OUTPUT_SOURCE_PRIORITY
+  #
+  # Returns:
+  #    # A Boolean indicating if the output priority was set succesfully
+  #    true # Example
+  SET_OUTPUT_SOURCE_PRIORITY = OP.new(command: lambda { |i| "POP#{CONS::OUTPUT_SOURCE_PRIORITY.key(i).to_s.rjust(2, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set battery re-charge voltage
+  #
+  # Input:
+  #    24.3 # => Any float is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the recharge voltage was successfully set
+  #    true # Example
+  SET_BATTERY_RECHARGE_VOLTAGE = OP.new(command: lambda { |input| "PBCV#{Float(input).to_s.rjust(4, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set battery re-discharge voltage
+  #
+  # Input:
+  #    24.3 # => Any float is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the re-discharge voltage was successfully set
+  #    true # Example
+  SET_BATTERY_REDISCHARGE_VOLTAGE = OP.new(command: lambda { |input| "PBDV#{Float(input).to_s.rjust(4, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device charger priority
+  #
+  # Input:
+  #    # (REQUIRED) Parameter 0 => A symbol donating the charger source priority
+  #    See AxpertConstants::CHARGER_SOURCE_PRIORITY
+  #
+  #    # (OPTIONAL) Parameter 1 => parallel_machine_number (Parallel mode only)
+  #    5 # => Do not pass in this value unless the device is running in parallel mode
+  #
+  # Returns:
+  #    # A Boolean indicating if the device charger priority was set successfully
+  #    true # Example
+  SET_CHARGER_SOURCE_PRIORITY = OP.new(command: lambda do |mode, parallel_machine_number = nil|
+    if parallel_machine_number.nil?
+      "PPCP#{Integer(parallel_machine_number).to_s}#{CONS::CHARGER_SOURCE_PRIORITY.key(mode).to_s.rjust(2, '0')}"
+    else
+      "PCP#{CONS::CHARGER_SOURCE_PRIORITY.key(mode).to_s.rjust(2, '0')}"
+    end
+  end, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device input voltage sensitivity
+  #
+  # Input:
+  #    # A symbol denoting the input voltage sensitivity
+  #    See AxpertConstants::INPUT_VOLTAGE_SENSITIVITY
+  #
+  # Returns:
+  #    # A Boolean indicating if the device input voltage sensitivity was set successfully
+  #    true # Example
+  SET_INPUT_VOLTAGE_SENSITIVITY = OP.new(command: lambda { |i| "PGR#{CONS::INPUT_VOLTAGE_SENSITIVITY.key(i).to_s.rjust(2, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set battery type
+  #
+  # Input:
+  #    # A symbol denoting the battery type
+  #    See AxpertConstants::BATTERY_TYPE
+  #
+  # Returns:
+  #    # A Boolean indicating if the device battery type was set successfully
+  #    true # Example
+  SET_BATTERY_TYPE = OP.new(command: lambda { |i| "PBT#{CONS::BATTERY_TYPE.key(i).to_s.rjust(2, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device battery cut-off voltage
+  #
+  # Input:
+  #    22.1 # => Any float is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the battery cut-off voltage was successfully set
+  #    true # Example
+  SET_BATTERY_CUTOFF_VOLTAGE = OP.new(command: lambda { |input| "PSDV#{Float(input).to_s.rjust(4, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device battery constant charging voltage
+  #
+  # Input:
+  #    28.3 # => Any float is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the battery constant charging voltage was successfully set
+  #    true # Example
+  SET_BATTERY_CONSTANT_CHARGING_VOLTAGE = OP.new(command: lambda { |input| "PCVV#{Float(input).to_s.rjust(4, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set device battery float charging voltage
+  #
+  # Input:
+  #    26.5 # => Any float is accepted, consult manual for valid values
+  #
+  # Returns:
+  #    # A Boolean indicating if the battery float charging was successfully set
+  #    true # Example
+  SET_BATTERY_FLOAT_CHARGING_VOLTAGE = OP.new(command: lambda { |input| "PBFT#{Float(input).to_s.rjust(4, '0')}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set parallel PV OK condition
+  #
+  # Input:
+  #    # A input symbol donating the PV Parallel OK condition mode setting
+  #    See AxpertConstants::PV_PARALLEL_OK_MODE
+  #
+  # Returns:
+  #    # A Boolean indicating if the parallel PV OK condition was set successfully
+  #    true # Example
+  SET_PV_PARALLEL_OK_MODE = OP.new(command: lambda { |i| "PPVOKC#{CONS::PV_PARALLEL_OK_MODE.key(i).to_s}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set PV power balance mode
+  #
+  # Input:
+  #    # A input symbol donating the PV Power balance mode
+  #    See AxpertConstants::PV_POWER_BALANCE_MODE
+  #
+  # Returns:
+  #    # A Boolean indicating if the PV power balance mode was set successfully
+  #    true # Example
+  SET_PV_POWER_BALANCE_MODE = OP.new(command: lambda { |i| "PSPB#{CONS::PV_POWER_BALANCE_MODE.key(i).to_s}" }, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set the maximum charging current
+  #
+  # Input:
+  #    # (REQUIRED) Parameter 0 => Charge current 
+  #    30  # => Any integer is accepted, consult manual for valid values
+  #
+  #    # (OPTIONAL) Parameter 1 => parallel_machine_number (Parallel mode only)
+  #    5 # => Do not pass in this value unless the device is running in parallel mode
+  #
+  # Returns:
+  #    # A Boolean indicating if the maximum charging current was set successfully
+  #    true # Example
+  SET_MAXIMUM_CHARGING_CURRENT = OP.new(command: lambda do |current, parallel_machine_number = 0|
+    current = Integer(current)
+    if (current >= 100)
+      "MNCHGC#{Integer(parallel_machine_number).to_s}#{current.to_s.rjust(3, '0')}"
+    else
+      "MCHGC#{Integer(parallel_machine_number).to_s}#{current.to_s.rjust(2, '0')}"
+    end
+  end, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  #
+  # Set the maximum charging current for utility
+  #
+  # Input:
+  #    # (REQUIRED) Parameter 0 => Charge current 
+  #    30  # => Any integer is accepted, consult manual for valid values
+  #
+  #    # (OPTIONAL) Parameter 1 => parallel_machine_number (Parallel mode only)
+  #    5 # => Do not pass in this value unless the device is running in parallel mode
+  #
+  # Returns:
+  #    # A Boolean indicating if the maximum charging current for utility was set successfully
+  #    true # Example
+  SET_MAXIMUM_UTILITY_CHARGING_CURRENT = OP.new(command: lambda do |current, parallel_machine_number = 0|
+    "MUCHGC#{Integer(parallel_machine_number).to_s}#{Integer(current).to_s.rjust(2, '0')}"
+  end, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  ##
+  # Set the parallel output mode (or single mode)
+  #
+  # Input:
+  #    # (REQUIRED) Parameter 0 => A input symbol donating output mode
+  #    See AxpertConstants::OUTPUT_MODE
+  #
+  #    # (OPTIONAL) Parameter 1 => parallel_machine_number (Parallel mode only)
+  #    5 # => Do not pass in this value unless the device is running in parallel mode
+  #
+  # Returns:
+  #    # A Boolean indicating if the parallel output mode was set successfully
+  #    true # Example
+  SET_OUTPUT_MODE = OP.new(command: lambda do |mode, parallel_machine_number = 0|
+   "POPM#{CONS::OUTPUT_MODE.key(mode)}#{Integer(parallel_machine_number).to_s}"
+  end, error_on_nak: false, parser: lambda { |r| (r.data == '(ACK') })
+
+  require 'axpert_constants'
+  CONS = ::AxpertConstants # :nodoc:
+  send(:remove_const, :OP)
+end
+
+# This is hacky but it is really a must for accurate parsing
+module ::Kernel # :nodoc:
+  def Boolean(input) # :nodoc:
+    return true if input.equal?(TrueClass)
+    return false if input.equal?(FalseClass)
+    parse = input.to_s.chomp.downcase
+    return true if ('true' == parse) || ('y' == parse) || ('t' == parse) || (1 == (Integer(parse) rescue nil))
+    return false if ('false' == parse) || ('n' == parse) || ('f' == parse) || (0 == (Integer(parse) rescue nil))
+    raise
+  rescue StandardError, ScriptError
+    raise ::ArgumentError.new("invalid value for Boolean(): \"#{input}\"")
+  end
+end

data/lib/axpert_constants.rb

@@ -0,0 +1,151 @@
+##
+# A list of constants used by the Axpert devices with a convenient parser
+#
+# @author: Johan van der Vyver
+module AxpertConstants
+  def self.lookup_hash(type, values) # :nodoc:
+    type = type.to_s.strip.freeze
+    values.values.each(&:freeze)
+    lookup = Hash.new do |_, k|
+      if lookup.has_key?(k.to_s)
+        lookup[k.to_s]
+      elsif (k.is_a?(Numeric) && (k.to_i == k) && (lookup.values.count > k))
+        lookup.values[k]
+      elsif lookup.values.include?(k)
+        k
+      else
+        raise ::AxpertConstants::UnknownConstant.new("Unknown #{type} '#{k}'")
+      end
+    end
+    lookup.instance_eval <<-RUBY_CODE
+      def key(input) # :nodoc: 
+        parse = super(self[input]) rescue nil
+        parse = (super(input.to_s.to_sym) rescue nil) if parse.nil?
+        parse = (super(input) rescue nil) if parse.nil?
+        return parse unless parse.nil?
+        raise ::AxpertConstants::UnknownConstant.new("Could not find the #{type} constant '\#{input}' in \#{self.values}")
+      end
+    RUBY_CODE
+    lookup.merge!(values).freeze
+  end
+
+  ##
+  # The type of batteries connected to the device
+  # Used to determine the float, bulk charging, re-charge and re-discharge voltage ranges
+  #
+  #    :agm # => Absorbent Glass Mat (AGM)
+  #    :flooded # => Flooded Cell
+  #    :user # => User defined
+  BATTERY_TYPE = lookup_hash('battery type', {'0' => :agm, '1' => :flooded, '2' => :user})
+
+  ##
+  # The current device mode
+  #
+  #    :power # => Power on
+  #    :standby # => Standby
+  #    :line # => Line
+  #    :battery # => Battery
+  #    :fault # => Fault
+  DEVICE_MODE = lookup_hash('device mode', {'P' => :power, 'S' => :standby, 'L' => :line, 'B' => :battery, 'F' => :fault})
+
+  ##
+  # The input voltage is monitored to determine if it is within an acceptable range
+  # The sensitivity determines when the unit switches output mode to/from Utility
+  #
+  #    :appliance # => Appliance mode sensitivity (see manual for ranges)
+  #    :ups # => UPS mode sensitivity (see manual for ranges)
+  INPUT_VOLTAGE_SENSITIVITY = lookup_hash('input voltage sensitivity', {'0' => :appliance, '1' => :ups})
+
+  ##
+  # Device output priority
+  #
+  #    :utility # => Prefer utility as first output power source
+  #    :solar # => Prefer solar as first output power source
+  #    :sbu # => Prefer solar first, then battery and utility last as output power source
+  OUTPUT_SOURCE_PRIORITY = lookup_hash('output source priority', {'0' => :utility, '1' => :solar, '2' => :sbu})
+
+  ##
+  # Battery charger source priority
+  #
+  #    :utility_first # => Charge batteries from utility first
+  #    :solar:first # => Charge batteries from solar first,
+  #    :solar_and_utility # => Charge batteries from solar & utility
+  #    :solar_only # => Charge batteries from solar only
+  CHARGER_SOURCE_PRIORITY = lookup_hash('charger source priority', {'0' => :utility_first, '1' => :solar_first, '2' => :solar_and_utility, '3' => :solar_only})
+
+  ##
+  # The type of device
+  #
+  #    :grid_tie # => Grid tie device
+  #    :off_grid # => Off-Grid device
+  #    :hybrid # =>Hybrid device
+  DEVICE_TYPE = lookup_hash('device type', {'00' => :grid_tie, '01' => :off_grid, '10' => :hybrid})
+
+  ##
+  # The internal device topology
+  # NOTE: All models make use of a transformer in Inverter mode
+  #
+  #    :transformerless # => The device output does not pass through an isolation transformer
+  #    :transformer # => The device output does pass through an isolation transformer
+  DEVICE_TOPOLOGY = lookup_hash('device topology', {'0' => :transformerless, '1' => :transformer})
+
+  ##
+  # The current output mode of the device
+  #
+  #    :single # => The device is running in single mode, single phase output
+  #    :parallel # => The device is running in parallel mode (allow multiple units in parallel), single phase output
+  #    :phase1 # => The device is running in parallel mode, 3 phase output, set to phase 1 of 3
+  #    :phase2 # => The device is running in parallel mode, 3 phase output, set to phase 2 of 3
+  #    :phase3 # => The device is running in parallel mode, 3 phase output, set to phase 3 of 3
+  OUTPUT_MODE = lookup_hash('output mode', {'0' => :single, '1' => :parallel, '2' => :phase1, '3' => :phase2, '4' => :phase3})
+
+  ##
+  # Only applicable to units running in Parallel!
+  # The required mode for the PV to report OK on the inverter in parallel mode
+  #
+  #    :one # => Only one unit needs to report PV is OK
+  #    :all # => All units must report that PV is OK
+  PV_PARALLEL_OK_MODE = lookup_hash('PV parallel mode', {'0' => :one, '1' => :all})
+
+  ##
+  # The PV power balance mode setting
+  #
+  #    :charge # => PV output is limited to battery charge current
+  #    :charge_and_load # => PV output will attempt to use enough power for charging the battery and enough to supply the connected load
+  PV_POWER_BALANCE_MODE = lookup_hash('PV power balance mode', {'0' => :charge, '1' => :charge_and_load})
+
+  ##
+  # Possible fault codes returned by the device
+  FAULT_CODE = lookup_hash('fault code',
+   { '00' => 'No faults',
+     '01' => 'Fan is locked',
+     '02' => 'Over temperature',
+     '03' => 'Battery voltage is too high',
+     '04' => 'Battery voltage is too low',
+     '05' => 'Output short circuited/Over temperature',
+     '06' => 'Output voltage is too high',
+     '07' => 'Overload time out',
+     '08' => 'Bus voltage is too high',
+     '09' => 'Bus soft start failed',
+     '11' => 'Main relay failed',
+     '51' => 'Inverter over current',
+     '52' => 'Bus soft start failed',
+     '53' => 'Inverter soft start failed',
+     '54' => 'Self-test failed',
+     '55' => 'Inverter over voltage on DC output',
+     '56' => 'Battery connection is open',
+     '57' => 'Current sensor failed',
+     '58' => 'Output voltage is too low',
+     '60' => 'Inverter negative power',
+     '71' => 'Parallel version different',
+     '71' => 'Output circuit failed',
+     '80' => 'CAN communication failed',
+     '81' => 'Parallel host line lost',
+     '82' => 'Parallel synchronized signal lost',
+     '83' => 'Parallel battery voltage is detected as different',
+     '84' => 'Parallel line voltage or frequency is detected as different',
+     '85' => 'Parallel line input current unbalanced',
+     '86' => 'Parallel output setting is different' })
+
+  class UnknownConstant < RuntimeError; end # :nodoc:
+end

data/lib/axpert_rs232.rb

@@ -0,0 +1,2 @@
+require 'axpert_commands'
+

data/lib/voltronic_device_operation.rb

@@ -0,0 +1,113 @@
+##
+# A convenient immutable object to encapsulate the logic
+# of a Voltronic Device operation consisting of:
+# Command, parameter validation and result parser
+#
+# @author: Johan van der Vyver
+class VoltronicDeviceOperation
+  require 'voltronic_rs232'
+  require 'time'
+
+  def initialize(input, &blk)
+    input = {}.merge(input) rescue (raise ::ArgumentError.new("Expected an input hash")) 
+
+    @command = begin
+      as_lambda(input.fetch(:command))
+    rescue ::StandardError => err
+      err = "#{err.class.name.to_s} thrown; #{err.message.to_s}"
+      raise ::ArgumentError.new("Expected :command to be a String with a device command or Proc (#{err})")
+    end
+
+    @error_on_nak = (true == input.fetch(:error_on_nak, true))
+
+    @parser = begin
+      as_lambda(input.fetch(:parser))
+    rescue ::StandardError => err
+      err = "#{err.class.name.to_s} thrown; #{err.message.to_s}"
+      raise ::ArgumentError.new("Expected :parser to be a Proc or Lambda (#{err})")
+    end
+
+    @read_timeout = Integer(input.fetch(:serial_read_timeout_seconds, 2))
+    @write_timeout = Integer(input.fetch(:serial_write_timeout_seconds, 2))
+
+    @termination_character = begin
+      parse = input.fetch(:serial_termination_character, "\r").to_s
+      raise ::ArgumentError.new("Expected :serial_termination_character to be a single character") unless (parse.length == 1)
+      parse.freeze
+    end
+
+    freeze
+  end
+
+  ##
+  # Issue a command to the device and parse the output result
+  def issue_command(serial, *args)
+    serial.read_timeout = -1 # Prevent locking on serial
+
+    serial.write(command(*args).bytes)
+    result = begin
+      parse = ''
+      read_timeout = ::Time.now.to_i + @read_timeout # 2 seconds
+      while(true)
+        ch = serial.getc # Retrieve a single character from Serial port
+        if ch.nil?
+          sleep 0.1 # 100ms pause before polling again
+          next
+        end
+        parse += ch
+        break if (@termination_character == ch)
+        raise ::IOError.new("IO read timeout reached, giving up") if (Time.now.to_i > read_timeout)
+      end
+      parse
+    end
+
+    parse_result(result[0..-4])
+  end
+
+  ##
+  # Create an VoltronicRS232 object containing a command
+  # and optional parameter to execute on the device
+  def command(*args)
+    RS232_PROTO.new(@command.yield(*args))
+  end
+
+  ##
+  # Parse the command output returned from the Voltronic device
+  def parse_result(result)
+    result = RS232_PROTO.new(result)
+    if (@error_on_nak && ('(NAK' == result.data.upcase))
+      raise NAKReceivedError.new("Received NAK from device, this usually means an error occured, an invalid value was supplied or the command is not supported")
+    end
+    @parser.yield(result)
+  rescue ::StandardError, ::ScriptError => err
+    raise err if err.is_a?(NAKReceivedError)
+    err = "#{err.class.name.to_s} thrown; #{err.message.to_s}"
+    raise RS232ParseError.new("Could not parse the result, the output format may have changed (#{err})")
+  end
+
+  def to_s # :nodoc:
+    "#{self.class.name.to_s.split('::').last}"
+  end
+
+  def inspect # :nodoc:
+    self.to_s
+  end
+
+  private
+
+  def as_lambda(input)
+    if !input.is_a?(Proc)
+      input = begin 
+        input_string = input.to_s.chomp.freeze
+        lambda { input_string.to_s.chomp.freeze }
+      end
+    end
+    result = Object.new
+    result.define_singleton_method(:_, &input)
+    result.method(:_).to_proc.freeze
+  end
+
+  RS232_PROTO = ::VoltronicRS232 # :nodoc
+  class NAKReceivedError < ::RuntimeError; end # :nodoc:
+  class RS232ParseError < RuntimeError; end # :nodoc:
+end

data/lib/voltronic_rs232.rb

@@ -0,0 +1,75 @@
+##
+# Simple immutable object representing the Voltronic RS232 protocol
+#
+# @author: Johan van der Vyver
+class VoltronicRS232
+  ##
+  # The human readable command to be sent to the device
+  attr_reader :data
+
+  ##
+  # The calculated CRC for the data
+  attr_reader :crc
+
+  ##
+  # The encoded data that will be transmitted over the wire
+  # Format: <DATA><CRC><CR>
+  attr_reader :bytes
+
+  def initialize(data) #:nodoc:
+    @data = data.to_s.chomp.dup.freeze
+    if (@data != @data.encode(::Encoding.find('ASCII'), {invalid: :replace, undef: :replace, replace: ''}))
+      raise ArgumentError.new("Input data can only be ASCII")
+    end
+    @crc = calculate_crc(data.bytes.to_a).map { |b| b.chr }.join.freeze
+    @bytes = "#{@data}#{@crc}\r".freeze
+    self.freeze
+  end
+
+  def to_s #:nodoc:
+    "#{self.class.name.to_s.split('::').last}(data: '#{data}')"
+  end
+
+  def inspect #:nodoc:
+    to_s
+  end
+
+  def ==(other) #:nodoc:
+    return true if self.equal?(other)
+    return false if other.nil?
+    return false unless other.respond_to?(:bytes)
+    (self.bytes == other.bytes)
+  end
+
+  private
+
+  # CRC calculation source: http://forums.aeva.asn.au/pip4048ms-inverter_topic4332_post53760.html#53760
+  def calculate_crc(pin) #:nodoc:
+    crc, da = 0, 0
+    for index in 0..(pin.length-1)
+      da = byte(byte(crc >> 8) >> 4)
+      crc = short(short(crc << 4) ^ CRC_TABLE[byte(da ^ byte(pin[index] >> 4))])
+      da = byte(byte(crc >> 8) >> 4)
+      crc = short(short(crc << 4) ^ CRC_TABLE[byte(da ^ byte(pin[index] & 0x0f))])
+    end
+
+    crc_low, crc_high = byte(crc & 0x00FF), byte(crc >> 8)
+    crc_low = short(crc_low + 1) if CRC_MOD.include?(crc_low)
+    crc_high = short(crc_high + 1) if CRC_MOD.include?(crc_high)
+    crc = short(short(crc_high << 8) | crc_low)
+    [byte(short(crc >> 8) & 0xff), byte(crc & 0xff)]
+  end
+
+  def byte(input) #:nodoc:
+    (input & 255)
+  end
+
+  def short(input) #:nodoc:
+    (input & 65535)
+  end
+
+  CRC_TABLE = [0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
+               0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef].freeze #:nodoc:
+
+  CRC_MOD = [0x28, 0x0d, 0x0a].freeze #:nodoc:
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: axpert_rs232
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Johan van der Vyver
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-26 00:00:00.000000000 Z
+dependencies: []
+description: Simplify communicating with a Voltronics Axpert range inverter
+email: johan.vdvyver@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/axpert_commands.rb
+- lib/axpert_constants.rb
+- lib/voltronic_device_operation.rb
+- lib/voltronic_rs232.rb
+- lib/axpert_rs232.rb
+homepage: http://rubygems.org/gems/axpert_rs232
+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.0.14
+signing_key: 
+specification_version: 4
+summary: Simplify communicating with a Voltronics Axpert range inverter
+test_files: []