How to Build a Dashboard

How to build a SharKNX dashboard in the app: spaces, pages and widgets, the editor, how a dashboard looks and runs, and how to share it.

A dashboard is a touch screen for a KNX installation: rooms with buttons, sliders and readings that send to and listen on group addresses. You build it in the app's editor, and you or your customer use it in Dashboard view. This guide assumes you know KNX basics (group addresses, datapoint types); it does not assume you know SharKNX.

Prefer a text editor? A dashboard is a JSON file you can also write by hand. See the Dashboard File Format reference and its examples.

Free plan: dashboards are included in every plan. Each command a dashboard sends counts toward the free plan's daily sends; the status reads when it opens do not. See Subscription Plans.

On this page

1. What a dashboard is made of
2. Start a dashboard
3. The editor
4. Spaces and pages
5. Adding widgets
6. A widget's form
7. Which widget for what
8. Making it look right
9. Connection, project and security
10. Running a dashboard
11. A dashboard for your customer
12. Sharing and backup
13. When something looks wrong

What a dashboard is made of

The app's main interface, with the Project, Monitor and other tools, is called Professional view. Dashboards live on the Dashboards page, the third tab in the bottom navigation bar.

Limits: 10 pages per space, 100 widgets per page, 8 levels of spaces below Home, 500 spaces and 5,000 widgets per dashboard, names up to 50 characters. See Limits.

Start a dashboard

On the Dashboards page, tap +:

• Create Dashboard opens the editor on a new, empty dashboard: Home with one page. Nothing is stored until you save it.
• Import dashboard reads a .json file, such as one exported from another device or one of the examples.

A saved dashboard's card has ▶ (Run, open it in Dashboard view) and ✎ (open it in the editor). Tap elsewhere on the card for all its actions - see Dashboards Page.

From an ETS project: with a project loaded in the app and a dashboard that has only Home, the editor's ⋮ → Create spaces from ETS builds the space tree from the project's buildings, floors and rooms (names, nesting and icons). It creates spaces only, each with one empty page; you add the widgets.

The editor

The editor is a model of the dashboard, not a live one: it sends nothing and reads nothing. Widgets show a sample look, and tapping one selects it instead of operating it.

On a phone:

• Top row: ✕ (Close editor), the space you are in (tap to go to another space), ⋮ (Dashboard settings) and Save.
• Bottom: Grid / Tree, Appearance, Select and + (Add).

On a tablet or desktop: the same controls, with Add, Grid, Tree, Appearance and Select in a rail at the side. From 840 dp wide, the top row shows the path to the current space (Home › Ground floor › Kitchen), and each step opens that space.

Grid and Tree are two views of the same dashboard. Grid shows the pages as they will look. Tree shows the structure: spaces, their pages and their widgets. In Tree you can drag spaces and pages to move them.

Saving is explicit. Nothing is saved until you tap Save. Closing with unsaved changes asks whether to Save, Discard or Cancel. Removals and moves offer Undo in their message.

Back goes to the space you were in before, as in a browser. Use ✕ to leave the editor.

Spaces and pages

Add → Space opens the New space form:

• Name, parent space, position and icon.
• Add navigation widget (on by default): places a link to the new space on the page you were on, so it can be reached from there. Turn it off for spaces you reach another way.

Add another creates the space and keeps the form open for the next one, with the same parent and icon. To make a numbered run at once (Room 1 to Room 12), use Multiple spaces….

