The dashboard file

A dashboard is one JSON file. It holds the connections to your devices and services, with their settings and credentials, the grid, and the screens with their tiles. The app writes it when you edit a dashboard; you can also write it or change it by hand, for example on a server’s admin page.

A field without a default may be left out. The app leaves out a value that equals its default when it saves.

{
    "schemaVersion": 4,
    "connections": {
        "home": {
            "driver": "homeassistant",
            "config": { "host": "192.168.1.10", "token": "your long-lived access token" }
        }
    },
    "grid": { "columns": 4 },
    "background": "#000000",
    "tileStyle": { "radius": 12 },
    "screens": [
        {
            "name": "Home",
            "tiles": [
                {
                    "type": "value",
                    "label": "Outside",
                    "layout": { "x": 1, "y": 1, "width": 2, "height": 2 },
                    "dataSource": {
                        "connection": "home",
                        "params": { "entity": "sensor.outdoor_temperature" }
                    },
                    "options": {
                        "numberFormat": "0.0",
                        "unit": "°C",
                        "gauge": { "min": -10, "max": 35 }
                    }
                }
            ]
        }
    ]
}

Connections and data sources

A connection is one device or service that the dashboard reads: a Home Assistant, a P1 meter, a Hue Bridge, Tilez Cloud’s weather. It is in the dashboard’s connections, under a name of your choice (home in the example above). It says which driver talks to it and, in config, how to reach it: its address, a key or a password. It is written once, however many tiles read it.

A data source is one thing a tile reads through a connection. It is in the tile: the connection’s name, and in params what to read there, such as an entity, a device and one of its values, a meter reading or a query. Which params a connection takes depends on its driver: see the driver’s page under Connections. The tile in the example reads the Home Assistant entity sensor.outdoor_temperature through the connection home.

• Many tiles, one connection: every tile that reads the same device names the same connection, each with a data source of its own. To move them all to another address or key, change only the connection.
• One tile, several data sources: a tile with one data source gives it as dataSource. A tile that reads more, such as a solar tile or a graph with several lines, names each in dataSources, and its options say which name is used for what, such as "load": "use" in the solar tile’s example. dataSource is short for the data source named primary, which is also the name an option takes when it is left out.
• No data source: a text, or a video with the camera’s address in its options, reads nothing.
• How often: a data source is read every refreshInterval seconds: its own, else its connection’s, else the driver’s own pace (AirGradient always keeps its own).
• Commands: a tile that changes something, such as a light, a switch or a thermostat, sends its command through its data source’s connection, to the device that data source reads.

In the editor you pick a connection and then, from what it lists, what to read: the editor writes the data source.

The file

Field	Type	Default	What
schemaVersion	4	required	Schema version. The version of this format; the app moves an older file up to it.
connections	object by name	{}	Connections. The devices and services the tiles read, by name, with their settings and credentials.
connections.<name>.driver	text	required	Driver. The built-in driver, for example influx or anna. Which there are: Connections.
connections.<name>.config	object	required	Settings. The driver’s own settings, its credentials included. Which settings a driver has: its page under Connections.
grid	object		Grid. The grid of every screen.
grid.columns	whole number, at least 1		Columns. Across the width; left out, 4 when rows is left out too, else 48.
grid.rows	whole number, at least 1		Rows. The grid fills the screen with them; left out, the grid is as tall as its tiles and scrolls, a row as high as a column is wide.
grid.margin	number, at least 0		Margin. From the screen’s edges, in pixels.
grid.spacing	number, at least 0		Spacing. Between tiles, in pixels.
background	colour		Background. Behind every screen’s tiles; black when left out.
tileStyle	object		Tile style. Every tile’s style, where a tile sets none of its own. Its fields: Tile style.
tileStyles	list		Own tile styles. Styles to pick for a tile, after the built-in ones.
tileStyles[].name	text	required	Name. What the style picker shows.
tileStyles[].type	one of value, graph, solar, thermostat, airquality, video, image, light, switch, action, table, status, forecast, text	required	Tile type. The type of tile it is for.
tileStyles[].shape	one of wide, square, tall		Shape. The tile shape it is made for; left out: any.
tileStyles[].style	object	{}	Tile style. Any of a tile style’s properties. Its fields: Tile style.
tileStyles[].options	object	{}	Look options. Look options of its tile type, as a tile’s options nest them. Which options a type has: its page under Tiles; the look options are marked.
screens	list	required	Screens. At least one; the first is shown first.
screens[].name	text	required	Name. In the side menu; a tap can go to the screen by its name.
screens[].icon	icon name		Icon. In the side menu, by its name in the icon set.
screens[].tiles	list	required	Tiles. Its tiles and groups. Each is a tile, below, or a group.

Every tile

What every tile has, besides its type and options, which are on the page of its type.

