atrea_control 3.2.0 → 4.0.0

data/lib/atrea_control/duplex/login_session.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "login_discovery"
+
+module AtreaControl
+  module Duplex
+    # Discover account tokens, then poll until a usable unit session or deadline.
+    class LoginSession
+      def initialize(unit_id:, request:, wait:, diagnostic:)
+        @request = request
+        @wait = wait
+        @diagnostic = diagnostic
+        @discovery = LoginDiscovery.new(request: request, unit_id: unit_id)
+      end
+
+      def call
+        @user_id = @discovery.user_id
+        @unit = @discovery.unit
+        sid = query
+        if sid == "0"
+          connect
+          sid = poll
+          @diagnostic.call("login_complete")
+        else
+          @diagnostic.call("session_reused")
+        end
+        { user_id: @user_id, unit_id: @unit[:ident], sid: sid }
+      end
+
+      private
+
+      def query
+        body = @request.call("session_query", :get, "/apps/rd5Control/handle.php", { Sync: 1, action: "unitQuery", query: "loged", user: @user_id, unit: @unit[:ident] })
+        LoginXML.value(LoginXML.node(body, "/root/login")["sid"], "session SID")
+      end
+
+      def connect
+        params = { Sync: 1, action: "unitLogin", user: @user_id, unit: @unit[:ident], table: "userUnits", idPwd: @unit[:iid] }
+        body = @request.call("unit_login", :post, "/apps/rd5Control/handle.php", params, { comm: "config/login.cgi?magic=" })
+        LoginXML.node(body, "/root/sended")
+      end
+
+      def poll
+        loop do
+          sid = query
+          return sid unless sid == "0"
+
+          @wait.call
+        end
+      end
+    end
+  end
+end

