Inkhaus

Config reference#

Every key of config.yaml and secrets.yaml, with its values, default and effect. The key tables are checked against the program code by site/check.py. If you are new, read Getting started first.

Both files live in the root of the SD card. Examples to copy: config.example.yaml and secrets.example.yaml. Mistakes are reported with their place, for example tabs[0].widgets[2].entity (line 34): see Settings, Reading the Config row. The file may be at most 64 KB.

config.yaml#

Your dashboard. It contains no secrets.

version: 1
timezone: "CET-1CEST,M3.5.0,M10.5.0/3"
groups:
  downstairs_shutters: [cover.living_room_shutter, cover.kitchen_shutter]
tabs:
  - title: Living room
    landscape_columns: 4
    portrait_columns: 3
    widgets:
      - entity: light.living_room_ceiling
      - group: downstairs_shutters
        name: Downstairs shutters
      - entity: sensor.living_room_climate
        name: Living room
        size: 2x1
        attribute: temperature
        details: [humidity, dew_point]
        decimals: 1

Top level#

KeyValuesDefaultEffect
version1requiredThe file format version.
timezonePOSIX TZ stringCET-1CEST,M3.5.0,M10.5.0/3Time zone for the clock and the wake schedule.
sleep_screenblock, see belownoneOptional blocks of the sleep screen.
groupsmap of name: [entities]noneNamed entity lists. Names use a-z, 0-9, _. All members share one kind. Up to 16 each.
tabslist of tabsrequired1 to 16 tabs.

sleep_screen#

KeyValuesDefaultEffect
weathera weather. entity idnoneAdds the weather block.
calendara calendar. entity idnoneAdds the next event block.
notificationstrue or falsefalseAdds the notifications block (count and newest title).

Tabs#

KeyValuesDefaultEffect
titletextrequiredThe tab label.
widgetslist of widgetsrequiredUp to 24 per tab. A tab that does not fit splits into pages.
landscape_columns4 or 55Grid columns in landscape. With 4, wide widgets are 2 cells.
portrait_columns2, 3 or 42Grid columns in portrait.

Widgets, all types#

Each widget has exactly one of entity or group (except type: notifications and type: energy, which have neither).

KeyValuesDefaultEffect
entityentity id, domain.object_idnoneThe Home Assistant thing. Supported domains: cover, light, switch, automation, climate, sensor, binary_sensor, weather, vacuum, media_player, calendar, alarm_control_panel, lock.
groupa name from groupsnoneA widget for all members of the group. Needs name.
nametextthe Home Assistant nameThe label. Required for groups. Default Alerts for notifications.
sizeWxHdepends on the typeSee Widgets, Sizes. Sizes a type does not allow are corrected.
typesensor, cover, light, switch, automation, climate, binary_sensor, weather, vacuum, media_player, calendar, alarm_control_panel, lock, garage, notifications, energyfrom the entityPick the widget type yourself, for example type: sensor for person.alice. notifications needs no entity. garage is a cover entity shown as a garage door; a cover with device_class garage or gate becomes one without type.

Sensor options#

KeyValuesDefaultEffect
attributea-z, 0-9, _, up to 40 charactersthe stateShow this attribute instead of the state.
detailslist of up to 2 attribute namesnoneA details line (only at 2x1 and wider).
unittext, up to 8 charactersfrom Home AssistantReplaces the unit of the main value.
decimals0 to 3whole numbers as is, others 1 decimalRounds numbers.

Weather option#

KeyValuesDefaultEffect
forecasttrue or falsefalseAdds the next 3 days to a weather widget. Single entity only. Needs a wide tile; the size is raised.

Media player option#

KeyValuesDefaultEffect
arttrue or falsetrueShows the cover art of the playing track. false keeps the text-only tile and popup. Media player widgets only.

Lock and garage option#

KeyValuesDefaultEffect
confirmtrue or falselock: ask before unlocking only; garage: ask both waysWhether a tap asks before it acts. Lock and garage widgets only. Stopping a moving door never asks.

Alarm panel, lock and garage widgets are single-entity, 1x1 tiles (no group, no size). See Widgets.

Energy widget#

type: energy, no entity or group. At least one of usage and solar is needed. Size is always 2x1. name and size are accepted but not shown.

KeyValuesDefaultEffect
usagesensor idnoneThe consumption sensor, the top row (Used). A running total (total_increasing, such as a Shelly 3EM total) works: the widget shows the change since local midnight.
solarsensor idnoneThe solar production sensor, the second row (Solar). Same rules.
historyfalseonhistory: false switches the long press popup off.

Both sensors need long-term statistics in Home Assistant (any sensor with a state_class has them). Wh is shown as kWh.

Graph and history#

KeyValuesDefaultEffect
displaygraph or defaultdefaultgraph draws the history right on the tab. Sensor and binary sensor only, single entity, no attribute, not with history: false.
historyfalse, hours (history: 48), or a blockon, 24 hoursOptions of the graph and of the long-press popup. false switches both off.
hours1 to 72024How far back.
statisticmean, min, max, sum, changemean (sum for energy sensors)What a bar shows. Only with type: bar.
periodauto, hour, dayautoBar width. Only with type: bar. Hourly bars over more than 128 hours are an error.
minnumber below maxautomaticLowest value of the y axis.
maxnumber above minautomaticHighest value of the y axis.
sourceauto, history, statisticsautoWhere the data comes from. type: bar with history is an error.

Inside history:, type has its own values: auto, line, bar and step (default auto).

- entity: sensor.energy_today
  display: graph
  history:
    hours: 168
    type: bar
    statistic: sum
    period: day

Notes#

Size limits#

Tested on the device with the largest allowed dashboard (16 tabs of 24 widgets, 384 widgets, every widget type, long names, 25 % unknown ids): it boots, fetches the states in chunks of 40 ids, cycles tabs and takes taps for 19 minutes without a crash.

secrets.yaml#

Private: your Wi-Fi password and the Home Assistant token. Keep it off the internet. It is stored as plain text on the card, so treat the card like a key.

wifi:
  - name: Home
    ssid: "MyWifi"
    password: "secret"
    ha_url: internal
    static_ip:
      ip: 192.168.1.50
      gateway: 192.168.1.1
      subnet: 255.255.255.0
      dns: 192.168.1.1
  - name: Phone hotspot
    ssid: "MyPhone"
    password: "secret2"
    ha_url: external
home_assistant:
  internal_url: http://192.168.1.10:8123
  external_url: https://example.ui.nabu.casa
  token: "long-lived-token"
KeyValuesDefaultEffect
wifilist of 1 to 4 profilesrequiredIn priority order: the first one in range is used. A single profile without the list dash is also accepted.
name1 to 20 characters, uniqueNetwork 1, Network 2, ...The label shown in Settings.
ssid / passwordtextssid required, password optional (open network)Network name and password, inside quotes. Each profile needs a different SSID.
ha_urlinternal, external, autoautoWhich address to use on this network. external needs external_url.
static_ipblockDHCPA fixed IP address. All four fields are then required.
ip / gateway / subnet / dnsIPv4 addressesnoneThe static_ip fields.
home_assistantblockrequiredThe Home Assistant address and token.
internal_url / external_url / tokentextinternal_url and token requiredinternal_url starts with http:// or https://. external_url is optional and must start with https://. The token is a long-lived access token (see Getting started).
connectionblock (old format)noneOld format of the three rows above, inside config.yaml. It is an error once secrets.yaml exists.

← Sleep screenTroubleshooting →