58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# Peak Power Manager
|
|
|
|
Keeps your electricity capacity tariff in check by watching live power draw
|
|
(from InfluxDB) and shedding/restoring large consumers (via Home Assistant)
|
|
whenever the current 15-minute billing block is projected to exceed a target.
|
|
|
|
## How it works
|
|
|
|
Belgian-style capacity tariffs bill on the highest 15-minute average power of
|
|
the month. Every `CONTROL_LOOP_INTERVAL_MS` (default 10s), the app:
|
|
|
|
1. Reads recent power samples for the current quarter-hour block from InfluxDB.
|
|
2. Projects what that block's final average will be if current draw continues.
|
|
3. If the projection exceeds `TARGET_KW`, it sheds the lowest-priority
|
|
configured device (turns a switch off, or lowers a number set-point to its
|
|
floor) via Home Assistant.
|
|
4. Once the projection is comfortably back under target, it restores the
|
|
highest-priority shed device.
|
|
|
|
A minimum dwell time per device (configurable) prevents rapid on/off cycling.
|
|
Devices with "manual override" enabled are left alone by the control loop.
|
|
|
|
## Setup
|
|
|
|
1. Copy `.env.example` to `.env` and fill in your InfluxDB and Home Assistant
|
|
connection details, the measurement/field that holds live power, and your
|
|
target kW.
|
|
2. `docker compose up --build`
|
|
3. Open `http://localhost:3000`, go to the **Devices** tab, and add your EV
|
|
charger, heat pump, and any other large consumers with their Home
|
|
Assistant entity IDs, control type (switch or number), and priority
|
|
(lower priority number = shed first).
|
|
|
|
## Local development
|
|
|
|
```
|
|
npm install
|
|
npm run dev:backend # Fastify API on :3000
|
|
npm run dev:frontend # Vite dev server on :5173, proxies /api to :3000
|
|
npm test # backend unit tests (quarter-hour projection, control decisions)
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- `backend/src/influx` — queries live power samples from InfluxDB (Flux).
|
|
- `backend/src/control/quarterHour.ts` — pure logic computing the running and
|
|
projected average power for the current 15-minute block.
|
|
- `backend/src/control/loop.ts` — pure decision logic: which device to shed
|
|
or restore given the projection and device states.
|
|
- `backend/src/control/runner.ts` — orchestrates the above against real
|
|
InfluxDB/Home Assistant/SQLite on each tick.
|
|
- `backend/src/homeassistant` — Home Assistant REST client and device
|
|
shed/restore abstraction.
|
|
- `backend/src/db` — SQLite config store (devices, target, action log, block
|
|
history).
|
|
- `frontend/` — React dashboard: live status, device list, 30-day peak
|
|
history chart, recent actions log, and a Devices config page.
|