# butterfly-rack-homeassistant

Home Assistant configuration for the **Butterfly EDFA Rack** (the 1550 nm MOPA: Koheron CTL200 seed + Agiltron M511 EYDFA booster, bridged to MQTT by an ESP32). The firmware and bill of materials live in the separate `koheron-esp32-bridge` repo; this repo is only the HA side.

Almost everything is auto-discovered over MQTT: the firmware publishes `homeassistant/.../config` topics, so the rack's sensors, switches and numbers appear by themselves under one device, `butterfly_edfa_rack`. These files add only what discovery cannot: the derived mW power sensors, the emergency-shutdown script, and the dashboard.

## Files

| File | Where it goes on the HA host | Purpose |
|------|------------------------------|---------|
| `configuration.butterfly.yaml` | merge into `/config/configuration.yaml` | mW template sensors (dBm→mW for the EDFA input, pre-amp and output PDs) + the `butterfly-rack` YAML-dashboard registration |
| `scripts.butterfly.yaml` | merge into `/config/scripts.yaml` | `butterfly_edfa_shutdown` emergency-off script |
| `ui-lovelace-butterfly.yaml` | copy whole to `/config/ui-lovelace-butterfly.yaml` | the dashboard itself |
| `deploy.sh` | run from this repo | push the dashboard to the host, validate config, restart HA |

`configuration.butterfly.yaml` and `scripts.butterfly.yaml` hold top-level keys to merge into the matching HA files; they are not standalone configs. `ui-lovelace-butterfly.yaml` is copied whole.

## The HA host

HA runs in Docker on `lab-desktop.local` (broker host `192.168.0.102`). The compose file bind-mounts `~/HA/homeassistant/` on the host as the container's `/config`, and the container is named `homeassistant`. The MQTT broker is anonymous, so this config needs no secrets; `secrets.yaml` on the host is unrelated and is git-ignored here.

Reach it with `ssh lab@lab-desktop.local`. The web UI is `http://lab-desktop.local:8123`; the dashboard shows in the sidebar as **Butterfly Rack** at `/butterfly-rack`.

## Deploy

```bash
./deploy.sh            # scp the dashboard, check_config, restart HA
./deploy.sh --dash-only  # just the dashboard (no restart; browser refresh picks it up)
```

The dashboard reloads on a browser refresh. Changes to `configuration.yaml` or `scripts.yaml` need the restart. Merge the two snippet files into their targets on the host by hand the first time (or whenever their keys change); `deploy.sh` does not merge them for you, so it does not clobber unrelated config.

## Notes

- The `*_mw` sensors derive from the internal-PD dBm telemetry, which reads ~0.5 dB optimistic. Indicative, not calibrated.
- The seed temperature setpoint is the CTL200 thermistor resistance (`rtset`, in ohms); the °C readout is a firmware-side NTC β-model. See the firmware repo README.
- Safety: Class 4, >1 W, invisible 1550 nm. The dashboard's PUMP OFF / SEED OFF / SHUTDOWN controls and the shutdown script drop the pump before the seed; they are operational conveniences, not hardware interlocks.