Skip to content

Latest commit

 

History

History
570 lines (379 loc) · 12.9 KB

Config.md

File metadata and controls

570 lines (379 loc) · 12.9 KB

Configuration

README | Documentation | Installation | Configuration | Panels | FAQ

Example Configuration

To get an idea of the configuration, take also a look into example configurations.

Common Configuration

For time and date formats see:

Babel Documentation https://babel.pocoo.org/en/latest/dates.html#date-fields

Python Documenation https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes

  • time_format string

    Time format

  • date_format string

    Date format

  • date_format_babel string

    Babel date format

time_format: "%H:%M"
date_format: "%A, %d. %B %Y"
date_format_babel: "full"

Device Configuration

device dict

  • name string

    The name of the panel device, defaults to received mqtt_name value

  • locale string

    The locale of the device

  • button_left_entity string

    The entity to use for button left. Default None.

  • button_right_entity string

    The entity to use for button right. Default None.

  • show_home_button bool

    Should the panels show a home button. Default False.

  • log_commands bool

    Should commands be logged. Default False.

  • home_on_wakeup bool

    Should the display exit the sleep/wakeup panel and return home directly after wakeup. Default False.

  • home_on_first_touch bool

    Should the display exit the sleep/wakeup panel and return home on first iteraction event or wait until touched again. Default True.

  • home_only_when_on bool

    Should the display exit the sleep/wakeup panel and return home only when the display state is on. Default False.

  • home_on_button_toggle bool

    Should the display exit the sleep/wakeup panel and return home when a button is toggled. Default False.

  • always_return_to_home bool

    Should the display always return to the home panel or should it restore the previous panel. Default False.

  • sound_on_startup bool

    Should a sound be played when the display is connected after startup. Default True.

    • sound_on_notification bool

    Should a sound be played when the display recieves a notification. Default True.

device:
  name: null
  locale: "en_US"
  button_left_entity: null
  button_right_entity: null
  show_home_button: false
  log_commands: false
  home_on_wakeup: false
  home_on_first_touch: true
  home_only_when_on: false
  home_on_button_toggle: false
  always_return_to_home: false
  sound_on_startup: true
  sound_on_notification: true

Navigation Configuration

navigation dict

navigation:
  page_timeout: 2.0

Notification Configuration

notification dict

notification: {}

MQTT Controller

mqtt dict

mqtt:
  topic_prefix: nspanel_haui/nspanel_haui
  • topic_prefix

Update Controller

The update controller is responsible for checking version informations and notify about any issues.

To enable update checks set an interval > 0 and/or set check_on_connect to true.

update dict

update:
  auto_install: True  # Install tft file automatically if no or a unknown tft file is installed
  auto_update: false  # Update automatically on new releases
  tft_filename: nspanel_haui.tft  # The asset filename to load
  check_on_connect: false  # Should be checked for updates when connected
  on_connect_delay: 60  # Delay between connect and check
  interval: 0  # Set to 86400 for daily checks
  • auto_install bool
  • auto_update bool
  • tft_filename string
  • interval int
  • check_on_connect bool
  • on_connect_delay int

Connection Controller

connection dict

connection:
  interval: null
  overdue_factor: 2.0
  • interval int
  • overdue_factor float

Gesture Controller

gesture dict

gesture: {}

Panels

panels list

panels:
  - type: panel_type
    ...

Config values:

# panel type (required)
type: panel_type  # for ex. weather, grid, etc.
# panel mode (Default: panel)
mode: panel  # string, panel, subpanel or popup
# internal identifier for panel
key: identifier  # string, can be used for navigation with navigate:
# title of panel
title: Panel Title
# is panel the home panel
home_panel: false
# is panel the sleep panel
sleep_panel: false
# is panel the wakeup panel
wakeup_panel: false
# show home button (Default: device config value `show_home_button`)
show_home_button: null
# single entity
entity: None
# multiple entities
entities: []
# unlock code for panel
unlock_code: null
# close panel after amount of time
close_timeout: null

See Panels Overview for more details about the different panels and configuration.

Panel Modes

A panel supports different modes:

  • panel Panel, that shows up in navigation (Default)
  • subpanel Subpanel, will not show up in navigation
  • popup Popup, will not show up in navigation

By default a panel will be used as a navigation panel.

Each panel configured will by default be included in the navigateable panels list. To not include a panel in the navigation, set mode to subpanel. When navigating to an panel that is not navigateable then this panel will be added to a stack, so that it is always possible to return to the last item navigated.

Entry Details, Popups, Settings, About and other special pages will not appear in navigation.

mode: panel

Accessing a panel

