atrea_control 3.2.0 → 4.0.0

data/lib/atrea_control/duplex/user_ctrl.rb

@@ -5,7 +5,7 @@ require "nokogiri"
 module AtreaControl
   module Duplex
     # Parse `userCtrl.xml`
-    class UserCtrl
+    class UserCtrl # rubocop:disable Metrics/ClassLength
       # @param (see #initialize)
       def self.data(user_id:, unit_id:, sid:)
         user_ctrl = new(user_id: user_id, unit_id: unit_id, sid: sid)
@@ -14,6 +14,7 @@ module AtreaControl
           sensors: user_ctrl.sensors,
           modes: user_ctrl.modes,
           user_modes: user_ctrl.user_modes,
+          input_temperature_source: user_ctrl.input_temperature_source,
         }
       end
 
@@ -33,8 +34,13 @@ module AtreaControl
 
       # Get and parse XML with user/unit configuration source
       def user_ctrl
-        response = request.call(_t: "lang/userCtrl.xml", _async: 1)
-        Nokogiri::XML response.body
+        return @user_ctrl if @user_ctrl
+
+        response = read(_t: "lang/userCtrl.xml", _async: 1)
+        xml = parse_xml(response.body)
+        raise AtreaControl::ProtocolError, "Expected userCtrl layout XML" unless xml.at_xpath("/root/layout/body")
+
+        @user_ctrl = xml
       end
 
       # User-defined name of home (RD5 unit)
@@ -47,99 +53,104 @@ module AtreaControl
       def sensors
         return @sensors if @sensors
 
-        power = user_ctrl.xpath("//body/content/i[@title='$currentPower']")
-        mode = user_ctrl.xpath("//body/content/i[@title='$currentMode']")
-        outdoor_temp = user_ctrl.xpath("//body/content/i[@title='$outdoorTemp']")
-
-        switch_mode = mode.xpath("displayval").text[/values\.(\w+)/, 1]
-
-        power_input = power.xpath("onchange").text[/getUrlPar\('(\w+)',val\)/, 1]
-        m = mode.xpath("onchange").text.match(/getUrlPar\('(\w+)',val\).*getUrlPar\(.(\w+).,2\)/)
-
-        preheat_temperature = user_ctrl.xpath("//body/content/i[@title='$requiredTemp']")
-
-        input_temp = user_ctrl.xpath("//body/content/i[@title='$inletTemp']") # "I10200"
-        input_temperature = input_temp.xpath("displayval").text[/val=values\.(\w\d+);/, 1]
+        power = sensor_node("$currentPower")
+        mode = sensor_node("$currentMode")
+        power_command = RD5Command.discover(power.xpath("onchange").text, power: true)
+        mode_command = RD5Command.discover(mode.xpath("onchange").text)
         @sensors = {
-          "outdoor_temperature" => outdoor_temp.attribute("id").value, # "I10208"
-          "preheat_temperature" => preheat_temperature.attribute("id").value, # "H10706"
-          "input_temperature" => input_temperature,
-          "current_power" => power.attribute("id").value, # "H10704"
-          "current_mode" => mode.attribute("id").value, # "H10705"
-          "current_mode_switch" => switch_mode, # "H10712"
-          "power_input" => power_input, # "H10708"
-          "mode_input" => m[1], # "H10709"
-          "mode_switch" => m[2], # "H10701"
-        }
+          "outdoor_temperature" => sensor_node("$outdoorTemp")["id"],
+          "preheat_temperature" => sensor_node("$requiredTemp")["id"],
+          "input_temperature" => sensor_node("$inletTemp", optional: true)&.[]("id"),
+          "current_power" => power["id"],
+          "current_mode" => mode["id"],
+          "current_mode_switch" => mode.xpath("displayval").text[/values\.(\w+)/, 1], # "H10712"
+          **power_command.transform_keys { |key| "power_#{key}" },
+          **mode_command.transform_keys { |key| "mode_#{key}" },
+        }.tap { |mappings| validate_sensors(mappings) }
+      end
+
+      # Persist the source-resolution rule with mappings, not the downloaded JavaScript.
+      def input_temperature_source
+        @input_temperature_source ||= RD5Configuration.input_temperature_source(user_ctrl.xpath("/root/layout/body/content/i[@title='$inletTemp']/displayval").text)
       end
 
       # Generic modes
       # @return [Hash]
       def modes
