The HABPanel user interface is installed by default when choosing any initial setup package, and allows the creation of user-friendly dashboards, particularly suited for (e.g. wall-mounted) tablets. These dashboards can be designed interactively in the embedded designer, rather than using configuration files.
Despite being similar, HABPanel’s dashboards and sitemaps are separate concepts, and can be designed independently as they aren’t related to each other; however, they rely and act on items which must therefore be defined first. The demo setup package, available for installation when starting openHAB for the first time, defines a series of sample items and configures HABPanel with a comprehensive set of dashboards to showcase a possible end result. It’s the same as the one installed on the openHAB Demo Server, and it may be modified without risk of breaking anything: it’s the best playground to discover HABPanel’s features.
HABPanel has its own terminology of entities presented below:
By default, when running HABPanel on a new browser or device, a tutorial will be displayed allowing the user to start from scratch, or switch to an previously defined panel configuration. Until a panel configuration is created (or chosen), HABPanel will run in “local storage” mode for this device: the settings will be retained in the browser’s local storage only and nothing will be persisted on the server. By contrast, when an active panel configuration is set, each change performed on the device will update the panel configuration on the server. This allows the sharing of panel configuration among devices, because other browsers and devices using this panel configuration will pick up the changes with a page refresh - this is useful for instance to design a panel comfortably on a computer, then use it on a tablet.
To switch from the local storage to a server-hosted panel configuration, go to the Settings page from the main menu or the side drawer (see below). A list of panel configurations will be presented in the Current storage configuration section; if only the “Local storage” option is available, click on the Save the current configuration to a new panel configuration link, give it a name to identify it (avoid spaces or special characters), and it should be added to the list. The radio button is also automatically checked, meaning it is now the active panel configuration.
Even when there is an active panel configuration, HABPanel uses the browser’s storage to sync a locally-managed copy. With the Edit the local panel configuration (experts only) link under the “Local storage” storage configuration option in the settings screen, the raw structure of the panel configuration can be inspected, modified, and exported or imported from/to a .json file. It is also an alternative way to backup, restore and share the configuration.
HABPanel uses service configuration variables to store its data on the openHAB server. They can be accessed using Paper UI (Configuration > Services > UI > HABPanel > Configure) or in the openHAB Karaf console:
openhab> config:edit org.openhab.habpanel
openhab> config:property-get <property>
The following properties are defined:
panelsRegistry
: contains the entire registry serialized in JSON, it is maintained by the application and shouldn’t be modified directly (editing it by hand, while possible, is strongly discouraged);lockEditing
: when enabled, all HABPanel instances will hide their editing features (a page refresh is necessary). When panels are complete and stable, it is advisable to turn on this setting so they cannot be easily modified by end users;initialPanelConfig
: if this option is unset and no prior local configuration is detected, the tutorial will be displayed until some dashboards are added or a panel configuration is selected. This setting allows to bypass the tutorial and switch directly to the existing panel configuration with the given name.The main menu is HABPanel’s home page. It contains tiles linking to the panel’s dashboards, and an icon to switch between the run mode and the edit mode (if available).
Use the gears icon in the top-right corner to switch between the two modes.
When in edit mode, several features are available:
The configuration dialog when clicking on a tile’s gear icon contains the following settings:
Setting | Description |
---|---|
Name | The name of the dashboard, also displayed on the tile |
Background URL | The URL of a background image for the main menu tile |
Backdrop Icon | Iconset and icon displayed on the tile as a Backdrop |
Center backdrop horizontally | When unchecked, the backdrop is aligned to the right of the tile; when checked, it is centered |
Icon | Icon associated with the dashboard, currently only used in the side drawer |
Size (icon) | (currently unused) |
Title Text Color | Color for the name of the dashboard on the tile |
Advanced tab | Contains settings currently unstable or buggy, for advanced users only |
It also contains a Delete button which will delete the entire dashboard and its contents - this happens immediately and cannot be undone!
The side drawer can be accessed from any screen by a swipe or drag to the right (on most elements where there isn’t a conflict with this gesture), or with the “hamburger icon” ☰ in the top-left corner.
It is comprised of three parts:
The dashboard designer is where widgets can be added, positioned, resized and configured. Placeholders are displayed where actual widgets would be on the running dashboard.
To add a widget, use the Add widget button and choose among the list of standard widgets, or eventual custom widgets in the panel configuration. See below for a description of the standard widgets.
Use the header of a widget placeholder (with the four-arrow icon and the widget type) to move the widget. Moving a widget over other widgets do not push them away to make room (contrary to the main menu tiles), so ensure there is sufficient room for your widget before moving it.
When hovering over a placeholder (or tapping inside it if on a touch interface), a chevron appears in the bottom-right corner allowing to resize it.
Use the ellipsis icon ⁝ to bring up the widget’s contextual menu, offering the following options:
Modifications to the dashboard are not saved automatically, use the Save button in the header to commit the changes to the panel configuration (or local storage). The Run button also saves, then runs the dashboard.
When a dashboard is running, widgets can be interacted with, and server-sent events are received when items’ states are updated, so widgets update automatically in HABPanel.
The icons in the top-right corner perform the following:
Apart from the storage configuration discussed above, the settings screen contains several settings kept as part of the panel configuration (meaning they are set separately):
Setting | Description |
---|---|
Panel name | An user-friendly name for the panel. It will be displayed in the header of the side drawer. |
Theme | HABPanel comes with a number of built-in themes, with this setting a different theme may applied to the panel. Themes are not user-modifiable. |
Background image | Sets the specified URL as background image for the whole panel. Tip: the background image works best with the ‘translucent’ theme! |
No clock on the home menu | (Deprecated) |
Prevent scrolling (when not editing) | When enabled, it is impossible to scroll the dashboard on a tablet (and it prevents the “elastic” bouncing effect on iOS/Safari) |
Manage > | Goes to the list of custom widget definitions for the active panel configuration |
Voice | Selects a voice from the detected list for text-to-speech* |
Speak the new value of the following item when it changes | When the selected String item change to a new text, HABPanel will use the browser’s text-to-speech engine and the selected voice to read it aloud* |
Display a floating speech button at the bottom of the screen | Use an alternative style for the Speak (voice input) button in dashboards |
When this item changes to a dashboard’s name, switch to it | This allows controlling the currently displayed dashboard by an openHAB item (useful with rules and as a side-effect to commands) |
*Note: the text-to-speech functionality featured in HABPanel is unrelated to the TTS services defined on the openHAB server, and they are not compatible (this is why a String item is required and the say()
function cannot be used). However, HABPanel will play audio streamed through the ‘webaudio’ sink, including spoken text.
The following built-in widgets are available:
The so-called dummy widget (whose name is explained by historical reasons - it evolved from the first developed widget) displays the current state of an item without any interactivity, along with a label and an optional icon.
The switch widget is a simple widget to control a Switch item as defined in openHAB - it reports its state and is able to toggle it between ON and OFF.
The label widget is straightforward: it simply displays a fixed text and has a few appeareance options (color, font). It can for example be used as a header for a group of widgets below it.
The button widget can be clicked (or tapped) and will perform an action, like sending commands to an item or navigating to another dashboard. It can also adjust its colors depending on the state of the underlying item.
Multiple buttons are often used together to present different options for an item.
The slider widget can reflect the state of, and update, numerical items within a range of values. Several options are available to alter its appearance and behavior.
The knob widget is similar in essence to the slider, but in a rotary fashion. It also offers extensive configurability over its appearance and behavior.
The color picker widget offers several ways of displaying and updating the state of an openHAB Color item (or group).
The image widget can display an image, directly or via an openHAB String item, and can refresh it at regular intervals.
The frame widget displays an external web page in a HTML <iframe>
.
The clock widget displays an analog or digital clock. It can also be used to display the current date.
The chart widget can leverage openHAB persistence services to plot numerical series over a time period. It can also display server-generated chart images (default or rrd4j variants).
The timeline widget is the chart widget’s counterpart for non-numerical items. It can display multiple “swimlanes” of items with color-coded slices representing their state changes during the selected period. Hovering or tapping inside a color slice displays details on the state of the item at the time.
The template widget allows an user-configured AngularJS HTML template to be rendered and hosted inside the widget boundaries; it exposes several helper functions and other facilities to retrieve and update openHAB’s items from the template’s markup.
Refer to the Developing templates and custom widgets section below for more information on template development.
Templates are defined inline, for each particular instance, and thus are not optimized for sharing and re-use. For those cases, developing a custom widget is more appropriate.
Custom widgets are similar to (and based on) the template widget but are designed to be reused, shared, and configured. A custom widget is an AngularJS template with an associated set of configuration settings. It can be added to dashboards and configured individually, like a built-in widget. Definitions of custom widgets are stored in the registry at the panel configuration level; this means they are specific to a panel configuration and each panel configuration has its own custom widgets (see the Concepts section above).
(Community thread about this feature)
The list of custom widgets either via the dashboard designer (click/tap the gears icon in the Add Widget dropdown menu), or with the “Manage” button in the settings screen.
From the list, custom widgets can be created from scratch, or imported from a previously exported .json file. Members of the openHAB community present their custom widgets on the forum. The Get widgets from the openHAB community link brings up a filtered lists of custom widgets from the community.
Once they are created, custom widgets can be exported to a .json file or deleted from the list using the context menu accessed with the ellipsis icon ⁝ on the tiles.
Upon clicking on a custom widget definition, the widget designer opens. It contains three tabs:
Code: This tab is an editor for the template’s code. You can use the Ctrl-S (or Cmd-S) keyboard shortcut to save the widget while editing the code;
Settings: This tab hosts the widget’s general settings and configuration settings structure to be defined.
Click on the Add setting to add a new configuration setting. Each configuration setting must have a type, a technical ID, and other optional attributes. Each type of setting determines the UI element presented in the dashboard designer when configuring instances of the custom widget.
Use the arrow buttons to move configuration settings up or down, and the trash bin icon to remove them.
When instantiated, the value of configuration settings are set in the template’s scope as config.<setting_id>
(except those of type Icon which define an additional value, the iconset name, as config.<setting_id>_iconset
);
Preview: Upon switching to this tab, a test instance of the widget is rendered in an otherwise blank testbed dashboard. Use the sliders to resize the widget in order to preview it at different sizes. If it defines configuration settings, they must likely be set for this preview using the gears icon: this will bring up the widget instance’s configuration dialog as it would appear in the dashboard designer.
Don’t forget to save the changes with the Save button.
This chapter will cover in detail how to write templates to build custom widgets. It is not yet written, in the meantime use the resources below: