Dashboard-Dateiformat

Das JSON-Dateiformat für SharKNX-Visualisierungsdashboards: Räume, Seiten, Widgets und die verwendeten Gruppenadressen.

Ein Dashboard lässt sich als JSON-Datei aus SharKNX exportieren und auf demselben oder einem anderen Gerät wieder importieren. Sie können es auch in einem Texteditor schreiben: Die App exportiert alle Felder, benötigt beim Import aber nur Angaben, die sie nicht selbst ableiten kann. So bleibt ein von Hand erstellter Entwurf kurz.

Beginnen Sie am einfachsten mit dem leeren Dashboard oder dem Beispielhaus. Oder erstellen Sie ein kleines Dashboard in der App, exportieren Sie es und bearbeiten Sie die Datei.

Auf dieser Seite

1. Struktur
2. Dashboard
3. Räume und Seiten
4. IDs und Verknüpfungen
5. Widgets
6. Gruppenadressen
7. Farben und Symbole
8. Widget-Typen
9. Verbindung
10. Vollständiges Beispiel
11. Validierung
12. Versionen

Struktur

Ein Dashboard enthält einen Raum, Home. Jeder andere Raum liegt in Home oder in einem weiteren Raum. Ein Raum hat eine oder mehrere Seiten, zwischen denen Sie wischen. Jede Seite enthält Widgets in einem Raster.

{
  "format": 1,
  "name": "Villa",
  "home": {
    "name": "Home",
    "tiles": [
      { "type": "switch", "name": "Hall light", "command": "1/0/1", "status": "1/0/2" }
    ],
    "rooms": [
      {
        "name": "Kitchen",
        "tiles": [
          { "type": "switch", "name": "Counter light", "command": "1/4/1" }
        ]
      }
    ]
  }
}

In der Datei heißen Räume rooms, Seiten panels und Widgets tiles. Die Datei verwendet UTF-8-JSON; eine Byte-Order-Mark am Anfang wird akzeptiert.

Dashboard

Die oberste Ebene der Datei.

Ein Feld project in einer importierten Datei wird ignoriert: Der Verweis auf ein Projekt im Archiv gehört zu dem Gerät, das die Datei erstellt hat.

Räume und Seiten

Verwenden Sie entweder tiles oder panels, nicht beide. Jede Seite in panels hat folgende Felder:

{
  "format": 1,
  "name": "Two pages",
  "home": {
    "name": "Home",
    "panels": [
      { "tiles": [{ "type": "switch", "name": "Hall light", "command": "1/0/1" }] },
      { "tiles": [{ "type": "switch", "name": "Porch light", "command": "1/0/5" }] }
    ]
  }
}

IDs und Verknüpfungen

Jeder Raum, jede Seite und jedes Widget hat eine ID: r für Räume, p für Seiten, t für Widgets, gefolgt von einer Zahl bis 999999. IDs sind innerhalb eines Dashboards eindeutig, nicht über mehrere Dashboards hinweg.

• Lassen Sie IDs weg, weist der Import sie oberhalb der höchsten ID in der Datei zu.
• Geben Sie eine ID an, wenn etwas darauf verweist: für einen Raum, den ein Navigationswidget öffnet, und ein Widget in favorites.
• Eine Verknüpfung oder ein Favorit muss eine in der Datei angegebene ID nennen. Eine ID, die die Datei nie deklariert, ist ein Fehler, selbst wenn der Import diese ID einem anderen Element zugewiesen hätte.
• Eine exportierte Datei enthält immer alle IDs.

Widgets

Felder, die jedes Widget hat:

Eine Datei mit einem Typ, den diese SharKNX-Version nicht kennt, wird nicht importiert.

Gruppenadressen

Ein Widget sendet an bestimmte Adressen (Befehl) und zeigt andere an (Status). Gruppenadressen werden in drei Ebenen geschrieben, z. B. "1/2/3". Ein DPT besteht aus Haupt- und Untertyp, z. B. "1.001" oder "9.001".

Kurzform. Geben Sie nur die Adresse an; sie übernimmt den DPT ihrer Funktion: ein Schaltbefehl 1.001, die Helligkeit eines Dimmers 5.001, eine Wertanzeige den DPT ihres valueType. Jeder Widget-Typ unten nennt seine Standardwerte.

{ "type": "switch", "name": "Hall light", "command": "1/0/1", "status": "1/0/2" }

Vollständige Form. Um einen anderen DPT desselben Haupttyps zu verwenden (1.019 für einen Fensterkontakt, 9.004 für einen Luxwert), einen Befehl an mehrere Adressen zu senden oder einen Status beim Öffnen des Dashboards nicht zu lesen:

