waterfurnace_aurora 0.1.1

data/lib/aurora.rb

@@ -0,0 +1,15 @@
+require 'rmodbus'
+
+require 'aurora/abc_client'
+require 'aurora/iz2_zone'
+require 'aurora/modbus/server'
+require 'aurora/modbus/slave'
+require 'aurora/registers'
+
+# extend ModBus for WaterFurnace's custom functions
+ModBus::RTUServer.include(Aurora::ModBus::Server)
+ModBus::Client::Slave.prepend(Aurora::ModBus::Slave)
+ModBus::RTUSlave.prepend(Aurora::ModBus::RTU)
+
+module Aurora
+end

data/lib/aurora/abc_client.rb

@@ -0,0 +1,82 @@
+module Aurora
+  class ABCClient
+    attr_reader :modbus_slave,
+      :iz2_zones,
+      :current_mode,
+      :fan_speed,
+      :entering_air_temperature,
+      :relative_humidity,
+      :leaving_air_temperature,
+      :leaving_water_temperature,
+      :entering_water_temperature,
+      :dhw_water_temperature,
+      :waterflow,
+      :compressor_speed,
+      :outdoor_temperature,
+      :fp1,
+      :fp2
+
+    def initialize(modbus_slave)
+      @modbus_slave = modbus_slave
+      @modbus_slave.read_retry_timeout = 15
+      @modbus_slave.read_retries = 2
+      iz2_zone_count = @modbus_slave.holding_registers[483]
+      @iz2_zones = (0...iz2_zone_count).map { |i| IZ2Zone.new(self, i + 1) }
+    end
+
+    def refresh
+      registers_to_read = [19..20, 30, 344, 740..741, 900, 1110..1111, 1114, 1117, 3027, 31003]
+      # IZ2 zones
+      iz2_zones.each_with_index do |_z, i|
+        base1 = 21203 + i * 9
+        base2 = 31007 + i * 3
+        base3 = 31200 + i * 3
+        registers_to_read << (base1..(base1 + 1))
+        registers_to_read << (base2..(base2 + 2))
+        registers_to_read << base3
+      end
+
+      registers = @modbus_slave.holding_registers[*registers_to_read]
+      Aurora.transform_registers(registers)
+
+      @fan_speed                  = registers[344]
+      @entering_air_temperature   = registers[740]
+      @relative_humidity          = registers[741]
+      @leaving_air_temperature    = registers[900]
+      @leaving_water_temperature  = registers[1110]
+      @entering_water_temperature = registers[1111]
+      @dhw_water_temperature      = registers[1114]
+      @waterflow                  = registers[1117]
+      @compressor_speed           = registers[3027]
+      @outdoor_temperature        = registers[31003]
+      @fp1                        = registers[19]
+      @fp2                        = registers[20]
+      @locked_out                 = registers[1117]
+
+      outputs = registers[30]
+      if outputs.include?(:lockout)
+        @current_mode = :lockout
+      elsif outputs.include?(:cc2)
+        @current_mode = outputs.include?(:rv) ? :c2 : :h2
+      elsif outputs.include?(:cc)
+        @current_mode = outputs.include?(:rv) ? :c1 : :h1
+      elsif outputs.include?(:eh2)
+        @current_mode = :eh2
+      elsif outputs.include?(:eh1)
+        @current_mode = :eh1
+      elsif outputs.include?(:blower)
+        @current_mode = :blower
+      else
+        @current_mode = :standby
+      end
+
+      iz2_zones.each do |z|
+        z.refresh(registers)
+      end
+    end
+
+    def inspect
+      "#<Aurora::ABCClient #{(instance_variables - [:@modbus_slave]).map { |iv| "#{iv}=#{instance_variable_get(iv).inspect}" }.join(', ')}>"
+    end
+  end
+end

data/lib/aurora/iz2_zone.rb

