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
11 changes: 11 additions & 0 deletions addon/suncore/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,17 @@ run against real hardware yet; the guide lists what is unverified.

Change options on the app's **Configuration** tab and restart the app.

## Expert settings (environment variables)

Three timing settings of the price service are not app options (keep the Configuration tab
simple). Experts can set them as environment variables of the container:

| Variable | Default | Description |
|---|---|---|
| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). |
| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. |
| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. |

## Demo mode

With `demo_mode` switched on, SunCore does not read your entities. A
Expand Down
11 changes: 11 additions & 0 deletions addon/suncore_beta/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,17 @@ run against real hardware yet; the guide lists what is unverified.

Change options on the app's **Configuration** tab and restart the app.

## Expert settings (environment variables)

Three timing settings of the price service are not app options (keep the Configuration tab
simple). Experts can set them as environment variables of the container:

| Variable | Default | Description |
|---|---|---|
| `SUNCORE_TARIFF_REFRESH_INTERVAL_S` | `3600` | Spacing of the regular price refresh in seconds (60–86400). |
| `SUNCORE_TARIFF_TOMORROW_AFTER` | `13:00` | Local time from which tomorrow's day-ahead prices are expected. |
| `SUNCORE_TARIFF_TOMORROW_POLL_S` | `900` | Spacing of the asks between that time and the arrival of tomorrow's prices. |

## Demo mode

With `demo_mode` switched on, SunCore does not read your entities. A
Expand Down
35 changes: 32 additions & 3 deletions docs/STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@
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-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:** `phase-4/b-storage` (stacked on `claude/zealous-mayer-j5oda9`)
**Last update:** 2026-10-17 · **Phase:** 4 in progress – PR 4-A contracts, 4-B storage, 4-C
tariffs; 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:** `phase-4/c-tariff` (stacked
on `phase-4/b-storage`)

## Done

Expand Down Expand Up @@ -338,6 +339,33 @@ maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/
- **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 at the start of 4-G, after the maintainer accepted it.
- **PR 4-C (WP4, branch `phase-4/c-tariff`)**: `suncore/tariff/` - a template-driven price adapter
(`engine.py`: action or attribute source, list or mapping shape, per-MWh conversion, native grid
from `end - start` or the timestamp spacing, 15/60-minute mixes as segments, gaps `None`, DST
safe; a kWh/MWh unit mismatch between sensor and template is refused), fixed and HT/NT sources,
`PriceFormula` on spot-only sources only, export fixed/tiered/none, the region's
`no_remuneration` rule (export price 0 in slots with a negative spot price; for all-in sources the
import end price is the proxy), `TariffService` (refresh hourly, on entity change for attribute
sources, every 15 min from 13:00 local until tomorrow's prices arrive, back-off after failures,
throttled calls are not failures, good data is never replaced by an empty or failed fetch,
prices stored in `timeseries.db`) and `GET /api/v1/prices?hours=48`. Templates `tibber.price`
(updated), `nordpool.price`, `entsoe.price` (+`_mwh`), `epex_spot.total_price`/`market_price`,
`octopus_energy.rates`, `generic.price_list`; schema changes are additive (templates README
changelog). Wiring in `suncore/app/adapters.py`; demo and simulator: the fake answers
`tibber.get_prices` through the same template path, scenario `negative_prices`.
`PriceFormula.end_price` is the 4-A `apply` under a name the actuator boundary test does not
reserve. `UNVERIFIED`: see the price rows in the table below.
Review fixes: a failing attribute source backs off; a fetch without a known price fails and keeps
the old data (unknown slots are carried over, `quality.carried_slots`); the old tail never overlaps
new data; Nord Pool `date` is the CET delivery day (`date_tz`, research note in
`research/integrations.md`) and "tomorrow covered" ends at the market's day end; a source in
another currency than the region is refused; `segments_from_points` (4-A) treats a multiple-step
hole at the list end as a gap. A spot-only price without a formula is a system-check warning and
`GET /api/v1/prices` says `formula_missing: true` with the top-level `price_includes`.
**For 4-F: the planner must refuse `spot_only` import prices without a formula (it must not
plan with bare market prices).** Known: the error argument `available` of
`tariff.error.ambiguous_series` carries the home names/areas of the response (shown to the user,
they are needed to choose one).
- 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 @@ -533,6 +561,7 @@ maintainer's shadow test · **Branch:** `phase-4/b-storage` (stacked on `claude/
| 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 |
| Nord Pool `config_entry` id source, sensor translation keys, publication time; Octopus/ENTSO-E/EPEX entity matchers (platform and unit only, no translation keys); `start`/`end` sent to `tibber.get_prices` as ISO with offset; negative-price rule proxy for all-in sources | `templates/tariff/*.yaml`, `suncore/tariff/pricing.py` | live check on a system with the integration |
| 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 |
| Energy colour variable names (`--energy-*`) | `frontend/src/app.css` | read HA frontend source |
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ flowchart TB
api --> storage
ha --> core
forecast --> ha
tariff --> ha
tariff --> templates
planner --> forecast
planner --> tariff
planner --> core
Expand Down Expand Up @@ -101,7 +101,7 @@ Package map (ADR-0001):
| `suncore/core` | Domain model: `Site`, `Asset` (grid, pv, battery, device), `Signal` (typed time series with unit and quality), `Capability`, `Plan`, `Intent`, `Decision`, `Reason`, units and sign conventions | stdlib, pydantic |
| `suncore/ha` | `HAConnection` (Supervisor or Direct transport), entity subscription with staleness tracking, service calls with read-back, write rate limiter, registry queries, MQTT discovery publisher | core, aiohttp |
| `suncore/forecast` | Adapter protocol + Solcast, Forecast.Solar, Open-Meteo, generic-attribute, built-in model; blending by measured skill; bias calibration; load profiles | core, ha, templates |
| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules | core, ha, templates |
| `suncore/tariff` | Import/export price sources (Tibber, Nord Pool, ENTSO-E/EPEX via HACS, fixed, HT/NT), price formula, region profiles, negative-price rules (Home Assistant reaches it through an injected action caller and entity reader wired in `suncore/app/adapters.py`) | core, templates |
| `suncore/planner` | Model builder, HiGHS solver worker, heuristic fallback, plan explanation, what-if | core, highspy, numpy |
| `suncore/controller` | Surplus computation, priority allocation, hysteresis state machines, peak shaving, export limiting, §14a limit | core |
| `suncore/safety` | Invariant checks, operating modes, override detection, watchdogs, fail-safe transitions; the only caller of actuators | core, devices |
Expand Down
36 changes: 36 additions & 0 deletions docs/plans/phase-4.md
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,39 @@ shadow and assisted run is the acceptance test.
nicht ausführbar. Reicht das, oder soll eine generische „Zwangsladen“-Entität bzw. später ein
eigener §3.4-ADR kommen?

