lvx, eg4, and evse

openevse/README.md

@@ -0,0 +1,101 @@
+# 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).