Formato file delle dashboard

Il formato JSON delle dashboard di visualizzazione SharKNX: spazi, pagine, widget e indirizzi di gruppo utilizzati.

Puoi esportare una dashboard da SharKNX come file JSON e importarla sullo stesso dispositivo o su un altro. Puoi anche scriverla in un editor di testo: l’app esporta tutti i campi, ma per l’importazione richiede solo ciò che non può dedurre. Un progetto scritto a mano rimane quindi breve.

Per iniziare rapidamente, usa la dashboard vuota o la casa di esempio. Oppure crea una piccola dashboard nell’app, esportala e modifica il file.

In questa pagina

1. Struttura
2. Dashboard
3. Spazi e pagine
4. ID e collegamenti
5. Widget
6. Indirizzi di gruppo
7. Colori e icone
8. Tipi di widget
9. Connessione
10. Esempio completo
11. Validazione
12. Versioni

Struttura

Una dashboard contiene uno spazio, Home. Ogni altro spazio si trova in Home o in un altro spazio. Uno spazio ha una o più pagine tra cui scorrere, e ogni pagina contiene widget in una griglia.

{
  "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" }
        ]
      }
    ]
  }
}

Nel file, gli spazi si chiamano rooms, le pagine panels e i widget tiles. Il file usa JSON UTF-8; è accettato un marcatore dell’ordine dei byte all’inizio.

Dashboard

Il livello principale del file.

Il campo project di un file importato viene ignorato: il collegamento a un progetto nell’Archivio appartiene al dispositivo che ha creato il file.

Spazi e pagine

Usa tiles o panels, non entrambi. Ogni pagina in panels contiene:

{
  "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" }] }
    ]
  }
}

ID e collegamenti

Ogni spazio, pagina e widget ha un ID: r per gli spazi, p per le pagine, t per i widget, seguito da un numero fino a 999999. Gli ID sono univoci all’interno di una dashboard, non tra dashboard diverse.

• Se ometti gli ID, l’importazione li assegna proseguendo oltre l’ID più alto del file.
• Scrivi un ID quando qualcosa vi fa riferimento: uno spazio aperto da un widget di navigazione e un widget elencato in favorites.
• Un collegamento o preferito deve indicare un ID scritto nel file. Un ID mai dichiarato nel file è un errore, anche se l’importazione avrebbe assegnato quell’ID a un altro elemento.
• Un file esportato contiene sempre tutti gli ID.

Widget

Campi comuni a tutti i widget:

Un file con un tipo non riconosciuto da questa versione di SharKNX non viene importato.

Indirizzi di gruppo

Un widget invia ad alcuni indirizzi (comando) e mostra altri (stato). Gli indirizzi di gruppo si scrivono su tre livelli, ad esempio "1/2/3". Un DPT si scrive con tipo principale e sottotipo, ad esempio "1.001" o "9.001".

Forma breve. Scrivi solo l’indirizzo e verrà usato il DPT della sua funzione: 1.001 per un comando di accensione, 5.001 per la luminosità di un dimmer, il DPT di valueType per la visualizzazione di un valore. Ogni tipo di widget indica i propri valori predefiniti sotto.

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

Forma completa. Per usare un altro DPT dello stesso tipo principale (1.019 per un contatto finestra, 9.004 per un valore in lux), inviare un comando a più indirizzi o evitare la lettura di uno stato all’apertura della dashboard:

{
  "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 }
}

Un DPT deve corrispondere alla funzione: un interruttore accetta qualsiasi DPT 1 (1.001 commutazione, 1.008 su/giù, …), la luminosità di un dimmer usa DPT 5.001.

Colori e icone

I colori sono nomi: red, orange, yellow, green, blue, purple o grey. Ognuno ha una tonalità chiara e una scura, scelta dal tema.

Le icone sono nomi del catalogo dell’app, ad esempio light_group, floor_lamp, table_lamp, wall_lamp, socket, shutter, curtains, heating, cooling, window, door, temperature, humidity, relax, dinner, all_off. Le icone degli spazi includono home, living, kitchen, dining, bedroom, bathroom, office, hallway, garage, garden e terrace. Il selettore di icone dell’app mostra tutti i nomi.

Un nome di colore o icona sconosciuto viene conservato e visualizzato con il valore predefinito, così un file di una versione più recente di SharKNX rimane importabile.

Tipi di widget

Navigazione

Apre un altro spazio.

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

Interruttore

Un tocco alterna tra acceso e spento oppure invia sempre lo stesso valore.

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

Indicatore di stato

Mostra uno stato acceso/spento; un tocco non fa nulla.

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

Visualizzazione del valore

Mostra un numero o byte grezzi così come arrivano. Il suo type è valueDisplay.

La dimensione 1x1 è adatta solo a valori di 1 o 2 byte.

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

Comando del valore

Invia un numero: con − e +, un cursore o pulsanti per valori predefiniti.

{
  "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" }]
}

Visualizzazione della modalità

Mostra un byte come stati con nome, ad esempio una modalità HVAC.