The space menu (tap the current space's name) lets you browse spaces one level at a time and offers Add space, Edit space and Delete space. Deleting a space also deletes its sub-spaces, their widgets and every link to them, and offers Undo. Home cannot be deleted.

Pages: use the controls under the pages to add or remove a page (a space keeps at least one). In Tree, drag a page to reorder it or onto another space to move it there.

Links are not the hierarchy. A space link (navigation widget) can open any space, anywhere in the tree, and several links can open the same space. Deleting a link never deletes its space.

Adding widgets

Add → Widget (or the dashed Add widget slot after the last widget) opens the widget catalog, grouped by category:

Search finds a widget by name or description. Many entries are presets, a generic widget already set up for a purpose: Light switch is a Binary control with light names and icons, and Temperature is a Value status in °C. They open a form titled by the preset, with its choices made.

The widget is added to the page you are on, after its last widget.

Arranging: tap a widget to select it and open its actions: Edit widget, Duplicate, Move… (to another position, page or space) and Delete (with Undo). A space link also offers Open. To reorder by hand, long-press a widget and drag it; hold it at the side of the screen to carry it to the next page.

Select picks several widgets (or several spaces) at once, across pages and spaces, to duplicate, move or delete them together. You can also start it by long-pressing a widget and releasing it in place.

How a page is laid out: widgets fill the page row by row, in their order, each at the first place where it fits. A widget that does not fit the rest of a row starts the next one, and the gap stays: the editor shows it, and you close it by reordering or resizing. Widgets are never enlarged to fill space. The same layout serves every screen; a wider screen just has more columns.

A widget's form

Every widget has the same kind of form, in cards from top to bottom. On a phone it opens as a full page; on a tablet, in a sheet at the side.

A small ⓘ next to a field explains it.

Addresses

• Typing: three-level (1/2/3), two-level (1/515) or a plain number. The keyboard offers only digits and /.
• Picking from a project: with a project loaded, the magnifier opens its group addresses to search and pick. A picked address also fills in the widget's name and its type (for example, a window contact's Open/Close names and icon).
• Status suggestion: after you pick a switch address, the form may suggest the matching status address it found on the same device channel. Tap Use to take it; it is never filled in on its own.
• Several send addresses: a Binary control or Value control can send the same value to up to 10 addresses (Add address).
• Types are checked: an address whose datapoint type cannot work for the widget is marked and blocks saving. An address with no type set in ETS is always accepted.
• Read status on open (at the end of the KNX addresses card, with a status address): asks the status address for its value when the dashboard opens or reconnects. Turn it off for objects that cannot be read.

Status or no status? With a status address, the widget shows what the device reports, including changes made by wall switches, timers and central functions. Without one, it shows the last value written to its send address, by the dashboard or by anyone else on the bus. That's fine for simple loads, but it cannot see a change made on another address.

Adding and saving

• Add places the widget and closes the form.
• Add another places it and keeps the form open for the next one, keeping its settings but clearing the name and addresses, which identify one widget.
• Save (when editing) keeps the widget's place on the page.

A widget that still lacks something it needs, such as a required address, shows as Incomplete: Add and Save stay off until it is complete.

Which widget for what

Making it look right

Theme and buttons