@@ -0,0 +1,99 @@
+module Aurora
+  class IZ2Zone
+    attr_reader :zone_number,
+      :target_mode,
+      :current_mode,
+      :target_fan_mode,
+      :current_fan_mode,
+      :fan_intermittent_on,
+      :fan_intermittent_off,
+      :priority,
+      :size, :normalized_size,
+      :ambient_temperature,
+      :cooling_target_temperature,
+      :heating_target_temperature
+
+    def initialize(abc, zone_number)
+      @abc = abc
+      @zone_number = zone_number
+    end
+
+    def refresh(registers)
+      @ambient_temperature = registers[31007 + (zone_number - 1) * 3]
+
+      config1 = registers[31008 + (zone_number - 1) * 3]
+      config2 = registers[31009 + (zone_number - 1) * 3]
+      config3 = registers[31200 + (zone_number - 1) * 3]
+
+      @target_fan_mode = config1[:fan]
+      @fan_intermittent_on = config1[:on_time]
+      @fan_intermittent_off = config1[:off_time]
+      @cooling_target_temperature = config1[:cooling_target_temperature]
+      @heating_target_temperature = config2[:heating_target_temperature]
+      @target_mode = config2[:mode]
+      @current_mode = config2[:call]
+      @current_fan_mode = config2[:damper] == :open
+
+      @priority = config3[:zone_priority]
+      @size = config3[:zone_size]
+      @normalized_size = config3[:normalized_size]
+    end
+
+    def target_mode=(value)
+      value = Aurora::HEATING_MODE.invert[value]
+      return unless value
+      @abc.modbus_slave.holding_registers[21202 + (zone_number - 1) * 9] = value
+      @target_mode = Aurora::HEATING_MODE[@abc.modbus_slave.holding_registers[21202 + (zone_number - 1) * 9]]
+    end
+
+    def target_fan_mode=(value)
+      value = Aurora::FAN_MODE.invert[value]
+      return unless value
+      @abc.modbus_slave.holding_registers[21205 + (zone_number - 1) * 9] = value
+      registers = @abc.modbus_slave.read_multiple_holding_registers(31008 + (zone_number - 1) * 3)
+      Aurora.transform_registers(registers)
+      @target_fan_mode = registers.first.last[:fan]
+    end
+
+    def fan_intermittent_on=(value)
+      return unless value >= 0 && value <= 25 && value % 5 == 0
+      @abc.modbus_slave.holding_registers[21206 + (zone_number - 1) * 9] = value
+      registers = @abc.modbus_slave.read_multiple_holding_registers(31008 + (zone_number - 1) * 3)
+      Aurora.transform_registers(registers)
+      @fan_intermittent_on = registers.first.last[:on_time]
+    end
+
+    def fan_intermittent_off=(value)
+      return unless value >= 0 && value <= 40 && value % 5 == 0
+      @abc.modbus_slave.holding_registers[21207 + (zone_number - 1) * 9] = value
+      registers = @abc.modbus_slave.read_multiple_holding_registers(31008 + (zone_number - 1) * 3)
+      Aurora.transform_registers(registers)
+      @fan_intermittent_on = registers.first.last[:off_time]
+    end
+
+    def heating_target_temperature=(value)
+      return unless value >= 40 && value <= 90
+      value = (value * 10).to_i
+      @abc.modbus_slave.holding_registers[21203 + (zone_number - 1) * 9] = value
+
+      base = 31008 + (zone_number - 1) * 3
+      registers = @abc.modbus_slave.read_multiple_holding_registers(base..(base + 1))
+      Aurora.transform_registers(registers)
+      registers[base + 1][:heating_target_temperature]
+    end
+
+    def cooling_target_temperature=(value)
+      return unless value >= 54 && value <= 99
+      value = (value * 10).to_i
+      @abc.modbus_slave.holding_registers[21204 + (zone_number - 1) * 9] = value
+
+      registers = @abc.modbus_slave.read_multiple_holding_registers(31008 + (zone_number - 1) * 3)
+      Aurora.transform_registers(registers)
+      registers.first.last[:cooling_target_temperature]
+    end
+
+    def inspect
+      "#<Aurora::IZ2Zone #{(instance_variables - [:@abc]).map { |iv| "#{iv}=#{instance_variable_get(iv).inspect}" }.join(', ')}>"
+    end
+  end
+end

data/lib/aurora/modbus/server.rb

@@ -0,0 +1,72 @@
+module Aurora
+  module ModBus
+    module Server
+      def parse_request(func, req)
+        case func
+        when 65
+          # 1 function register, a multiple of two words
+          return unless (req.length - 1) % 4 == 0
+          params = []
+          req[1..-1].unpack("n*").each_slice(2) do |(addr, quant)|
+            params << { addr: addr, quant: quant }
+          end
+          params
+        when 66
+          return unless (req.length - 1) % 2 == 0
+          req[1..-1].unpack("n*")
+        when 67
+          # 1 function register, a multiple of two words
+          return unless (req.length - 1) % 4 == 0
+          params = []
+          req[1..-1].unpack("n*").each_slice(2) do |(addr, val)|
+            params << { addr: addr, val: val }
+          end
+          params
+        when 68
+          return unless req.length == 5
+          { noidea1: req[1,2].unpack("n"), noidea2: req[3,2].unpack("n") }
+        else
+          super
+        end
+      end
+
+      def parse_response(func, res)
+        return {} if func == 67 && res.length == 1
+        return { noidea: res[-1].ord } if func == 68 && res.length == 2
+        func = 3 if func == 65 || func == 66
+        super
+      end
+
+      def process_func(func, slave, req, params)
+        case func
+        when 65
+          pdu = ""
+          params.each do |param|
+            if (err = validate_read_func(param, slave.holding_registers))
+              return (func | 0x80).chr + err.chr
+            end
+
+            pdu += slave.holding_registers[param[:addr],param[:quant]].pack('n*')
+          end
+          pdu = func.chr + pdu.length.chr + pdu
+          pdu
+        when 66
+          pdu = params.map { |addr| slave.holding_registers[addr] }.pack('n*')
+          pdu = func.chr + pdu.length.chr + pdu
+          pdu
+        when 67
+          slave.holding_registers[param[:addr]] = param[:val]
+          pdu = req[0,2]
+        else
+          super
+        end
+      end
+    end
+  end
+end
+
+# 65 => read multiple discontiguous register ranges (command is a list of pairs of addr and quant)
+# 66 => read multiple discontiguous registers (command is a list of addrs)
+# 67 => write multiple discontiguous registers (command is a list of pairs of addr and value; response has no content)
+# 68 => ?? request has 4 bytes, response has 1 byte that seems to be 0 (for success?)
+ModBus::Server::Funcs.concat([65, 66, 67, 68])

