127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
# SillyHome Next 1.0.0 Operating Guide
|
|
|
|
Diese Version stabilisiert den produktiven Kern: schnelle Dashboard-Nutzung,
|
|
lokales Caching, klare Aktor-/Sensor-Kategorien und nachvollziehbare Freigabe
|
|
gelernter Aktionen.
|
|
|
|
Die detaillierte Abnahme steht in
|
|
[`V1_0_ACCEPTANCE.md`](V1_0_ACCEPTANCE.md). Dort sind erledigte, teilweise
|
|
erledigte und fuer v1.0.x offene Punkte getrennt dokumentiert.
|
|
|
|
## Grundprinzip
|
|
|
|
- Home Assistant bleibt die Quelle fuer aktuelle States und Services.
|
|
- SillyHome cached schwere Entity-/Discovery-Metadaten lokal als JSON.
|
|
- Die Startansicht liest nur lokale Store-/Cache-Daten.
|
|
- Vollstaendige Discovery, Vorschlaege und Detailanalysen laden blockweise nach.
|
|
- Es gibt keine externen Pings oder Cloud-Abfragen im Dashboard-Startpfad.
|
|
|
|
## Wichtige Endpunkte
|
|
|
|
- `GET /health`
|
|
Lokaler API-Status ohne externe Abfrage.
|
|
- `GET /health/websocket`
|
|
Status des Home-Assistant-WebSocket-Listeners.
|
|
- `GET /v1/actuators/dashboard`
|
|
Schnelle Dashboard-Startdaten aus Store und JSON-Cache.
|
|
- `GET /v1/actuators/summary`
|
|
Schlanke Liste beobachteter Aktoren ohne Lernmuster-Payload.
|
|
- `GET /v1/actuators/discovery`
|
|
Aktor-Auswahl aus gecachten oder frisch geladenen HA-Entities.
|
|
- `GET /v1/actuators/context-options?actuator_entity_id=...`
|
|
Sensor-/Kontextvorschlaege fuer einen konkreten Aktor.
|
|
- `POST /v1/actuators/{entity_id}/assignment`
|
|
Manuelle Sensor-/Kontextzuordnung speichern.
|
|
- `POST /v1/actuators/{entity_id}/activation`
|
|
Freigabe oder Stop des automatischen Schaltens.
|
|
|
|
## Cache
|
|
|
|
Der Entity-Cache liegt neben dem Aktor-Store als `ha_entity_cache.json`.
|
|
Er enthaelt HA-Entity-Metadaten wie Friendly Name, Bereich, Device und
|
|
Kategoriegrundlagen.
|
|
|
|
Der Cache wird geschrieben, wenn Discovery frische HA-Entities liest. Danach
|
|
koennen Dashboard und Summary ohne erneute HA-Vollabfrage Namen, Raeume und
|
|
Gruppen anzeigen.
|
|
|
|
## Dashboard-Nutzung
|
|
|
|
1. Startansicht oeffnen.
|
|
2. `System & Cache` zeigt API, WebSocket, Cache-Groesse und geladene
|
|
Discovery-Gruppen.
|
|
3. `Geraet zum Lernen auswaehlen` nutzt Suche, Typfilter und direkte
|
|
Entity-ID-Eingabe.
|
|
4. `Beobachtete Geraete` zeigt gelernte Aktoren nach Raum oder Typ gruppiert.
|
|
5. `Details` zeigt Lernfortschritt, Freigabe, Vorhersage, verwendete
|
|
Sensoren/Zustaende und Entscheidungsgruende.
|
|
|
|
## Kategorien
|
|
|
|
Aktoren:
|
|
|
|
- Licht, LED, Lampen
|
|
- Schalter, Steckdosen, Helper
|
|
- Lueftung, Ventilatoren, Befeuchter/Entfeuchter
|
|
- Heizungen/Klima
|
|
- Rolllaeden/Cover
|
|
- TV/Medien/Fernbedienungen
|
|
- Szenen, Buttons, Schloesser, Ventile
|
|
|
|
Sensoren und Kontext:
|
|
|
|
- Luftfeuchtigkeit und Feuchte
|
|
- Temperatur
|
|
- Wetter
|
|
- Helligkeit/Lux
|
|
- Bewegung, Praesenz, Anwesenheit
|
|
- Tuer/Fenster/Oeffnung
|
|
- Licht-/Schalter-/Steckdosenstatus
|
|
- Strom, Leistung, Energie, Einspeisung
|
|
- PV, Akku, Wechselrichter
|
|
- Helper und Szenen
|
|
|
|
## Qualitaetspruefung
|
|
|
|
Vor Release:
|
|
|
|
```bash
|
|
.venv/bin/pytest -q
|
|
.venv/bin/ruff check .
|
|
.venv/bin/mypy app backend tests
|
|
git diff --check
|
|
```
|
|
|
|
Live nach Installation:
|
|
|
|
```bash
|
|
wget -qO- http://58adbe1e-sillyhome-next:8000/health
|
|
wget -qO- http://58adbe1e-sillyhome-next:8000/health/websocket
|
|
wget -qO /tmp/summary.json http://58adbe1e-sillyhome-next:8000/v1/actuators/summary
|
|
wget -qO /tmp/dashboard.json http://58adbe1e-sillyhome-next:8000/v1/actuators/dashboard
|
|
```
|
|
|
|
Wenn der Add-on-Container aus dem Agent-Host nicht direkt routbar ist, gilt der
|
|
Home-Assistant-Supervisor als Verifikationsquelle:
|
|
|
|
- Add-on-Info pruefen: Version, `version_latest`, `update_available`, `state`,
|
|
`boot` und `watchdog`.
|
|
- Vor Updates eine Home-Assistant-Teil-Sicherung fuer **SillyHome Next**
|
|
erstellen.
|
|
- Nach einem Store-Reload und Update muss `version == version_latest`,
|
|
`update_available == false`, `state == started`, `boot == auto` und
|
|
`watchdog == true` gelten.
|
|
- Den HA-/Ingress-Tab nach jedem Update hart neu laden, weil Home Assistant
|
|
sonst alte HTML-/JavaScript-Ressourcen aus dem bestehenden Tab verwenden kann.
|
|
- Rollback erfolgt ueber die vorherige Add-on-Teil-Sicherung oder den letzten
|
|
Git-Tag; beide Referenzen im Release-/Abnahmeprotokoll notieren.
|
|
|
|
## Rollback
|
|
|
|
Der stabile Vor-1.0-Stand ist `v0.7.21`. Vor dem 1.0.0-Umbau wurde ein
|
|
Git-Bundle-Backup erstellt:
|
|
|
|
`/root/.openclaw/workspace/backups/sillyhome-next/`
|
|
|
|
Bei Problemen kann auf `v0.7.21` zurueck installiert werden.
|