### Offene Fragen aus PR 4-C (an den Maintainer)

1. **Zusätzliche Tarif-Einstellungen:** Damit Nord Pool (`config_entry`, `areas`), Octopus (zwei
Ereignis-Entitäten), mehrere Tibber-Häuser und ENTSO-E mit eigener Preisformel funktionieren,
bekommt `tariff.import` vier optionale Felder: `role_entities`, `action_params`, `series_key`,
`price_includes` (Aussage des Nutzers, ob die Quelle schon Steuern/Netzentgelte enthält).
Alte Dokumente bleiben gültig. Einverstanden?
2. **Nord Pool `config_entry`:** Die ID des Konfigurationseintrags muss der Nutzer eintragen
(Entwicklerwerkzeuge → Aktionen zeigt sie). Ob SunCore sie aus der Entity-Registry lesen kann,
ist nicht verifiziert (`UNVERIFIED`). Reicht die manuelle Eingabe für Phase 4?
3. **Negativpreis-Regel bei All-in-Quellen (Tibber):** Der Spotpreis ist nicht bekannt; als Ersatz
gilt der Endpreis (Import) < 0. Das markiert weniger Viertelstunden als die echten
Negativ-Spot-Stunden, die Einspeisung wird dann dort noch vergütet gerechnet (`UNVERIFIED`
gegen die Praxis). Alternative: zusätzlich die Spot-Quelle (z. B. EPEX Spot Marktpreis) als
Referenz konfigurieren (Phase 5). Einverstanden mit dem Ersatzwert?
4. **`curtailment_required`:** ändert in Phase 4 keinen Preis (Abregelung ist Sache von
Planer/Regler, nicht des Preises). Nur `no_remuneration` setzt den Einspeisepreis auf 0.
5. **Dynamische Einspeisepreise:** keine der verifizierten Quellen liefert welche; der Einspeisepreis
kommt aus `tariff.export` (fest, gestaffelt, keiner). Octopus-Export-Entitäten sind nicht
angebunden.
6. **HT/NT-Preis:** pro Viertelstunde zum Beginn der Viertelstunde; Fensterkanten, die nicht auf
:00/:15/:30/:45 liegen, wirken ab der nächsten Viertelstunde.
7. **Veröffentlichung der Preise für morgen:** Standard 13:00 Ortszeit, danach alle 15 min bis die
Preise da sind (`UNVERIFIED`; Experten-Umgebungsvariablen `SUNCORE_TARIFF_TOMORROW_AFTER`,
`SUNCORE_TARIFF_TOMORROW_POLL_S`, `SUNCORE_TARIFF_REFRESH_INTERVAL_S`, keine App-Optionen,
dokumentiert in beiden `DOCS.md`). Bitte an deinem System beobachten.
8. **§51 EEG und Inbetriebnahmedatum:** Ob bei negativen Preisen vergütet wird, hängt vom
Inbetriebnahmedatum der Anlage ab. Die Regel kommt heute nur aus dem Regionsprofil (`de`:
`no_remuneration`). Soll es später (Phase 5) pro Anlage eine Abschaltmöglichkeit geben
(„diese Anlage wird auch bei negativen Preisen vergütet“)?
9. **Namensabgrenzung:** `PriceFormula.apply` heißt für Aufrufer jetzt `end_price` (der Grenztest
reserviert `.apply(` für den Geräteschreibpfad); `apply` bleibt als Alias.