{
  "type": "switch",
  "name": "All lights",
  "command": { "targets": ["1/0/1", "1/1/1", "1/4/1"], "dpt": "1.001" },
  "status": { "address": "1/0/2", "dpt": "1.001", "readOnOpen": false }
}

Ein DPT muss zur Funktion passen: Ein Schalter verwendet beliebige DPT 1 (1.001 Schalten, 1.008 Auf/Ab, …), die Helligkeit eines Dimmers DPT 5.001.

Farben und Symbole

Farben sind Namen: red, orange, yellow, green, blue, purple oder grey. Jede Farbe hat einen hellen und einen dunklen Farbton, den das Design auswählt.

Symbole sind Namen aus dem Symbolkatalog der App, z. B. light_group, floor_lamp, table_lamp, wall_lamp, socket, shutter, curtains, heating, cooling, window, door, temperature, humidity, relax, dinner, all_off. Raumsymbole sind unter anderem home, living, kitchen, dining, bedroom, bathroom, office, hallway, garage, garden und terrace. Die Symbolauswahl in der App zeigt alle Namen.

Unbekannte Farb- oder Symbolnamen bleiben erhalten und werden mit dem Standard dargestellt. So lässt sich eine Datei aus einer neueren SharKNX-Version weiterhin importieren.

Widget-Typen

Navigation

Öffnet einen anderen Raum.

{
  "format": 1,
  "name": "Links",
  "home": {
    "name": "Home",
    "tiles": [{ "type": "navigation", "name": "Kitchen", "icon": "kitchen", "target": "r1" }],
    "rooms": [{ "id": "r1", "name": "Kitchen", "tiles": [] }]
  }
}

Schalter

Ein Tippen wechselt zwischen Ein und Aus oder sendet immer denselben Wert.

{ "type": "switch", "name": "Garden pump", "icon": "valve", "command": "1/5/1", "status": "1/5/2", "zeroLabel": "Stopped", "oneLabel": "Running" }

Statusanzeige

Zeigt einen Ein/Aus-Zustand; Tippen hat keine Wirkung.

{ "type": "statusIndicator", "name": "Window", "icon": "window", "status": { "address": "6/1/1", "dpt": "1.019" }, "zeroLabel": "Closed", "oneLabel": "Open" }

Wertanzeige

Zeigt eine Zahl oder Rohbytes so an, wie sie ankommen. Ihr type ist valueDisplay.

1x1 eignet sich nur für Werte mit 1 oder 2 Bytes.

{ "type": "valueDisplay", "name": "Power", "icon": "electricity", "valueType": "s32", "unit": "kW", "decimals": 2, "displayScale": 1000, "status": { "address": "9/1/1", "dpt": "13.010" } }

Wertsteuerung

Sendet eine Zahl: mit − und +, einem Schieberegler oder Tasten für feste Werte.

{
  "type": "valueControl",
  "name": "Hood fan",
  "valueType": "percent",
  "control": "buttons",
  "command": { "address": "6/2/1", "dpt": "5.001" },
  "status": { "address": "6/2/2", "dpt": "5.001" },
  "choices": [{ "value": 0, "name": "Off" }, { "value": 50, "name": "Half" }, { "value": 100, "name": "Full" }]
}

Modusanzeige

Zeigt ein Byte als benannte Zustände, z. B. einen HVAC-Modus.

{
  "type": "modeStatus",
  "name": "Heating mode",
  "status": { "address": "3/1/9", "dpt": "20.102" },
  "states": [{ "value": 1, "name": "Comfort" }, { "value": 2, "name": "Standby" }, { "value": 3, "name": "Economy" }]
}

Dimmer

Eine dimmbare Leuchte: Das Symbol schaltet sie, ein Schieberegler setzt die Helligkeit oder − und + dimmen sie.

{ "type": "dimmer", "name": "Sofa lamp", "icon": "floor_lamp", "switch": "1/1/10", "switchStatus": "1/1/11", "brightness": "1/1/12", "brightnessStatus": "1/1/13" }

Jalousie

Eine Jalousie oder ein Rollladen: auf, stopp und ab oder eine Position.

0 % ist geöffnet, 100 % geschlossen. Nur die Sendeobjekte der gewählten Steuerung dürfen angegeben werden, Lamellenobjekte nur mit slatAdjustment.

{ "type": "blind", "name": "Terrace blind", "move": "2/1/1", "stop": "2/1/2", "positionStatus": "2/1/3" }

Szene

Ruft eine Szene ab. Im Modus toggle wechselt sie zwischen zwei Szenen; im Modus threshold wählt sie anhand eines Werts eine aus, z. B. Szene A ab 20 lux.

{ "type": "scene", "name": "Cinema", "icon": "relax", "mode": "toggle", "command": "4/2/1", "scene": 4, "sceneB": 5, "nameA": "Movie", "nameB": "Lights up" }

