# OpenEVSE → Home Assistant (MQTT discovery)

The OpenEVSE WiFi firmware natively publishes raw values to `openevse/<key>`
on whichever MQTT broker you've configured it against, but it does **not**
publish HA discovery configs. Without those, HA can't see any of it unless
you hand-write `mqtt: sensor:` blocks in `configuration.yaml`.

This package fixes that with a single one-shot tool that publishes retained
`homeassistant/.../config` payloads pointing at the OpenEVSE state topics
the firmware already provides. No daemon, no broker proxy — HA subscribes
to OpenEVSE's own topics directly once discovery is in place.

## Status: live

23 entities exposed for the charger at `10.0.0.249` (device id `a048`):

```
sensor.openevse_power            W      live charging power
sensor.openevse_voltage          V
sensor.openevse_amp              A      (firmware reports mA; converted in HA)
sensor.openevse_pilot            A      pilot current the EVSE is signalling
sensor.openevse_max_current      A      hardware/soft-limit ceiling
sensor.openevse_session_energy   Wh
sensor.openevse_total_energy     Wh     total_increasing → Energy dashboard
sensor.openevse_total_day        kWh    total_increasing
sensor.openevse_total_week       kWh
sensor.openevse_total_month      kWh
sensor.openevse_total_year       kWh
sensor.openevse_session_elapsed  s
sensor.openevse_uptime           s      diagnostic
sensor.openevse_temp             °C     (firmware reports tenths-°C; converted)
sensor.openevse_temp_max         °C
sensor.openevse_status           text   "active" / "disabled" / "sleeping" / ...
sensor.openevse_state             #     numeric state code
sensor.openevse_srssi            dBm    diagnostic — Wi-Fi signal
sensor.openevse_freeram          B      diagnostic
sensor.openevse_total_switches   #      diagnostic — total_increasing
binary_sensor.openevse_vehicle           plug — car connected
binary_sensor.openevse_evse_connected    connectivity (diagnostic)
binary_sensor.openevse_manual_override
```

Availability is wired to OpenEVSE's retained announce topic
(`openevse/announce/<id>`), which the firmware uses as its LWT — entities
flip to "Unavailable" if the EVSE drops off the broker.

## How it works

1. `bin/openevse-publish-discovery` connects to the broker, reads the
   retained `openevse/announce/<id>` payload to learn the device id and
   metadata (name, http URL).
2. Builds 23 `homeassistant/{sensor,binary_sensor}/openevse_<key>/config`
   payloads — one per entity. Each declares `state_topic` pointing at the
   matching `openevse/<key>` topic, plus `device_class`, `unit_of_measurement`,
   `state_class`, `value_template` (where unit conversion is needed),
   `suggested_display_precision`, and a shared `availability` block.
3. Publishes them with QoS 0, `retain=true`. HA picks them up immediately
   via its existing `homeassistant/#` subscription.

The two unit conversions baked into discovery payloads (so HA never sees
raw units):

| Source topic           | Raw value      | HA value |
|------------------------|----------------|----------|
| `openevse/amp`         | milliamps      | A (`/ 1000`) |
| `openevse/temp[_max]`  | tenths-°C      | °C (`/ 10`) |

## What's in the box

```
openevse/
├── README.md                          ← you are here
├── Install.md                         ← run order, verification, rollback
└── bin/
    └── openevse-publish-discovery     ← one-shot (PEP-723 uv inline-script)
```

## Quick start

Broker creds default-load from `~/.config/powermon/powermon.yaml`
(`mqttbroker.{name,port,username,password}`), so on this host:

```bash
~/solar/openevse/bin/openevse-publish-discovery
```

That's it. To remove every entity later:

```bash
~/solar/openevse/bin/openevse-publish-discovery --purge
```

See [`Install.md`](./Install.md) for verification steps, dry-run preview,
and CLI overrides if your broker isn't the one in `powermon.yaml`.

## Related packages

- [`../LVX6048/`](../LVX6048/) — same broker, same discovery pattern (via
  patched powermon).
- [`../eg4battery/`](../eg4battery/) — same broker, same discovery pattern
  (via `eg4-battery` daemon).