data/lib/aurora/modbus/slave.rb

@@ -0,0 +1,52 @@
+module Aurora
+  module ModBus
+    module Slave
+      def read_multiple_holding_registers(*ranges)
+        values = if ranges.any? { |r| r.is_a?(Range) }
+          addrs_and_lengths = ranges.map { |r| r = Array(r); [r.first, r.last - r.first + 1] }.flatten
+          query("\x41" + addrs_and_lengths.pack("n*")).unpack("n*")
+        else
+          query("\x42" + ranges.pack("n*")).unpack("n*")
+        end
+        ranges.map { |r| Array(r) }.flatten.zip(values).to_h
+      end
+
+      def holding_registers
+        WFProxy.new(self, :holding_register)
+      end
+    end
+
+    class WFProxy < ::ModBus::ReadWriteProxy
+      def [](*keys)
+        return super if keys.length == 1
+        @slave.read_multiple_holding_registers(*keys)
+      end
+    end
+
+    module RTU
+      def read_rtu_response(io)
+        # Read the slave_id and function code
+        msg = read(io, 2)
+        log logging_bytes(msg)
+  
+        function_code = msg.getbyte(1)
+        case function_code
+          when 1,2,3,4,65,66 then
+            # read the third byte to find out how much more
+            # we need to read + CRC
+            msg += read(io, 1)
+            msg += read(io, msg.getbyte(2)+2)
+          when 5,6,15,16 then
+            # We just read in an additional 6 bytes
+            msg += read(io, 6)
+          when 22 then
+            msg += read(io, 8)
+          when 0x80..0xff then
+            msg += read(io, 3)
+          else
+            raise ModBus::Errors::IllegalFunction, "Illegal function: #{function_code}"
+        end
+      end
+    end
+  end
+end

data/lib/aurora/registers.rb

