Configuration

Introduction

The entire appearance and functionality of the SmartHomePanel dashboard are defined in a single, well-structured XML configuration file.
This file must be named config.xml and placed in the application's root directory.
The file controls communication settings (binders), panel layouts, navigation, and all widget behavior.

Root Element

<?xml version = "1.0" encoding = "UTF-8"?>
<smart_home_panel_config>
...
</smart_home_panel_config>

Tag	Description
smart_home_panel_config	The mandatory root element for the configuration file.

Communication Configuration

This section defines the communication backend systems that will be used by the panels for communication.

MQTT (<mqtt_config>)

   <mqtt_config>
      <client
         id = "main"
         server = "ssl://192.168.111.222:8883"
         client_id = "SmartHomePanel"
         ca =   "/etc/SmartHomePanel/certs/ca.crt"
         cert = "/etc/SmartHomePanel/certs/client.crt"
         key =  "/etc/SmartHomePanel/certs/client.key"
      />
   </mqtt_config>

Tag	Description
mqtt_config	Container for all MQTT client definitions.
client	Defines a single MQTT connection.

client Attributes	Description
id (mandatory)	A unique identifier for this client (e.g., "main"). Used to reference this connection in actions and sources.
server (mandatory)	IP address or hostname of the MQTT broker (e.g., "192.168.111.222").
client_id (mandatory)	The MQTT Client ID used to connect to the broker (e.g., "SmartHomePanel").
ca (optional)	Path to the Certification Authority (CA) certificate file for secure connections (TLS/SSL).
cert (optional)	Path to the client certificate file for mutual authentication (TLS/SSL).
key (optional)	Path to the client private key file for mutual authentication (TLS/SSL).

🎨User Style Configuration

This section defines the user-defined styles.

Style Configuration (<style_config>)

<style_config>
    <style
        id = "example_flat_style"
        type = "flat"
        text_scale = "1.5"
        valign = "top"
        halign = "center"
        border_size = "2"

        text_color = "#FFFFFF"
        indicator_color = "#00FF00"
        control_color = "#0000FF"
        background_color = "#000000"
        on_color = "#FF0000"
        off_color = "#888888"
        thing_color = "#FFFF00"
    />
    </style_config>

Tag	Description
style_config	Container for all user style definitions.
style	Defines a single, reusable style template that can be applied to widgets.

style Attributes	Description
id (mandatory)	A unique identifier for this style (e.g., "example_flat_style"). Used when applying the style to a widget.
type (mandatory)	Specifies the visual rendering type for the style (e.g., "native", "flat").
text_scale (optional)	Factor to proportionally increase or decrease the font size.
halign (optional)	Specifies the horizontal position of the widget's content (e.g., left, center, right).
valign (optional)	Specifies the vertical position of the widget's content (e.g., top, middle, bottom).
border_size (optional)	Thickness of the widget's frame border, measured in pixels or grid units.
text_color (optional)	Color of the widget's text and foreground content.
indicator_color (optional)	Primary color for non-clickable (display-only) parts of the widget.
control_color (optional)	Primary color for clickable (interactive) parts of the widget.
background_color (optional)	Color of the main widget background area.
on_color (optional)	Color for the active (ON) state, or the slider track segment between the minimum and the knob.
off_color (optional)	Color for the inactive (OFF) state, or the slider track segment between the knob and the maximum.
thing_color (optional)	Color for the main decorative element, such as the slider's knob/thumb or the switch's inner symbol.

Graphical User Interface (GUI) Configuration

This section defines the visual structure of the dashboard.

<gui_config>

   <gui_config home = "panel-1">
   ...
   </gui_config>

Tag	Description
gui_config	The main container for the dashboard layout.

gui_config Attributes	Description
home (mandatory)	The id of the panel that will be loaded as the application's starting (home) screen (e.g., "panel-1").
text_scale (optional)	Specifies the font size as a fraction or multiple of the base font size, e.g.: a value "0.5" results in a font size that is half the standard base size.

<panel>

   <panel id = "panel-1">
   ...
   </panel>

Tag	Description
panel	Defines a single screen in the dashboard.

panel Attributes	Description
id (mandatory)	A unique identifier for the panel, used for navigation (e.g., "panel-1").
text_scale (optional)	Specifies the font size as a fraction or multiple of the base font size, e.g.: a value "0.5" results in a font size that is half the standard base size.

Widgets and Controls

Elements placed inside a <panel> define the user interaction points. All widgets use a grid system for positioning.

   <panel id="panel-1">
      <button position = "0, 0" size = "1, 1" text = "Button">
         <action>
            <mqtt id = "main" topic = "SmartHomePanel/Button/state" on = "down" off = "up" lost = "lost"/>
         </action>
      </button>
      <text position = "1, 0" size = "1, 1" text = "Label">
         <source>
            <mqtt id = "main" topic = "SmartHomePanel/Text/value"/>
         </source>
      </text>
   </panel>

