# 2026-04-26 — MQTT entity cleanup

Pruned the published MQTT/HA entity set after noticing two issues:
**HA frontend rendering cell voltages as integers** (e.g. `3 V` instead of
`3.285 V`) and **208 entities per pack** flooding the HA Devices UI with
mostly-redundant `register_NN` debug data.

## What changed

1. **Per-field display precision.** Discovery configs now include
   `suggested_display_precision`. HA frontend renders each field with the
   appropriate decimal count.

   | Field                                | Precision | Example  |
   |--------------------------------------|-----------|----------|
   | `cell_NN_voltage`, `cell_voltage_min/max` | 3    | `3.285 V` |
   | `pack_voltage`, `pack_current`, `max_current_limit` | 2 | `52.56 V` |
   | `capacity_ah`, `remaining_ah`        | 1         | `100.0 Ah`|
   | `soc`, `soh`, `cycle_count`, `temperature_*`, `cell_*` (delta/index) | 0 | `100 %` |

2. **`expose_raw_registers: false`** new config option (default off).
   Gates the `register_NN` raw-Modbus-register dump that was useful during
   register-map reverse-engineering but is pure noise in production. Set
   `expose_raw_registers: true` in `~/.config/eg4-battery/eg4-battery.yaml`
   and restart the daemon to re-enable for diagnostics.

3. **Dropped three superseded named fields:**
   - `bms_version_hi` / `bms_version_lo` — u16 dumps of regs 41-42, made
     redundant by `firmware_version` (decoded ASCII string from regs 117-119)
   - `uptime_ds` — bare counter, increments every second; no operational
     value, only useful for raw debugging

4. **`tmp/eg4-purge-orphans` new tool.** Publishes empty retained payloads
   to the deprecated discovery-config topics so HA forgets the orphaned
   entities the broker still has cached. Idempotent; works against both
   paho-mqtt 1.x and 2.x.

   ```bash
   tmp/eg4-purge-orphans <broker_host> <user> <password>
   ```

## Net effect

| Metric                            | Before | After | Delta  |
|-----------------------------------|--------|-------|--------|
| Published state topics per pack   | 208    | 69    | −67 %  |
| Published state topics across stack (3 packs) | 624    | 207   | −67 %  |
| Orphan retained discovery configs purged from broker | — | 417 | one-time |
| Cell voltage display in HA frontend | `3 V`  | `3.285 V` | precision restored |

## Files touched

```
M  bin/eg4-battery
A  tmp/eg4-purge-orphans
```

## How to verify

```bash
# Discovery configs now include precision hint
mosquitto_sub -h <broker> -u mqtt -P <pass> \
    -t 'homeassistant/sensor/lifepower4_1_cell_01_voltage/config' -W 5 -v
# Expect: ..., "suggested_display_precision": 3, ...

# State values still flowing at full source resolution
mosquitto_sub -h <broker> -u mqtt -P <pass> \
    -t 'homeassistant/sensor/lifepower4_1_cell_01_voltage/state' -W 5 -v
# Expect: 3.282 (or similar — 3-decimal mV-derived value)

# Confirm no register_NN, bms_version_*, or uptime_ds left
mosquitto_sub -h <broker> -u mqtt -P <pass> \
    -t 'homeassistant/sensor/+/state' -W 12 -v \
  | grep -E 'lifepower4_._(register|bms_version|uptime)'
# Expect: zero matches
```

## Rollback

```bash
git checkout HEAD~1 -- bin/eg4-battery
sudo install -m 755 bin/eg4-battery /usr/local/bin/eg4-battery
sudo systemctl restart eg4-battery.service
# Old register_NN/bms_version_*/uptime_ds will republish on next cycle.
# (To restore them in HA after rollback, the daemon's own publish_pack will
# recreate the discovery configs naturally — no purge undo needed.)
```