atrea_control 3.2.0 → 4.0.0

data/README.md

@@ -1,89 +1,242 @@
 # atrea_control
-Ventilation systems by https://www.atrea.eu are build with web UI portal - but this portal did not provide any API interface...
 
-This gem provide way how to connect to portal and obtain data from unit as API.
+Ruby client for ATREA DUPLEX ventilation units with **RD5 regulation**, using
+the [RD5 cloud portal](https://control.atrea.eu/). RD5-only support is intentional:
+this unofficial gem uses cloud HTTP/XML, not aMotion Cloud or Modbus TCP.
 
-## Highlights
-
-* connect to portal, wait for login
-* provide basic data
-  * temperature
-  * fan power
-  * power mode
-* allow change
-  * power
-  * mode
+**Login and end-to-end reads were verified against a live RD5 unit on 2026-10-25:**
+configuration discovery, fresh snapshots, getters/JSON and repeated refreshes
+succeeded. A missing `Sync=1` parameter in the unit-login request was corrected
+after comparison with the current portal. Live writes and requested-value
+read-back semantics remain unverified. See [protocol evidence and limitations](docs/rd5-cloud-protocol.md).
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem "atrea_control"
 ```
 
-And then execute:
-```bash
-bundle install
-```
-
-Or 
-```bash
-bundle add atrea_control
-```
-
-Or install it yourself as:
-
-```bash
-gem install atrea_control
-```
+Run `bundle install`, or install directly with `gem install atrea_control`.
 
-## Usage
+## Login and snapshots
 
-At the begin you need obtain `user_id`, `unit_id` and `sid` (auth token). For this use "Login"
-
-* `user_id` is atrea internal ID of user account
-* `unit_id` is atrea `ident` - identification number of airflow unit (ventilation system) - 10 digits
-* `sid` is session ID - auth token, valid for logged session. Its validity is unknown
+Supply credentials through your application's environment. The library does not
+load `.env` files automatically. Never log credentials or returned tokens.
 
 ```ruby
-tokens = AtreaControl::Duplex::Login.user_tokens login: "myhome", password: "sup3r-S3CR3T-kocicka"
-tokens # => { user_id: "1234", unit_id: "85425324672", sid: 4012 }
+require "atrea_control"
+
+tokens = AtreaControl::Duplex::Login.user_tokens(
+  login: ENV.fetch("ATREA_USERNAME"),
+  password: ENV.fetch("ATREA_PASSWORD"),
+  unit_id: ENV.fetch("ATREA_UNIT_IDENT"),
+  timeout: 300,
+  poll_interval: 1,
+  open_timeout: 10,
+  read_timeout: 60
+)
+
+control = AtreaControl::Duplex::Unit.new(**tokens, time_zone: "Europe/Prague")
+values = control.values
+values[:current_power] # Numeric configured power value, not universally percent.
+values[:current_mode]  # Translated label; may describe a user input such as CO2.
+control.refresh!      # Explicitly fetch and validate a new snapshot.
 ```
-I recommend to store then somewhere...
-Then you can call Unit for data...
 
-Example usage:
+`Login.new(...).call` accepts the same keywords. `unit_id:` selects the unit's
+`ident`, **not** its portal row ID. Omit it to select the first listed unit.
+Returned tokens contain `user_id`, `unit_id` and secret `sid`.
+
+Account authentication and unit-session acquisition are separate stages. Defaults
+are `timeout: 300`, `poll_interval: 1`, `open_timeout: 10`, `read_timeout: 60`, in
+seconds. The entire login, including authentication, discovery and polling, must
+finish within five minutes; shorter `timeout:` values are allowed, larger ones
+are rejected. Each HTTP operation has a separate 60-second total limit covering
+connection, writing and reading, also bounded by the outer login limit. Both use
+Faraday's Net::HTTP adapter and standard-library `Timeout`, without a custom
+transport. Server ETA is advisory, not a loop count. Timeout does not establish
+that credentials were rejected or the unit is offline.
+
+Ordinary unit requests also have a 60-second total limit, not just a per-read
+timeout. `Duplex::Request.new(..., timeout: ...)` accepts shorter total limits;
+`open_timeout:` and `read_timeout:` can independently shorten connection/read
+waits. The adapter never automatically retries requests.
+
+### Snapshot lifetime and temperature semantics
+
+* First reading fetches one complete snapshot; later getters reuse it without
+  implicit network refresh. `refresh!` explicitly replaces it.
+* Every current-value getter and serializer checks freshness: timestamp must be
+  newer than `now - 900` seconds and no later than `now + 60` seconds. Exactly
+  15 minutes old is expired. `valid?` inspects cached state without fetching.
+* Failed refresh invalidates current data and preserves the failure until another
+  `refresh!`. A write attempt also discards the pre-write snapshot, even when its
+  response fails; next reading fetches again. No stale fallback is exposed.
+* `values`/`as_json` use symbol keys; `parsed` uses string keys. Readers include
+  `power`/`current_power`, `mode`/`current_mode`, `outdoor_temperature`,
+  `required_temperature`, `preheat_temperature`, `input_temperature`, `preheating`
+  / `preheating?`, and `timestamp`. Temperatures are degrees Celsius.
+* `required_temperature` is the requested temperature. Historical
+  `preheat_temperature` reader and hash key remain aliases in meaning; both keys
+  are present. This is **not** a measured preheater temperature.
+* Optional `input_temperature` is `nil` when unavailable or its discovered logic
+  is unsupported. It is not fabricated as zero.
+* Legacy `preheating` is an aggregate of heating-related signals, not a verified
+  dedicated preheater state.
+* Optional `time_zone:` accepts an IANA identifier (also on `SensorParser.new`).
+  `nil` preserves process-local timestamp interpretation. Set the actual unit's
+  zone explicitly to remove deployment-zone ambiguity. Invalid zones and
+  ambiguous/nonexistent DST-local timestamps raise `ProtocolError`.
+* Device timestamps may omit leading zeroes (for example, `17:7:32`). These are
+  normalized while invalid calendar dates and times are still rejected.
+
+Loading the gem registers translations and sets global `I18n.default_locale` to
+`:cs`. Sensor/mode maps use string keys. `user_modes` keys are numeric strings,
+not input names such as `"D1"`.
+
+### Configuration discovery
+
+`Unit.new` accepts `user_ctrl:` to reuse a `Duplex::UserCtrl` for the **same unit**.
+It caches successfully validated layout/text configuration per instance; recreate
+it after configuration changes. `UserCtrl.data` exports JSON-safe configuration,
+including `input_temperature_source`: `"rd5_standard"` selects the recognized
+device source-selection rule; `"unsupported"` keeps inlet temperature unavailable.
+Persist this field alongside the sensor/mode maps and expose it when reconstructing
+a custom `user_ctrl:` object, such as an ActiveRecord model. Without it, only the
+legacy direct sensor mapping can be used. Missing/nil metadata retains that legacy
+behavior; explicit unknown metadata returns `nil`, without guessing a sensor.
+
+Custom objects supply `name`, `sensors`, `modes`, `user_modes` and the persisted
+`input_temperature_source`. Sensor interpretation stays inside the gem, not the
+application UI. Command mappings must include discovered `power_input`, `power_switch`,
+`mode_input` and `mode_switch` fields. Derive mappings from the unit's `UserCtrl`,
+not fixture addresses. `control.configuration` returns the fresh snapshot's
+`Duplex::RD5Configuration` policy (`[]`, `fetch`, `to_h`).
+
+## Power and mode commands
+
+Setter values must be nonnegative integers, finite integral Floats, or ASCII
+decimal-digit strings: `88`, `88.0`, `"88"` normalize to 88. `nil`, booleans,
+negative/fractional numbers, NaN/infinity, whitespace, signs and `"88.0"` raise
+`ArgumentError`. Values are never silently truncated or clamped. Commands also
+require a supported configuration and discovered register mapping.
+
+Power semantics follow RD5 `H10510` in the vendor's
+[Communication MODBUS — RD5 and aMotion, version 04](https://atrea.eu/_files/documents/modbus-comm-amot-rd5-cz-v04_834.pdf),
+section 3.1, page 9:
+
+| `H10510` | Configuration | Accepted power values |
+| --- | --- | --- |
+| 0 | Direct speed | 0 or integers 12–100 |
+| 1 | Constant flow | Integers 0–100 (configured flow scale) |
+| 2 | Constant pressure | 0, 1, 2 (levels) |
+| 3 | External input | No power writes; `UnsupportedConfiguration` |
+| 4 | Multiport | 0, 10–12, 20–22, 30–38 (enumerated settings) |
+| Missing/unknown | Unsupported | `UnsupportedConfiguration` |
+
+These are not universal fan-speed percentages or measured airflow. Modes must be
+discovered numeric IDs 0–7 and satisfy equipment prerequisites: 0/2 unrestricted;
+1/6/7 require `C10508=0`; 3 additionally requires `C10509=1`; 4 additionally
+requires `H11700=1`; 5 requires `I11401=1`. Missing prerequisites fail explicitly.
+Translated current-mode labels are not command values.
+
+Schedule policy uses the discovered control register: manual 0 sends only the
+setpoint; scheduled 1 or temporary 2 sends the setpoint plus temporary control 2,
+including for power zero. It does not permanently disable schedules. A temporary
+request lasts until the next scheduled interval under the documented RD5 policy.
+
+### Unconfirmed writes
+
 ```ruby
-control = AtreaControl::Duplex::Unit.new user_id: "1234", unit_id: "85425324672", sid: 4012
-control.values # => { current_power: 88.0, current_mode: "CO2" }
-control.power # => 88.0 
+response = control.set_power(88, verify: false)
+response = control.set_mode(2, verify: false)
+control.power = 88
+control.mode = 2
 ```
 
-### Dig deeper
-`AtreaControl::Duplex::Unit` expect optional argument `user_ctrl` which should be object respond to 
+`verify: false` returns the HTTP response, without application/read-back
+confirmation. `power=` and `mode=` delegate with `verify: false`. Ruby assignment
+expressions evaluate to their right-hand value, **not** confirmation. HTTP success
+alone does not establish that the unit accepted or applied the request. Writes
+are never automatically retried.
 
-`name` (String) = Name of unit
-`sensors` (Hash) = Map of sensors, for example: `{ outdoor_temperature: "HI10208", current_power: "H10704" }`
-`modes` (Hash) = Is a map of "changable" modes - in unit its something like "builtin?" modes. They are translated by unit lang - `{ "0" => "Vypnuto", "1" => "Automat" }` 
-`user_modes` (Hash) = Is a map user specific modes, based on home switches / devices (D1, D2, D3, IN1, IN2 ...). They are translated by user texts - `{ "D1" => "Koupelna", "D2" => "CO2", "IN1" => "ovladač" }`
+### Verified writes require an independently proven mapping
 
-__Please check [lib/atrea_control/duplex/user_ctrl.rb](./lib/atrea_control/duplex/user_ctrl.rb) for more details !__
+`set_power(value, verify: true, timeout: 30, poll_interval: 5)` and `set_mode`
+default to verification. **The default configuration has no proven requested-value
+read-back profile:** verified calls raise `UnsupportedConfiguration` before writing.
+Neither the PDF's current-value fields nor old fixture `idw` fields are selected
+automatically.
 
-This object is used to translate internal unit modes to user-friendly texts & translations.
+Only supply `verification_registers:` after independently verifying requested-value
+semantics for that exact unit/profile. It accepts a nonempty Hash with symbol keys
+`:power` and/or `:mode`, and String values matching `H` plus exactly five digits.
+Syntax validation does not establish register semantics. This example deliberately
+supplies no literal register address:
 
-I strong recommend to use `AtreaControl::Duplex::UserCtrl` object from "cache",
-for optimize network traffic - because they are static data.
-
-## Development
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+# These environment values must come from your independently verified profile.
+verified_control = AtreaControl::Duplex::Unit.new(
+  **tokens,
+  time_zone: "Europe/Prague",
+  verification_registers: {
+    power: ENV.fetch("ATREA_VERIFIED_POWER_REQUEST_REGISTER"),
+    mode: ENV.fetch("ATREA_VERIFIED_MODE_REQUEST_REGISTER")
+  }
+)
+confirmed_power = verified_control.set_power(88, timeout: 30, poll_interval: 5)
+confirmed_mode = verified_control.set_mode(2, timeout: 30, poll_interval: 5)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Verification fetches a fresh baseline, writes once, then polls for the normalized
+request in a snapshot **newer than the baseline**. One absolute budget includes
+baseline, lazy discovery, dispatch, read-back and sleeps. It confirms a requested
+setpoint, not physical airflow, effective mode or override of safety functions.
+`WriteNotConfirmed` means outcome unknown after dispatch; do not blindly retry.
+
+## Errors and migration
+
+All library errors inherit `AtreaControl::Error`; invalid caller command inputs
+raise standard `ArgumentError`.
+
+| Error | Meaning |
+| --- | --- |
+| `AuthenticationError` | Portal rejected authentication. |
+| `SessionExpired` | Unit HTTP 401/403, or missing/stale/future snapshot timestamp. Freshness failure alone does not prove authentication expired. |
+| `ProtocolError` | Malformed/unexpected XML, invalid register/timestamp or DST ambiguity. |
+| `TransportError` | Failed HTTP response or connection. |
+| `UnitConnectionTimeout` | Transport timeout or exhausted login/verification-baseline budget; subclass of `TransportError`. |
+| `UnsupportedConfiguration` | Missing/unsupported configuration, command profile or proven verification mapping. |
+| `WriteNotConfirmed` | Verification budget exhausted after dispatch; outcome unknown. |
+
+Migration from 3.2.x: `nil` formerly could become zero; it now raises
+`ArgumentError`. Other malformed inputs no longer silently coerce. All cached
+getters/serializers can now raise freshness or refresh errors. Handle optional
+inlet temperature `nil`, the additional `required_temperature` hash key, strict
+configuration/mode validation, and preserved manual schedule control. Explicit
+`set_power`/`set_mode` default to verification; existing assignment setters remain
+unconfirmed. These changes require a **major-version upgrade** from 3.2.x.
+
+## Protocol reference and development
+
+See [RD5 cloud protocol evidence](docs/rd5-cloud-protocol.md) for supported
+declarative discovery forms, fixture/PDF differences and current integration blocker.
+The PDF describes **Modbus TCP**, not cloud framing, acknowledgements or rate
+limits. Port 502, enabling Modbus and its five-second batch interval are not
+prerequisites or established HTTP constraints for this gem.
+
+Run `bin/setup` to install dependencies. `bundle exec rake` runs specs then
+RuboCop. CI retains the Ruby spec matrix and runs a separate RuboCop job. Focused
+test: `bundle exec rspec spec/atrea_control/duplex/unit_spec.rb`, optionally with
+`:LINE`. WebMock/local fixtures need no portal credentials or physical unit.
+Use `bin/console` for an interactive prompt.
+
+Gem contents come from `git ls-files`; new runtime files must be tracked before
+packaging. `bundle exec rake build` builds locally. Publishing requires a separate
+release decision: `bundle exec rake release` pushes commits/tags and publishes to
+RubyGems; it is not a verification command.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/luk4s/atrea_control. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/luk4s/atrea_control/blob/master/CODE_OF_CONDUCT.md).
-
-## Code of Conduct
-
-Everyone interacting in the AtreaControl project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/luk4s/atrea_control/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at https://github.com/luk4s/atrea_control.
+Participants must follow the [code of conduct](CODE_OF_CONDUCT.md).

data/atrea_control.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Get data control.atrea.eu"
   spec.description = "Read data from web controller of RD5 duplex by Atrea."
   spec.homepage = "https://github.com/luk4s/atrea_control"
-  spec.required_ruby_version = Gem::Requirement.new("~> 3.2")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -35,8 +35,9 @@ Gem::Specification.new do |spec|
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html
 
-  spec.add_dependency "faraday", "~> 2.7"
+  spec.add_dependency "faraday", "~> 2.14"
   spec.add_dependency "faraday-cookie_jar", "~> 0.0"
-  spec.add_dependency "i18n", "~> 1.14"
-  spec.add_dependency "nokogiri", "~> 1.15"
+  spec.add_dependency "i18n", "~> 1.15"
+  spec.add_dependency "nokogiri", "~> 1.16"
+  spec.add_dependency "tzinfo", "~> 2.0"
 end

data/docs/rd5-cloud-protocol.md

@@ -0,0 +1,253 @@
+# RD5 cloud protocol: evidence and supported profiles
+
+This client intentionally targets RD5 cloud HTTP/XML only. It is neither aMotion
+Cloud nor a Modbus TCP implementation. Local fixture coverage establishes parser
+and policy behavior, not current firmware compatibility.
+
+## Evidence ledger
+
+1. **Older portal fixtures:** `spec/fixtures/files/userCtrl.xml` and `unit.xml`,
+   plus login response fixtures. These support declarative layout discovery and
+   register parsing. The unit fixture timestamp is historical, not a live sample.
+2. **Vendor PDF:** *Communication MODBUS — RD5 and aMotion*, version 04, cover
+   issue `2025_04_25`, sections 2.3.1 and 3.1 (especially pages 9–13),
+   [public source](https://atrea.eu/_files/documents/modbus-comm-amot-rd5-cz-v04_834.pdf).
+   The contents page has a different issue date; use version and cover issue as
+   identity. It establishes RD5 register semantics, not cloud framing, login,
+   acknowledgements or HTTP rate limits. Modbus's five-second batch interval is
+   not evidence of a cloud HTTP limit.
+3. **Initial read-only audits:** account authentication and unit-record discovery
+   succeeded. Advertised package
+   `3001022`, normalized with leading zeroes, matches `CONTROL_VERSION`
+   `003001022`. SID remained zero. The full 360-second budget ended exactly with
+   `AtreaControl::UnitConnectionTimeout`, `stage=session_query`.
+
+4. **Successful live audit on 2026-10-25, after production client shutdown:** the
+   unmodified handshake still timed out. Unit metadata reported a server contact
+   about 101 seconds earlier, so zero SID alone did not establish disconnection.
+   Inspection of current portal source identified a missing `Sync=1` on the
+   unit-login POST. Adding only this parameter obtained a SID in about 127 seconds
+   and allowed valid reads. After applying the fix, a separate public-API run
+   logged in in 5.86 seconds, read values/configuration, serialized getters/JSON,
+   and completed three refreshes with advancing timestamps and data roughly five
+   seconds old. Another run checked the unit-name reader, constructed power/mode
+   commands from the actual configuration without sending them, rejected an aged
+   live snapshot under a process-local controlled clock, and recovered via refresh.
+   The rebuilt `pkg/atrea_control-3.2.1.gem` was then unpacked outside the workspace
+   and used for another real login (5.9 seconds), valid read and successful refresh;
+   this checked the packaged runtime, not only the working-tree source.
+5. **Faraday-only follow-up:** after removing the extra transport, live login
+   completed in 1.45 seconds. Both Login and Request used `Faraday::Adapter::NetHttp`;
+   HTTPX was not loaded. Values and refresh passed, with refreshed data roughly
+   five seconds old. This audit also exposed unpadded timestamp components
+   (`2026-10-25 17:7:32 `); the parser now accepts those valid fields after
+   normalization. No control writes were dispatched.
+
+**Remaining integration boundary:** current login, configuration discovery and
+reads are proven for this unit/package. Cloud acknowledgement shape, actual
+writes and requested-value read-back semantics are not. No live control writes
+were run; those need separate agreement. No credentials, account names, unit
+identifiers or SID values are retained here.
+
+## Cloud sequence implemented
+
+`Login` posts credentials to the portal (`?action=login`), accepts its expected
+302, requires the session cookie, obtains a client ID from `core/core.php`, lists
+`userUnits`, and resolves the `units` record to its `ident`. Explicit `unit_id:`
+matches that ident through the account list; otherwise the first unit is selected.
+
+`apps/rd5Control/handle.php` with `action=unitQuery`, `query=loged` returns a
+`/root/login` SID. A zero SID triggers `Sync=1&action=unitLogin` with the unit's
+account row reference and `comm=config/login.cgi?magic=`, requiring `/root/sended`, then
+polling the session query. Server wait estimates do not shorten or extend the
+absolute budget. A nonempty, nonzero SID is required for success. No browser
+application-launch request is needed in the verified library sequence.
+
+The current portal's `core/start.js` shared `sendSync` implementation prepends
+`Sync=1` to its requests. The RD5 app's `setUnit` function, returned by
+`core/core.php?action=run&object=app`, invokes that synchronous helper for
+`unitLogin`. This source comparison, followed by live success, supports the
+parameter fix without executing downloaded application code in the gem. A
+`/root/sended` response alone had not proved successful session establishment.
+
+`Request` sends unit requests through `comm/sw/unit.php` with authentication and
+version parameters. These parameters are secret-bearing: do not retain full URLs.
+Targets include:
+
+| Target | Purpose |
+| --- | --- |
+| `lang/userCtrl.xml`, `_async=1` | Layout and declarative discovery |
+| `config/texts.xml` | User-defined labels |
+| `config/xml.xml` | Register snapshot |
+| `config/xml.cgi`, `_w=1` | Command request |
+
+No cloud application ACK shape has been proven. A successful HTTP response is
+transport success only, including on an unconfirmed write. The client never
+automatically retries a write whose outcome may already be unknown.
+
+Login's default and maximum total limit is 300 seconds; polling is one second.
+Every HTTP operation has a separate 60-second total limit, including connection,
+write and response read. The outer login timer can stop a request earlier.
+Default connect/read waits are 10/60 seconds; shorter overrides are supported.
+Faraday's stock Net::HTTP adapter is the sole transport and disables retries.
+Standard-library `Timeout.timeout` wrappers use explicit `StandardError`-derived
+exception classes to preserve Net::HTTP's TLS-connect cleanup. No custom socket,
+resolver or transport plugin is needed. Verification keeps its own aggregate
+30-second default limit, including lazy configuration discovery and read-back.
+The earlier 360-second audit timings above predate this simplification.
+
+## Snapshot and raw register interpretation
+
+Snapshots require strict XML with `/RD5WEB/RD5`, no DTD and a valid root `t`
+timestamp: a four-digit year and one- or two-digit month/day/hour/minute/second
+fields (`YYYY-M-D H:M:S` or zero-padded equivalents), allowing surrounding
+whitespace. Fields are normalized before strict calendar/timezone validation.
+Registers are `/RD5WEB/RD5/*/O` elements with
+`I` identifiers and decimal `V` values in 0–65535. Last occurrence wins for a
+duplicate identifier. Missing required mapped readings, malformed numbers and
+unexpected XML fail explicitly; no partial snapshot is published.
+
+`SensorParser#raw_values` preserves unsigned integers. Temperature projection
+alone applies signed 16-bit conversion then tenths-of-degree scaling: 65535 is
+−0.1 °C, 65036 is −50.0 °C. A high configuration value stays unsigned.
+`RD5Configuration` consumes the same raw snapshot without changing service
+configuration. `Unit` checks freshness at every getter/serialization, publishes
+atomically and invalidates on failed refresh or any attempted write.
+
+## Declarative discovery: fixture profile confirmed on the live unit
+
+`UserCtrl` looks up `/root/layout/body/content/i` by title, rather than treating
+fixture IDs as universal:
+
+| Title | Discovery |
+| --- | --- |
+| `$outdoorTemp` | `id` for outdoor temperature |
+| `$requiredTemp` | `id` for requested temperature, both public alias names |
+| `$inletTemp` | Optional `id` and recognized `displayval` logic |
+| `$currentPower` | `id` for current power; `onchange` for input/control fields |
+| `$currentMode` | `id` for current mode; `displayval` reference for user-input selector; `onchange` for input/control fields |
+
+`Mode` and `ModeText` option lists define numeric-string-keyed labels; translated
+labels never replace numeric command IDs. Successful layout/text discovery is
+cached per `UserCtrl` instance. Unknown command scripts raise
+`UnsupportedConfiguration`; downloaded JavaScript is never evaluated.
+
+`RD5Command.discover` accepts this **complete** function shape, with whitespace
+between tokens and register IDs matching `H` plus five decimal digits:
+
+```javascript
+function(val) {
+  saved=true;
+  send2Unit(getUrlPar('INPUT',val)+(values.SWITCH==1?'&'+getUrlPar('SWITCH',2):''));
+}
+```
+
+`INPUT` and `SWITCH` above are notation, not literal accepted IDs. Both `SWITCH`
+references must be identical. Actual older fixture forms are:
+
+```javascript
+function(val) {
+  saved=true;
+  send2Unit(getUrlPar('H10708',val)+(values.H10700==1?'&'+getUrlPar('H10700',2):''));
+  if(val>0 && values.H10715==0) {
+    flyDown=false;
+    this.nextSibling.nextSibling.onmousedown();
+  }
+}
+function(val) {
+  saved=true;
+  send2Unit(getUrlPar('H10709',val)+(values.H10701==1?'&'+getUrlPar('H10701',2):''));
+}
+```
+
+The power-only UI tail is optional, but if present must match that specific
+recognized form; arbitrary extra statements are unsupported. Input/control IDs
+can differ when the complete supported form matches. The resulting string-keyed
+maps contain `power_input`, `power_switch`, `mode_input`, `mode_switch`.
+
+The successful live run discovered outdoor `I10208`, requested temperature
+`H10706`, current power/mode `H10704`/`H10705`, selector `H10712`, power
+input/switch `H10708`/`H10700`, and mode input/switch `H10709`/`H10701`.
+Observed configuration included direct-speed control `H10510=0`, orientation
+`H10501=1`, inlet profile `H11300=0`, `C10508=0`, `I11401=0`, and scheduled
+power/mode control states of 1. These observations establish this unit's profile,
+not universal addresses or behavior for every RD5 firmware.
+
+Commands concatenate a discovered holding-register ID and exactly five decimal
+digits (e.g. the older fixture's `H10708` plus 88 becomes `H1070800088`). One
+write request carries the setpoint and, when needed, its control switch. Unlike
+the UI's conditional, library policy treats **both** scheduled 1 and temporary 2
+as temporary-control writes; manual 0 stays manual. Zero power follows the same
+policy. Unknown/missing control state fails before dispatch. Permanent schedule
+disable is outside these setters.
+
+## Temperature profile and heating limitations
+
+Supported inlet logic is `RD5Configuration::INLET_SOURCE_RULE`, matched as a complete
+declarative form after whitespace removal:
+
+* `H11300=0`, `H10501=1`: use `I10200` only when `H10200>0` and temperature is
+  not 126.0 °C (unsigned raw sentinel 1260).
+* `H11300=0`, `H10501=2`: use `I10201` only when `H10201>0` and not sentinel.
+* `H11300=1`: use `I10204` if present.
+* Missing required optional sensor, stopped fan, other configuration or unknown
+  inlet script: return `nil`, without inventing a reading.
+
+`UserCtrl.data` exports `input_temperature_source` as a JSON-safe string:
+`"rd5_standard"` for the recognized rule, `"unsupported"` otherwise. Applications
+that persist this data must also expose that field on reconstructed `user_ctrl:`
+objects. The field selects device interpretation, not UI presentation; M1/M2/direct
+selection continues to use the current raw snapshot inside the gem.
+
+Legacy custom objects without `input_temperature_source` (or with nil metadata)
+can supply a direct inlet mapping; callers own its correctness. Explicit unknown
+metadata keeps the optional reading unavailable. Refresh previously cached metadata
+on upgrade rather than interpreting the new map as a legacy direct source.
+Outdoor mapping always comes
+from `UserCtrl`: old fixture uses `I10208`, whereas PDF page 11 calls `I10211`
+T-ODA. No blanket substitution is justified.
+
+PDF `H10706` means requested temperature, not measured preheater temperature.
+`required_temperature` and retained `preheat_temperature` reader/hash key expose
+that same reading. Legacy `preheating` ORs `C10200`, `C10202`, `C10215`, `C10217`
+when equal to 1. PDF descriptions include water-heater pump/heat-pump signals;
+this aggregate does not establish dedicated preheater operation. No replacement
+mapping has been fabricated.
+
+## Requested versus effective values and verification
+
+The PDF lists power/mode read fields `H10704`/`H10705` and write inputs
+`H10708`/`H10709`. Older layout fixtures separately label `idw=H10714`/`H10715`
+as requested power/mode while `id` fields are current readings. This difference
+is unresolved for current firmware. Neither pair is automatically chosen as a
+proven cloud requested-value read-back profile.
+
+Verified `Unit#set_power` / `set_mode` default to `verify: true`, timeout 30
+seconds and polling every five seconds. Without an explicit proven mapping they
+raise `UnsupportedConfiguration` **before writing**. Trusted callers may provide
+`Unit.new(..., verification_registers: mapping)` after independently establishing
+semantics for the exact unit/profile. Mapping is a nonempty Hash with only symbol
+keys `:power` and/or `:mode`, each mapped to a String matching `\AH[0-9]{5}\z`.
+Validation checks syntax, not truth of the caller's profile.
+
+Verification loads a fresh baseline containing the mapped raw register, builds
+and sends one command, and polls fresh snapshots until the timestamp is strictly
+newer than baseline and the raw requested value equals the normalized command.
+A stale matching value cannot confirm. Budget includes all baseline/discovery,
+HTTP, dispatch and sleep work. Baseline deadline failure raises
+`UnitConnectionTimeout`; verification timeout after dispatch raises
+`WriteNotConfirmed` with unknown outcome. Confirmation would establish a requested
+setpoint only, not effective operation or physical airflow. No current live ACK
+or read-back profile has been captured.
+
+## Remaining integration acceptance
+
+* Establish requested-value mappings and any application ACK from actual evidence.
+* Only with separate agreement, test one ordinary write and restore both original
+  setpoint and original manual/scheduled/temporary control state. Do not alter
+  service configuration.
+
+These remain hardware/protocol acceptance items, independent of fixture-suite
+success. Temperature/zone setters, alarms, flow telemetry, external temperature
+injection and Modbus transport remain deferred. External temperature injection's
+90-second refresh rule must not be applied to ordinary power/mode requests.