Szenen

Mehrere Szenentasten auf einer Adresse.

{
  "type": "scenes",
  "name": "Moods",
  "command": "4/1/1",
  "scenes": [{ "name": "Relax", "scene": 0, "icon": "relax" }, { "name": "Dinner", "scene": 1, "icon": "dinner" }]
}

Einstellbares Weiß

Eine Leuchte mit Helligkeit und Farbtemperatur in einer von drei Objektanordnungen.

Die erforderlichen Sendeobjekte und ihre optionalen Statusobjekte hängen von objects ab; Objekte einer anderen Anordnung sind ein Fehler.

{ "type": "tunableWhite", "name": "Reading light", "switch": "1/2/1", "brightness": "1/2/2", "temperature": "1/2/3", "temperatureStatus": "1/2/4" }

Farblicht

Eine RGB-, RGBW- oder RGB-Leuchte mit einstellbarem Weiß.

Jedes Sendeobjekt hat ein gleichnamiges Statusobjekt mit angehängtem Status (rgbStatus, redStatus, …; beim Weißpegel whiteStatus). Farbstatusobjekte werden entweder alle angegeben oder keines.

{ "type": "colorLight", "name": "Accent strip", "light": "rgb", "switch": "1/3/1", "rgb": "1/3/2", "rgbStatus": "1/3/3" }

Thermostat

Zeigt den Sollwert oder die Raumtemperatur und ändert den Sollwert.

{ "type": "thermostat", "name": "Living room", "setpoint": "3/1/1", "setpointStatus": "3/1/2", "roomTemperature": "3/1/3" }

Fan Coil

Die Lüfterstufen eines Fan-Coil-Geräts, optional mit Ein/Aus, Auto/Manuell, Heizen/Kühlen, HVAC-Modi und Thermostat. Die Einstellungen legen die Objekte fest; jedes vorhandene Sendeobjekt ist erforderlich, Statusobjekte sind optional.

{ "type": "fanCoil", "name": "Office fan coil", "fanSpeed": "7/1/1", "fanSpeedStatus": "7/1/2", "onOff": true, "switchCommand": "7/1/3", "switchStatus": "7/1/4" }

Klimagerät

Ein Splitgerät oder VRV über sein KNX-Gateway. Sein type ist airConditioner.

{ "type": "airConditioner", "name": "Bedroom AC", "switchCommand": "8/1/1", "switchStatus": "8/1/2", "setpoint": "8/1/3", "mode": "8/1/4", "fanSpeed": "8/1/5" }

Verbindung

Wie sich das Dashboard beim Öffnen verbindet. Ohne Angabe arbeitet es automatisch: Es behält eine bestehende Verbindung der App bei, verwendet sonst das ausgewählte Gateway und sucht andernfalls.

Das Objekt gateway:

{
  "format": 1,
  "name": "Office",
  "connection": { "mode": "gateway", "gateway": { "name": "Office router", "host": "10.0.0.5", "transport": "tcp" } },
  "home": { "name": "Home", "tiles": [] }
}

Exporte der Option Einfaches JSON enthalten keine Schlüssel oder Zugangsdaten. Einfaches JSON und Mit Schlüsseln verwenden beide die Erweiterung .json; der Import erkennt den Schutz am Dateiinhalt.

Passwortgeschütztes JSON

Die Option Mit Schlüsseln verschlüsselt den gesamten Inhalt. Sein JSON-Container lässt sich in einem Texteditor öffnen, aber Dashboard-Definition und Schlüssel müssen zum Lesen oder Ändern entschlüsselt werden. Das Exportpasswort ist für den Import erforderlich und wird nie gespeichert.

Die Authentifizierung bindet den Inhalt zusätzlich an SharKNX dashboard protected JSON v1. Falsche Passwörter oder manipulierte verschlüsselte Daten können kein importiertes Dashboard erzeugen. Die gewählte Datei ist auf 32 MiB begrenzt, der entschlüsselte Inhalt auf 16 MiB.

Der entschlüsselte Inhalt enthält dashboard (die in dieser Referenz beschriebene Definition) und nur bei einer eigenen Schlüsselquelle keys. Ohne keys bleibt das Projekt automatisch: Die empfangende App liefert ihre eigene Sicherheit. Ein eigenes Paket, selbst ein leeres, wird als Importierte Schlüssel geführt und mit einer neuen lokalen Identität verschlüsselt beim Dashboard gespeichert. Der Verweis auf das Quellprojekt und das Exportpasswort werden nie in den App-Speicher übernommen.

