inkBoard Configuration¶

These entries are provided by a base inkBoard installation. More may be added by integrations or even platforms.

Base Entries¶

The entries explained here below can be considered the basic entries.

`inkBoard`¶

The inkBoard entry configures some general settings for the dashboard. It is required.

class InkboardEntry

Sets some basic inkBoard functionality. Required, setup using the inkBoard config entry.

Map for inkBoard specific settings.

date_format: str = '%-d-%m-%Y'

Default format to use when representing dates.

Default may be device/region specific. This site can help giving your the correct format string from a date: https://www.dateformatgenerator.com/?lang=Python&q=17-09-2013

integration_start_time: duration = 30: Maximum time to allow integrations to run their start tasks before inkBoard continues to printing. Gets parsed to seconds, set to -1 for to wait until everything is set up. Keep in mind that setting this may cause issues with integrations. Default is 30.

integrations: Literal['all'] | tuple = (): List with integrations to load, if they do not have a config key defined (i.e. for custom elements)

main_element: str = None

The id of the element to use as a the main element.

If not set, the main_tabs will be used, which is the default.

name: str: The name to give the instance. Used for i.e. the name of the Device in Home Assistant

time_format: str = '%H:%M'

Default format to use when representing time.

Default may be device/region specific. This site can help giving your the correct format string from a time: https://www.dateformatgenerator.com/?lang=Python&q=11%3A11

`device`¶

The device entry is used to setup the device and platform. It is required. The platform key is required. Otherwise, see the documentation for the platform for the available options.

class DeviceEntry

Entry to setup the device, under the device config entry.

Dict to configure the device. Mainly important to import the correct device. If the emulator key is defined, inkBoard will automatically try and run as emulator using the device settings. This config entry accepts any optional arguments to allow for various platforms to be set up via this config.

model: str: Model of the device. May be required for some platforms, others don’t need it or can set it automatically.

platform: str: The platform (device type) the dashboard will run on, or that will be emulated. A list will be somewhere in the docs.

`screen`¶

The screen entry is used to set up the screen instance, which manages the dashboard. It is required.

class ScreenEntry

The entry that sets up the screen. Setup under the screen entry.

The screen manages the dashboard and handles the connection between it and the device.

background: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] = 'inkboard-background': The background of the dashboard. Can be an image file or a solid color.

background_fit: Literal['contain', 'cover', 'crop', 'resize'] = 'cover'

The method used to fit the background image on the screen.

Contain: makes the entire image fit on the screen, without changing the width/height ratio. Any leftover screen area is either filled up with the default screen color, or a color specified under ‘color’ in fit_arguments.
Cover: size the image to the smallest size to cover the entire screen without changing the width/height ratio, and crop out anything that is too large. Cropping is generally centered, but can be set using ‘centering’ in fit_arguments
Crop: Crops out a part of the image and resizes it to fit the screen area, without mainting the width/height ratio. Cropped out area defaults to the center area of the image that fits the screen. Otherwise, can be set using ‘box’ in fit_arguments (see documentation of tools.fit_Image for usage)
Resize: resizes the entire image to fit the screen area, without maintaining width/height ratio.

background_fit_arguments: dict = mappingproxy({})

Additional arguments to use when fitting the background.

See the Pillow documentation for what arguments what method accepts.

backlight_behaviour: Literal['Manual', 'On Interact', 'Always'] | None = 'Manual'

Determines how the backlight behaves when interacting with the screen. Requires a device with the backlight feature.

Manual and Always function almost the same, the difference being that the latter turns on the backlight when this setting is applied. Applying manual does not change the state. Using one of these values means the backlight has to be toggled manually, via i.e. elements.

On Interact means the screen will turn on the backlight when interacting with the screen (provided it is off). It will then keep the backlight on until backlight_time_on time has elapsed without any interaction.

backlight_time_on: float | duration = None

Time to keep the backlight on after the last interaction. Requires a device with the backlight feature.