To be able to access a panel from within the configuration, the panel needs to have a key defined. By this key the panel can be accessed now for navigation by using navigation.key as an entity.

key: identifier

Closing a panel automatically

To automatically close a panel after some amount of time, set close_timeout to a value bigger than 0.

close_timeout: 2.0

Using a Panel as a Home Panel

home_panel bool

If not defined the first configured panel will be used. If defined, then the defined home panel will be used.

Only one panel can be a home panel

home_panel: true

Using a Panel as a Sleep Panel

sleep_panel bool

After page_timeout the sleep panel will be activated.

Only one panel can be a sleep panel

sleep_panel: true

Using Panel as a Wakeup Panel

wakeup_panel bool

wakeup_panel: true

When the display changes into dimmed state and a sleep panel is set or changes into sleep state and wakes up, then if no wakeup panel is defined, it will return to the home panel. If defined, it will return to the defined panel.

If no sleep occured but page was changed, it will return to the last active panel.

Only one panel can be a wakeup panel

wakeup_panel: true

Locking a Panel with a Code

unlock_code string

unlock_code: "1234"

Panels can be locked with a code. If a unlock_code is set, the panel will be only accessible after entering the unlock code.

Entities

HAUIConfigEntity is used internally to provide access to the entity from the config.

Basic values:

  • entity the entity id (ex. sensor.temperature)
  • name name override, a default entity name will be used if not set
  • value value override, a default entity value will be used if not set
  • icon icon override, a default entity icon will be used if not set
  • color color override, a default entity color will be used if not set
  • state state override, by default state will be used

the name, value, icon and color can also contain homeassistant template code. These values can contain mdi: icons which will be replaced by its unicode representations.

Entity State

haui_entity.get_state()

The state of the entity. By default, the state will be used. It is possible to override the state value by defining a state in config. If a string is set, the entity attribute with that name will be used. If a list is provided, the list values are being used as keys to get the state value from attributes.

# use attribute forecast condition as state of a weather entity
  - entity: weather.home
    state: ["forecast", 1, "condition"]

# use attribute temperature as state
  - entity: weather.home
    state: "temperature"

Entity Name

haui_entity.get_name()

The name of the entity. The name to be returned can be configured in different ways. By default it will return a value based on the entity. Either name or friendly name will be returned.

If a string is provided, this will be used as the name.

If a dict is provided and the entity state matches the dict key, then this name will be returned.

Accepts:

  • dict:

    state: value assignment based on current entity state

    - entity: switch.example_entity
  name:
    on: "name x"
    off: "name y"

  • str:

    name to use

    name: Name

Entity Value

haui_entity.get_value()

The entity value to display. The value to be returned can be configured in different ways. By default it will return a value based on entity state and type.

It is possible to override the value in the config of the entity.

If a string is provided, this will be used as a value.

If a dict is provided and the entity state matches the dict key, then this value will be returned.

Accepts:

  • dict:

    state: value assignment based on current entity state

    value:
  on: value x
  off: value y

  • str:

    value to use

    value: Text

Entity Icon

Icons Cheatsheet

haui_entity.get_icon()

Templating using HomeAssistant

name, value, icon and color can also be templated. The value needs to start with template:

  • template: home assistant template

Icon value type

  • dict:

    state: icon assignment based on current entity state

    icon:
  on: "icon_name_x"
  off: "icon_name_y"

  • str:

    icon to use

    icon: "icon_name"

Entity Color

haui_entity.get_color()

  • dict:

    state: color assignment based on current entity state

    Note: Use quotes for on and off to not prevent yaml to be interpreted as boolean.

    color:
  "on": [255, 255, 255]
  "off": "6339"

  • list, tuple:

    color to use as list with rgb values

    color: [255, 255, 255]

  • str, int:

    color to use as rgb565 number

    color: "6339"
color: 6339

Internal Entities

Internal entities begin with a keyword followed by : or just the keyword.

  - entity: skip
  - entity: text:Text to use as value
...
  - entity: navigate:key

Entity: skip

  • skip

    The entity should be skipped. This is the same as entity: null

    - entity: "skip"
- entity: skip
...
- entity: null

Entity: text

  • text

    Use the text instead of an entity, the text is available as the entity value text:Text to use

    - entity: "text:Text to use"

Entity: navigate

  • navigate

    Navigate to the panel with the key navigate:key

    - entity: "navigate:key"

Entity: action

  • action

    Action to execute

    Pass parameters using action_data

    - entity: "action:action_to_call"
  action_data:
    val: x

Override a default popup

popup_key string

popup_key: popup_media_player

A different than the default popup can be opened when executing by setting popup_key to the panel key to open.