Skip to content

JSON SmartHome Dashboard

Diese Dokumentation beschreibt die aktuelle App vollständig aus zwei Blickwinkeln:

  • als Anwender- und Integrationsdokumentation für die JSON-Konfiguration
  • als Entwicklerdokumentation für Architektur, Laufzeitverhalten und öffentliche Code-APIs
  • Repository: JSON-SmartHome-Dashboard auf git.kulbox.de
  • Quellcode, lokale Anpassungen und Weiterentwicklung starten im Repository
  • Für Konfiguration, Architektur und Beispiele bleibst du in dieser Dokumentation

Was die App kann

  • Smart-Home-Dashboards aus externer JSON-Konfiguration laden
  • Konfiguration per direkter Dashboard-URL, index.json-Profilverzeichnis oder lokaler Datei beziehen
  • Widgets als Icon/Text, Bild, Slider, Select oder Rollladensteuerung darstellen
  • Status über HTTP-Requests mit optionalen Headern und optionalem JSON-Body abrufen
  • Request-Methode optional pro Endpoint konfigurieren; ohne Angabe gilt GET ohne Body und POST mit Body
  • Antworten als JSON oder PNG verarbeiten
  • Tabs, Gruppen, Rastergrössen und Vollbreiten-Zeilenwidgets konfigurieren
  • gemeinsame Statusabfragen pro Aktualisierung nur einmal ausführen
  • Widget-Aktionen als Endpoint-Aufruf, Tab-Wechsel oder Browser-Öffnung ausführen
  • dynamische Titel, Werte, Icon-Namen und Farblogik aus JSON-Antworten ableiten

Dokumentationskarte

  • Schnellstart: in wenigen Minuten zur ersten lauffähigen Konfiguration
  • Architektur: Schichten, Datenfluss und Laufzeitmodell
  • Konfiguration: vollständige JSON-Referenz
  • Widget-Typen: Detailseiten je Widget-Art
  • Layout: Sortierung, Gruppen, Grid-Packing und Vollbreite
  • Referenz: zentrale Klassen, Resolver, ViewModel-Methoden und Composables
  • Beispiele: einsatznahe Konfigurationen
  • Fehlersuche: typische Fehlerbilder und Lösungen

Zielgruppe

Diese Doku ist so aufgebaut, dass sie drei Rollen gleichzeitig gut bedient:

  • Integratoren, die nur JSON-Dateien schreiben wollen
  • Power-User, die ihr Dashboard systematisch strukturieren möchten
  • Entwickler, die die App erweitern, refactoren oder testen wollen

Schnellorientierung

Wenn du gerade erst loslegst, ist diese Reihenfolge sinnvoll:

  1. Schnellstart
  2. Konfiguration Überblick
  3. Widgets
  4. Status und Requests
  5. Aktionen und Dialoge

Wenn du die App weiterentwickelst, starte hier:

  1. Architektur
  2. Code-API
  3. Tabs, Gruppen und Grid

Wichtige Grundregeln

  • URLs sind nur erlaubt, wenn sie https://... sind oder http://192.168.x.x/... verwenden.
  • Jede Widget-ID, Gruppen-ID, Tab-ID und Shared-Request-ID muss eindeutig sein.
  • Ein Widget braucht genau eine Statusquelle: status.request oder status.sharedRequestId.
  • Bei Gruppen dürfen Widgets nicht mehrfach in verschiedenen Gruppen vorkommen.
  • Innerhalb desselben Tabs darf ein Widget nicht zugleich direkt und über eine Gruppe eingebunden sein.

Dateistandorte im Projekt

  • Dokumentation: doku/
  • MkDocs-Konfiguration: mkdocs.yml
  • Beispiel-Dashboard: sample-dashboard-config.json
  • Beispiel-Profilindex: sample-dashboard-index.json
  • reale Beispielkonfiguration: widgets.json
  • Konfigurationsmodelle: app/src/main/java/de/ringelbaer/jsonsmarthomedashboard/data/model/DashboardConfig.kt

Hinweis zum Umfang

Die Referenzseiten dokumentieren den aktuellen Stand der App. Sie sind nicht als abstraktes Wunsch-Schema geschrieben, sondern leiten sich direkt aus den tatsächlichen Kotlin-Modellen und der Laufzeitlogik ab.