docs(frisko): add vendor app and map findings for the RX910-SE21

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/frisko/app-knowledge.md

@@ -0,0 +1,120 @@
+# Frisko app and map knowledge for the RX910-SE21
+
+What the vendor app (`FriskoOnline2025.apk`, decompiled with androguard, nothing run), the XML maps
+and the PDFs say. **Everything here is unverified on the device** unless
+[rx910-se21.md](rx910-se21.md) says so. Source tags: `PDF` = `RX910-SE21-AdresyMODBUS`, `XML` =
+`RX910-SE21_v24062015.xml`, `MR208` = MR208-PC+ manual/map (another model: hints only), `APK` =
+class in `com.frisko.frisko_mobile`.
+
+## Key finding: the app has no control logic
+
+The app is a generic Modbus viewer: every screen, scale, value name and icon comes from the XML
+(`XmlHandler`, `ListDataParam`). It contains no register numbers except 4011 (`Comm_thread.STATUS_REG`),
+base 4000 (`Frisko_Sterownik.ADR_BAZOWY`, only for its local array index; the wire address is the raw
+register) and the XML tag set. It never reads 4221, 4222–4225, 4227, 4228, 4119 or 4129. Meanings
+below therefore come from the PDF, the XML and the MR208 manual, not from code.
+
+## Alarm: register 4011 (the app) vs 4221 (the PDF)
+
+| Register | Source | Meaning |
+|---|---|---|
+| 4221 "Instalacja" | PDF | 0 = installation OK, 1 = installation fault. Binary, no bits, no codes. |
+| 4011 "Status" | XML (Status screen) | Fault code, not a bit field: 0 OK, 2 Err_Tzew, 3 Err_Tco, 4 Err_Twew, 5 Err_Tcwu, 14 Err_Tpc, 15 Err_Tdz, 1003 Err_Presostat |
+| 4073 "Presostat" | XML, PDF | 0 OK, 1 error (pressure switch input) |
+
+- The app polls 4011 always, and on any non-zero value (even one not in the XML list) raises a
+  notification "Awaria sterownika: <number>" with sound and vibration; it repeats only when the code
+  changes (`Comm_thread.update_regs`, `status_error`). It never reads 4221.
+- Likely mapping of names (inference from naming and the MR208 manual): `Tzew` outdoor 4065, `Tco`
+  buffer 4067, `Twew` indoor 4066, `Tcwu` 4069, `Tpc` pump outlet 4072, `Tdz` ground source
+  (4070/4071); codes 2–5, 14, 15 = sensor fault (MR208 "ErrTemp": pump off), 1003 = pressure switch
+  (MR208 "ErrPres": pump off; three trips in one cycle latch it until service clears it).
+- MR208 also reports TmaxPC, TminDZ, dTmaxDZ shutdowns; SE21 may put them in 4011 or 4221
+  (unknown). 4011 is not in the PDF map. Next: log a read-only FC 3 of 4011 beside 4221 and 4073.
+
+## Registers 4119, 4222–4225, 4228
+
+| Reg | What is known | Source |
+|---|---|---|
+| 4119 `WyCHL` | Output, "0 OFF, 100 ON" like 4112–4118. "CHL" probably means cooling (the gateway calls it `output_cooling`; a guess). Not in the XML, so the app never shows it. The −14308 read means the register is not implemented on this firmware | PDF; read per rx910-se21.md |
+| 4222–4225 | Not in the PDF, XML or APK. MR208 uses 4225 for TFer (a different layout, do not transfer). Gateway fixtures show 0 | none |
+| 4228 `StanZB` | PDF text is cut: "0 –", "2 – zbCW" (value 1 and the text of 0 are missing from the PDF extract, also with `-raw`). "ZB" is not explained; not in the XML | PDF |
+| 4227 `StanCO/CW` | 0 pc STOP, 1 pcCO, 2 pcCW, 3 pcCO/CW. Not in the XML; the app shows output icons instead | PDF |
+| 4226 `Status` | 0 Ferie, 1 Tygodn (weekly), 2 Party, 3 ROZRUCH (start-up), 4 STOP, 5 Dezynf. Same list in the XML "Program pracy" with icons `program_ferie`, `program_tygodniowy`, `program_party`, `praca`, `stop`, `dezynf` | PDF, XML |
+
+4226 is the effective state; 4140 is the chosen program (4226 can say STOP while 4140 says weekly).
+
+Open: the gateway test fixture (real output, PR #40) shows 4226 = 0 while the settings backup has
+4140 = 1 (weekly) and rx910-se21.md observed the weekly program. If 4226 really reads 0 then, the
+PDF numbering may be shifted by one. Check by reading 4226 and 4140 together, then changing nothing.
+
+## Modes and programs
+
+| Reg | Values | Source |
+|---|---|---|
+| 4121 `TrybLZ` | Effective season: 0 summer, 1 winter. Read-only on the app's Status screen | PDF, XML |
+| 4122 `TrypRA` | 0 R, 1 A, 2 *. Not in the XML. MR208 shows "Zima(A)" on its main screen: season plus A (automatic) or R (manual) | PDF, MR208 manual |
+| 4123 `Tryb` | Season setting: 0 Lato, 1 Zima, 2 Auto (editable; backup value 2). Auto switches at 4124 `Temp progu Z/L` (5–35 °C whole, backup 18) | XML, PDF, backup |
+| 4125 `Tryb pracy` | 0 STOP, 1 PRACA (editable; backup 1) | XML, PDF |
+| 4140 `Prg` | 0 Ferie, 1 Tygodniowy, 2 Party (editable) | XML, PDF |
+| 4141 Ferie days | 0–90 (XML). MR208: 0 = until switched back by hand | XML, MR208 manual |
+| 4142 Party hours | 0–90 (XML). MR208: 0 = until switched back; counts down to the end of Party | XML, MR208 manual |
+
+MR208 semantics (SE21 likely the same, unverified): Ferie keeps CO at the ferie target (4133) and CWU
+at economy or off; Party keeps comfort for CO and CWU; weekly intervals are comfort, the rest economy.
+
+## Economy or comfort period
+
+- The app does not decide this. It shows the XML values only; the XML has no "period" register.
+- The controller decides: weekly program intervals (4169–4176) give comfort, everything else economy
+  (MR208 manual, "Programy"). Ferie and Party override it as above.
+- The effective targets 4201 (room), 4203 (CWU) are the answer. Inference for a UI: compare 4201
+  with 4131 (economy), 4132 (comfort), 4133 (ferie), and 4203 with 4143 / 4144. Ambiguous when two
+  setpoints are equal. 4202 (CO supply target) comes from the heating curve (4134) and is not a setpoint.
+
+## "Heating CWU / CO" in the app
+
+The app shows no such state. Its "Stan wyjść" screen lists outputs 4117 Pompa DZ, 4113 BUF, 4112 CO,
+4118 CWU, 4116 CCW, 4114 Sprężarka (0/33/66/100), 4115 Grzałka CWU, each as an icon for 0, 1 or 100
+(XML). Heating CO or CWU means output 4112 or 4118 on. 4227 is the controller's own summary of the
+same thing (PDF); the app ignores it.
+
+## How the app writes (read-only knowledge for a later milestone)
+
+| Item | Finding | Source |
+|---|---|---|
+| Function codes | FC 3 read, FC 6 write one register. FC 16 exists in the code (`WRITE_REG_MULTI = 16`, `MDBwriteMulti`) but no UI path uses it | `Frisko_MDBRozkaz`, `Frisko_ModbusTCPSystem` |
+| Unlock or password | None. No other frame is sent; `HasloLAN` 4129 (PDF) is never used. Matches the FC 6 test on 4143 | APK, rx910-se21.md |
+| Unit id | The "slave" number set per controller in the app, in the MBAP unit byte | `Comm_thread`, `MDBsendData` |
+| Scales | Value = register / 10 for format `XXX.X`; whole for `XX`. `ster_format` MZ = sign-magnitude: a negative write n is sent as 0x8000 + \|n\| | XML, `JavaToSterownik` |
+| Range check | Min and max from the XML only, on the phone | XML |
+| Queue | Writes go to the front of the queue (`AddPriorRozkaz`), ahead of polling | `Frisko_ModbusTCPSystem` |
+| Confirmation | The reply (function, transaction id, address) is checked; no explicit read-back. The screen shows the new value after the next poll of that register | `MDBreadODP` |
+| Failure | Up to 3 attempts per request, 500 ms between them; then the socket is closed and re-opened | `MBD_ERROR`, `ERROR_TIME_OUT` |
+| Delay after write | 200 ms after FC 6, 300 ms after FC 16 | `run()` |
+| Program selector | Circuit 4177 and day 4167 are plain writes, then the interval registers are polled; no explicit wait. MR208 map prescribes 500 ms between selecting and reading or writing | APK, MR208 map |
+
+The XML schema also has `menu_set_adr` / `menu_set_val` (write a fixed value on opening a menu);
+the SE21 XML does not use it.
+
+## Request pacing
+
+| Item | Value | Source |
+|---|---|---|
+| Pause after each request | 200 ms (300 ms after FC 16); poll thread starts after 250 ms | `Frisko_ModbusTCPSystem.run` |
+| Poll list empty | 200 ms, then rebuilt: continuous polling, about 5 requests/s while a screen is open | `MDB_TIME_BREAK` |
+| Timeout | 5000 ms default, user setting (2–5 digits) | `MDB_TIME_OUT`, `SterSettingsActivity` |
+| Block read | Up to 28 registers per request, gaps up to 5 registers are read through | `MBD_SIZE_OPTYMAL`, `MBD_BREAK_OPTYMAL` |
+| What is polled | Only the registers on the open screen, plus 4011 | `REG_DATA_STATUS`, `Comm_thread.set_reg` |
+| Connections | One socket held open, up to 50 reconnect attempts | `disconnect_retries` |
+
+The vendor documents no limit. The app's 200 ms pause is the only known pacing; our 36 registers in
+5 blocks took 2.5 s (rx910-se21.md), so a 10 s cycle is far below the app's load.
+
+## Open questions
+
+- What are 4222–4225, and the missing values of 4228? (a read-only log over a heating cycle)
+- Does 4011 exist and move on this firmware? Its relation to 4221.
+- Is 4226 numbered as the PDF says (see above)?
+- What does 4119 read when it is implemented, and is the register used at all?
+- Meaning of 4122 value 2 ("*") and of 4126 `Uklad` (no values given).

docs/frisko/rx910-se21.md

@@ -28,7 +28,7 @@ unless marked otherwise.
 | Setpoints (F3) | 4131/4132 CO economy/comfort (5–35), 4143/4144 CWU economy/comfort (5–70) | whole °C |
 | Protection | 4158 TmaxPc = 52 °C, 4149 TmaxCWU = 55, 4148 HistCWU = 5, 4146 PriorCWU = 1, 4147 heater delay = 20 | read 2026-10-23 |
 
-Unknown: 4119 `WyCHL` reads −14308.
+Unknown: 4119 `WyCHL` reads −14308. Vendor-app findings, all unverified: [app-knowledge.md](app-knowledge.md).
 
 ## Weekly program