initialize

eg4battery/homeassistant/README.md

@@ -0,0 +1,58 @@
+# HA-side configuration for the eg4-battery daemon
+
+Reference configs that go into your Home Assistant instance — they aren't
+installed by `install.sh` (HA typically lives on a different host / in an
+HA OS appliance), but they're tracked here so the full stack is reproducible.
+
+## What's in here
+
+| File                      | Where it goes in HA                                 |
+|---------------------------|-----------------------------------------------------|
+| `recorder.yaml`           | `configuration.yaml` → under a `recorder:` key, or merge into existing |
+| `template_sensors.yaml`   | `configuration.yaml` → under a top-level `template:` list, or include via `!include` |
+| `lovelace_overview.yaml`  | Raw Lovelace card config — paste into a new dashboard view |
+
+All of it assumes pack names `lifepower4_1`, `lifepower4_2`, `lifepower4_3`
+matching the daemon's default config. If you renamed your packs, do a
+`sed -i 's/lifepower4_/your_prefix_/' *.yaml` first.
+
+## Recommended retention tiers
+
+Full rationale in [`../NOTES.md`](../NOTES.md) and the architecture thread,
+but the short version:
+
+- **Tier 1 — keep forever**: `pack_voltage`, `pack_current`, `soc`, `soh`,
+  `cycle_count`, `cell_voltage_min/max/delta_mv`, `capacity_ah`.
+- **Tier 2 — keep short**: all 14 `warning_*` + 14 `protection_*`,
+  `error_code`, `remaining_ah`, `heater`, the derived `temperature_max`
+  and `pack_power`.
+- **Tier 3 — exclude** (the `recorder.yaml` here does this): all 47 raw
+  `register_NN` entities, the 16 individual `cell_NN_voltage` series,
+  static metadata (`bms_version_*`, `battery_mode`, `cell_count`, etc.),
+  and the `uptime_ds` counter that increments every second.
+
+## Enabling in HA
+
+Easiest path:
+
+```yaml
+# configuration.yaml
+
+# merge our recorder exclusions with your existing recorder config
+recorder: !include eg4_battery/recorder.yaml
+
+# include the template sensors (creates a new `template:` list block)
+template: !include eg4_battery/template_sensors.yaml
+```
+
+And drop the two YAMLs into `~/homeassistant/eg4_battery/`.
+
+If you already have `recorder:` or `template:` keys elsewhere, merge by
+hand — HA doesn't allow two definitions of the same top-level key.
+
+## Energy dashboard wiring (optional)
+
+Once the derived `pack_power` template sensors exist, add them to the
+Energy dashboard via **Settings → Dashboards → Energy → Home battery
+storage** — each pack's `pack_power` integrates to `pack_energy_in_kwh`
+and `pack_energy_out_kwh` automatically, with per-pack bars.