{
  "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

Una luce dimmerabile: l’icona la accende o spegne, un cursore imposta la luminosità oppure − e + la regolano.

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

Veneziana

Una veneziana o tapparella: su, stop e giù, oppure una posizione.

0 % significa aperta e 100 % chiusa. Si possono indicare solo gli oggetti di invio del comando scelto, e quelli delle lamelle solo con slatAdjustment.

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

Scena

Richiama una scena. In modalità toggle alterna tra due scene; in modalità threshold ne sceglie una in base a un valore, ad esempio la scena A da 20 lux in su.

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

Scene

Un insieme di pulsanti scena su un indirizzo.

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

Bianco regolabile

Una luce con luminosità e temperatura di colore in una delle tre disposizioni di oggetti.

Gli oggetti di invio obbligatori e i relativi stati, se presenti, dipendono da objects; gli oggetti di un’altra disposizione sono un errore.

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

Luce colorata

Una luce RGB, RGBW o RGB + bianco regolabile.

Ogni oggetto di invio ha uno stato con lo stesso nome seguito da Status (rgbStatus, redStatus, …; quello del livello bianco è whiteStatus). Gli stati colore sono indicati tutti o nessuno.

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

Termostato

Mostra il setpoint o la temperatura ambiente e modifica il setpoint.

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

Ventilconvettore

Le velocità di un ventilconvettore, con acceso/spento, automatico/manuale, caldo/freddo, modalità HVAC e termostato opzionali. Le impostazioni determinano gli oggetti del widget; tutti gli oggetti di invio presenti sono obbligatori, gli stati sono facoltativi.

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

Condizionatore

Un’unità split o VRV tramite il suo gateway KNX. Il suo type è 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" }

Connessione

Come la dashboard si connette all’apertura. Se omessa è automatica: mantiene una connessione esistente dell’app, altrimenti usa il gateway selezionato, altrimenti esegue una ricerca.

L’oggetto gateway:

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

Le esportazioni dell’opzione JSON non protetto non contengono chiavi o credenziali. JSON non protetto e Con chiavi usano entrambi l’estensione .json; l’importazione riconosce la protezione dal contenuto.

JSON protetto da password

L’opzione Con chiavi cifra l’intero contenuto. Il contenitore JSON può essere aperto in un editor di testo, ma la definizione della dashboard e le chiavi devono essere decifrate per leggerle o modificarle. La password di esportazione è richiesta per importare e non viene mai salvata.

L’autenticazione vincola il contenuto anche a SharKNX dashboard protected JSON v1. Password errate o testo cifrato alterato non possono produrre una dashboard importata. Il file selezionato è limitato a 32 MiB; il contenuto decifrato a 16 MiB.

Il contenuto decifrato contiene dashboard (la definizione descritta qui) e, solo per una fonte di chiavi propria, keys. Senza keys, il progetto rimane automatico: l’app ricevente fornisce la propria sicurezza. Un pacchetto proprio, anche vuoto, diventa Chiavi importate, salvate cifrate con questa dashboard sotto una nuova identità locale. Il riferimento al progetto originale e la password di esportazione non vengono mai salvati nell’app.

keys.groupKeys associa numeri decimali di indirizzi di gruppo KNX (0–65535, scritti come stringhe) a chiavi esadecimali di 32 cifre. Sono conservati solo gli indirizzi usati. Il campo opzionale keys.credentials contiene devices per un gateway sicuro configurato, con address, deviceAuthCode opzionale e interfaces (userId, individualAddress, password); il multicast sicuro contiene invece backboneKeyHex e backboneSecurityEnabled. Sono esclusi Tool Keys, indirizzi e gateway non pertinenti e nomi dei progetti.

La connessione e il progetto automatici usano la configurazione dell’app ricevente. Non contengono mai una copia della connessione o del progetto dell’app esportatrice. Una dashboard con chiavi proprie e connessione automatica può contenere le chiavi di gruppo usate, ma nessuna credenziale del gateway. Le impostazioni del progetto mostrano Chiavi importate finché non salvi Automatico o un altro progetto; scegliere un progetto abilita anche la sua lista di indirizzi e l’aggiornamento delle chiavi. Le chiavi importate possono essere esportate di nuovo.

L’importazione si trova in + → Aggiungi → Importa dashboard. Al termine rimani in Dashboard; in caso di nome uguale puoi scegliere Importa come copia o Sostituisci. Gli errori appaiono in un dialogo con una sezione di codice scorrevole e Copia dettagli.

Esempio completo

La casa di esempio: Home con collegamenti a due spazi, un soggiorno con due pagine e una cucina, un widget di scene Moods, due preferiti e un gateway configurato.

{
  "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" }
        ]
      }
    ]
  }
}

Validazione

L’importazione verifica l’intero file ed elenca ogni problema con la sua posizione, ad esempio $.home.rooms[1].tiles[3].status.address. Un file con un problema non viene importato; non viene salvato nulla.

Limiti

Versioni

Ogni file esportato inizia con "format": 1. Senza questo campo viene letto come formato attuale. Un file con un numero superiore proviene da una versione più recente di SharKNX e non viene importato; aggiorna l’app.

I file rimangono importabili con l’evoluzione di SharKNX: i nuovi campi hanno valori predefiniti, quindi un file precedente può semplicemente non contenerli. Un campo non cambia mai significato mantenendo lo stesso nome. Un file nuovo in un’app precedente perde solo i campi che quell’app non riconosce.