-        return @modes if @modes
-
-        @modes = {}
-        user_ctrl.xpath("//op[@id='Mode']/i").each do |mode|
-          m = translate_mode(mode)
-          @modes[m[:id]] = m[:value]
-        end
-        @modes
+        @modes ||= mode_map("Mode")
       end
 
       # Modes by inputs - switches - named by user custom texts
       # @return [Hash]
       def user_modes
-        return @user_modes if @user_modes
+        @user_modes ||= mode_map("ModeText")
+      end
+
+      private
+
+      def read(params)
+        request.call(**params)
+      end
 
-        @user_modes = {}
-        user_ctrl.xpath("//op[@id='ModeText']/i").each do |mode|
-          m = translate_mode(mode)
-          @user_modes[m[:id]] = m[:value]
+      def sensor_node(title, optional: false)
+        user_ctrl.at_xpath("/root/layout/body/content/i[@title='#{title}']") ||
+          (raise(AtreaControl::UnsupportedConfiguration, "Missing sensor #{title}") unless optional)
+      end
+
+      def validate_sensors(mappings)
+        mappings.except("input_temperature").each do |field, id|
+          raise AtreaControl::UnsupportedConfiguration, "Missing or invalid #{field} mapping" unless id&.match?(/\A[A-Z]\d+\z/)
         end
-        @user_modes
+        mappings
       end
 
-      private
+      def mode_map(id)
+        nodes = user_ctrl.xpath("/root/layout/options/op[@id='#{id}']/i")
+        raise AtreaControl::UnsupportedConfiguration, "Missing #{id} definitions" if nodes.empty?
+
+        nodes.to_h { |node| translate_mode(node) }
+      end
+
+      def parse_xml(body)
+        xml = Nokogiri::XML(body) { |config| config.strict.nonet }
+        raise AtreaControl::ProtocolError, "Unexpected configuration DTD" if xml.internal_subset
+
+        xml
+      rescue Nokogiri::XML::SyntaxError
+        raise AtreaControl::ProtocolError, "Malformed configuration XML", cause: nil
+      end
 
       # User defined texts in RD5 unit
       # @return [Hash]
       def user_texts
         return @user_texts if @user_texts
 
-        response = request.call(_t: "config/texts.xml")
-        xml = Nokogiri::XML response.body
-        @user_texts = xml.xpath("//i").to_h do |node|
-          value = node.attributes["value"].value
-          id = node.attributes["id"].value
+        response = read(_t: "config/texts.xml")
+        xml = parse_xml(response.body)
+        raise AtreaControl::ProtocolError, "Expected user texts XML" unless xml.at_xpath("/root/texts")
+
+        @user_texts = xml.xpath("/root/texts/i").to_h do |node|
+          value = node["value"]
+          id = node["id"]
+          raise AtreaControl::ProtocolError, "Invalid user text" if id.to_s.empty? || value.nil?
+
           [id, value.gsub(/%u([\dA-Z]{4})/) { |i| +"" << i[Regexp.last_match(1)].to_i(16) }]
         end
       end
 
       # @param [Nokogiri::XML::Element] mode
-      # @return [Hash{Symbol->String}]
+      # @return [Array(String, String)]
       def translate_mode(mode)
-        id = mode.attributes["id"].value
-        title = mode.attributes["title"].value
+        id = mode["id"]
+        title = mode["title"]
+        raise AtreaControl::UnsupportedConfiguration, "Invalid mode definition" if id.to_s.empty? || title.to_s.empty?
+
         title = if title.start_with?("$")
                   I18n.t(title[/\w+/])
                 else
                   user_texts[title]
                 end
-        { id: id, value: title }
-      end
-
-      # Re-generate copy of locale files
-      # @note internal use only
-      def update_locales_files!
-        { cs: "0", de: "1", en: "2" }.each do |name, atrea_id|
-          response = request.call(_t: "lang/texts_#{atrea_id}.xml")
-
-          xml = Nokogiri::XML response.body
-          # `eval` JS object (= hash)
-          locale = eval xml.xpath("//words/text()")[0].text
-          yaml = { name.to_s => JSON.parse(locale.to_json) }.to_yaml
-          File.write(File.expand_path("../../../config/locales/#{name}.yml", __dir__), yaml)
-        end
+        [id, title]
       end
     end
   end