@@ -0,0 +1,660 @@
+module Aurora
+  extend self
+
+  def normalize_ranges(ranges)
+    registers = ranges.map { |r| Array(r) }.flatten.sort.uniq
+    result = []
+    totals = []
+    run_start = nil
+    count = 0
+    registers.each_with_index do |r, i|
+      run_start ||= r
+      if i + 1 == registers.length || r + 1 != registers[i + 1]
+        if r == run_start
+          result << r
+          if (count += 1) == 100
+            totals << result
+            result = []
+            count = 0
+          end
+        else
+          range = run_start..r
+          if count + range.count > 100
+            totals << result
+            result = []
+            count = 0
+          end
+          count += range.count
+          result << range
+        end
+        run_start = nil
+      end
+    end
+    totals << result unless result.empty?
+    totals
+  end
+
+  TO_HUNDREDTHS = ->(v) { v.to_f / 100 }
+  TO_TENTHS = ->(v) { v.to_f / 10 }
+  TO_LAST_LOCKOUT = ->(v) { v & 0x8000 == 0x8000 ? v & 0x7fff : nil }
+  NEGATABLE = ->(v) { v & 0x8000 == 0x8000 ? v - 0x10000 : v }
+
+  def from_bitmask(v, flags)
+    result = []
+    flags.each do |(bit, flag)|
+      result << flag if v & bit == bit
+      v &= ~bit
+    end
+    result << "0x%04x" % v if v != 0
+    result
+  end
+
+  def to_string(registers, idx, length)
+    puts "converting #{idx} of length #{length}"
+    (idx...(idx + length)).map do |i|
+      (registers[i] >> 8).chr + (registers[i] & 0xff).chr
+    end.join.sub(/[ \0]+$/, '')
+  end
+
+  FAULTS = {
+    1 => "Input Flt Limit",
+    2 => "High Pressure",
+    3 => "Low Pressure",
+    4 => "FP2",
+    5 => "FP1",
+    7 => "Condensate Limit",
+    8 => "Over/Under Voltage",
+    9 => "AirF/RPM",
+    10 => "CompMon",
+    11 => "FP1/2 Snr Limit",
+    12 => "RefPerfrm Limit",
+    13 => "NCrtAxbSr Limit",
+    14 => "CrtAxbSnr Limit",
+    15 => "HW Limit",
+    16 => "VSPumpFlt Limit",
+    17 => "CommTStat Limit",
+    18 => "NCritComm Limit",
+    19 => "Crit Comm Limit",
+    21 => "Low Loop Pressure",
+    22 => "ComEcmErr Limit",
+    23 => "HAGenAlrm1 Limit",
+    24 => "HAGenAlrm2 Limit",
+    25 => "AxbEevErr Limit",
+    41 => "High Drive Temp Limit",
+    42 => "High Discharge Temp Limit",
+    43 => "Low Suction Pressure Limit",
+    44 => "Low Con Pressure Limit",
+    45 => "High Con Pressure Limit",
+    46 => "Out Power Limit",
+    47 => "EevIDComm Limit",
+    48 => "EevODComm Limit",
+    49 => "CabTmpSnr Limit",
+    51 => "Discharge Temp Sensor Limit",
+    52 => "Suction Presure Sensor Limit",
+    53 => "Con Pressure Sensor Limit",
+    54 => "Low Supply Voltage Limit",
+    55 => "OutEnvelp Limit",
+    56 => "Suction Pressure Sensor Limit",
+    57 => "Drive Over/Under Voltage Limit",
+    58 => "High Drive Temp Limit",
+    59 => "Internal Drive Error Limit",
+    61 => "MultSafm",
+    71 => "ChrgLoss",
+    72 => "Suction Temp Sensor Limit",
+    73 => "Leaving Air Temp Sensor Limit",
+    74 => "Maximum Operating Pressure Limit",
+    75 => "Charge Loss",
+    76 => "Suction Temperatur Sensor Limit",
+    77 => "Leaving Air Temperature Sensor Limit",
+    78 => "Maximum Operating Pressure Limit",
+  }
+
+  AR_SETTINGS = {
+    0 => "Cycle with Compressor",
+    1 => "Cycle with Thermostat Humidification Call",
+    2 => "Slow Opening Water Valve",
+    3 => "Cycle with Blower"
+  }
+
+  def dipswitch_settings(v)
+    return :manual if v == 0x7fff
+    {
+      fp1: v & 0x01 == 0x01 ? "30ºF" : "15ºF",
+      fp2: v & 0x02 == 0x02 ? "30ºF" : "15ºF",
+      rv: v & 0x04 == 0x04 ? "O" : "B",
+      ar: AR_SETTINGS[(v >> 3) & 0x7],
+      cc: v & 0x20 == 0x20 ? "Single Stage" : "Dual Stage",
+      lo: v & 0x40 == 0x40 ? "Continouous" : "Pulse",
+      dh_rh: v & 0x80 == 0x80 ? "Dehumdifier On" : "Reheat On",
+    }
+  end
+
+  SYSTEM_OUTPUTS = {
+    0x01 => :cc, # compressor stage 1
+    0x02 => :cc2, # compressor stage 2
+    0x04 => :rv, # reversing valve (cool instead of heat)
+    0x08 => :blower,
+    0x10 => :eh1,
+    0x20 => :eh2,
+    0x200 => :accessory,
+    0x400 => :lockout,
+    0x800 => :alarm,
+  }
+
+  SYSTEM_INPUTS = {
+    0x01 => "Y1",
+    0x02 => "Y2",
+    0x04 => "W",
+    0x08 => "O",
+    0x10 => "G",
+    0x20 => "Dehumidifer",
+    0x40 => "Emergency Shutdown",
+    0x200 => "Load Shed",
+  }
+
+  def status(v)
+    result = {
+      lps: v & 0x80 == 0x80 ? :closed : :open,
+      hps: v & 0x100 == 0x100 ? :closed : :open,
+    }
+    result[:load_shed] = true if v & 0x0200 == 0x0200
+    result[:emergency_shutdown] = true if v & 0x0040 == 0x0040
+    leftover = v & ~0x03c0
+    result[:unknown] = "0x%04x" % leftover unless leftover == 0
+    result
+  end
+
+  VS_DRIVE_DERATE = {
+    0x01 => "Drive Over Temp",
+    0x04 => "Low Suction Pressure",
+    0x10 => "Low Discharge Pressure",
+    0x20 => "High Discharge Pressure",
+    0x40 => "Output Power Limit",
+  }
+
+  VS_SAFE_MODE = {
+    0x01 => "EEV Indoor Failed",
+    0x02 => "EEV Outdoor Failed",
+    0x04 => "Invalid Ambient Temp",
+  }
+
+  VS_ALARM1 = {
+    0x8000 => "Internal Error",
+  }
+
+  VS_ALARM2 = {
+    0x0001 => "Multi Safe Modes",
+    0x0002 => "Out of Envelope",
+    0x0004 => "Over Current",
+    0x0008 => "Over Voltage",
+    0x0010 => "Drive Over Temp",
+    0x0020 => "Under Voltage",
+    0x0040 => "High Discharge Temp",
+    0x0080 => "Invalid Discharge Temp",
+    0x0100 => "OEM Communications Timeout",
+    0x0200 => "MOC Safety",
+    0x0400 => "DC Under Voltage",
+    0x0800 => "Invalid Suction Pressure",
+    0x1000 => "Invalid Discharge Pressure",
+    0x2000 => "Low Discharge Pressure",
+  }
+
+  VS_EEV2 = {
+    0x0010 => "Invalid Suction Temperature",
+    0x0020 => "Invalid Leaving Air Temperature",
+    0x0040 => "Invalid Suction Pressure",
+    
+  }
+
+  AXB_INPUTS = {
+  }
+
+  AXB_OUTPUTS = {
+    0x10 => "Accessory 2",
+    0x02 => "Loop Pump",
+    0x01 => "DHW"
+  }
+
+  HEATING_MODE = {
+    0 => :off,
+    1 => :auto,
+    2 => :cool,
+    3 => :heat,
+    4 => :eheat
+  }
+
+  FAN_MODE = {
+    0 => :auto,
+    1 => :continuous,
+    2 => :intermittent
+  }
+
+  HUMIDIFIER_SETTINGS = {
+    0x4000 => :auto_dehumidification,
+    0x8000 => :auto_humidification,
+  }
+
+  INVERSE_HUMIDIFIER_SETTINGS = {
+    0x4000 => :manual_dehumidification,
+    0x8000 => :manual_humidification,
+  }
+
+  ZONE_SIZES = {
+    0 => 0,
+    1 => 25,
+    2 => 45,
+    3 => 70,
+  }
+
+  CALLS = {
+    0x0 => :standby,
+    0x1 => :unknown1,
+    0x2 => :h1,
+    0x3 => :h2,
+    0x4 => :h3,
+    0x5 => :c1,
+    0x6 => :c2,
+    0x7 => :unknown7,
+  }
+
+  def iz2_demand(v)
+    {
+      fan_demand: v >> 8,
+      unit_demand: v & 0xff,
+    }
+  end
+
+  def zone_configuration1(v)
+    fan = if v & 0x80 == 0x80
+      :continuous
+    elsif v & 0x100 == 0x100
+      :intermittent
+    else
+      :auto
+    end
+    result = {
+      fan: fan,
+      on_time: ((v >> 9) & 0x7) * 5,
+      off_time: (((v >> 12) & 0x7) + 1) * 5,
+      cooling_target_temperature: ((v & 0x7e) >> 1) + 36,
+      heating_target_temperature_carry: v & 01
+    }
+    leftover = v & ~0x7fff
+    result[:unknown] = "0x%04x" % leftover unless leftover == 0
+    result
+  end
+
+  def zone_configuration2(registers, k)
+    prior_v = registers[k - 1] if registers.key?(k - 1)
+    v = registers[k]
+    result = {
+      call: CALLS[(v >> 1) & 0x7],
+      mode: HEATING_MODE[(v >> 8) & 0x03],
+      damper: v & 0x10 == 0x10 ? :open : :closed
+    }
+    if prior_v
+      carry = prior_v.is_a?(Hash) ? prior_v[:heating_target_temperature_carry] : v & 0x01
+      result[:heating_target_temperature] = ((carry << 5) | ((v & 0xf800) >> 11)) + 36
+    end
+    leftover = v & ~0xfb1e
+    result[:unknown] = "0x%04x" % leftover unless leftover == 0
+    result
+  end
+
+  # hi order byte is normalized zone size
+  def zone_configuration3(v)
+    size = (v >> 3 ) & 0x3
+    result = {
+      zone_priority: (v & 0x20) == 0x20 ? :economy : :comfort,
+      zone_size: ZONE_SIZES[size],
+      normalized_size: v >> 8,
+    }
+    leftover = v & ~0xff38
+    result[:unknown] = "0x%04x" % leftover unless leftover == 0
+    result
+  end
+
+  # intermittent on time allowed: 0, 5, 10, 15, 20
+  # intermittent off time allowed: 5, 10, 15, 20, 25, 30, 35, 40
+
+  REGISTER_CONVERTERS = {
+    TO_HUNDREDTHS => [2, 3, 807, 813, 816, 817, 819, 820, 825, 828],
+    method(:dipswitch_settings) => [4, 33],
+    TO_TENTHS => [19, 20, 401, 567, 740, 745, 746, 900, 1105, 1106, 1107, 1108, 1110, 1111, 1114, 1117, 1134, 1136,
+      21203, 21204,
+      21212, 21213,
+      21221, 21222,
+      21230, 22131,
+      21239, 21240,
+      21248, 21249,
+      31003,
+      31007, 31010, 31013, 31016, 31019, 31022],
+    TO_LAST_LOCKOUT => [26],
+    ->(v) { from_bitmask(v, SYSTEM_OUTPUTS) } => [27, 30],
+    ->(v) { from_bitmask(v, SYSTEM_INPUTS) } => [28],
+    method(:status) => [31],
+    ->(registers, idx) { to_string(registers, idx, 4) } => [88],
+    ->(registers, idx) { to_string(registers, idx, 12) } => [92],
+    ->(registers, idx) { to_string(registers, idx, 5) } => [105],
+    ->(v) { from_bitmask(v, VS_DRIVE_DERATE) } => [214],
+    ->(v) { from_bitmask(v, VS_SAFE_MODE) } => [216],
+    ->(v) { from_bitmask(v, VS_ALARM1) } => [217],
+    ->(v) { from_bitmask(v, VS_ALARM2) } => [218],
+    ->(v) { from_bitmask(v, VS_EEV2) } => [280],
+    NEGATABLE => [346, 1146],
+    ->(v) { from_bitmask(v, AXB_INPUTS) } => [1103],
+    ->(v) { from_bitmask(v, AXB_OUTPUTS) } => [1104],
+    ->(v) { TO_TENTHS.call(NEGATABLE.call(v)) } => [1136],
+    ->(v) { HEATING_MODE[v] } => [21202, 21211, 21220, 21229, 21238, 21247],
+    ->(v) { FAN_MODE[v] } => [21205, 21214, 21223, 21232, 21241, 21250],
+    ->(v) { from_bitmask(v, HUMIDIFIER_SETTINGS) } => [31109],
+    ->(v) { { humidification_target: v >> 8, dehumidification_target: v & 0xff } } => [31110],
+    method(:iz2_demand) => [31005],
+    method(:zone_configuration1) => [31008, 31011, 31014, 31017, 31020, 31023],
+    method(:zone_configuration2) => [31009, 31012, 31015, 31018, 31021, 31024],
+    method(:zone_configuration3) => [31200, 31203, 31206, 31209, 31212, 31215],
+    ->(registers, idx) { to_string(registers, idx, 13) } => [31400],
+    ->(registers, idx) { to_string(registers, idx, 8) } => [31413],
+    ->(registers, idx) { to_string(registers, idx, 13) } => [31421],
+    ->(registers, idx) { to_string(registers, idx, 13) } => [31434],
+    ->(registers, idx) { to_string(registers, idx, 13) } => [31447],
+    ->(registers, idx) { to_string(registers, idx, 13) } => [31460],
+  }
+
+  REGISTER_FORMATS = {
+    "%ds" => [1, 6, 9, 15, 84, 85],
+    "%dV" => [16, 112],
+    "%0.1fºF" => [19, 20, 401, 567, 740, 745, 746, 900, 1110, 1111, 1114, 1134, 1136,
+      21203, 21204,
+      21212, 21213,
+      21221, 21222,
+      21230, 21231,
+      21239, 21240,
+      21248, 21249,
+      31003,
+      31007, 31010, 31013, 31016, 31019, 31022],
+    "E%d" => [25, 26],
+    "%d%%" => [282, 321, 322, 346, 565, 741],
+    "%0.1fA" => [1105, 1106, 1107, 1108],
+    "%0.1fgpm" => [1117],
+    "%dW" => [1147, 1149, 1151, 1153, 1165],
+    "%dBtuh" => [1157],
+  }
+
+  def ignore(range)
+    range.zip(Array.new(range.count)).to_h
+  end
+
+  def faults(range)
+    range.map { |i| [i, "E#{i % 100}"] }.to_h
+  end
+
+  def zone_registers
+    (1..6).map do |i|
+      base1 = 21202 + (i - 1) * 9
+      base2 = 31007 + (i - 1) * 3
+      base3 = 31200 + (i - 1) * 3
+      {
+        base1 => "Zone #{i} Heating Mode",
+        (base1 + 1) => "Zone #{i} Heating Setpoint (write)",
+        (base1 + 2) => "Zone #{i} Cooling Setpoint (write)",
+        (base1 + 3) => "Zone #{i} Fan Mode (write)",
+        (base1 + 4) => "Zone #{i} Intermittent Fan On Time (write)",
+        (base1 + 5) => "Zone #{i} Intermittent Fan Off Time (write)",
+        base2 => "Zone #{i} Ambient Temperature",
+        (base2 + 1) => "Zone #{i} Configuration 1",
+        (base2 + 2) => "Zone #{i} Configuration 2",
+        base3 => "Zone #{i} Configuration 3",
+      }
+    end.inject({}, &:merge)
+  end
+
+  WRITEABLE = [112, 340, 341, 342, 346, 347]
+
+  # these are the valid ranges (i.e. the ABC will return _some_ value)
+  # * means 6 sequential ranges of equal size (i.e. must be repeated for each
+  # IZ2 zone)
+  # ==================================================================
+  REGISTER_RANGES = [
+    0..155,
+    170..253,
+    260..260,
+    280..288,
+    300..301,
+    320..326,
+    340..348,
+    360..368,
+    400..419,
+    440..516,
+    550..573,
+    600..749,
+    800..913,
+    1090..1165,
+    1200..1263,
+    2000..2026,
+    2100..2129,
+    2800..2849,
+    2900..2915,
+    2950..2959,
+    3000..3003,
+    3020..3030,
+    3040..3049,
+    3060..3063,
+    3100..3105,
+    3108..3115,
+    3118..3119,
+    3200..3253,
+    3300..3332,
+    3400..3431,
+    3500..3524,
+    3600..3609,
+    3618..3634,
+    3700..3714,
+    3800..3809,
+    3818..3834,
+    3900..3914,
+    12000..12019,
+    12098..12099,
+    12100..12119,
+    12200..12239,
+    12300..12319,
+    12400..12569,
+    12600..12639,
+    12700..12799,
+    20000..20099,
+    21100..21136,
+    21200..21265,
+    21400..21472,
+    21500..21589,
+    22100..22162, # *
+    22200..22262, # *
+    22300..22362, # *
+    22400..22462, # *
+    22500..22562, # *
+    22600..22662, # *
+    30000..30099,
+    31000..31034,
+    31100..31129,
+    31200..31229,
+    31300..31329,
+    31400..31472,
+    32100..32162, # *
+    32200..32262, # *
+    32300..32362, # *
+    32400..32462, # *
+    32500..32562, # *
+    32600..32662, # *
+    60050..60053,
+    60100..60109,
+    60200..60200,
+    61000..61009
+  ]
+
+  def read_all_registers(modbus_slave)
+    result = []
+    REGISTER_RANGES.each do |range|
+      # read at most 100 at a time
+      range.each_slice(100) do |keys|
+        result.concat(modbus_slave.holding_registers[keys.first..keys.last])
+      end
+    end
+    REGISTER_RANGES.map(&:to_a).flatten.zip(result).to_h
+  end
+
+  def diff_registers(r1, r2)
+    diff = {}
+    r1.each_key do |k|
+      diff[k] = [r1[k], r2[k]] if r1[k] != r2[k]
+    end
+    diff
+  end
+
+  REGISTER_NAMES = {
+    1 => "Random Start Delay",
+    2 => "ABC Program Version",
+    3 => "IZ2 Version?",
+    4 => "DIP Switch Override",
+    6 => "Compressor Anti-Short Cycle Delay",
+    8 => "Unit Type?",
+    9 => "Compressor Minimum Run Time",
+    15 => "Blower Off Delay",
+    16 => "Line Voltage",
+    19 => "FP1",
+    20 => "FP2",
+    21 => "Condensate", # >= 270 normal, otherwise fault
+    25 => "Last Fault Number",
+    26 => "Last Lockout",
+    27 => "System Outputs (At Last Lockout)",
+    28 => "System Inputs (At Last Lockout)",
+    30 => "System Outputs",
+    31 => "Status",
+    33 => "DIP Switch Status",
+    50 => "ECM Speed Low (== 5)",
+    51 => "ECM Speed Med (== 5)",
+    52 => "ECM Speed High (== 5)",
+    54 => "ECM Speed Actual",
+    84 => "Slow Opening Water Valve Delay",
+    85 => "Test Mode Timer",
+    88 => "ABC Program",
+    92 => "Model Number",
+    105 => "Serial Number",
+    112 => "Setup Line Voltage",
+    201 => "Discharge Pressure", # I can't figure out how this number is represented; 
+    203 => "Suction Pressure",
+    205 => "Discharge Temperature",
+    207 => "Loop Entering Water Temperature",
+    209 => "Compressor Ambient Temperature",
+    211 => "VS Drive Details (General 1)",
+    212 => "VS Drive Details (General 2)",
+    213 => "VS Drive Details (Derate 1)",
+    214 => "VS Drive Details (Derate 2)",
+    215 => "VS Drive Details (Safemode 1)",
+    216 => "VS Drive Details (Safemode 2)",
+    217 => "VS Drive Details (Alarm 1)",
+    218 => "VS Drive Details (Alarm 2)",
+    280 => "EEV2 Ctl",
+    281 => "EEV Superheat", # ?? data format
+    282 => "EEV Open %",
+    283 => "Suction Temperature", ## ?? data format
+    284 => "Saturated Suction Temperature", ## ?? data format
+    321 => "VS Pump Min",
+    322 => "VS Pump Max",
+    340 => "Blower Only Speed",
+    341 => "Lo Compressor ECM Speed",
+    342 => "Hi Compressor ECM Speed",
+    344 => "ECM Speed",
+    346 => "Cooling Airflow Adjustment",
+    347 => "Aux Heat ECM Speed",
+    362 => "Active Dehumidify", # any value is true 
+    401 => "DHW Setpoint",
+    414 => "On Peak/SmartGrid 2", # 0x0001 only
+    483 => "Number of IZ2 Zones",
+    564 => "IZ2 Compressor Speed Desired",
+    565 => "IZ2 Blower % Desired",
+    567 => "Entering Air",
+    740 => "Entering Air",
+    741 => "Relative Humidity",
+    745 => "Heating Set Point",
+    746 => "Cooling Set Point",
+    807 => "AXB Version",
+    813 => "IZ2 Version?",
+    816 => "AOC Version 1?",
+    817 => "AOC Version 2?",
+    819 => "MOC Version 1?",
+    820 => "MOC Version 2?",
+    825 => "EEV2 Version",
+    828 => "AWL Version",
+    900 => "Leaving Air",
+    1103 => "AXB Inputs",
+    1104 => "AXB Outputs",
+    1105 => "Blower Amps",
+    1106 => "Aux Amps",
+    1107 => "Compressor 1 Amps",
+    1108 => "Compressor 2 Amps",
+    1109 => "Heating Liquid Line",
+    1110 => "Leaving Water",
+    1111 => "Entering Water",
+    1114 => "DHW Temp",
+    1117 => "Waterflow",
+    1134 => "Saturated Discharge Temperature",
+    1135 => "SubCooling",
+    1147 => "Compressor Watts",
+    1149 => "Blower Watts",
+    1151 => "Aux Watts",
+    1153 => "Total Watts",
+    1157 => "Ht of Rej",
+    1165 => "VS Pump Watts",
+    3027 => "Compressor Speed",
+    31003 => "Outdoor Temp",
+    31005 => "IZ2 Demand",
+    31109 => "Humidifier Mode", # write to 21114
+    31110 => "Manual De/Humidification Target", # write to 21115
+    31400 => "Dealer Name",
+    31413 => "Dealer Phone",
+    31421 => "Dealer Address 1",
+    31434 => "Dealer Address 2",
+    31447 => "Dealer Email",
+    31460 => "Dealer Website",
+  }.merge(ignore(89..91)).
+    merge(ignore(93..104)).
+    merge(ignore(106..109)).
+    merge(faults(601..699)).
+    merge(zone_registers).
+    merge(ignore(31401..31412)).
+    merge(ignore(31414..31420)).
+    merge(ignore(31422..31433)).
+    merge(ignore(31435..31446)).
+    merge(ignore(31447..31459)).
+    merge(ignore(31461..31472))
+
+  def transform_registers(registers)
+    registers.each do |(k, v)|
+      value_proc = REGISTER_CONVERTERS.find { |(_, z)| z.include?(k) }&.first
+      next unless value_proc
+
+      value = value_proc.arity == 2 ? value_proc.call(registers, k) : value_proc.call(v)
+      registers[k] = value
+    end
+    registers
+  end
+
+  def print_registers(registers)
+    result = []
+    registers.each do |(k, v)|
+      # ignored
+      next if REGISTER_NAMES.key?(k) && REGISTER_NAMES[k].nil?
+      name = REGISTER_NAMES[k]
+      value_proc = REGISTER_CONVERTERS.find { |(_, z)| z.include?(k) }&.first || ->(v) { v }
+      format = REGISTER_FORMATS.find { |(_, z)| z.include?(k) }&.first || "%s"
+      format = "%1$d (0x%1$04x)" unless name
+      name ||= "???"
+  
+      value = value_proc.arity == 2 ? value_proc.call(registers, k) : value_proc.call(v)
+      value = value.join(", ") if value.is_a?(Array)
+      value = sprintf(format, value) if value
+  
+      result << "#{name} (#{k}): #{value}"
+    end
+    result.join("\n")
+  end
+end