# Home Assistant MQTT

`com.glidevizion.home-assistant-mqtt` publishes durable NVR detection cards as
Home Assistant MQTT Event messages. It consumes the same scoped evidence index
as Detection Webhooks; it does not receive RTSP URLs, camera credentials,
recordings, or raw SQLite access.

Grant one camera under **Camera access**, select that camera in settings, and
enter the MQTT broker address used by Home Assistant. The extension publishes:

- retained Event discovery at
  `homeassistant/event/glidevizion_nvr_<camera>_detections/config`;
- retained availability at `<topic_prefix>/status`;
- non-retained occurrences at
  `<topic_prefix>/cameras/<camera>/detections`; and
- the latest acknowledged detection at
  `<topic_prefix>/cameras/<camera>/latest_detection` for general MQTT consumers.

Each occurrence contains Home Assistant's required `event_type` plus the stable
`delivery_id`, camera/detection IDs, capture and playback times, label,
confidence, and source. Occurrences are never retained, so reconnecting Home
Assistant cannot turn an old person or vehicle into a new alert.

## Delivery contract

Every message that can advance the durable `(time_ms,id)` cursor is published
at MQTT QoS 1. The worker waits for the matching broker `PUBACK` before saving
progress. As required by QoS 1, an interrupted acknowledgement can produce a
duplicate; automations that perform non-idempotent work should use
`delivery_id` as their deduplication key.

Discovery and availability are retained so Home Assistant can recreate the
entity after restarting. The broker password is a write-only extension setting.
A broker outage marks only this extension unhealthy and retries; recording,
detection persistence, and playback remain independent.

## Local development

```bash
go build -o home-assistant-mqtt ./plugins/home-assistant-mqtt/cmd/home-assistant-mqtt

NVR_BASE_URL=http://127.0.0.1:8085 \
NVR_API_TOKEN=dev-token \
NVR_PLUGIN_STATE_DIR=/tmp/nvr-home-assistant-mqtt \
MQTT_ADDR=homeassistant.local:1883 \
MQTT_USERNAME=nvr \
MQTT_PASSWORD=secret \
CAMERA_ID=cam01 \
MINIMUM_CONFIDENCE=0.5 \
LABELS=person,vehicle \
./home-assistant-mqtt
```