data/lib/atrea_control/duplex/write_verification.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module AtreaControl
+  module Duplex
+    # One monotonic budget, with an explicitly unknown outcome after command dispatch.
+    class WriteVerification
+      def self.registers(mapping)
+        return nil if mapping.nil?
+
+        valid = mapping.is_a?(Hash) && !mapping.empty? && mapping.all? { |key, id| valid_register?(key, id) }
+        raise ArgumentError, "Expected verification register map with power/mode symbol keys and H plus five digits" unless valid
+
+        mapping.transform_values { |id| id.dup.freeze }.freeze
+      end
+
+      def self.valid_register?(key, id)
+        %i[power mode].include?(key) && id.is_a?(String) && id.match?(/\AH[0-9]{5}\z/)
+      end
+      private_class_method :valid_register?
+
+      def initialize(timeout:, poll_interval:)
+        { timeout: timeout, poll_interval: poll_interval }.each do |key, value|
+          raise ArgumentError, "#{key} must be positive and finite" unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+        end
+        @deadline = monotonic_time + timeout
+        @poll_interval = poll_interval
+      end
+
+      def remaining
+        budget = @deadline - monotonic_time
+        return budget if budget.positive?
+
+        timeout!
+      end
+
+      def run(&)
+        Timeout.timeout(remaining, AtreaControl::UnitConnectionTimeout, "Write verification timed out", &)
+      rescue Timeout::Error, AtreaControl::UnitConnectionTimeout
+        timeout!
+      end
+
+      def dispatch
+        remaining
+        @attempted = true
+        yield
+        remaining
+      end
+
+      def confirm
+        loop do
+          remaining
+          matched = yield
+          remaining
+          return if matched
+
+          Kernel.sleep([@poll_interval, remaining].min)
+        end
+      end
+
+      private
+
+      def timeout!
+        raise AtreaControl::WriteNotConfirmed, "Write not confirmed; outcome unknown", cause: nil if @attempted
+
+        raise AtreaControl::UnitConnectionTimeout, "Write verification baseline timed out", cause: nil
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/atrea_control/duplex.rb

@@ -8,6 +8,8 @@ module AtreaControl
 
     autoload :Login, "atrea_control/duplex/login"
     autoload :Request, "atrea_control/duplex/request"
+    autoload :RD5Configuration, "atrea_control/duplex/rd5_configuration"
+    autoload :RD5Command, "atrea_control/duplex/rd5_command"
     autoload :Unit, "atrea_control/duplex/unit"
     autoload :UserCtrl, "atrea_control/duplex/user_ctrl"
   end

data/lib/atrea_control/logger.rb

@@ -4,8 +4,10 @@ require "logger"
 
 module AtreaControl
   module Logger
+    attr_writer :logger
+
     def logger
-      @logger ||= ::Logger.new($stdout)
+      @logger ||= ::Logger.new($stdout, level: ::Logger::INFO)
     end
   end
 end

data/lib/atrea_control/sensor_parser.rb

@@ -2,6 +2,7 @@
 
 require "nokogiri"
 require "time"
+require "tzinfo"
 
 module AtreaControl
   # Call RD5 unit ang get current sensors values
@@ -10,44 +11,38 @@ module AtreaControl
     include AtreaControl::Logger
 
     # @param [AtreaControl::Duplex::UserCtrl] user_ctrl
-    def initialize(user_ctrl)
+    def initialize(user_ctrl, time_zone: nil)
       @user_ctrl = user_ctrl
+      @time_zone = TZInfo::Timezone.get(time_zone) unless time_zone.nil?
+    rescue TZInfo::InvalidTimezoneIdentifier
+      raise AtreaControl::ProtocolError, "Invalid unit time zone", cause: nil
     end
 
     def values(xml)
-      format_data(parse(xml))
+      snapshot(xml).fetch(:values)
+    end
+
+    # Readings and policy share one validated register map, without mutable caches.
+    def snapshot(xml)
+      document = validated_document(xml)
+      registers = extract_registers(document)
+      configuration = Duplex::RD5Configuration.new(registers)
+      { values: format_data(project(document, registers, configuration)), configuration: configuration, registers: registers.freeze }
     end
 
     def input(sensor, value)
