Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
97f21f4
docs: accept ADR-0013 and record the maintainer's default answers
claude Oct 19, 2026
aaf0210
docs: wrap the ADR-0013 STATUS line
claude Oct 19, 2026
05e478b
Merge branch 'claude/zealous-mayer-j5oda9' into phase-4/h-ui-docs
claude Oct 28, 2026
a593931
feat(frontend): plan view, battery card and forecast panel (WP11 part 1)
claude Oct 28, 2026
b10bf74
wip(frontend): Phase 4 wizard steps and tests, work in progress (WP11)
claude Oct 28, 2026
8f25bee
test(frontend): Playwright specs for plan, battery card and wizard st…
claude Oct 28, 2026
88d63c8
docs: demo screenshots of the plan view, battery card and the battery…
claude Oct 28, 2026
cc127dd
feat(frontend): plan view, battery card and the Phase 4 wizard steps …
claude Oct 28, 2026
e676ada
docs: user guide for planning and battery control (en/de, WP13 part 1)
claude Oct 28, 2026
91dddb9
docs: quick start and surplus control updated for Phase 4 (WP13 part 2)
claude Oct 28, 2026
7add669
docs: Phase 4 user guide for planning and battery control, quick star…
claude Oct 28, 2026
2b2aea8
docs: fallback timer procedure needs the watchdog off, review fixes (…
claude Oct 29, 2026
67439b4
docs: make the fallback-timer measurement safe (control-safety review)
claude Oct 29, 2026
ca46d02
docs: wrap a line in the German planning guide
claude Oct 29, 2026
32e7a85
fix(frontend): keep a stored price formula, move plan time on, price …
claude Oct 29, 2026
5793d24
fix(frontend): regenerate demo screenshots and keep every PNG under 3…
claude Oct 30, 2026
d9f2dc6
ci: pin the frontend job to ubuntu-24.04 (Playwright 1.56.1 has no Ch…
claude Oct 30, 2026
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
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,9 @@ jobs:

frontend:
name: Frontend
runs-on: ubuntu-latest
# Pinned: Playwright 1.56.1 cannot install Chromium on the ubuntu-latest image
# (ubuntu 26.04, "Playwright does not support chromium on ubuntu26.04-x64").
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v5
with:
Expand Down
33 changes: 19 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,20 @@
planner and a real-time surplus controller in one app – explainable, safe
by default, set up in minutes.**

> Status: **pre-alpha, Phase 3 implemented** (waiting for the maintainer's
> shadow-mode test on real hardware). The beta app has a guided **setup
> assistant**, a device template gallery (LG ThinQ air conditioner, generic
> switch, climate and adjustable load, water heaters, Tibber, Solcast), the live
> energy-flow view and a **real-time surplus controller** with a safety layer:
> priorities, hysteresis, minimum run times, no grid import caused by SunCore,
> respect for manual changes, an emergency stop, and a "Why?" and decision log
> for every decision. Everything starts in **shadow mode** and switches nothing
> until you set a device to automatic; the controller has never run against real
> hardware yet. Forecasts, planner and battery control follow in Phase 4. See
> [Surplus control](docs/user/en/surplus-control.md), the
> [roadmap](docs/roadmap.md) and [status](docs/STATUS.md).
> Status: **pre-alpha, Phase 4 implemented** (waiting for the maintainer's shadow-mode
> tests on real hardware: first Phase 3, then Phase 4). The beta app has a guided **setup
> assistant**, a device template gallery (LG ThinQ air conditioner, generic switch, climate and
> adjustable load, water heaters, Tibber, Nord Pool, ENTSO-E, EPEX Spot, Octopus Energy, Solcast,
> Forecast.Solar, Open-Meteo Solar Forecast, battery adapters), the live energy-flow view, a
> **real-time surplus controller** and, new in Phase 4, **forecasts, tariffs, a 48 hour planner
> and battery control**: a plan with a reason for every interval, a risk level and buffers, and
> limits on your home battery (generic Home Assistant entities, Kostal Plenticore), all behind a
> safety layer. Everything starts in **shadow mode** and switches or writes nothing until you
> set a device or the battery to automatic or assisted; neither the controller nor the planner
> and battery control have run against real hardware yet. See
> [Planning and battery control](docs/user/en/planning-and-battery.md),
> [Surplus control](docs/user/en/surplus-control.md), the [roadmap](docs/roadmap.md) and
> [status](docs/STATUS.md).

![SunCore "Now" view: live energy flow between solar, grid, battery and house](docs/assets/screenshots/now-tablet-light-en.png)

Expand Down Expand Up @@ -68,6 +70,8 @@ young: see the roadmap.
[Schnellstart](docs/user/de/quick-start.md)
- [Surplus control](docs/user/en/surplus-control.md) ·
[Überschusssteuerung](docs/user/de/surplus-control.md)
- [Planning and battery control](docs/user/en/planning-and-battery.md) ·
[Planung und Akkusteuerung](docs/user/de/planning-and-battery.md)
- [Contribute a device template](docs/user/en/device-templates.md) ·
[Compatibility list](docs/user/compatibility.md)
- [Roadmap](docs/roadmap.md) · [Status](docs/STATUS.md)
Expand All @@ -79,8 +83,9 @@ young: see the roadmap.
Once the first beta is released, add `https://github.com/pxljake/suncore`
as an app repository in Home Assistant (Settings → Apps → App store →
menu → Repositories) and install **SunCore (beta)**. The beta guides you through
the setup, shows the live energy flow and runs the surplus controller in shadow
mode; there are no forecasts or planner yet.
the setup, shows the live energy flow, runs the surplus controller, the planner and
the battery control in shadow mode and lets you take them to assisted and automatic
one step at a time.
Start with the [quick start](docs/user/en/quick-start.md)
([Deutsch](docs/user/de/quick-start.md)). Menu names differ between Home
Assistant versions (older ones say "Add-ons" and "Add-on store").
Expand Down
99 changes: 79 additions & 20 deletions addon/suncore/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,64 @@
Energy management for Home Assistant: forecasts, a cost-optimising planner
and a real-time surplus controller in one app.

## What SunCore does today (Phase 3)
## What SunCore does today (Phase 4)

SunCore is **pre-alpha**. This version helps you describe your installation,
shows your energy flow live and can distribute your solar surplus to devices:
shows your energy flow live, distributes your solar surplus to devices, plans
the next 48 hours and can set limits on your home battery:

- **Setup assistant**: ten steps for region, Energy dashboard import, grid,
solar, battery, tariff, devices, priorities and goals, operating mode and
a system check. Entities are detected and ranked, and a live sign check
solar (with forecast sources), battery (adapter, model, strategy, risk
level), tariff (price formula, HT/NT), devices, priorities and goals (grid
charging, self-sufficiency weight), operating mode and a system check with a
first plan preview. Entities are detected and ranked, and a live sign check
catches inverted sensors.
- **Device templates** (LG ThinQ air conditioner, generic switch, climate and
adjustable load, Tibber, Solcast, regions) with a gallery; see the
adjustable load, water heaters, Tibber, Nord Pool, ENTSO-E, EPEX Spot,
Octopus Energy, Solcast, Forecast.Solar, Open-Meteo Solar Forecast, battery
adapters for generic entities and Kostal Plenticore, regions) with a gallery;
see the
[compatibility list](https://github.com/pxljake/suncore/blob/main/docs/user/compatibility.md).
- **Forecasts**: several solar forecast sources blended by their measured
accuracy, a bias calibration that becomes active after 30 days, clipping
recognised, a load forecast learnt from Home Assistant's statistics (base
load without the controlled devices, workday and weather inputs), and an
accuracy panel.
- **Tariffs**: dynamic prices from Tibber, Nord Pool, ENTSO-E, EPEX Spot and
Octopus Energy, fixed and HT/NT prices, a price formula for spot prices,
fixed, tiered or no feed-in remuneration and the negative-price rule of the
region.
- **Planner**: a 48 hour plan in 15 minute steps, recomputed every 15 minutes
and on events, with an optimiser (HiGHS) and a rule-based fallback, a risk
level (cautious by default: targets met in about 9 of 10 cases), morning
buffer, evening target, bridging a poor next day, strategies
(self-consumption, keep the battery as full as possible, target by a time),
optional grid charging (off by default) and a reason for every interval
("Why?"). The **Plan** view shows it.
- **Battery control**: through adapters (generic Home Assistant entities,
Kostal Plenticore through the core integration, Kostal Plenticore G3 through
Modbus) SunCore sets **limits only**, never power set-points, behind the
safety layer with read-back, release to the inverter's own control, respect
for manual changes and the effective reserve. The battery starts in **shadow
mode**; the Kostal Modbus adapter is capped at assisted until the inverter's
fallback timer has been measured.
- **Live energy flow** between solar, grid, battery and house.
- **Surplus control** every 5 seconds: free surplus by priority, with hysteresis,
minimum run and pause times and smoothing against cloud flicker, and no
grid import caused by SunCore. Climate units get their set-point shifted
inside your comfort band; switches, adjustable loads and stepped water
heaters (simulator only) follow the surplus.
- **Shadow mode is the default**, for the whole system and for every new
device: SunCore only logs what it *would have* done. A device is controlled
only after you set the overall mode **and** the device to automatic (or to
assisted, where you confirm every action).
heaters (simulator only) follow the surplus. The plan sets bands (battery
first until the morning buffer) that the controller follows.
- **Shadow mode is the default**, for the whole system, for every new device
and for the battery: SunCore only logs what it *would have* done. A device
or the battery is controlled only after you set the overall mode **and** its
own mode to automatic (or to assisted, where you confirm every action).
- **Safety layer**: invariants, manual changes are respected, watchdogs,
hand-back of devices on shutdown, crash recovery and connection loss, and a
persisted **Emergency stop** in the header of every view.
- **"Why?" and decision log**: every decision has its reasons in plain
language.
hand-back of devices and the battery on shutdown, crash recovery and
connection loss, and a persisted **Emergency stop** in the header of every
view.
- **"Why?" and decision log**: every decision and every plan interval has its
reasons in plain language.
- Values that are outdated, unavailable or invalid are marked as such
instead of being guessed.

Expand Down Expand Up @@ -84,6 +115,20 @@ for you if not. On a sunny day with a charging battery, PV must be positive
and the battery arrow must point into the battery. Power sensors in W and kW
are understood; other units are rejected rather than guessed.

## Planning and battery control

Forecasts, tariffs, how the plan is made, risk levels and buffers, grid
charging, the battery modes, the adapters (including how to enable the Kostal
`Battery:MinSoc` entity and how to measure the Kostal Modbus fallback timer),
a walk-through for your first battery in assisted mode and the known
limitations are in
[Planning and battery control](https://github.com/pxljake/suncore/blob/main/docs/user/en/planning-and-battery.md)
([Deutsch](https://github.com/pxljake/suncore/blob/main/docs/user/de/planning-and-battery.md)).
Short version: keep everything in shadow mode first, read the **Plan** view for
a day or two, then switch the battery to **assisted** and confirm the first
proposals yourself. Planner and battery control have never run against real
hardware yet; the guide lists what is unverified.

## Surplus control

How the controller decides, the three operating modes, what happens when you
Expand Down Expand Up @@ -122,9 +167,13 @@ Some timing and budget settings of the price service and the planner are not app

With `demo_mode` switched on, SunCore does not read your entities. A
simulated house (a sunny summer day) feeds the panel, a banner says "Demo
mode", and nothing from your installation is used or modified. Use it to
look around, to take screenshots or to report a UI problem. Switch it off
again and restart to see your own data.
mode", and nothing from your installation is used or modified. The demo
includes simulated prices, solar forecasts and a plan. Use it to look around,
to take screenshots or to report a UI problem. Switch it off again and restart
to see your own data. Experts can also set `SUNCORE_DEMO_START_TIME` (time of
day the demo starts, default `10:00`) and `SUNCORE_DEMO_BATTERY_CONTROL=1`
(gives the simulated house a controllable inverter, so the battery card can be
tried; off by default).

## Troubleshooting

Expand All @@ -144,6 +193,9 @@ again and restart to see your own data.
connection to SunCore; it retries automatically.
- **"Access denied. Open SunCore from Home Assistant."**: use the sidebar
entry; direct access to the app's port is blocked on purpose.
- **No plan, a rule-based plan, a stale plan, a spot price without a formula**:
see the troubleshooting section of
[Planning and battery control](https://github.com/pxljake/suncore/blob/main/docs/user/en/planning-and-battery.md#9-troubleshooting).
- **Logs**: the app's **Log** tab. Set `log_level` to `debug` for more
detail and attach the log when you report a problem. Tokens are redacted.
- **Health**: the app serves `/health` internally; Home Assistant uses it
Expand All @@ -153,16 +205,23 @@ again and restart to see your own data.

## What is not there yet

No forecasts, planner, history charts or tariff prices in use (they are
only stored), no battery or inverter control, no charge point (wallbox)
Nothing of the planner and the battery control has run on real hardware yet.
Kostal Plenticore cannot be told to charge from the grid (the plan only shows
it), and a Kostal Modbus battery stays capped at assisted mode until you have
measured the inverter's fallback timer. There are no history charts, what-if
analysis or backtesting (the plan view is minimal), no machine-learning load
model, no built-in internet fallbacks for solar forecasts and prices, no thermal
models for air conditioners and water heaters in the plan, no export limiting
through the inverter, no charge point (wallbox), heat pump or shiftable program
control, and no Home Assistant entities (MQTT discovery follows in a later
phase; the Mosquitto app is not needed yet). See the
[roadmap](https://github.com/pxljake/suncore/blob/main/docs/roadmap.md).

## Privacy

SunCore runs locally. It needs no account, sends no telemetry and makes no
cloud requests of its own in this version. Your configuration stays in the app's
cloud requests of its own: forecasts and prices come from the integrations you
already run in Home Assistant. Your configuration stays in the app's
`/data` folder.

## Support
Expand Down
Loading
Loading