Format de fichier des tableaux de bord

Le format JSON des tableaux de bord de visualisation SharKNX : espaces, pages, widgets et adresses de groupe utilisées.

Un tableau de bord peut être exporté depuis SharKNX au format JSON, puis importé sur le même appareil ou un autre. Vous pouvez aussi l’écrire dans un éditeur de texte : l’application exporte tous les champs, mais l’importation ne demande que les informations qu’elle ne peut pas déduire. Un fichier écrit à la main reste ainsi court.

Le plus simple est de commencer avec le tableau de bord vide ou la maison d’exemple. Vous pouvez aussi créer un petit tableau de bord dans l’application, l’exporter et modifier le fichier.

Sur cette page

1. Structure
2. Tableau de bord
3. Espaces et pages
4. Identifiants et liens
5. Widgets
6. Adresses de groupe
7. Couleurs et icônes
8. Types de widgets
9. Connexion
10. Exemple complet
11. Validation
12. Versions

Structure

Un tableau de bord contient un espace, Home. Tous les autres espaces se trouvent dans Home ou dans un autre espace. Un espace contient une ou plusieurs pages entre lesquelles vous balayez l’écran, avec des widgets disposés en grille.

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

Dans le fichier, les espaces s’appellent rooms, les pages panels et les widgets tiles. Le fichier utilise JSON en UTF-8 ; une marque d’ordre des octets au début est acceptée.

Tableau de bord

Le niveau supérieur du fichier.

Le champ project d’un fichier importé est ignoré : le lien vers un projet de l’Archive appartient à l’appareil qui a créé le fichier.

Espaces et pages

Utilisez tiles ou panels, pas les deux. Chaque page de panels contient :

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

Identifiants et liens

Chaque espace, page et widget a un identifiant : r pour les espaces, p pour les pages, t pour les widgets, suivi d’un nombre jusqu’à 999999. Les identifiants sont uniques dans un tableau de bord, pas entre plusieurs tableaux de bord.

• Si vous omettez les identifiants, l’importation les attribue au-delà du plus grand identifiant du fichier.
• Indiquez un identifiant lorsqu’un élément y fait référence : un espace ouvert par un widget de navigation, ou un widget figurant dans favorites.
• Un lien ou un favori doit désigner un identifiant écrit dans le fichier. Un identifiant jamais déclaré est une erreur, même si l’importation aurait attribué cet identifiant à un autre élément.
• Un fichier exporté contient toujours tous les identifiants.

Widgets

Champs communs à tous les widgets :

Un fichier contenant un type inconnu de cette version de SharKNX n’est pas importé.

Adresses de groupe

Un widget envoie sur certaines adresses (commande) et affiche les valeurs d’autres adresses (état). Les adresses de groupe s’écrivent sur trois niveaux, par exemple "1/2/3". Un DPT comporte un type principal et un sous-type, par exemple "1.001" ou "9.001".

Forme abrégée. Écrivez uniquement l’adresse ; elle prend le DPT de sa fonction : 1.001 pour une commande marche/arrêt, 5.001 pour la luminosité d’un variateur, le DPT de valueType pour un affichage de valeur. Chaque type de widget ci-dessous indique ses valeurs par défaut.

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

Forme complète. Pour utiliser un autre DPT du même type principal (1.019 pour un contact de fenêtre, 9.004 pour une valeur en lux), envoyer une commande à plusieurs adresses ou empêcher la lecture d’un état à l’ouverture du tableau de bord :

{
  "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 doit correspondre à sa fonction : un interrupteur accepte tout DPT 1 (1.001 marche/arrêt, 1.008 montée/descente, …), la luminosité d’un variateur utilise DPT 5.001.

Couleurs et icônes

Les couleurs sont des noms : red, orange, yellow, green, blue, purple ou grey. Chacune possède une nuance claire et une sombre, choisies par le thème.

Les icônes sont des noms du catalogue de l’application, par exemple light_group, floor_lamp, table_lamp, wall_lamp, socket, shutter, curtains, heating, cooling, window, door, temperature, humidity, relax, dinner, all_off. Les icônes d’espaces comprennent home, living, kitchen, dining, bedroom, bathroom, office, hallway, garage, garden et terrace. Le sélecteur d’icônes de l’application affiche tous les noms.

Un nom de couleur ou d’icône inconnu est conservé et affiché avec la valeur par défaut. Un fichier provenant d’une version plus récente de SharKNX reste ainsi importable.

Types de widgets

Navigation

Ouvre un autre espace.

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

Interrupteur

Un appui alterne entre marche et arrêt, ou envoie toujours la même valeur.

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

Indicateur d’état

Affiche un état marche/arrêt ; un appui ne fait rien.

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

Affichage de valeur

Affiche un nombre ou des octets bruts tels qu’ils arrivent. Son type est valueDisplay.

Une taille 1x1 convient uniquement aux valeurs de 1 ou 2 octets.

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

Commande de valeur

Envoie un nombre : avec − et +, un curseur ou des boutons de valeurs prédéfinies.

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

Affichage du mode

Affiche un octet sous forme d’états nommés, par exemple un mode 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" }]
}

Variateur

Un éclairage à variation : l’icône l’allume ou l’éteint, un curseur règle la luminosité, ou − et + la font varier.

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

Store

Un store ou un volet : montée, arrêt et descente, ou une position.