-      sensor + value.to_s.rjust(5, "0")
+      Duplex::RD5Command.encode(sensor, value)
+    end
+
+    # Validated register values stay unsigned until mapped to temperature fields.
+    def raw_values(xml)
+      extract_registers(validated_document(xml))
     end
 
-    # @see scripts.php -> loadRD5Values(node, init)
-    # @note
-    #   if(values[key]>32767) values[key]-=65536;
-    # 			if(params[key] && params[key].offset)
-    # 				values[key]=values[key]-params[key].offset;
-    # 			if(params[key] && params[key].coef)
-    # 				values[key]=values[key]/params[key].coef;
     def parse(xml)
-      xml = Nokogiri::XML xml
-      parsed = @user_ctrl.sensors.transform_values do |id|
-        # node = xml.xpath("//O[@I=\"#{id}\"]/@V").last
-        node = xml.xpath("//O[@I=\"#{id}\"]").last
-        # logger.debug node.to_s
-        value = node.attribute("V").value.to_i
-        value -= 65_536 if value > 32_767
-        # value -= 0 if "offset"
-        # value = value / coef if "coef"
-        value
-      end
-      preheating = %w[C10200 C10202 C10215 C10217].any? do |i|
-        xml.xpath("//O[@I=\"#{i}\"]/@V").last&.value == "1"
-      end
-      # @note timestamp seems to be localtime of creation of xml
-      parsed["timestamp"] = xml.xpath("//RD5WEB").attribute("t").to_s
-      parsed["preheating"] = preheating
-      parsed
+      document = validated_document(xml)
+      registers = extract_registers(document)
+      project(document, registers, Duplex::RD5Configuration.new(registers))
     end
 
     # @param [Hash] values
@@ -58,14 +53,83 @@ module AtreaControl
         "current_power" => values["current_power"].to_f,
         "outdoor_temperature" => values["outdoor_temperature"].to_f / 10.0,
         "preheat_temperature" => values["preheat_temperature"].to_f / 10.0,
-        "input_temperature" => values["input_temperature"].to_f / 10.0,
+        "required_temperature" => values["preheat_temperature"].to_f / 10.0,
+        "input_temperature" => values["input_temperature"]&.fdiv(10),
         "preheating" => values["preheating"],
-        "timestamp" => Time.strptime(values["timestamp"], "%Y-%m-%d %H:%M:%S"),
+        "timestamp" => timestamp_time(values["timestamp"]),
       }
     end
 
     private
 
