Formato de archivo de los paneles

El formato JSON de los paneles de visualización de SharKNX: espacios, páginas, widgets y las direcciones de grupo que utilizan.

Puedes exportar un panel desde SharKNX como archivo JSON e importarlo de nuevo en el mismo dispositivo o en otro. También puedes escribirlo en un editor de texto: la aplicación exporta todos los campos, pero al importar solo necesita lo que no puede deducir. Así, un diseño escrito a mano queda breve.

La forma más rápida de empezar es usar el panel vacío o la casa de ejemplo. También puedes crear un panel pequeño en la aplicación, exportarlo y editar el archivo.

En esta página

1. Estructura
2. Panel
3. Espacios y páginas
4. IDs y enlaces
5. Widgets
6. Direcciones de grupo
7. Colores e iconos
8. Tipos de widgets
9. Conexión
10. Ejemplo completo
11. Validación
12. Versiones

Estructura

Un panel contiene un espacio, Home. Los demás espacios están dentro de Home o de otro espacio. Un espacio tiene una o varias páginas entre las que puedes deslizar, y cada página contiene widgets en una cuadrícula.

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

En el archivo, los espacios se llaman rooms, las páginas panels y los widgets tiles. El archivo es JSON UTF-8; se acepta una marca de orden de bytes al principio.

Panel

El nivel superior del archivo.

Se ignora el campo project de un archivo importado: el enlace a un proyecto del Archivo pertenece al dispositivo que creó el archivo.

Espacios y páginas

Usa tiles o panels, pero no ambos. Cada página de 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" }] }
    ]
  }
}

IDs y enlaces

Cada espacio, página y widget tiene un ID: r para espacios, p para páginas y t para widgets, seguido de un número hasta 999999. Los IDs son únicos dentro de un panel, no entre paneles.

• Si omites los IDs, la importación los asigna a partir del ID más alto del archivo.
• Escribe un ID cuando algo lo use como referencia: un espacio que abre un widget de navegación o un widget incluido en favorites.
• Un enlace o favorito debe indicar un ID escrito en el archivo. Si apunta a un ID que el archivo nunca declara, es un error, aunque la importación hubiera asignado ese ID a otro elemento.
• Un archivo exportado siempre incluye todos los IDs.

Widgets

Campos comunes a todos los widgets:

No se importa un archivo que contiene un tipo desconocido para esta versión de SharKNX.

Direcciones de grupo

Un widget envía a ciertas direcciones (comando) y muestra otras (estado). Las direcciones de grupo se escriben en tres niveles, por ejemplo "1/2/3". Un DPT se escribe con tipo principal y subtipo, por ejemplo "1.001" o "9.001".

Forma abreviada. Escribe solo la dirección y tomará el DPT de su función: 1.001 para un comando de interruptor, 5.001 para el brillo de un regulador y el DPT de valueType para una visualización de valor. Cada tipo de widget indica sus valores predeterminados más abajo.

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

Forma completa. Para usar otro DPT del mismo tipo principal (1.019 para un contacto de ventana, 9.004 para un valor de lux), enviar un comando a varias direcciones o evitar leer un estado al abrir el panel:

{
  "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 debe corresponder a su función: un interruptor admite cualquier DPT 1 (1.001 conmutación, 1.008 subir/bajar, …), y el brillo de un regulador usa DPT 5.001.

Colores e iconos

Los colores son nombres: red, orange, yellow, green, blue, purple o grey. Cada uno tiene un tono claro y otro oscuro, elegido por el tema.

Los iconos son nombres del catálogo de la aplicación, por ejemplo light_group, floor_lamp, table_lamp, wall_lamp, socket, shutter, curtains, heating, cooling, window, door, temperature, humidity, relax, dinner, all_off. Los iconos de espacios incluyen home, living, kitchen, dining, bedroom, bathroom, office, hallway, garage, garden y terrace. El selector de iconos de la aplicación muestra todos los nombres.

Un nombre de color o icono desconocido se conserva y se dibuja con el valor predeterminado, por lo que un archivo de una versión más reciente de SharKNX sigue siendo importable.

Tipos de widgets

Navegación

Abre otro espacio.

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

Interruptor

Al tocar, alterna entre encendido y apagado o envía siempre el mismo valor.

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

Indicador de estado

Muestra un estado de encendido/apagado; tocar no hace nada.

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

Visualización de valor

Muestra un número o bytes sin procesar tal como llegan. Su type es valueDisplay.

El tamaño 1x1 solo admite valores de 1 o 2 bytes.

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

Control de valor

Envía un número: con − y +, un deslizador o botones para valores fijos.

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

Visualización del modo

Muestra un byte como estados con nombre, por ejemplo un modo 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" }]
}

Regulador

Una luz regulable: el icono la enciende o apaga, un deslizador ajusta el brillo o − y + lo regulan.

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

Persiana