data/lib/atrea_control/duplex/rd5_command.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AtreaControl
+  module Duplex
+    # Build one coherent command from discovered mappings and one fresh configuration.
+    class RD5Command
+      COMMAND_PROFILE = /
+        send2Unit \s* \( \s* getUrlPar \s* \( \s* '(?<input>H[0-9]{5})' \s* , \s* val \s* \)
+        \s* \+ \s* \( \s* values \s* \. \s* (?<switch>H[0-9]{5}) \s* == \s* 1 \s* \?
+        \s* '&' \s* \+ \s* getUrlPar \s* \( \s* '\k<switch>' \s* , \s* 2 \s* \)
+        \s* : \s* '' \s* \) \s* \) \s* ; \s*
+      /x
+      POWER_UI_TAIL = /
+        (?: if \s* \( \s* val \s* > \s* 0 \s* && \s* values \s* \. \s* H10715 \s* == \s* 0 \s* \) \s* \{
+          \s* flyDown \s* = \s* false \s* ; \s* this \s* \. \s* nextSibling \s* \. \s* nextSibling
+          \s* \. \s* onmousedown \s* \( \s* \) \s* ; \s* \} \s*
+        )?
+      /x
+
+      def self.normalize(value)
+        integer = case value
+                  when Integer then value
+                  when Float then integral_float(value)
+                  when String then Integer(value, 10) if value.match?(/\A[0-9]+\z/)
+                  end
+        raise ArgumentError, "Expected nonnegative integral command value" unless integer && integer >= 0
+
+        integer
+      end
+
+      def self.integral_float(value)
+        value.to_i if value.finite? && value == value.to_i
+      end
+      private_class_method :integral_float
+
+      def self.encode(sensor, value)
+        raise AtreaControl::UnsupportedConfiguration, "Invalid holding-register mapping" unless sensor.is_a?(String) && sensor.match?(/\AH[0-9]{5}\z/)
+        raise ArgumentError, "Expected unsigned 16-bit integer" unless value.is_a?(Integer) && (0..65_535).cover?(value)
+
+        sensor + format("%05d", value)
+      end
+
+      # Only supported, complete onchange forms; never execute or extract arbitrary JS.
+      def self.discover(source, power: false)
+        # Whitespace is allowed between tokens, never inside identifiers or quoted IDs.
+        tail = power ? POWER_UI_TAIL : //
+        match = source.match(/\A\s*function\s*\(\s*val\s*\)\s*\{\s*saved\s*=\s*true\s*;\s*#{COMMAND_PROFILE}#{tail}\}\s*\z/)
+        raise AtreaControl::UnsupportedConfiguration, "Unsupported command profile" unless match
+
+        { input: match[:input], switch: match[:switch] }
+      end
+
+      def initialize(configuration, user_ctrl, parser)
+        @configuration = configuration
+        @user_ctrl = user_ctrl
+        @parser = parser
+      end
+
+      def build(setting, value)
+        case setting
+        when :power then @configuration.validate_power!(value)
+        when :mode then @configuration.validate_mode!(value, @user_ctrl.modes)
+        else raise ArgumentError, "Unknown command setting"
+        end
+        input = @parser.input(@user_ctrl.sensors["#{setting}_input"], value)
+        switch = @user_ctrl.sensors["#{setting}_switch"]
+        override = @parser.input(switch, 2)
+        @configuration.temporary_control?(switch) ? [input, override] : [input]
+      end
+    end
+  end
+end

data/lib/atrea_control/duplex/rd5_configuration.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module AtreaControl
+  module Duplex
+    # Immutable policy over validated, unsigned registers from one RD5 snapshot.
+    class RD5Configuration
+      REGISTERS = %w[H10510 H10501 H11300 H11700 C10508 C10509 I11401 H10700 H10701].freeze
+      POWER_DOMAINS = { 0 => [0, *(12..100)].freeze, 1 => (0..100), 2 => (0..2),
+                        4 => [0, *(10..12), *(20..22), *(30..38)].freeze, }.freeze
+      MODE_REQUIREMENTS = {
+        0 => {}, 2 => {}, 1 => { "C10508" => 0 }, 6 => { "C10508" => 0 }, 7 => { "C10508" => 0 },
+        3 => { "C10508" => 0, "C10509" => 1 }, 4 => { "C10508" => 0, "H11700" => 1 }, 5 => { "I11401" => 1 },
+      }.transform_values(&:freeze).freeze
+
+      # Recognize known logic as data, never execute configuration JavaScript.
+      INLET_SOURCE_RULE = <<~JS.gsub(/\s+/, "").freeze
+        function() {
+          var val, na=false;
+          if(values.H11300==0){
+            if(values.H10501==1 && values.H10200>0 && values.I10200!=126.0)
+              val=values.I10200;
+            else if(values.H10501==2 && values.H10201>0 && values.I10201!=126.0)
+              val=values.I10201;
+            else
+              na=true;
+          }else if(values.H11300==1){
+            val=values.I10204;
+          }else na=true;
+          if(na) return words['unavail'];
+          return val;
+        }
+      JS
+
+      def self.input_temperature_source(source)
+        source.gsub(/\s+/, "") == INLET_SOURCE_RULE ? "rd5_standard" : "unsupported"
+      end
+
+      def initialize(registers)
+        @registers = registers.dup.freeze
+        @configuration = @registers.slice(*REGISTERS).freeze
+        freeze
+      end
+
+      def [](id)
+        @configuration[id]
+      end
+
+      # Command policy must explicitly request its prerequisites.
+      def fetch(id)
+        @configuration.fetch(id) { raise AtreaControl::UnsupportedConfiguration, "Missing configuration register #{id}" }
+      end
+
+      def to_h
+        @configuration
+      end
+
+      def validate_power!(value)
+        domain = POWER_DOMAINS.fetch(fetch("H10510")) { raise AtreaControl::UnsupportedConfiguration, "Unsupported power profile" }
+        raise ArgumentError, "Power outside configured range" unless value.is_a?(Integer) && domain.include?(value)
+
+        value
+      end
+
+      def validate_mode!(value, modes)
+        raise ArgumentError, "Mode outside 0..7" unless value.is_a?(Integer) && (0..7).cover?(value)
+        raise AtreaControl::UnsupportedConfiguration, "Undiscovered mode" unless modes.key?(value.to_s)
+
+        MODE_REQUIREMENTS.fetch(value).each do |id, expected|
+          raise AtreaControl::UnsupportedConfiguration, "Mode unavailable: #{id}" unless fetch(id) == expected
+        end
+        value
+      end
+
+      # Use the discovered switch from this same validated snapshot, including custom mappings.
+      def temporary_control?(id)
+        state = @registers.fetch(id) { raise AtreaControl::UnsupportedConfiguration, "Missing control register #{id}" }
+        raise AtreaControl::UnsupportedConfiguration, "Unknown control state for #{id}" unless [0, 1, 2].include?(state)
+
+        state != 0
+      end
+
+      # Supported userCtrl inlet source rule; return unsigned temperature or nil.
+      def input_temperature
+        case self["H11300"]
+        when 0
+          case self["H10501"]
+          when 1 then fan_temperature("H10200", "I10200")
+          when 2 then fan_temperature("H10201", "I10201")
+          end
+        when 1
+          @registers["I10204"]
+        end
+      end
+
+      private
+
+      def fan_temperature(fan, sensor)
+        speed = @registers[fan]
+        temperature = @registers[sensor]
+        temperature if speed&.positive? && temperature != 1260
+      end
+    end
+  end
+end

data/lib/atrea_control/duplex/request.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "timeout"
 
 module AtreaControl
   module Duplex
@@ -12,7 +13,15 @@ module AtreaControl
       # @param [String, Integer] unit_id
       # @param [String, Integer] sid
       # @note `ver` is done by atrea server
-      def initialize(user_id:, unit_id:, sid:)
+      def initialize(user_id:, unit_id:, sid:, timeout: 60, open_timeout: 10, read_timeout: 60) # rubocop:disable Metrics/ParameterLists
+        { timeout:, open_timeout:, read_timeout: }.each do |key, value|
+          raise ArgumentError, "#{key} must be positive and finite" unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+        end
+        raise ArgumentError, "timeout must not exceed 60 seconds" if timeout > 60
+
+        @timeout = timeout
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
         @params = {
           _user: user_id.to_i,
           _unit: unit_id,
@@ -23,15 +32,34 @@ module AtreaControl
 
       # @param [Hash] params
       # @option params [String] :_t ("config/xml.xml") file name
-      def call(params)
+      def call(params = nil, **keywords)
+        params = keywords.merge(params.to_h)
+        response = Timeout.timeout(@timeout, Timeout::Error) { connection.get("#{AtreaControl::Duplex::CONTROL_URI}/comm/sw/unit.php", @params.merge(params)) }
+        logger.debug "stage=unit_request status=#{response.status}"
+        raise AtreaControl::SessionExpired, cause: nil if [401, 403].include?(response.status)
+        raise AtreaControl::TransportError, "Unit request failed (HTTP #{response.status})", cause: nil unless (200...300).cover?(response.status)
+
+        response
+      rescue Faraday::TimeoutError, Timeout::Error
+        raise AtreaControl::UnitConnectionTimeout, "Unit request timed out", cause: nil
+      rescue Faraday::Error => e
+        raise AtreaControl::UnitConnectionTimeout, "Unit request timed out", cause: nil if e.wrapped_exception.is_a?(Timeout::Error)
+
+        raise AtreaControl::TransportError, "Unit connection failed", cause: nil
+      rescue IOError, SystemCallError, SocketError
+        raise AtreaControl::TransportError, "Unit connection failed", cause: nil
+      end
+
+      private
+
+      def connection
         @connection ||= Faraday.new do |f|
+          f.options.open_timeout = @open_timeout
+          f.options.timeout = @read_timeout
           f.request :url_encoded
-          f.adapter Faraday.default_adapter
+          f.adapter(:net_http) { |http| http.max_retries = 0 }
         end
-
-        @connection.get("#{AtreaControl::Duplex::CONTROL_URI}/comm/sw/unit.php", @params.merge(params))
       end
     end
   end
 end
-# https://control.atrea.eu/comm/sw/unit.php?ver=003001022&_user=2113&_unit=126399332270040&auth=49852&_t=config/xml.xml&_X=Ti&_async=1

data/lib/atrea_control/duplex/unit.rb

@@ -1,27 +1,33 @@
 # frozen_string_literal: true
 
+require "json"
+require_relative "unit_commands"
+
 module AtreaControl
   module Duplex
     # Communication with RD5 unit (read/write)
     class Unit
       include AtreaControl::Logger
+      include UnitCommands
+
+      CURRENT_FIELDS = %w[current_mode current_power outdoor_temperature preheat_temperature required_temperature input_temperature preheating timestamp].freeze
 
-      attr_reader :current_mode, :current_power, :outdoor_temperature, :preheat_temperature, :input_temperature
-      # @return [Boolean] preheating air is ON ?
-      attr_reader :preheating
+      CURRENT_FIELDS.each do |field|
+        define_method(field) { parsed[field] }
+      end
       # @return [UserCtrl]
       attr_reader :user_ctrl
-      # @return [Time, DateTime]
-      attr_writer :timestamp
 
       # @param [String, Integer] user_id
       # @param [String, Integer] unit_id
       # @param [String, Integer] sid
       # @param [AtreaControl::Duplex::UserCtrl] user_ctrl
-      def initialize(user_id:, unit_id:, sid:, user_ctrl: nil)
+      def initialize(user_id:, unit_id:, sid:, user_ctrl: nil, time_zone: nil, verification_registers: nil) # rubocop:disable Metrics/ParameterLists
         @user_id = user_id
         @unit_id = unit_id
         @sid = sid
+        @time_zone = time_zone
+        @verification_registers = WriteVerification.registers(verification_registers)
         @user_ctrl = user_ctrl || UserCtrl.new(user_id: user_id, unit_id: unit_id, sid: sid)
       end
 
@@ -30,58 +36,45 @@ module AtreaControl
       end
 
       def mode
-        current_mode || values[:current_mode]
+        current_mode
       end
 
       def power
-        current_power || values[:current_power]
+        current_power
       end
 
-      def timestamp
-        @timestamp ||= values[:timestamp]
+      # Preserve the writer for loaded, valid snapshots without sharing mutable Time objects.
+      def timestamp=(value)
+        candidate = parsed.merge("timestamp" => value.dup.freeze).freeze
+        raise AtreaControl::SessionExpired unless valid?(candidate)
+
+        @snapshot = candidate
       end
 
       def preheating?
-        preheating || values[:preheating]
+        preheating
       end
 
-      # @param [String] value 0 - power-off; 1 - automat
-      def mode=(value)
-        v = [parser.input(@user_ctrl.sensors["mode_input"], value.to_s)]
-        v << parser.input(@user_ctrl.sensors["mode_switch"], "2")
-        write(*v)
-      end
+      def parsed
+        raise @snapshot_error if @snapshot_error
 
-      def power=(value)
-        v = [parser.input(@user_ctrl.sensors["power_input"], value.to_s)]
-        # overtake schedule control
-        v << "H1070000002" if value.to_i.positive?
-        write(*v)
-      end
+        load_snapshot unless @snapshot
+        raise AtreaControl::SessionExpired unless valid?
 
-      def parsed
-        @parsed ||= parser.values(read.body)
+        @snapshot
       end
 
       def values
-        parsed.each do |name, value|
-          instance_variable_set :"@#{name}", value
-        end
-        raise AtreaControl::SessionExpired unless valid?
+        parsed.transform_keys(&:to_sym)
+      end
 
-        as_json
+      # Configuration belongs to the same fresh snapshot as parsed readings.
+      def configuration
+        parsed && @configuration
       end
 
       def as_json(_options = nil)
-        {
-          current_mode: current_mode,
-          current_power: current_power,
-          outdoor_temperature: outdoor_temperature,
-          preheat_temperature: preheat_temperature,
-          input_temperature: input_temperature,
-          preheating: preheating,
-          timestamp: timestamp,
-        }
+        values
       end
 
       def to_json(*)
@@ -91,19 +84,39 @@ module AtreaControl
       # Expire cached data and fetch them again
       # @return [Hash] new values
       def refresh!
-        remove_instance_variable(:@parsed) if defined?(@parsed)
+        @snapshot_error = nil
+        load_snapshot
         values
       end
 
-      # Data are valid if timestamp within 15.minutes
-      def valid?
-        return false unless timestamp
+      # Inspect the snapshot directly: no lazy fetch and no timestamp-reader recursion.
+      def valid?(snapshot = @snapshot)
+        timestamp = snapshot && snapshot["timestamp"]
+        return false unless timestamp.is_a?(Time)
 
-        timestamp > (Time.now - (15 * 60.0))
+        now = Time.now
+        timestamp > now - 900 && timestamp <= now + 60
       end
 
       private
 
+      # Publish only a complete, fresh snapshot. A failed attempt stays failed until refresh!.
+      def load_snapshot
+        @snapshot = nil
+        @configuration = nil
+        @registers = nil
+        bundle = parser.snapshot(read.body)
+        candidate = bundle.fetch(:values).transform_values { |value| value.dup.freeze }.freeze
+        raise AtreaControl::SessionExpired unless valid?(candidate)
+
+        @configuration = bundle.fetch(:configuration)
+        @registers = bundle[:registers]
+        @snapshot = candidate
+      rescue StandardError => e
+        @snapshot_error = e
+        raise
+      end
+
       # Additional "parameters" for each sensor
       # @note it's changed in time ?
       def params
@@ -112,7 +125,7 @@ module AtreaControl
       end
 
       def parser
-        @parser ||= ::AtreaControl::SensorParser.new(@user_ctrl)
+        @parser ||= ::AtreaControl::SensorParser.new(@user_ctrl, time_zone: @time_zone)
       end
 
       # Request to RD5
@@ -123,13 +136,6 @@ module AtreaControl
       def read
         request.call(_t: "config/xml.xml")
       end
-
-      # @param [Array<String>] values in format SENSOR0000VALUE
-      def write(*values)
-        inputs = values.to_h { |i| [i, nil] }
-        logger.debug("set RD5 #{inputs}")
-        request.call({ _t: "config/xml.cgi", _w: 1 }.merge(inputs))
-      end
     end
   end
 end

data/lib/atrea_control/duplex/unit_commands.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "write_verification"
+
+module AtreaControl
+  module Duplex
+    # RD5 command dispatch and opt-in requested-value verification for Unit.
+    module UnitCommands
+      %i[mode power].each do |setting|
+        define_method(:"#{setting}=") { |value| public_send(:"set_#{setting}", value, verify: false) }
+        define_method(:"set_#{setting}") do |value, verify: true, timeout: 30, poll_interval: 5|
+          normalized = RD5Command.normalize(value)
+          verification = WriteVerification.new(timeout: timeout, poll_interval: poll_interval)
+          next command(setting, normalized) unless verify
+
+          verification.run { verified_command(setting, normalized, verification) }
+        end
+      end
+
+      private
+
+      def verified_command(setting, normalized, verification)
+        register = @verification_registers&.fetch(setting, nil)
+        raise AtreaControl::UnsupportedConfiguration, "No verified readback mapping for #{setting}" unless register
+
+        @snapshot_error = nil
+        load_snapshot
+        verification.remaining
+        baseline = @snapshot.fetch("timestamp")
+        raise AtreaControl::UnsupportedConfiguration, "Missing baseline readback register #{register}" unless @registers.key?(register)
+
+        commands = RD5Command.new(configuration, @user_ctrl, parser).build(setting, normalized)
+        verification.dispatch { write(*commands) }
+        verification.confirm do
+          load_snapshot
+          raw = @registers.fetch(register) { raise AtreaControl::ProtocolError, "Missing readback register #{register}" }
+          @snapshot.fetch("timestamp") > baseline && raw == normalized
+        end
+        normalized
+      end
+
+      def command(setting, normalized)
+        commands = RD5Command.new(configuration, @user_ctrl, parser).build(setting, normalized)
+        write(*commands)
+      end
+
+      # @param [Array<String>] values in format SENSOR0000VALUE
+      def write(*values)
+        inputs = values.to_h { |i| [i, nil] }
+        logger.debug("set RD5 #{inputs}")
+        # The device may apply a command even if its response fails or times out.
+        # Discard prewrite data on every attempt; the next reader must fetch again.
+        @snapshot = @configuration = @registers = @snapshot_error = nil
+        params = { _t: "config/xml.cgi", _w: 1 }.merge(inputs)
+        request.call(params)
+      end
+    end
+  end
+end