The editor's Appearance button picks the dashboard's theme: Automatic (follows the device's light or dark mode), Light, Dark, Night, Great Wave, Sahara Dusk, Aurora or Neon City. It also picks how on-card Buttons look: Filled (a soft background) or Plain (glyphs only). The theme can also be changed later from Dashboard view.

Sizes

Each widget offers the sizes where it has something more to show, from 1×1 up to 4×2 (and 3×3 for some). A bigger card shows more: a dimmer's 1×1 shows its level, a 3×1 adds a drag strip, and a 2×2 adds the slider or − +. Pick sizes in General; the preview shows the result. A row of four cells fills a phone's width.

Sections

A Section (in Layout) is a title over the widgets after it, up to the next section. It always takes a row of its own. Give it an icon and a color. Turn on Collapsible to fold and unfold its widgets with a tap in Dashboard view; it always opens unfolded.

Colors

By default every widget takes its colors from the theme. Open a widget's Appearance card to give it its own:

• Card color: the card's background, in every state.
• On color and Off color (widgets with an on state) or Icon color (the others): the icon, the state text, and the outline while on. The widget's buttons and slider take this color too.

Each one offers Theme, seven named colors, or Custom (any color, picked on a color field or typed as #RRGGBB):

• Named colors follow the theme. A Blue card is the theme's card tinted toward blue: light blue in a light theme, deep blue in a dark one. A named icon color takes a light or dark shade, whichever reads on its card.
• Custom colors are exact, the same in every theme.
• Text and buttons adjust automatically: on a card color, text turns white or black when the theme's would not read, and buttons whose color would not read take a shade of the card's own color instead.

Color tips:

• Give each room, or each group under a section, its own card color, so a space reads at a glance.
• Keep accents for meaning: one On color for all lights, another for heating.
• Check custom colors in the preview, especially a dark card in a light theme.

Connection, project and security

The editor's ⋮ opens Dashboard settings: Name, Connection, Project, Security, and Create spaces from ETS. Changes apply when the sheet closes.

Connection

How Dashboard view reaches the bus each time it opens:

If the app is already connected somewhere else when the dashboard opens, it asks whether to Keep current or Switch. Leaving the dashboard leaves the connection as it is.

Credentials (secure tunnelling passwords, the backbone key) are set up in Professional view, never in the dashboard - see Set Up KNX IP Secure.

Project and security

The dashboard itself has no security settings. The app encrypts and decrypts Data Secure addresses with the keys it has loaded.

• No project (default): the editor picks addresses from the project open in the app, and the dashboard uses whatever security the app has loaded.
• This dashboard's project: pick an ETS project from the Archive. The dashboard keeps its own copy of the project's Data Secure group keys and IP Secure credentials, encrypted on the device. When it runs on an app with nothing loaded, the keys are installed silently. If something else is loaded, it asks to Unload that or Keep current. Whatever it installed is removed when the run ends.

The Security row shows what the dashboard has (secure addresses, tunnels, backbone key) and whether it matches the connection.

A secure address whose keys are missing never updates. It does not cause an error, so check Security when a secure widget stays unknown. See KNX Data Secure.

Running a dashboard

Tap ▶ Run. Dashboard view opens at once, full screen, and connects in the background. Values fill in as they are read and heard: the page on screen first, then the rest of the dashboard.

Operating widgets

• Lights and switches: a tap toggles. On a light with a dimmer, color or white control, tap the icon to switch it and the rest of the card for its controls.
• Scenes and space links: a tap recalls the scene or opens the space.
• Everything else: sliders, − + and buttons work on the card where it shows them; a tap elsewhere on the card opens its control sheet, which holds the widget's full set of controls: presets, a typed value, every mode.
• Readings do nothing on a tap.

A card with a status address shows ? until the status answers; one without starts from a default (Off, 0 %) until something is sent to its address. Two marks may appear at its corner: ! when the gateway rejected the last command, and a broken link when its status address does not answer.

The dock

The bar at the bottom holds ⌂ (Home), ☰ (spaces; a sidebar on tablets) and ⚙ (settings), plus the connection status on tablets (top right on phones): a green link when connected, amber while connecting, a broken link when not connected. Tap the status for the gateway page, with Reconnect.

⚙ Settings: Gateway, Appearance (theme and buttons, saved at once), Keep screen on, Arrange widgets, and Back to Professional view.

The bell at the top lists the run's notifications (Activity): commands the gateway rejected, connection lost and restored, addresses that never answer. Mute notification banners keeps them in Activity only.

Favourites, dock shortcuts and arranging

Arrange widgets (in ⚙, or long-press an empty part of a page) lets the dashboard's user tidy it without the editor:

• Drag a card (long press) to reorder it, or to another page of the same space. Dropping it after the last page makes a new page.
• Tap a card for Add to Favorites and Add to dock.
• Undo and Done are at the top.

Favourites appear as their own page, before every space's first page (★ in the page dots). On that page, drag to reorder them.

Dock shortcuts put up to 6 widgets in the dock as icons. A shortcut does what its card's tap does: a light toggles (and lights up while on), a scene recalls, a dimmer or thermostat opens its control sheet. On a narrow phone the last slot becomes ⋯ for the shortcuts that don't fit.

Changes made in Dashboard view (theme, keep screen on, arranging, favourites, dock) are saved in the dashboard. Adding, editing and deleting widgets stay in the editor.

A dashboard for your customer

For a wall panel or a customer's tablet:

1. Build and save the dashboard, and run it once to check every widget.
2. Use Configured gateway if the device should always connect to one gateway, or keep Automatic to use the app's.
3. For a Data Secure or IP Secure installation, choose This dashboard's project so the dashboard carries its keys.
4. On the Dashboards page, open the dashboard's actions → Open at app startup. The app then opens this dashboard as its only screen. Optionally set a PIN to leave (4 or 6 digits).
5. Turn on Keep screen on in Dashboard view's ⚙ for a panel that should never sleep.

The PIN is asked before Back to Professional view. It is not security; it only keeps the dashboard from being left by mistake.

Forgotten PIN: hold ⌂ (Home) in the dock for 20 seconds. The PIN is removed and Professional view opens. The dashboard still opens at startup.

Sharing and backup

Export (in the dashboard's actions on the Dashboards page) saves a .json file:

• Plain JSON: the dashboard as an editable file, with no keys or passwords. Use it for backups, for sharing a design, or to edit by hand.
• With keys: the dashboard plus the Data Secure keys of the addresses it uses and the credentials its connection needs, encrypted with a password you choose. Use it to hand a secure installation's dashboard to another device.

Import dashboard (under + on the Dashboards page) reads either kind; a protected file asks for its password. If a dashboard with the same name exists, choose Import as copy or Replace. If the file has problems, a list explains each one, with Copy details.

The format is described in full in the Dashboard File Format reference.

When something looks wrong

Related

• Dashboards Page - the tab where dashboards and hunts are kept
• Dashboard File Format - every field of the JSON file, with examples
• Load an ETS Project - for picking addresses and Create spaces from ETS
• Limits - spaces, pages, widgets and dock shortcuts