# solar — home power monitoring & control

Monitoring, control, and calibration tooling for an off-grid-leaning solar + storage
install, all published to one Home Assistant MQTT broker (`10.0.0.41`).

## The system

```
6× EG4 LifePower4 v2 packs ──RS485 (1 FTDI each)──┐
2× MPP Solar LVX6048 inverters ──USB-HID/PI18──────┤  monitoring Pi  ──MQTT──► Home Assistant
1× OpenEVSE charger (10.0.0.249) ───────────────────┘  (daemons)            10.0.0.41:1883
```

- **14.4 kW PV** (36×400 W, 4×9s strings, 9s2p per inverter, 45° south) → 2 paralleled
  LVX6048 inverters → **~30 kWh** EG4 LifePower4 bank (6× 100 Ah, 16S).

## Subsystems

| Dir | What | Entities |
|-----|------|----------|
| [`LVX6048/`](./LVX6048/) | 2 inverters via powermon (PI18/USB) + `lvx-flash` settings tool + `lvx-control` HA→PI18 bridge | `lvx6048_{1,2}_*` |
| [`eg4battery/`](./eg4battery/) | 6 battery packs via RS485/Modbus daemon | `lifepower4_{1..6}_*` |
| [`openevse/`](./openevse/) | EV charger HA-discovery publisher | `openevse_*` |
| [`battery/`](./battery/) | legacy V1 protocol decoder (historical) | — |

Each subsystem has its own `README.md` / `Install.md` / `NOTES.md`.

## Agent skills

Agent-runnable skills for monitoring, troubleshooting, and calibration live in
[`.claude/skills/`](./.claude/skills/) — start with
[`.claude/skills/REFERENCE.md`](./.claude/skills/REFERENCE.md) (system map, real HA
entity ids, known firmware quirks, action policy):

- `solar-health-check` — whole-system sweep + cross-checks + R/Y/G verdict
- `troubleshoot-inverter` / `troubleshoot-battery` — subsystem deep-dives
- `power-usage` — load vs PV vs grid vs battery balance
- `calibration-charge` — re-anchor drifted EG4 SoC via a full charge
- helpers: `lib/solar-snapshot` (live MQTT), `lib/ha-history` (HA recorder lookback),
  `lib/grid-cal-monitor` (supervised grid calibration with auto-revert)

## Notable findings (see per-subsystem docs + the skills' REFERENCE)

- **EG4 SoC drifts** (counters never re-anchor without a full charge) → fixed by the
  `calibration-charge` skill.
- **"Low" PV is mostly geometry + curtailment, not a fault** — both strings are healthy
  (~16 A @ 300 V at clear-noon peak); the shortfall is 45° tilt, heat, trees, and the
  battery charge cap throttling midday harvest.
- **LVX6048 firmware quirks**: PI18 `POP` is single-digit (`POP1`, not `POP01`);
  MCHGC locked while charging; force a full grid charge via output-priority **SUB**, not
  the voltage thresholds; PIRI readback lags ~5 min (verify by behavior).