Energy Optimiser

Amber wholesale energy optimiser for a Sigenergy hybrid inverter with ~13 kW solar and a 40 kWh battery. Solves a stochastic MILP (PuLP + HiGHS) over 5-min slots across the priced Amber forecast horizon, applies the slot-0 decision to the inverter via Modbus, and verifies behaviour against a 10-second post-write watcher.

An external dead-man watchdog sidecar enforces a safe state if the main service stops ticking — the Sigenergy firmware has no Modbus communication watchdog of its own (verified against live hardware; see KNOWN-ISSUES #0d).

Co-optimises battery dispatch with a Shelly-relayed Haier HP330M1-U1 hot water heat pump in PV mode.

Requirements

• Python 3.12 (pinned via .python-version)
• uv for dependency management
• Docker + Docker Compose for deploy (watchdog sidecar depends on compose)

Quick start

uv sync                       # install the project + dev group
uv run pytest tests/ -q       # full test suite

Local smoke testing (before touching hardware)

cp config.example.toml config.toml         # fill in secrets
uv run eo-smoke -c config.toml --offline   # synthetic LP solve, no network

Hardware deploy sequence

Run each smoke phase against live hardware and confirm clean output before moving to the next:

uv run eo-smoke -c config.toml --offline       # zero risk
uv run eo-smoke -c config.toml --modbus-read   # read-only Modbus probe
uv run eo-smoke -c config.toml --api-probe     # 1 call per API (costs 1 Solcast quota)
uv run eo-smoke -c config.toml --dry-tick      # full tick, prints proposed writes, no actuations

Once all four are clean, bring up the stack:

docker compose up -d          # runs both the service and the watchdog sidecar

For boot-time autostart, install the systemd unit — see DEPLOY.md.

Replay (post-deploy, once snapshots are flowing)

uv run eo-replay \
    -s '/var/lib/energy-optimiser/snapshots/2026-*.ndjson.gz' \
    -c candidate-config.toml \
    -o results.ndjson -v

Compares a candidate LP configuration against historical snapshot ticks.

Entry points

• energy-optimiser — the service (tick loop + wake loops)
• eo-smoke — read-only pre-deploy smoke tests
• eo-replay — replay historical ticks against a candidate config
• eo-watchdog — dead-man sidecar; pins the inverter to an explicit safe state if the main service stops ticking

Documentation

• CLAUDE.md — development guide (architecture, conventions, testing)
• SPEC-ENERGY-01.md — authoritative spec (design decisions, register map, acceptance criteria)
• DEPLOY.md — first-deployment runbook
• KNOWN-ISSUES.md — open issues and resolution history