Field	Type	Default	What
id	name		Id. Unique in the dashboard; from its place in the file when left out.
label	text		Title.
titleIcon	icon name		Icon. By its name in the icon set.
layout	object	required	Place. On the dashboard’s grid.
layout.x	whole number, at least 1	required	Column. Where it starts, from 1 at the left.
layout.y	whole number, at least 1	required	Row. Where it starts, from 1 at the top.
layout.width	whole number, at least 1	required	Width. In columns.
layout.height	whole number, at least 1	required	Height. In rows.
dataSource	object		Data source. The tile’s one data source: short for dataSources.primary.
dataSource.connection	name	required	Connection. The name of one of the dashboard’s connections.
dataSource.refreshInterval	number, above 0		Refresh interval. Seconds between readings; the driver’s own when left out.
dataSource.params	object	{}	What to read. The driver’s own: a device, an attribute, a query. What a driver reads: its page under Connections.
dataSources	object by name	{}	Data sources. The tile’s data sources by name, which its options name.
dataSources.<name>.connection	name	required	Connection. The name of one of the dashboard’s connections.
dataSources.<name>.refreshInterval	number, above 0		Refresh interval. Seconds between readings; the driver’s own when left out.
dataSources.<name>.params	object	{}	What to read. The driver’s own: a device, an attribute, a query. What a driver reads: its page under Connections.
style	object		Style. Over the dashboard’s tile style. Its fields: Tile style.
styleName	text		Style name. The style picked for it, only to show it: the tile keeps its own style and options.
tap	object		Tap. What a tap does, for tile types without a tap of their own. One of: “Go to a screen”, “Send a command”.
tap.kind	screen	required	Go to a screen: Which kind it is.
tap.screen	text	required	Go to a screen: Screen. The screen a tap goes to.
tap.kind	command	required	Send a command: Which kind it is.
tap.source	data source name	required	Send a command: Device. One of the tile’s data sources, by name: a device that takes commands.
tap.command	command name	required	Send a command: Command. What a tap sends to the device.
tap.argument	text, number or true or false		Send a command: Argument. Sent with the command, if it takes one.

Groups

A group is a box with a title, drawn behind the other tiles of its screen: lay it under tiles that belong together. It holds no tiles itself. A new group gets a frame and no background ("style": { "background": "none", "border": "#3a3a3a", "borderWidth": 1 }).

Field	Type	Default	What
type	group	required	Which kind it is.
id	name		Id. Unique in the dashboard; from its place in the file when left out.
label	text		Title.
titleIcon	icon name		Icon. By its name in the icon set.
layout	object	required	Place. On the dashboard’s grid.
layout.x	whole number, at least 1	required	Column. Where it starts, from 1 at the left.
layout.y	whole number, at least 1	required	Row. Where it starts, from 1 at the top.
layout.width	whole number, at least 1	required	Width. In columns.
layout.height	whole number, at least 1	required	Height. In rows.
style	object		Style. Over the dashboard’s tile style. Its fields: Tile style.
styleName	text		Style name. The style picked for it, only to show it: the tile keeps its own style and options.

Tile types

Type	Tile	What
value	Value	A number with its unit, optionally on a gauge or with a graph.
light	Light	A light that a tap switches on or off.
switch	Switch	A device that a tap switches on or off, such as a socket.
status	Status or mode	A state as a text or an icon; with a command, a tap changes it, such as a thermostat’s or a charger’s mode.
text	Text	A text of its own, or a source’s value in words, such as a note or a device’s state.
action	Action	A button that sends one command, such as a scene; it shows no state.
forecast	Weather forecast	The next hours, the next days and nights, or the week, with warnings, from a weather connection.
graph	Graph	Readings over time, as lines or bars.
table	Table	Columns and rows of values and texts.
thermostat	Thermostat	The temperature and the set point, which a tap changes; a thermostat’s mode and state too.
airquality	Air quality	CO₂, fine dust and VOC, coloured by how good they are.
solar	Solar	The flow of power between solar panels, the grid, a battery and the house.
video	Camera	A camera stream.
image	Image	A still picture, such as a camera’s snapshot.

Connections

A connection’s driver says what it connects to; its page says which settings go in its config, and what a data source of it reads in params.

Driver	Connects to	What
airgradient	AirGradient	Air quality from the sensor’s local API.
demo	Demo home	A simulated home: lights, climate, solar and a battery, meters, a car charger, the weather and prices, without any device.
ebusd	eBUS heating (ebusd)	Zones as thermostats, hot water and the system of an eBUS heating controller (Bulex MiPro Sense, Vaillant sensoCOMFORT, …) through ebusd on the LAN, and any other eBUS value.
evcc	EVCC	Chargers, vehicles, solar, grid and dynamic prices from evcc, with its charge modes.
uconnect	Fiat, Jeep, Alfa Romeo, … (Uconnect)	Battery or fuel, range, charging and climate of Stellantis cars through the Uconnect cloud, with start charging and climate on and off.
homeassistant	Home Assistant	Entities of a Home Assistant, with live updates, and its services as commands.
homewizardp1	HomeWizard P1 meter	Power, energy and water from the local API (v1).
homey	Homey	Devices of a Homey Pro through its local API, with live updates.
hubitat	Hubitat Elevation	Devices through the Maker API, with live events from the hub.
influx	InfluxDB	InfluxQL queries over the v1 query API.
openweathermap	OpenWeatherMap	Current weather, forecasts by the hour, day and night, and week, and warnings (One Call API 4.0).
hue	Philips Hue	Lights, rooms, zones, scenes and sensors of a Hue Bridge, with live updates.
anna	Plugwise Anna	Thermostat and boiler readings from the Smile gateway.
renson	Renson Healthbox	Air flow, temperature, humidity, CO₂ and VOC per room of a Renson Healthbox 3.0 ventilation unit, from its local API, with a room’s boost.
casa-prices	Tilez energy prices	Day-ahead electricity prices for a zone from Tilez Cloud, as your contract prices them. Prices: Energy-Charts (Fraunhofer ISE), CC BY 4.0.
casa-weather	Tilez weather	Current weather, forecasts and warnings from Tilez Cloud, without a key of your own. Weather: OpenWeatherMap.
myvaillant	Vaillant, Bulex, … heating (myVAILLANT cloud)	Zones as thermostats, hot water and the system of a Vaillant group heating controller (Bulex MiPro Sense, Vaillant sensoCOMFORT, …) through its internet gateway and the brand’s cloud.

How to write colours, gradients, number formats, transforms and conditions: Values.