Requires backlight_behaviour to be On Interact, otherwise does nothing. If None, the value will be left to the device and/or remain unchanged.

close_popup_time: duration = '1min': Default time after which popups will close automatically.

minimum_hold_time: duration = '0.5s': The minimum time to hold a touch before it is considered as being held.

on_interact: Callable[[dict, PSSMScreen, tuple[x, y]], None] | bool | None = None: Function to call for every interaction with the screen. Does not accept a dict like element actions yet, so shorthands have to be used directly.

on_interact_data: dict = mappingproxy({}): Any data to pass along to the on_interact function.

poll_interval: duration = '1min': Time between polling the device and its features states.

touch_debounce_time: duration = '1ms': The minimum time needed for a touch to register as valid. Workings may be dependent on the device’s features.

`logger`¶

The logger entry can be used to setup the logging interfaces of inkBoard. It is not required.

class LoggerEntry

This entry sets up the logging facilities of inkBoard, under the logger entry.

basic_config: mappingproxy[str, Any] | Literal[False] | None = False: Forcibly overwrite the basic logging config (i.e. the way logs are displayed). This is done before parsing the other logging options, so keep in mind you may overwrite settings.

level: int | Literal['NOTSET', 'VERBOSE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO': The base level for logging

log_to_file: mappingproxy[str, Any] | Literal[False] | None = False: Settings for logging to a file. This setting is ignored when running in the designer.

logs: mappingproxy[str, int | Literal['NOTSET', 'VERBOSE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']] = mappingproxy({}): Allows setting log levels for individual loggers

`substitutions`¶

The substitutions entry can be used to implement substitution in the configuration. It is not required. A substitution can be used later on in the config by referencing it via ${my_substitution}

Example:

substitutions:
   my_substitution: "Hello World!"

elements:
   - type: Button
     text: ${my_substitution}

`designer`¶

The designer entry can be used to configure specific settings when using the designer. It is not required.

class DesignerEntry

Additional settings for the designer. Setup under the designer entry.

Dict with settings for the designer, when developing new dashboards. Can also parse certain settings from the device key, like platform, if the key is present.

height: int = None: Optional height to give the screen. Overwrites device settings.

icons: MappingProxyType = mappingproxy({}): Optionally allows one to redefine the icons used for pssm elements in the element tree view, or set icons for their custom elements.

platform_validation: bool = True: Validates whether the device configuration is valid for the base platform.

width: int = None: Optional width to give the screen. Overwrites device settings.

Dashboard Entries¶

Dashboard entries are read out at a later point than the base entries. They are all used to define the elements and configure the last bits of the dashboard.

`elements`¶

Under elements, any kind of element can be defined. They are only validated for being an actual element.

`layouts`¶

Under layouts, inkBoard validates elements under this entry to be based on the Layout element. This helps in keeping your configuration organised by seperating single elements from their layout containers.

`popups`¶

Under popups, inkBoard validates that elements defined within are based on the Popup element. Also an entry to keep things organised.

`statusbar`¶

statusbar is used to setup the StatusBar element on the main dashboard element. Aside from the properties of a StatusBar, this entry also allows the keys size and location. It is not required, if the entry is not in the config, no StatusBar will be added.

size (DimensionString): specifies the size of the statusbar.
location (top, bottom, left, right): specifies the location of the StatusBar with respect to the main_tabs.

If not specified, the orientation property is automatically set based on the value of location.

`main_tabs`¶

main_tabs is used to setup a TabPages element that can be used to navigate through your dashboard. Under it you can simply setup all the properties for a TabPages element without specifying type.

Unless otherwise specified under the main_element key of inkBoard, this element will be used as the main element. If not overwritten in the element’s config, it can be accessed via the element id inkboard-main-tab-pages.

inkBoard Configuration¶

Base Entries¶

inkBoard¶

device¶

screen¶

logger¶

substitutions¶

designer¶