0 % signifie ouvert et 100 % fermé. Seuls les objets d’envoi de la commande choisie peuvent être indiqués ; les objets des lamelles nécessitent slatAdjustment.

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

Scène

Rappelle une scène. En mode toggle, alterne entre deux scènes ; en mode threshold, en choisit une selon une valeur, par exemple la scène A à partir de 20 lux.

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

Scènes

Un ensemble de boutons de scène sur une adresse.

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

Blanc réglable

Un éclairage avec luminosité et température de couleur, selon l’une de trois dispositions d’objets.

Les objets d’envoi requis et leurs états éventuels dépendent de objects ; les objets d’une autre disposition sont une erreur.

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

Éclairage couleur

Un éclairage RGB, RGBW ou RGB + blanc réglable.

Chaque objet d’envoi possède un état du même nom suivi de Status (rgbStatus, redStatus, … ; celui du niveau de blanc est whiteStatus). Les états de couleur sont tous indiqués ou tous omis.

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

Thermostat

Affiche la consigne ou la température ambiante et modifie la consigne.

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

Ventilo-convecteur

Les vitesses d’un ventilo-convecteur, avec marche/arrêt, auto/manuel, chaud/froid, modes HVAC et thermostat en option. Les réglages déterminent les objets du widget ; tous ses objets d’envoi sont obligatoires, les états sont facultatifs.

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

Climatiseur

Une unité split ou VRV via sa passerelle KNX. Son type est 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" }

Connexion

Connexion du tableau de bord à l’ouverture. Si omise, elle est automatique : conserve une connexion existante de l’application, sinon utilise sa passerelle sélectionnée, sinon lance une recherche.

L’objet gateway :

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

Les exports de l’option JSON non protégé ne contiennent ni clés ni identifiants. JSON non protégé et Avec les clés utilisent tous deux l’extension .json ; l’importation détecte la protection à partir du contenu.

JSON protégé par mot de passe

L’option Avec les clés chiffre l’ensemble du contenu. Le conteneur JSON peut être ouvert dans un éditeur de texte, mais la définition du tableau de bord et les clés doivent être déchiffrées pour être lues ou modifiées. Le mot de passe d’exportation est nécessaire à l’importation et n’est jamais enregistré.

L’authentification lie aussi le contenu à SharKNX dashboard protected JSON v1. Un mot de passe incorrect ou un texte chiffré altéré ne peut pas produire un tableau de bord importé. Le fichier sélectionné est limité à 32 MiB ; le contenu déchiffré à 16 MiB.

Le contenu déchiffré contient dashboard (la définition décrite ici) et, seulement pour une source de clés propre, keys. Sans keys, le projet reste automatique : l’application destinataire fournit sa propre sécurité. Un paquet propre, même vide, devient Clés importées, enregistré chiffré avec ce tableau de bord sous une nouvelle identité locale. La référence au projet source et le mot de passe d’exportation ne sont jamais enregistrés dans l’application.

keys.groupKeys associe les numéros décimaux d’adresses de groupe KNX (0–65535, sous forme de chaînes) à des clés hexadécimales de 32 chiffres. Seules les adresses utilisées sont conservées. Le champ facultatif keys.credentials contient devices pour une passerelle sécurisée configurée, avec address, éventuellement deviceAuthCode, et interfaces (userId, individualAddress, password) ; le multicast sécurisé contient plutôt backboneKeyHex et backboneSecurityEnabled. Les Tool Keys, adresses et passerelles sans rapport, ainsi que les noms de projets sont exclus.

La connexion automatique et le projet automatique utilisent la configuration de l’application destinataire. Ils ne transportent jamais une copie de la connexion ou du projet de l’application exportatrice. Un tableau de bord à clés propres avec connexion automatique peut contenir ses clés de groupe utilisées, mais aucun identifiant de passerelle. Les réglages du projet affichent Clés importées jusqu’à l’enregistrement du mode automatique ou d’un autre projet ; choisir un projet permet aussi d’utiliser sa liste d’adresses et d’actualiser les clés. Les clés importées peuvent être réexportées.

L’importation se trouve sous + → Ajouter → Importer un tableau de bord. Après réussite, vous restez sur les tableaux de bord ; si le nom existe, vous pouvez choisir Importer une copie ou Remplacer. Les erreurs apparaissent dans une fenêtre avec une section de code défilante et Copier les détails.

Exemple complet

La maison d’exemple : Home avec des liens vers deux espaces, un salon à deux pages et une cuisine, un widget de scènes Moods, deux favoris et une passerelle configurée.

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

Validation

L’importation vérifie tout le fichier et indique chaque problème avec son emplacement, par exemple $.home.rooms[1].tiles[3].status.address. Un fichier contenant un problème n’est pas importé ; rien n’est enregistré.

Limites

Versions

Chaque fichier exporté commence par "format": 1. Sans ce champ, il est lu au format actuel. Un fichier avec un numéro supérieur provient d’une version plus récente de SharKNX et n’est pas importé ; mettez l’application à jour.

Les fichiers restent importables lorsque SharKNX évolue : les nouveaux champs ont des valeurs par défaut, donc ils peuvent simplement manquer dans un ancien fichier. Un champ ne change jamais de sens sous le même nom. Dans une ancienne application, un fichier récent perd uniquement les champs inconnus de cette application.