Reshape boiler data

README.md

@@ -52,6 +52,7 @@ Uploads default to disabled until `[upload].url` is configured.
 | Solar API: PV, AC output, household load, grid power | `/solar_api/v1/GetPowerFlowRealtimeData.fcgi` |
 | Solar API: grid meter counters | `/solar_api/v1/GetMeterRealtimeData.cgi?Scope=System` |
 | Internal GEN24 API: boiler switch | `/api/status/emrs` |
+| Internal GEN24 API: boiler switch-on threshold | `/api/config/emrs` |
 
 Solar API must be enabled in the inverter's Communication settings. The collector
 only reads these endpoints. The boiler endpoint is an internal firmware interface;
@@ -67,6 +68,7 @@ if it stops working, boiler state is recorded as unknown rather than off.
 | `production_ac_total_wh` | Lifetime AC production counter |
 | `grid_import_total_wh`, `grid_export_total_wh` | Grid meter lifetime import/export counters |
 | `boiler_enabled`, `boiler_reason` | Output state (`true`, `false`, or `null`) and reason code |
+| `boiler_threshold_w`, `boiler_threshold_source` | Switch-on threshold in watts and `api` or `config` provenance |
 
 The meter must be installed at the grid feed-in point. Missing/stale readings and
 source errors never become zero energy or an off boiler. DC panel power differs
@@ -75,7 +77,19 @@ from AC output by conversion losses. The website uses AC output for its energy b
 The boiler switch enables heating but does not measure electricity use: the thermostat
 can stop heating while the output remains enabled. Five-minute polling can miss short
 transitions; enabled durations are estimates. A branch meter is needed for boiler kWh.
-The 2000 W threshold is power (2 kW), not energy (kWh).
+The threshold is power (W), not energy (Wh).
+
+The collector tries `/api/config/emrs` once per observation and reads
+`rules.<boiler_pin>.thresholdOn`, matching the GEN24's own web interface. Negative
+`pgrid` thresholds denote exported surplus; their absolute magnitude is used.
+This endpoint can require authentication even while the switch state is public.
+If it is protected, unavailable or has no valid threshold, the collector uses
+`[inverter].boiler_threshold_w` (default `2000`) from its private configuration.
+A settings failure does not invalidate a successfully read switch state. The
+threshold and its source are saved with each new observation and sent to Solar.
+Requests still respect the minimum four-second spacing. Existing archives remain
+readable; legacy switch-only samples receive the configured fallback when uploaded,
+without rewriting their original payload or replacing a threshold already recorded.
 
 ## Parquet archive, delivery and retention
 
@@ -107,8 +121,9 @@ totals are calculated by the receiving application.
 These common power readings match the sibling `solar` application's existing
 model: its `stats` table stores timestamped watts for Production and Consumption,
 then applies `5/60` only when calculating Wh totals. `production_ac_w` maps to
-Production and `consumption_w` maps to Consumption. The solar-side relay importer
-is separate work; this relay change prepares both record sources for ingestion.
+Production and `consumption_w` maps to Consumption. Solar currently imports only
+the boiler switch from these uploads; it continues to obtain production and
+consumption directly from Solar.web.
 
 The upload request is a JSON object with `schema_version: 1` and a `samples` array,
 authenticated with `upload.token` from private `config.toml`, or the environment
@@ -116,7 +131,7 @@ variable named by `upload.token_env` when that setting is empty. The website mus
 commit its data before responding:
 
 ```json
-{"accepted_ids": ["1599c148-612c-46ab-aa9a-cf9a13271a72"]}
+{"result":"success","data":{"accepted_ids":["1599c148-612c-46ab-aa9a-cf9a13271a72"]},"desc_lang_id":"","desc_lang_params":[]}
 ```
 
 Only explicitly acknowledged IDs receive an `uploaded_at` timestamp. A plain HTTP
@@ -124,8 +139,21 @@ Only explicitly acknowledged IDs receive an `uploaded_at` timestamp. A plain HTT
 acknowledgements mark only the accepted records; remaining records retry with
 exponential backoff. Delivery is **at least once**: a receiver must deduplicate stable
 UUIDs when a response is lost, so retries and replays do not double-count energy.
-The sibling solar app does not yet provide an HTTP receiver; leave uploads
-disabled until a compatible receiver is available.
+Solar uses its standard JSON result envelope: `result` must be `success`, and
+acknowledgements are read from `data.accepted_ids`. Plain `accepted_ids` responses
+from other compatible receivers are also supported.
+The sibling Solar app provides `index.php?a=relay` as this receiver. Set `[upload].url`
+to its HTTPS URL and `[upload].token` to the same private value as Solar's
+`Settings::SOLAR_RELAY_TOKEN`. The collector's `source_id` must match Solar's
+`Settings::SOLAR_RELAY_SOURCE_ID` (default `home-gen24`). Restart the relay after
+changing its private configuration. Pending samples then upload automatically;
+use `replay` to resend retained samples already acknowledged elsewhere.
+
+Solar stores five-minute `boiler` stats in watts: the recorded threshold when enabled,
+zero when off. It calculates daily Wh by summing watts × 5/60 and uses those totals
+for monthly and yearly charts. It acknowledges other readings without importing them,
+including historical recovery records whose boiler state is unknown. Solar's
+existing Solar.web import continues to supply production and consumption.
 
 `collector.retention_days` defaults to 30. All retention cutoffs are midnight in
 `collector.timezone`. For example, on November 2 with 30 days retained, the cutoff