+    def project(document, registers, configuration)
+      parsed = @user_ctrl.sensors.to_h do |field, id|
+        value = field == "input_temperature" ? input_temperature(registers, configuration) : mapped_value(registers, field, id)
+        value -= 65_536 if %w[outdoor_temperature preheat_temperature input_temperature].include?(field) && value.to_i > 32_767
+        [field, value]
+      end
+      parsed["required_temperature"] = parsed["preheat_temperature"]
+      # @note timestamp seems to be localtime of creation of xml
+      parsed["timestamp"] = document.root["t"]
+      parsed["preheating"] = %w[C10200 C10202 C10215 C10217].any? { |id| registers[id] == 1 }
+      parsed
+    end
+
+    def input_temperature(registers, configuration)
+      source = @user_ctrl.input_temperature_source if @user_ctrl.respond_to?(:input_temperature_source)
+      return configuration.input_temperature if source.to_s == "rd5_standard"
+      return nil unless source.nil?
+
+      registers[@user_ctrl.sensors["input_temperature"]]
+    end
+
+    def mapped_value(registers, field, id)
+      raise AtreaControl::UnsupportedConfiguration, "Invalid register mapping for #{field}" unless id.is_a?(String) && id.match?(/\A[A-Z]\d+\z/)
+      return registers[id] if %w[power_input power_switch mode_input mode_switch].include?(field)
+
+      registers.fetch(id) { raise AtreaControl::ProtocolError, "Missing required register #{id}" }
+    end
+
+    def validated_document(xml)
+      document = Nokogiri::XML(xml) { |config| config.strict.nonet }
+      raise AtreaControl::ProtocolError, "Expected RD5WEB/RD5 unit XML" if document.internal_subset || !document.at_xpath("/RD5WEB/RD5")
+
+      validate_timestamp(document.root["t"])
+      document
+    rescue Nokogiri::XML::SyntaxError
+      raise AtreaControl::ProtocolError, "Malformed unit XML", cause: nil
+    end
+
+    def validate_timestamp(timestamp)
+      raise AtreaControl::SessionExpired if timestamp.to_s.strip.empty?
+
+      timestamp_time(timestamp)
+    end
+
+    def timestamp_time(timestamp)
+      timestamp = timestamp.strip if timestamp.is_a?(String)
+      format = "%Y-%m-%d %H:%M:%S"
+      raise AtreaControl::ProtocolError, "Invalid unit timestamp" unless timestamp.is_a?(String) && timestamp.match?(/\A[0-9]{4}-[0-9]{1,2}-[0-9]{1,2} [0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2}\z/)
+
+      timestamp = timestamp.gsub(/[0-9]+/) { |component| component.rjust(2, "0") }
+      local = Time.strptime("#{timestamp} +0000", "#{format} %z")
+      raise AtreaControl::ProtocolError, "Invalid unit timestamp" unless local.strftime(format) == timestamp
+
+      @time_zone ? @time_zone.local_to_utc(local, nil) : Time.strptime(timestamp, format)
+    rescue ArgumentError, TZInfo::AmbiguousTime, TZInfo::PeriodNotFound
+      raise AtreaControl::ProtocolError, "Invalid unit timestamp", cause: nil
+    end
+
+    def extract_registers(document)
+      document.xpath("/RD5WEB/RD5/*/O").each_with_object({}) do |node, registers|
+        id = node["I"].to_s
+        value = node["V"].to_s
+        raise AtreaControl::ProtocolError, "Invalid register #{id.inspect}" unless id.match?(/\A[A-Z]\d+\z/) && value.match?(/\A\d+\z/) && value.to_i <= 65_535
+
+        registers[id] = Integer(value, 10)
+      end
+    end
+
     # `current_mode_switch` = mode trigger by wall switch or something similar
     # `current_mode` = is common "builtin" mode
     def parse_current_mode(values)

data/lib/atrea_control/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 # :nocov:
 
 module AtreaControl
-  VERSION = "3.2.0"
+  VERSION = "4.0.0"
 end

data/lib/atrea_control.rb

@@ -7,6 +7,13 @@ require "yaml"
 module AtreaControl
   class Error < StandardError; end
 
+  class AuthenticationError < Error; end
+  class TransportError < Error; end
+  class UnitConnectionTimeout < TransportError; end
+  class ProtocolError < Error; end
+  class UnsupportedConfiguration < Error; end
+  class WriteNotConfirmed < Error; end
+
   class SessionExpired < Error
     def message
       "Session expired. Please perform login again."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atrea_control
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Lukáš Pokorný
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.14'
 - !ruby/object:Gem::Dependency
   name: faraday-cookie_jar
   requirement: !ruby/object:Gem::Requirement
@@ -43,28 +43,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '1.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '1.15'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '1.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Read data from web controller of RD5 duplex by Atrea.
 email:
 - pokorny@luk4s.cz
@@ -78,6 +92,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -90,12 +105,20 @@ files:
 - config/locales/cs.yml
 - config/locales/de.yml
 - config/locales/en.yml
+- docs/rd5-cloud-protocol.md
+- docs/superpowers/plans/2026-10-24-rd5-reliability.md
 - lib/atrea_control.rb
 - lib/atrea_control/duplex.rb
 - lib/atrea_control/duplex/login.rb
+- lib/atrea_control/duplex/login_discovery.rb
+- lib/atrea_control/duplex/login_session.rb
+- lib/atrea_control/duplex/rd5_command.rb
+- lib/atrea_control/duplex/rd5_configuration.rb
 - lib/atrea_control/duplex/request.rb
 - lib/atrea_control/duplex/unit.rb
+- lib/atrea_control/duplex/unit_commands.rb
 - lib/atrea_control/duplex/user_ctrl.rb
+- lib/atrea_control/duplex/write_verification.rb
 - lib/atrea_control/logger.rb
 - lib/atrea_control/sensor_parser.rb
 - lib/atrea_control/version.rb
@@ -112,7 +135,7 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -121,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Get data control.atrea.eu
 test_files: []