# HA-side configuration for the LVX6048 stack

Reference configs that go into your Home Assistant instance — they aren't
installed by `install.sh` (HA typically lives on a different host or in an
HA OS appliance), but they're tracked here so the full stack is reproducible.

Mirrors the `eg4battery/homeassistant/` pattern.

## What's in here

| File                       | Where it goes in HA                                          |
|----------------------------|--------------------------------------------------------------|
| `mqtt_controls.yaml`       | `configuration.yaml` → `mqtt: !include lvx6048/mqtt_controls.yaml` (or merge by hand) |
| `template_sensors.yaml`    | `configuration.yaml` → `template: !include lvx6048/template_sensors.yaml` |
| `lovelace_controls.yaml`   | Raw Lovelace card config — paste into a new dashboard view   |

The auto-discovery sensors (battery V, fault code, mode, MPPT power, …)
arrive automatically from powermon — no HA-side config required for those.
This folder only adds the pieces HA can't infer:

- **Control entities** — selects + numbers that publish to
  `solar/control/lvx6048/<action>` so users can change settings from a
  dashboard without touching the LCD.
- **Stack-total derived sensors** — the PI18 GS command only exposes per-unit
  numbers, so a 240 V load split across two LVX6048s shows as ~half on each.
  `template_sensors.yaml` synthesizes household-level totals (apparent_power,
  active_power, mppt1_input_power).
- **A dashboard view** that wraps those controls with the existing
  telemetry into one screen.

## Architecture (control path)

```
HA dashboard (mqtt select / number)
    │
    │  payload e.g. "solar_battery_utility"
    ▼
solar/control/lvx6048/<action>
    │
    ▼
lvx-control.service (on the Pi)
    │   validates against allow-list,
    │   encodes to PI18 command (e.g. "POP01"),
    │   mirrors to BOTH inverters
    ▼
powermon/lvx6048_{1,2}/addcommand
    │
    ▼
powermon executes via PI18 setter, publishes
    "Succeeded" / "Failed" to powermon/lvx6048_{1,2}/result
```

## Enabling in HA

1. Drop both YAMLs into `~/homeassistant/lvx6048/` on your HA host.
2. Add to `configuration.yaml`:

   ```yaml
   mqtt: !include lvx6048/mqtt_controls.yaml
   ```

   (or, if you already have an `mqtt:` block, merge the `select:` and
   `number:` lists into it.)

3. Restart HA. The 3× selects and 1× number entity should appear under
   the "Home Assistant" device.

4. Add the dashboard:
   - **Settings → Dashboards → + Add Dashboard → New dashboard from scratch**
   - Open the new dashboard → ⋮ → **Edit dashboard → Raw configuration editor**
   - Paste the contents of `lovelace_controls.yaml`.

## Available controls

| Entity                                          | Effect                                                             |
|-------------------------------------------------|--------------------------------------------------------------------|
| `select.lvx6048_output_priority`                | POP — switch between SUB / SBU output source priority              |
| `select.lvx6048_charger_priority`               | PCP — solar-first / solar+utility / solar-only charging            |
| `select.lvx6048_solar_power_priority`           | PSP — battery+load+utility+AC vs load+battery+utility              |
| `number.lvx6048_max_charging_current`           | MCHGC — combined solar+AC charge cap, 10–80 A in 10 A steps        |
| `select.lvx6048_max_utility_charging_current`   | MUCHGC — grid-only charge cap, 2/10/20/…/80 A                       |

> **Note:** `MCHGC` / `MUCHGC` setters are sometimes rejected by the
> firmware while the inverter is actively charging (mode 06). Result topics
> show `"Failed"` in that case. If a charge-current change must apply
> immediately, either retry while idle (mode 01) or use
> `lvx-flash/flash.py apply` (which stops powermon for exclusive USB access).

Risky settings — battery thresholds (PSDV / MCHGV / BUCD), battery type
(PBT), output mode (POPM), factory reset (PF) — are intentionally **not**
exposed via HA. Use `lvx-flash/flash.py apply` with an explicit profile.

## Verifying

After HA reload, watch the result topics:

```bash
mosquitto_sub -h <broker> -u mqtt -P <pass> -v \
    -t 'powermon/lvx6048_1/result' \
    -t 'powermon/lvx6048_2/result'
```

…then flip a select in the dashboard. Both inverters should publish
`"Succeeded"` within ~1 s.

## Energy / SoC dashboard wiring (optional)

Once both inverters' `ac_output_active_power` and the EG4 daemon's
`pack_power` derived sensors are in place, the Energy dashboard can show
solar in / battery in/out / load — wire under
**Settings → Dashboards → Energy → Solar panels / Home battery storage**.