# Vogelalbum in Home Assistant

Zwei Teile:

```
GET /api/zustand/    in der Web-App — alles in einer Antwort
bruecke.py           holt das und spiegelt es nach MQTT
```

Home Assistant braucht **kein Integrationspaket**: Die Brücke meldet die
Entitäten über MQTT-Discovery an, HA legt sie von selbst an.

## Voraussetzung: ein Broker

⚠️ **Ohne MQTT-Broker geht nichts.** In Home Assistant:

```
Einstellungen → Add-ons → Add-on Store → "Mosquitto broker"
→ Installieren → Starten
```

Dann einen Benutzer anlegen (Mosquitto nimmt HA-Benutzer als
Zugangsdaten, es hat kein eigenes Benutzersystem):

```
Einstellungen → Personen → Benutzer → Hinzufügen
⚠ "Kann sich anmelden" an, Administrator AUS
```

🔑 **Dass es einen Broker braucht, ist der schwache Punkt dieses Weges.**
Wer Vogelalbum verteilt,
muss damit rechnen, dass viele Nutzer ebenfalls keinen haben. Deshalb ist
MQTT der Weg zum Ausprobieren, nicht der endgültige; eine Integration über
HACS käme ohne aus. Siehe Issue #4.

## Starten

```sh
VOGELALBUM_URL=http://sammlung.local:8000 \
VOGELALBUM_LESE_TOKEN=… \
MQTT_HOST=… MQTT_BENUTZER=vogelalbum MQTT_PASSWORT=… \
python homeassistant/bruecke.py
```

| Variable | Vorgabe | wofür |
|---|---|---|
| `VOGELALBUM_URL` | `http://127.0.0.1:8130` | wo die Web-App steht |
| `VOGELALBUM_LESE_TOKEN` | — | **Pflicht.** Leer heißt: Tür zu |
| `VOGELALBUM_INSTANZ` | `garten` | steckt in jeder Kennung |
| `VOGELALBUM_TAKT` | `10` | Sekunden zwischen zwei Abfragen |
| `MQTT_HOST` / `MQTT_PORT` | `127.0.0.1` / `1883` | der Broker |
| `MQTT_BENUTZER` / `MQTT_PASSWORT` | leer | falls der Broker sie verlangt |
| `VOGELALBUM_LIVE_<KENNUNG>` | leer | Livebild direkt vom Verteiler holen |

## Livebild, wenn die Web-App außer Haus steht

🔑 **Ein Riegel gegen die Öffentlichkeit darf nicht das eigene Haus
aussperren.** Steht die Web-App im Netz, gehört dort
`VOGELALBUM_LIVE_ERLAUBT=0` hin — ein Bild aus dem eigenen Garten ist nichts
für Fremde. Dann liefert `/api/zustand/` aber `bild_url: null`, und die
Brücke bekommt ebenfalls nichts, obwohl sie **im Heimnetz** läuft und den
Live-Verteiler des Detectors direkt erreicht.

Deshalb darf die Brücke die Adresse selbst kennen, je Kamera:

```sh
VOGELALBUM_LIVE_VOGELHAUS=http://erkennung.local:8131/bild.jpg
VOGELALBUM_LIVE_TRAENKE=http://erkennung.local:8132/bild.jpg
```

Der Name entsteht aus der **Kennung** der Kamera in Großbuchstaben; alles,
was kein Buchstabe und keine Ziffer ist, wird zum Unterstrich
(`vogelhaus-2` → `VOGELALBUM_LIVE_VOGELHAUS_2`). Eine Adresse auf `/live`
wird selbst auf `/bild.jpg` umgeschrieben — `/live` ist der endlose
MJPEG-Strom, den darf die Brücke nicht lesen. Ohne Eintrag bleibt alles wie
bisher: Die Adresse kommt aus der Schnittstelle.

⚠️ **So sieht dieser Ausfall aus, wenn man ihn nicht kennt:** In Home
Assistant bleibt das zuletzt empfangene Bild stehen und sieht aus wie ein
Livebild. Es gibt keine Fehlermeldung — weder in der Brücke noch in HA.
Eine Anlage lief so acht Tage lang, ohne dass es jemandem auffiel.

## Was rauskommt

26 Entitäten bei zwei Kameras, **11 davon standardmäßig abgeschaltet**.
Die Linie ist *„möglichst viel anbieten, entscheiden soll der Nutzer"* — `enabled_by_default: false` ist genau dafür da.

**Sammlung:** letzte Art · Arten gesammelt · Sichtungen heute und gesamt ·
Stufe · Rang · Punkte · Abzeichen · letztes Abzeichen · letzte Sichtung
(mit allen Angaben als Attribute)

**Je Kamera:** erreichbar · still seit · letzte Sichtung · Signalstärke ·
Chiptemperatur · Bildrate · Laufzeit · Livebild

## Drei Dinge, die man wissen muss

⚠️ **Die Kennungen sind der Vertrag.** Anzeigenamen darf jeder ändern, die
`unique_id` nicht. Wer sie nachträglich ändert, bekommt in HA eine NEUE
Entität, während die alte als Leiche im Register bleibt — mitsamt den
Automationen, die daran hängen.

⚠️ **Das Livebild kommt vom DETECTOR, nie von der Kamera.** Die Kamera
erlaubt genau einen Zuschauer; klinkt sich HA dort ein, verliert der
Detector sein Bild und die Arterkennung steht. Das Symptom wäre *„seit ich
das Dashboard gebaut habe, erkennt er nichts mehr"* — mit der Ursache
woanders.

⚠️ **Signalstärke und Temperatur holt die Brücke direkt vom Gerät**, nicht
über die Web-App. Sie kennt nur das Gerät selbst; über die Datenbank zu
gehen hieße, sie erst zu speichern, und dann wären sie alt.

Der Port dafür wird **probiert und gemerkt**, nicht geraten: erst
Streamport + 1 (der ESP32 hat einen eigenen Diagnose-Port, weil sein
Webserver einen einzigen Arbeiter hat), dann der Streamport (der Pi hat das
Problem nicht).

📌 **Erledigt:** Der Pi am Futterhaus antwortete am 25.09.2026 noch mit 404
auf `/status` — dort lief ältere Software ohne den Endpunkt. Seit dem
Rollout am 09.10.2026 liefert er ihn; am 11.10.2026 nachgemessen
(4,63 B/s, RSSI −51 dBm, 39 °C). Signalstärke und Temperatur stehen damit
für **beide** Kameras in Home Assistant.