## Deviations during implementation

- Phase 4 is split into the stacked PRs 4-A…4-I (§3) instead of one PR.
Expand All @@ -403,6 +436,9 @@ shadow and assisted run is the acceptance test.
page was unreachable. The built-in PV fallback stays opt-in and off.
- `BatteryAction` is part of the 4-A contracts but rejected by the gate until WP10
(ADR-0011 addendum); its semantics are proposed in ADR-0013.
- WP4: ENTSO-E and EPEX Spot get two templates each where the unit or the price content differs
(`entsoe.price`/`_mwh`, `epex_spot.total_price`/`market_price`): a template holds one value unit
and one `price_includes`. Octopus is included (its source was verified in 4-A).

## 7. Out of scope for Phase 4

Expand Down
9 changes: 9 additions & 0 deletions docs/research/integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,15 @@ exists but is undocumented on the page.
The action returns the undivided MWh value; the adapter divides by 1000.
The values are the day-ahead market price per area; VAT, grid fees and levies are not part
of them (no such field in the source).
- **Meaning of `date` (zone)**: the action passes `date` as `YYYY-MM-DD` to the library
(`home-assistant/core@5cfe9aad7cb428c2c2ebb449719ae81976780de1`
`homeassistant/components/nordpool/services.py:112-125`: `datetime.combine(asked_date,
dt_util.utcnow().time())`), which only formats it with `strftime("%Y-%m-%d")` as the `date`
query parameter of Nord Pool's `DayAheadPrices` (`pynordpool 0.4.0` `__init__.py:106-127`) and
keys the raw response by `deliveryDateCET` (`__init__.py:102`). So `date` is read as the **CET
delivery day** (Central European rules, i.e. `Europe/Berlin`), not the Home Assistant day; the
template sets `date_tz: Europe/Berlin`. Read from source only, the query semantics of the
Nord Pool API itself were not seen live (`UNVERIFIED`).
- **Resolution**: slot length = `end - start` per entry (the sensors compute
`resolution = entry.end - entry.start`, `sensor.py:58`), 15 or 60 minutes; a
coordinator tick every 15 minutes (`coordinator.py:57-73`). The adapter must not
Expand Down
9 changes: 8 additions & 1 deletion docs/user/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,14 @@ a template only tested in the simulator has never run against real hardware.

| Id | Kind | Name | Integration / platforms | Capabilities | Tested with | Unverified |
|---|---|---|---|---|---|---|
| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `entsoe.price` | tariff | ENTSO-E day-ahead price (kWh) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `entsoe.price_mwh` | tariff | ENTSO-E day-ahead price (MWh scale) | `entsoe` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `epex_spot.market_price` | tariff | EPEX Spot market price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `epex_spot.total_price` | tariff | EPEX Spot total price | `epex_spot` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `generic.price_list` | tariff | Generic price list (sensor attribute) | any | `price_curve`, `price_now` | not tested on hardware | 3 |
| `nordpool.price` | tariff | Nord Pool day-ahead price | `nordpool` | `price_curve`, `price_now` | not tested on hardware | 6 |
| `octopus_energy.rates` | tariff | Octopus Energy rates | `octopus_energy` | `price_curve`, `price_now` | not tested on hardware | 4 |
| `tibber.price` | tariff | Tibber dynamic price | `tibber` | `price_curve`, `price_now` | not tested on hardware | 6 |

## PV forecasts

Expand Down
Loading
Loading