Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions addon/suncore/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,11 @@ Supported architectures: `amd64` and `aarch64`.
the assistant; **Earlier versions** restores a previous save; **Export
configuration** and **Import configuration** back up everything as a file.
The settings are stored in the app's `/data` folder and are part of the app
backup. This version uses database schema 3, which earlier versions cannot open:
export the configuration before updating.
backup. This version uses database schema 4, which earlier versions cannot open:
export the configuration before updating. Measurements, forecasts and prices
live in a separate `timeseries.db`, which is left out of the app backup; SunCore
rebuilds its quarter-hour history from Home Assistant's statistics when the file
is missing.

### Sign convention

Expand Down
1 change: 1 addition & 0 deletions addon/suncore/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ backup_exclude:
- timeseries.db
- timeseries.db-wal
- timeseries.db-shm
- timeseries.db.corrupt*
map:
- type: homeassistant_config
read_only: true
Expand Down
7 changes: 5 additions & 2 deletions addon/suncore_beta/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,11 @@ Supported architectures: `amd64` and `aarch64`.
the assistant; **Earlier versions** restores a previous save; **Export
configuration** and **Import configuration** back up everything as a file.
The settings are stored in the app's `/data` folder and are part of the app
backup. This version uses database schema 3, which earlier versions cannot open:
export the configuration before updating.
backup. This version uses database schema 4, which earlier versions cannot open:
export the configuration before updating. Measurements, forecasts and prices
live in a separate `timeseries.db`, which is left out of the app backup; SunCore
rebuilds its quarter-hour history from Home Assistant's statistics when the file
is missing.

### Sign convention

Expand Down
1 change: 1 addition & 0 deletions addon/suncore_beta/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ backup_exclude:
- timeseries.db
- timeseries.db-wal
- timeseries.db-shm
- timeseries.db.corrupt*
map:
- type: homeassistant_config
read_only: true
Expand Down
37 changes: 34 additions & 3 deletions docs/STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
Read this first in every session, then `CLAUDE.md` (once it exists) and the
ADRs relevant to your task. Keep it short; history lives in git.

**Last update:** 2026-10-16 · **Phase:** 4 in progress – PR 4-A contracts; Phase 3 (3-A
**Last update:** 2026-10-17 · **Phase:** 4 in progress – PR 4-A contracts, PR 4-B storage; Phase 3 (3-A
`phase-3/a-safety`, 3-B `phase-3/b-controller`, 3-C `phase-3/c-ui`) implemented, waiting for the
maintainer's shadow test · **Branch:** `claude/zealous-mayer-j5oda9`
maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/zealous-mayer-j5oda9`)

## Done

Expand All @@ -29,6 +29,35 @@ maintainer's shadow test · **Branch:** `claude/zealous-mayer-j5oda9`
- ADR-0013 "Battery as a controlled asset" **proposed** (prerequisite of WP10).
- Review fixes: in progress (`fix(...)` commits on the branch).

- **Phase 4 – PR 4-B (WP3, storage and statistics; branch `phase-4/b-storage`, stacked on 4-A)**:
- `/data/timeseries.db` (own migrations and `user_version`; excluded from backups together with
its WAL/SHM and `timeseries.db.corrupt*`): `measurement` 48 h and `measurement_1m` 30 days
(primary key `(ts, key)`: about 5x fewer WAL bytes per flush than `(key, ts)`), `measurement_15m`
unlimited with a `derived` flag, `forecast` versioned by issue time (kept 45 days after the
slot), `price` 400 days, `meta`. `TimeseriesStore`: batched appends, series round trips,
`latest_forecast_before`, nightly job 03:30 local (wakes at most hourly, follows the time
zone): downsample (1-minute tier only for complete quarter hours), retention, `VACUUM` only
when worth it, `size_report`.
- Corruption handling: only "not a database"/"malformed"/a failing `quick_check` move the file
aside (with WAL/SHM, `timeseries.db.corrupt-<UTC>`, newest two kept); locked, full, I/O or
permission errors and a file with a newer schema run SunCore without time series, nothing is
moved or deleted.
- Rebuild of 28 days of site history from `recorder/statistics_during_period` (period `hour`,
explicit units) as `derived` quarter hours (`suncore/ha/statistics.py`,
`suncore/app/history.py`), until it succeeded once (marker in `timeseries.db`), back-off 1, 5,
15, then 60 min; `unknown_command` is final for the process.
- Controller measurements through a batched writer (flush every 60 s and at shutdown, only
OK-quality values; the tick hook cannot disturb control).
- `suncore.db` migration 0004 (`plan_snapshot` zlib JSON, 200 rows / 14 days; `learned_param`):
**DB schema 4, earlier versions refuse it – export before updating (release-risk note).**
- `ActionRateLimiter` per `domain.service[#sub-key]` for `call_action_response` (default 30 s,
`ActionRateLimitedError`, follow-up A3 done); boundary rule 7 admits only
`suncore.app.adapters`.
- Fixed: a cancelled `Database.transaction` could leave a transaction open on the shared
connection.
- Follow-ups: `size_report` is not on a diagnostics page yet; a too-new `timeseries.db` is only
logged (a UI hint follows in 4-H).

- **Fix after the first live test (2026-10-16, branch `fix/device-freshness`)**: on the maintainer's
HA the SunSpec battery SoC (84 % for 25 min) and the `smartthinq_sensors` power sensors (5 W for a
day) never advance `last_reported` for an unchanged value, so SunCore marked them "stale" and the
Expand Down Expand Up @@ -308,7 +337,7 @@ maintainer's shadow test · **Branch:** `claude/zealous-mayer-j5oda9`
(WP12, optional, after 4-E). Merge only after the Phase 3 acceptance.
- **ADR-0013 must be accepted before WP10** (4-G). Its contract changes (`BatteryAction` `None` =
baseline, `BatteryBand.grid_charge_max_w`/`discharge_lock`, `effective_reserve_pct`,
`battery_identity`) land in a WP2 fix before 4-B.
`battery_identity`) land at the start of 4-G, after the maintainer accepted it.
- Maintainer questions from 4-A: plan §6 "Offene Fragen aus PR 4-A" (grid-charge schedule
precedence, VAT on negative spot prices, export tiers, grid charging on the Kostal).