Una persiana o estor: subir, detener y bajar, o una posición.

0 % es abierta y 100 % cerrada. Solo se pueden indicar los objetos de envío del control seleccionado, y los de las lamas solo con slatAdjustment.

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

Escena

Activa una escena. En modo toggle alterna entre dos escenas; en modo threshold elige una según un valor, por ejemplo la escena A 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" }

Escenas

Un conjunto de botones de escena en una dirección.

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

Blanco regulable

Una luz con brillo y temperatura de color en una de tres disposiciones de objetos.

Los objetos de envío obligatorios y sus estados opcionales dependen de objects; los objetos de otra disposición son un error.

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

Luz de color

Una luz RGB, RGBW o RGB + blanco regulable.

Cada objeto de envío tiene un estado con su nombre seguido de Status (rgbStatus, redStatus, …; el del nivel de blanco es whiteStatus). Los estados de color se indican todos o ninguno.

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

Termostato

Muestra la consigna o la temperatura ambiente y modifica la consigna.

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

Fan coil

Las velocidades de un fan coil, con encendido/apagado, automático/manual, calor/frío, modos HVAC y termostato opcionales. Los ajustes determinan los objetos del widget; todos sus objetos de envío son obligatorios y los estados son opcionales.

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

Aire acondicionado

Una unidad split o VRV a través de su pasarela KNX. Su type es 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" }

Conexión

Cómo se conecta el panel al abrirse. Si se omite, es automática: conserva cualquier conexión de la aplicación; si no hay, usa la pasarela seleccionada; si tampoco hay, busca una.

El objeto gateway:

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

Las exportaciones JSON sin protección no contienen claves ni credenciales. JSON sin protección y Con claves usan la extensión .json; la importación detecta la protección por el contenido.

JSON protegido por contraseña

La opción Con claves cifra todo el contenido. Puedes abrir el contenedor JSON en un editor de texto, pero debes descifrar la definición y las claves para leerlas o cambiarlas. La contraseña de exportación se necesita para importar y nunca se guarda.

La autenticación vincula también el contenido a SharKNX dashboard protected JSON v1. Una contraseña incorrecta o un texto cifrado alterado no pueden producir un panel importado. El archivo seleccionado está limitado a 32 MiB y el contenido descifrado a 16 MiB.

El contenido descifrado contiene dashboard (la definición de esta referencia) y, solo para una fuente de claves propia, keys. Si falta keys, el proyecto sigue siendo automático: la aplicación receptora aporta su seguridad. Un paquete propio, incluso vacío, se convierte en Claves importadas, guardadas cifradas con el panel bajo una identidad local nueva. La referencia al proyecto original y la contraseña de exportación nunca se guardan en la aplicación.

keys.groupKeys relaciona números decimales de direcciones de grupo KNX (0–65535, escritos como cadenas) con claves hexadecimales de 32 dígitos. Solo se conservan las direcciones usadas. El campo opcional keys.credentials contiene devices para una pasarela segura configurada, con address, deviceAuthCode opcional e interfaces (userId, individualAddress, password); el multicast seguro contiene en su lugar backboneKeyHex y backboneSecurityEnabled. Se excluyen Tool Keys, direcciones y pasarelas ajenas y nombres de proyectos.

La conexión y el proyecto automáticos usan la configuración de la aplicación receptora. Nunca incluyen una copia de la conexión o del proyecto de la aplicación que exportó. Un panel con claves propias y conexión automática puede incluir las claves de grupo usadas, pero ninguna credencial de pasarela. Los ajustes de proyecto muestran Claves importadas hasta guardar Automático u otro proyecto; elegir un proyecto también habilita su lista de direcciones y la actualización de claves. Las claves importadas se pueden exportar de nuevo.

La importación está en + → Añadir → Importar panel. Al terminar, permaneces en Paneles; si coincide el nombre, puedes elegir Importar como copia o Sustituir. Los errores aparecen en un diálogo con una sección de código desplazable y Copiar detalles.

Ejemplo completo

La casa de ejemplo: Home con enlaces a dos espacios, un salón con dos páginas y una cocina, un widget de escenas Moods, dos favoritos y una pasarela configurada.

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

Validación

La importación comprueba todo el archivo e indica cada problema con su ubicación, por ejemplo $.home.rooms[1].tiles[3].status.address. Un archivo con algún problema no se importa; no se guarda nada.

Límites

Versiones

Cada archivo exportado empieza con "format": 1. Si falta, se lee como el formato actual. Un archivo con un número superior se creó con una versión más reciente de SharKNX y no se importa; actualiza la aplicación.

Los archivos siguen siendo importables a medida que crece SharKNX: se añaden campos con valores predeterminados, así que un archivo antiguo puede carecer de ellos. Un campo nunca cambia de significado bajo el mismo nombre. Un archivo nuevo en una aplicación antigua solo pierde los campos que esta no reconoce.