keys.groupKeys ordnet dezimalen KNX-Gruppenadressnummern (0–65535, als Zeichenketten) 32-stellige Hexadezimalschlüssel zu. Nur vom Dashboard verwendete Adressen bleiben erhalten. Das optionale keys.credentials enthält devices für ein konfiguriertes sicheres Gateway mit address, optionalem deviceAuthCode und interfaces (userId, individualAddress, password); sicheres multicast enthält stattdessen backboneKeyHex und backboneSecurityEnabled. Tool Keys, fremde Adressen und Gateways sowie Projektnamen sind ausgeschlossen.

Automatische Verbindung und automatisches Projekt verwenden die Konfiguration der empfangenden App. Sie enthalten nie eine Momentaufnahme der Verbindung oder des Projekts der exportierenden App. Ein Dashboard mit eigenen Schlüsseln und automatischer Verbindung kann seine verwendeten Gruppenschlüssel enthalten, aber keine Gateway-Zugangsdaten. Die Projekteinstellungen zeigen Importierte Schlüssel, bis automatisch oder ein anderes Projekt gespeichert wird. Ein gewähltes Projekt stellt außerdem seine Adressliste und die Schlüsselaktualisierung bereit. Importierte Schlüssel lassen sich erneut exportieren.

Der Import ist unter + → Hinzufügen → Dashboard importieren verfügbar. Nach Erfolg bleiben Sie auf Dashboards; bei gleichem Namen werden Als Kopie importieren oder Ersetzen angeboten. Importfehler erscheinen in einem Dialog mit scrollbarem Codebereich und Details kopieren.

Vollständiges Beispiel

Das Beispielhaus: Home mit Verknüpfungen zu zwei Räumen, ein Wohnzimmer mit zwei Seiten und eine Küche, ein Szenenwidget „Moods“, zwei Favoriten und ein konfiguriertes Gateway.

{
  "format": 1,
  "name": "Villa",
  "theme": "night",
  "keepScreenOn": true,
  "favorites": ["t1", "t4"],
  "connection": { "mode": "gateway", "gateway": { "name": "Main gateway", "host": "192.168.1.20" } },
  "home": {
    "name": "Home",
    "icon": "home",
    "tiles": [
      { "type": "navigation", "name": "Living room", "icon": "living", "target": "r1" },
      { "type": "navigation", "name": "Kitchen", "icon": "kitchen", "target": "r2" },
      { "type": "valueDisplay", "name": "Outdoor", "icon": "temperature", "valueType": "f16", "unit": "°C", "decimals": 1, "status": { "address": "5/1/1", "dpt": "9.001" } }
    ],
    "rooms": [
      {
        "id": "r1",
        "name": "Living room",
        "icon": "living",
        "panels": [
          {
            "tiles": [
              { "id": "t1", "type": "switch", "name": "Ceiling light", "icon": "light_group", "command": "1/1/1", "status": "1/1/2" },
              { "type": "dimmer", "name": "Sofa lamp", "icon": "floor_lamp", "switch": "1/1/10", "brightness": "1/1/12", "brightnessStatus": "1/1/13" },
              { "type": "blind", "name": "Terrace blind", "move": "2/1/1", "stop": "2/1/2", "positionStatus": "2/1/3" },
              { "id": "t4", "type": "thermostat", "name": "Living room", "setpoint": "3/1/1", "setpointStatus": "3/1/2", "roomTemperature": "3/1/3" }
            ]
          },
          {
            "tiles": [
              { "type": "tunableWhite", "name": "Reading light", "switch": "1/2/1", "brightness": "1/2/2", "temperature": "1/2/3" }
            ]
          }
        ]
      },
      {
        "id": "r2",
        "name": "Kitchen",
        "icon": "kitchen",
        "tiles": [
          { "type": "switch", "name": "Counter light", "command": "1/4/1", "status": "1/4/2" },
          { "type": "statusIndicator", "name": "Window", "icon": "window", "status": { "address": "6/1/1", "dpt": "1.019" }, "zeroLabel": "Closed", "oneLabel": "Open" }
        ]
      }
    ]
  }
}

Validierung

Der Import prüft die gesamte Datei und nennt jedes Problem mit seiner Position, z. B. $.home.rooms[1].tiles[3].status.address. Eine Datei mit einem Problem wird nicht importiert; es wird nichts gespeichert.

Grenzen

Versionen

Jede exportierte Datei beginnt mit "format": 1. Fehlt das Feld, wird die Datei als aktuelles Format gelesen. Eine Datei mit höherer Nummer stammt aus einer neueren SharKNX-Version und wird nicht importiert; aktualisieren Sie die App.

Dateien bleiben beim Wachstum von SharKNX importierbar: Neue Felder erhalten Standardwerte, sodass sie in älteren Dateien einfach fehlen können. Ein Feld ändert unter demselben Namen niemals seine Bedeutung. Bei einer neueren Datei in einer älteren App gehen nur die Felder verloren, die die App nicht kennt.