Widget Tag	Description
label	Static text display.
button	A clickable element that performs one or more actions.
switch	A toggle button (on/off state).
slider	An interactive control element that allows a user to select a value from a continuous range by moving a thumb along a track.
stepper	A clickable element to present, decrease and increment value.
text	Dynamic text that displays a value from a source (e.g., MQTT topic).
webview	Embeds external web content into the panel.

Common Widget Attributes

Attribute	Description
position (mandatory)	Grid coordinates as "x, y" (e.g., "0, 0").
size (mandatory)	Widget size in grid units as "width, height" (e.g., "3, 1").
id (optional)	The id of the widget that will be used for logging errors, warnings, and information messages related to its operation. This attribute is not used for internal control logic but solely to facilitate tracing and debugging by providing a clear identifier in system logs,
text (optional)	The string to be displayed on the widget (e.g., button label or static label content).
text_scale (optional)	Specifies the font size as a fraction or multiple of the base font size, e.g.: a value "0.5" results in a font size that is half the standard base size.
valign (optional)	Available only for the <label> and <text> widgets. Specifies the vertical alignment of the text within the widget cell. Accepted values are: "top", "bottom", or "center".
value (optional)	Initial value used by interactive and presenting widgets, until the source provides current value.
orientation (optional)	Defines the arrangement of the widget elements on the screen. See details in the table below.
range/step (optional)	Used by interactive widgets, e.g.<stepper>, to map between the displayed value and values provided by source and consumed by action.
strategy (optional)	Defines when the widget data is sent: "final" (after the widget is released) or "continuous" (with every change while active).
unit (optional)	Text to be appended to the displayed value; this text is not sent with the widget's action.
url (conditional)	Required for the <webview> widget. Specifies the full URL of the external web content to be displayed (e.g., "http://192.168.1.10/camera/stream").

📐 orientation Layout Options

Layout Name	Accepted Values	Description
Linear Layout	"horizontal", "vertical"	Standard arrangement for widgets that primarily stretch in one direction
Compact Layout	"top", "horizontal", "bottom"	Arrangement for widgets containing a main value display and adjacent control buttons (e.g., the value displayed with +/- buttons placed above/below/alongside).

🗺️ Widget to Layout Mapping

Widget	Applicable Layout
slider	Linear Layout
stepper	Compact Layout

Actions and Sources

These nested tags define what a widget does (<action>) and where it gets its data (<source>).

<action>

   <action>
   ...
   </action>

Tag	Parent	Description
action	Widget	Defines one or more operations to be executed upon user interaction (e.g., button click).

Navigation Actions (<nav>)

   <action>
      <nav cmd = "goto" target = "panel-2"/>
   </action>

Tag	Parent	Description
nav	action	Performs a panel navigation command.

nav Attributes	Description
cmd (mandatory)	The navigation command: goto (direct jump), home (return to the home panel), gosub (jump and remember return panel), return (return from gosub).
target (conditional)	Required for goto and gosub. The id of the destination panel.

MQTT Actions (<mqtt>)

   <action>
      <mqtt id = "main" topic = "SmartHomePanel/Button/state" on = "down" off = "up" lost = "lost"/>
   </action>

Tag	Parent	Description
mqtt	action	Sends a command/value over MQTT.

mqtt Attributes	Description
id (mandatory)	The id of the MQTT client defined in <mqtt_config>.
topic (mandatory)	The MQTT topic to publish the message to.
on/off (optional)	Value to send when a <switch> or <button> is activated/deactivated.
lost (optional)	Value to send when a <button> is released after the pointer/finger moved outside of the button's boundary. This allows for canceling or resetting an action.
range/step (optional)	Used by <stepper> to map the stepper value to the MQTT payload.
retained (optional)	Specifies whether the message should be retained by the MQTT broker after being sent. Accepts "true" or "false" (default).

<source>

   <source>
   ...
   </source>

Tag	Parent	Description
source	Widget (text)	Defines the origin of the data to be displayed.

MQTT Sources (<mqtt>)

   <source>
      <mqtt id = "main" topic = "SmartHomePanel/Button/state" on = "ACTIVE" off = "INACTIVE"/>
   </source>

Tag	Parent	Description
mqtt	source	Listens for data on an MQTT topic.

mqtt Attributes	Description
id (mandatory)	The id of the MQTT client.
topic (mandatory)	The MQTT topic to subscribe to for updates.
on (optional)	The string value (payload) received from the topic that should be interpreted as the widget's 'ON' or active state. Used by stateful widgets like <switch>.
off (optional)	The string value (payload) received from the topic that should be interpreted as the widget's 'OFF' or inactive state. Used by stateful widgets like <switch>.
range (optional)	Used to scale incoming data (e.g., for <stepper>).