Dashboard File Format

The JSON file format for SharKNX visualization dashboards: spaces, pages, widgets and the group addresses they use.

A dashboard can be exported from SharKNX as a JSON file and imported again, on the same device or another one. You can also write one in any text editor: the app exports every field, but an import needs only what it cannot work out for itself, so a hand-written design stays short.

The quickest start is the empty dashboard or the example house. Or build a small dashboard in the app, export it, and edit the file.

On this page

1. Structure
2. Dashboard
3. Spaces and pages
4. IDs and links
5. Widgets
6. Group addresses
7. Colors and icons
8. Widget types
9. Connection
10. Complete example
11. Validation
12. Versions

Structure

A dashboard holds one space, Home. Every other space sits inside Home or inside another space. A space has one or more pages that you swipe through, and each page holds widgets in a grid.

{
  "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 the file, spaces are called rooms, pages panels and widgets tiles. The file is UTF-8 JSON; a byte-order mark at the start is accepted.

Dashboard

The top level of the file.

A project field in an imported file is ignored: the link to a project in the Archive belongs to the device that made it.

Spaces and pages

Use either tiles or panels, not both. Each page in panels is:

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

Every space, page and widget has an ID: r for spaces, p for pages, t for widgets, followed by a number up to 999999. IDs are unique within a dashboard, not across dashboards.

• Leave IDs out and the import assigns them, continuing above the highest ID in the file.
• Write an ID where something refers to it: a space that a navigation widget opens, and a widget listed in favorites.
• A link or favourite must name an ID written in the file. One that names an ID the file never declares is an error, even if the import would have assigned that ID to something else.
• An exported file always carries every ID.

Widgets

Fields every widget has:

A file with a type this version of SharKNX does not know is not imported.

Group addresses

A widget sends to some addresses (a command) and shows others (a status). Group addresses are written in three levels, e.g. "1/2/3". A DPT is written as main and subtype, e.g. "1.001" or "9.001".

Short form. Write the address alone and it takes its role's DPT: a switch command 1.001, a dimmer's brightness 5.001, a Value status the DPT of its valueType. Each widget type below lists its defaults.

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

Full form. To use another DPT of the same main type (a window contact's 1.019, a lux value's 9.004), to send one command to several addresses, or to stop a status being read when the dashboard opens:

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

A DPT must fit the role: a switch takes any DPT 1 (1.001 Switch, 1.008 Up/Down, …), a dimmer's brightness DPT 5.001.

Colors and icons

Colors are names: red, orange, yellow, green, blue, purple or grey. Each has a light and a dark shade, chosen by the theme.

Icons are names from the app's icon catalog, e.g. light_group, floor_lamp, table_lamp, wall_lamp, socket, shutter, curtains, heating, cooling, window, door, temperature, humidity, relax, dinner, all_off. Space icons include home, living, kitchen, dining, bedroom, bathroom, office, hallway, garage, garden and terrace. The icon picker in the app shows every name.

An unknown color or icon name is kept and drawn as the default, so a file from a newer SharKNX still imports.

Widget types

Navigation

Opens another space.

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

Switch

A tap toggles between On and Off, or always sends the same value.

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

Status indicator

Shows an on/off state; a tap does nothing.

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

Value status

Shows a number (or raw bytes) as it arrives. Its type is valueDisplay.

A 1x1 fits values of 1 or 2 bytes only.

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

Value control

Sends a number: with − and +, a slider, or buttons for set values.

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

Mode status

Shows a byte as named states, e.g. an HVAC mode.

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

A dimmable light: the icon toggles it, a slider sets the brightness or − and + dim it.

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

Blind

A blind or shutter: up, stop and down, or a position.

0 % is open and 100 % closed. Only the send objects of the chosen control may be given, and slat objects only with slatAdjustment.

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

Scene

Recalls a scene. In toggle mode it alternates between two scenes; in threshold mode it picks one by a value, e.g. scene A at or above 20 lux.

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

Scenes

A set of scene buttons on one address.

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

Tunable white

A light with brightness and color temperature, in one of three arrangements of objects.

The required send objects (and their statuses, when given) depend on objects; objects of another arrangement are an error.

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

Color light

An RGB, RGBW or RGB + tunable white light.

Each send object has a status named after it with Status added (rgbStatus, redStatus, …; the white level's is whiteStatus). Color statuses are all given or none.

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

Thermostat

Shows the setpoint or the room temperature and changes the setpoint.

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

Fan coil

The fan stages of a fan coil unit, with optional On/Off, Auto/Manual, Heat/Cool, HVAC modes and a thermostat. The settings decide which objects the widget has; every send object it has is required, statuses are 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" }

Air conditioner

A split unit or VRV through its KNX gateway. Its type is 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" }

Connection

How the dashboard connects when it opens. Left out, it is automatic: it keeps any connection the app has, else uses the app's selected gateway, else searches.

The gateway object:

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

Plain JSON exports contain no keys or credentials. Both Plain JSON and With keys use the .json extension; Import detects protection from the file contents.

Password-protected JSON

With keys encrypts the entire payload. Its JSON container can be opened in a text editor, but the dashboard definition and keys must be decrypted before they can be read or changed. The export password is required to import it and is never saved.

Authentication also binds the content to SharKNX dashboard protected JSON v1. Incorrect passwords and tampered ciphertext cannot produce an imported dashboard. The selected file is limited to 32 MiB; the decrypted payload is limited to 16 MiB.

The decrypted payload has dashboard (the definition described in this reference) and, only for an owned key source, keys. An absent keys keeps Project automatic: the receiving app supplies its own security. An owned packet, even empty, becomes Imported keys, saved encrypted with this dashboard under a fresh local identity. Its source-project reference and export password never travel into app storage.

keys.groupKeys maps decimal KNX group-address numbers (0–65535, written as strings) to 32-digit hexadecimal keys. Only addresses used by the dashboard are kept. Optional keys.credentials contains devices for a configured secure gateway, with address, optional deviceAuthCode, and interfaces (userId, individualAddress, password); secure multicast instead carries backboneKeyHex and backboneSecurityEnabled. Tool Keys, unrelated addresses and gateways, and project names are excluded.

Automatic connection and Automatic project use the receiving app’s configuration. They never carry a snapshot of the exporting app’s connection or project. An owned-key dashboard with Automatic connection can carry its used group keys, but carries no gateway login. Project settings show Imported keys until Automatic or another project is saved; selecting a project also enables its address list and key refresh. Imported keys can be exported again.

Import is available under + → Add → Import dashboard. Success stays on Dashboards; a name match offers Import as copy or Replace. Import errors appear in a popup with a scrollable code section and Copy details.

Complete example

The example house: a Home with links to two spaces, a living room with two pages and a kitchen, a Moods scenes widget, two favourites and a configured 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" }
        ]
      }
    ]
  }
}

Validation

An import checks the whole file and lists every problem with its place in the file, e.g. $.home.rooms[1].tiles[3].status.address. A file with any problem is not imported; nothing is stored.

Limits

Versions

Every exported file starts with "format": 1. A file without it is read as the current format. A file with a higher number was made by a newer SharKNX and is not imported; update the app.

Files keep importing as SharKNX grows: new fields are added with defaults, so an older file simply lacks them, and a field never changes its meaning under the same name. A newer file in an older app loses only the fields that app does not know.