Expand Down Expand Up @@ -501,6 +530,8 @@ maintainer's shadow test · **Branch:** `claude/zealous-mayer-j5oda9`
| Kostal Modbus external battery management not enabled on the maintainer's inverter; how it is enabled; §3.5 fallback timer behaviour | `research/kostal-plenticore-modbus.md`, ADR-0013 | maintainer enables it and measures; `kostal_modbus` capped at assisted until then |
| Creating a modbus hub from the HA UI (else YAML) | `research/ha-websocket-api.md` | maintainer's HA |
| Supervisor proxy passes `recorder/*` and `energy/*` commands | `research/ha-websocket-api.md` | first Phase 4 run on HA OS |
| Supervisor proxy forwards `recorder/statistics_during_period` (the 4-B rebuild logs a warning and retries) | `suncore/ha/statistics.py` | first run on HA OS |
| `change`/`sum` rows of real energy counters (the rebuild reads them as verified from source, not tested against live counters); `backup_exclude` accepts the glob `timeseries.db.corrupt*` | `suncore/ha/statistics.py`, `addon/*/config.yaml` | maintainer's HA with an energy counter; a backup on HA OS |
| Publication time of next-day prices (Tibber, Nord Pool, ENTSO-E, EPEX) | `research/integrations.md` | observe on the maintainer's HA |
| VAT applied to negative spot prices | `suncore/core/tariff.py` | maintainer's bill / supplier terms |
| KNN load model performance on aarch64 | plan WP12 | CI arm runner benchmark |
Expand Down
1 change: 1 addition & 0 deletions frontend/src/lib/i18n/locales/de.json
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,7 @@
"grid.power": "Netzleistung (positiv = Bezug)",
"grid.power_hint": "Ein Sensor, der positiv ist, wenn du Strom beziehst, und negativ bei Einspeisung.",
"grid.sensors": "Netzsensoren",
"ha.error.action_rate_limited": "Eine Home-Assistant-Aktion wurde zu oft angefordert und übersprungen; SunCore fragt nach dem Mindestabstand erneut an.",
"log.all_devices": "Alle Geräte",
"log.count": "{count, plural, =0 {Keine Einträge} one {# Eintrag} other {# Einträge}}",
"log.device": "Gerät",
Expand Down
1 change: 1 addition & 0 deletions frontend/src/lib/i18n/locales/en.json
Original file line number Diff line number Diff line change
Expand Up @@ -408,6 +408,7 @@
"grid.power": "Grid power (positive = import)",
"grid.power_hint": "One sensor that is positive when you draw from the grid and negative when you feed in.",
"grid.sensors": "Grid sensors",
"ha.error.action_rate_limited": "A Home Assistant action was requested too often and skipped; SunCore asks again after the minimum interval.",
"log.all_devices": "All devices",
"log.count": "{count, plural, =0 {No entries} one {# entry} other {# entries}}",
"log.device": "Device",
Expand Down
4 changes: 2 additions & 2 deletions scripts/check_reasons.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* string constants starting with ``api.error.`` (the error ``detail`` keys of the API) or
``api.validation.`` in ``suncore/api`` (validation issue keys),
* string constants that are exactly one key with the prefix ``wizard.`` (check and import
reasons built from a variable) or ``detect.criterion.`` anywhere
reasons built from a variable), ``detect.criterion.`` or ``ha.error.`` anywhere
in ``suncore/``, and ``controller.`` in ``suncore/controller/reasons.py`` (the
controller's key constants).

Expand All @@ -28,7 +28,7 @@
SOURCE = ROOT / "suncore"
LOCALES = ROOT / "frontend" / "src" / "lib" / "i18n" / "locales"
ERROR_PREFIXES = ("api.error.", "api.validation.")
KEY_PREFIXES = ("wizard.", "detect.criterion.")
KEY_PREFIXES = ("wizard.", "detect.criterion.", "ha.error.")
CONTROLLER_KEYS = Path("controller") / "reasons.py"
"""The controller defines its keys as constants in one module (log event names elsewhere
may share the ``controller.`` prefix)."""
Expand Down
14 changes: 14 additions & 0 deletions suncore/app/adapters.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# SPDX-License-Identifier: Apache-2.0
"""Composition of the tariff and forecast adapters (Phase 4 WP4/WP5).

This module will build the price and forecast sources from the configured templates and hand
them the Home Assistant connection. It is the only module of ``suncore.app`` that may call
``HAConnection.call_action_response`` (``tests/safety/test_boundary.py``, rule 7): the call is a
read-only action with ``return_response`` and is rate limited per ``(domain, service)`` by the
connection (``ActionRateLimiter``). An adapter passes the polling interval of its template as
``min_interval_s`` and treats ``ActionRateLimitedError`` as "use the last value".

Empty on purpose until the first adapter lands (PR 4-C).
"""

from __future__ import annotations
47 changes: 46 additions & 1 deletion suncore/app/control.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
DeviationEvent,
)
from suncore.controller.loop import TickResult
from suncore.core.balance import compute_flows
from suncore.core.balance import FlowSnapshot, compute_flows
from suncore.core.config import GoalsConfig
from suncore.core.control import (
TEMPERATURE_ROLE,
Expand All @@ -62,6 +62,14 @@
from suncore.core.decisions import Action, Decision, Reason
from suncore.core.devices import DeviceConfig, control_roles
from suncore.core.identity import identity_token
from suncore.core.measurements import (
SITE_BATTERY_W,
SITE_GRID_W,
SITE_HOUSE_W,
SITE_PV_W,
SITE_SOC_PCT,
device_power_key,
)
from suncore.core.signals import Quality, Sample
from suncore.core.site import SiteConfig
from suncore.devices.drivers import ClimateDriver, NumberDriver, create_driver
Expand Down Expand Up @@ -101,6 +109,8 @@
"""What ``create_driver`` returns, structurally: the gate's actuator plus ``device_state``."""

StateChangeListener = Callable[[], None]
MeasurementSink = Callable[[datetime, Mapping[str, float | None]], None]
"""Receives ``(tick time, {measurement key: value or None})`` after every tick."""


def probe_temperature_c(cache: EntityCache, device: DeviceConfig) -> float | None:
Expand Down Expand Up @@ -169,6 +179,10 @@ class ControlStack:
(``gate.recover(after_handover=True)``).
predecessor: the gate of the replaced stack: devices it could not release (removed or
re-mapped while Home Assistant was down) are released with its actuators.
on_measurements: called after every tick with the tick time and the site and device
measurements of that tick (``suncore.core.measurements`` keys; ``None`` = no valid
value). Synchronous and cheap by contract; an exception is logged and swallowed -
recording can never disturb the control loop.
defer_recover: wait for :meth:`allow_recover` before ``gate.recover()`` (the runtime
first learns Home Assistant's time zone, whose change would rebuild the stack in
the middle of the recovery).
Expand Down Expand Up @@ -199,8 +213,10 @@ def __init__( # noqa: PLR0915 - the composition root of the control layer
after_handover: bool = False,
predecessor: SafetyGate | None = None,
defer_recover: bool = False,
on_measurements: MeasurementSink | None = None,
) -> None:
self._connection = connection
self._on_measurements = on_measurements
self._recover_allowed = not defer_recover
self._after_handover = after_handover
self._site = site
Expand Down Expand Up @@ -687,11 +703,40 @@ async def tick(self) -> TickResult | None:
)
self.estimates = estimates
self.states = states
self._record_measurements(now, flows, estimates)
self.last = await self.loop.tick(now, inputs)
self._maybe_save_models(now)
self._notify()
return self.last

def _record_measurements(
self,
now: datetime,
flows: FlowSnapshot | None,
estimates: Mapping[str, PowerEstimate],
) -> None:
"""Hand this tick's values to the recorder; only ``OK`` data counts (a gap otherwise)."""
if self._on_measurements is None:
return
try:
values: dict[str, float | None] = {}
if flows is not None:
for key, flow in (
(SITE_GRID_W, flows.grid_w),
(SITE_PV_W, flows.pv_w),
(SITE_BATTERY_W, flows.battery_w),
(SITE_SOC_PCT, flows.battery_soc_pct),
(SITE_HOUSE_W, flows.house_w),
):
values[key] = flow.value if flow.quality is Quality.OK else None
for device_id, estimate in estimates.items():
values[device_power_key(device_id)] = (
estimate.value_w if estimate.quality is Quality.OK else None
)
self._on_measurements(now, values)
except Exception:
log.exception("control.measurement_sink_failed")

async def drain(self) -> None:
"""Wait for the submissions and observations in flight (they wait on simulated time)."""
await self.loop.drain()
Expand Down
Loading
Loading