v2018-12-14 Written by Seb Francis seb303 on Loxone English Google Group Browser support Configuration Change log To-do list
This software requires a modern browser that supports WebSockets. It has been tested extensively with Firefox, and is also expected to work perfectly with Chrome and Safari. It will probably also work with Internet Explorer, but not with the example config.js due to the use of `back-ticks` to enclose blocks of HTML. This syntax requires Firefox 34+, Chrome 41+, Safari 9+, Opera 28+ and is not currently supported by Internet Explorer. An alternative syntax is to use 'single quotes' and a back-slash at the end of each line.
All configuration is done in config/config.js and config/config.css
When upgrading to a new version, keep the existing config directory and replace all other files.
config.js contains a single global object 'config' which has the following properties:
miniserver
The hostname or IP (and optional port) of the Miniserver.
credentials
The credentials to connect to the Miniserver in the form <username>:<password>
tabs
Definition of each tabbed page of the interface.
tabs: [
{
id: <unique id>,
name: <display name>,
type: <tab type>
},
...
]
The unique id must contain alphanumeric characters only.
The display name can contain inline HTML markup if desired.
The tab type can be either 'general', 'lighting' or 'external'. The tab contents are defined in the corresponding properties, described below.
The stylesheet definition for the tab contents can be placed in config.css, and any images in the config directory.
defaultTab
Id of tab to show on first load.
general
Definition of each general tab.
general: {
<tab id>: {
html: `<inner html of the tab>`
},
...
}
Note that the use of `back-ticks` to enclose multiple lines of HTML is only supported by recent browsers, and currently not Internet Explorer. An alternative syntax is to use 'single quotes' and a back-slash at the end of each line.
Each HTML element where data values should be displayed/controlled is defined by the following attributes.
INPUT and SELECT elements can be used, to send control data to the Miniserver.
data-control="control name"
Control name as defined in the Loxone config.
Push-button and Switch controls are supported, as well as InfoOnly controls.
data-room="room name"
Optional room name - can be necessary if "control name" is not unique.
data-cat="category name"
Optional category name - can be necessary if "control name" is not unique.
data-display="display type"
Optional, defaults to "value". Possible values:
value Display a value (can be a numeric value, text or icon).
Formatting depends on the Loxone config or data-function.
bar Display a numeric value overlaid on a bar indicator.
chart Display a mini chart of the current day's values.
When clicked, it loads a large chart.
output Used in connection with input range element (see below).
data-addplus
Optional. Add a plus sign in front of a positive numeric value.
data-function="name of Javascript function to format value"
Optional. By default the formatting depends on the Loxone config.
The function needs to be defined in the config object in config.js
The raw value is passed to the function, and the value returned is displayed.
e.g. To turn a comma separated text string into a bulleted list:
formatAsList: function(v) {
try {
return '<ul><li>'+v.replace(/, /g, '<li>')+'</ul>';
}
catch (e) {
return v;
}
}
data-keys
Defines shortcut keys for INPUT and SELECT elements. Possible values:
number Number keys will focus the input element, to be able to enter a numeric value.
enter Enter/Return key operates control.
<chars> Sequence of 1 or more individual characters operates control.
For data-display="bar"
data-barscale="ratio of bar length in pixels to value"
Optional, defaults to 1.
e.g. For a 150px long bar & value range 0-100, use 1.5
The bar and value are inserted as separate divs with class "bar" and "barvalue" as follows:
<div class="bar" style="width:...px;"></div><div class="barvalue">...</div>
The CSS to display the bar and value appropriately needs to be defined in config.css
For data-display="chart"
data-chartrange
Optional. Indicates element where the time range of the mini charts should be written.
e.g. at 9pm, this will be: 0:00-21:00
This should be a separate HTML element, not containing anything else.
data-chartcontrols
Optional. Indicates element where the mini charts controls should be written.
This allows to change the day displayed, and shows the current date & time range.
This should be a separate HTML element, not containing anything else.
data-largechartinitialrange="number of days"
Optional, defaults to 7.
Number of days to show initially in large chart.
data-largechartmaxrange="number of months"
Optional, defaults to 13.
Maximum number of months to load in large chart.
data-chartvalueset="value set"
Optional. Only applicable for statistics with multiple value sets.
Specifies which value set to plot on the chart (1, 2, 3, etc.)
If ommitted then all value sets are plotted on the same chart.
data-chartwidth="width in pixels"
Optional, defaults to 75
Specifies width of mini chart in pixels
Looping over multiple rooms
data-looproom="comma separated list of rooms"
The HTML element and descendants will be repeated for each of the rooms, with
the descendant elements evaluated as if data-room="room name" were present.
Do not insert any spaces either side of the comma unless they are actually
present in the room name.
data-thisroom
Used in a descendant of a data-looproom element.
The descendant element will be populated with the room name.
data-suppresserrors
Will suppress any error message if a control isn't found. Useful within a room loop
if not all rooms have every control. It can also be used outside of a room loop.
Support of INPUT and SELECT elements
There is partial support for use of form elements to send control data to the Miniserver. The following elements/types are supported:
<input type="text">
Sends numeric or text value.
<input type="radio">
Use with a Loxone Radio Buttons block. A single HTML radio element will be automatically be expanded according to the Loxone config data, and can be styled as needed in config.css.
e.g.
<input type="radio" data-control="Loxone Control Name" data-keys="abc">
=>
<div id="[uuid]-Container">
<div>
<input type="radio" id="[uuid]" value="1">
<label for="[uuid]">
<span class="radiolabeltext">Loxone Button Description 1</span>
<span class="radioshortcut">A</span>
</label>
</div>
<div>
<input type="radio" id="[uuid]" value="2">
<label for="[uuid]">
<span class="radiolabeltext">Loxone Button Description 2</span>
<span class="radioshortcut">B</span>
</label>
</div>
<div>
<input type="radio" id="[uuid]" value="3">
<label for="[uuid]">
<span class="radiolabeltext">Loxone Button Description 3</span>
<span class="radioshortcut">C</span>
</label>
</div>
</div>
<input type="range">
Use with Loxone faders, virtual inputs, etc. The min, max and step attributes of the range control are set according to the Loxone config data.
An optional output element can be included in the html to display the current value of the control.
e.g.
<output data-control="Loxone Control Name" data-display="output"></output>
<input type="checkbox">
Use with Loxone digital/switch controls.
<input type="button">
Use with Loxone digital/switch controls. The input element gains class "active" when it is on (which can be styled as needed).
<select></select>
Use with Loxone Lighting Controllers (v1 or v2). The OPTION elements are automatically created from the lighting scenes/moods.
lighting
Definition of each lighting tab.
lighting: {
<tab id>: {
img: 'config/<image filename>', // Background image
imgsize: [x, y], // Array of x,y dimensions of background image
lights: [ // Array defining lights
{
areas: [ ['rect', x1, y2, x2, y2, class], ['circle', x, y, radius, class], ... ], // class is optional
room: <room name>, // Room name (required)
cat: <category name>, // Category name (optional)
control: <control name>, // Name of simple control or Lighting Controller (required)
subcontrol: <subcontrol name>, // Name of subcontrol of Lighting Controller (optional)
subcontrolonly: <boolean>, /* If present and true, the controls for the parent
Lighting Controller will not be shown. This might
be desirable if, for example, the Lighting Controller
has only a single subcontrol. (optional) */
group: 'Group name' // Name of group to which this light belongs (optional)
},
...
],
groups: { // Object defining additional control for groups of lights
'Group name': {
room: <room name>, // (required)
cat: <category name>, // (optional)
control: <control name>, // (required)
subcontrol: <subcontrol name>, // (optional)
subcontrolonly: <boolean> // (optional)
},
...
]
detectors: [ // Array defining detectors (PiR sensors, etc.)
{
areas: [ ['rect', x1, y2, x2, y2, class], ['circle', x, y, radius, class], ... ], // class is optional
room: <room name>, // Room name (required)
cat: <category name>, // Category name (optional)
control: <control name>, // Name of controller (type InfoOnlyDigital) (required)
},
...
],
),
...
}
The background image will be scaled to fit the width of the browser window, so a higher resolution image is best.
The background image dimensions define the size of the coordinate area within which the light shapes are placed.
Each light is defined as one or more areas on the background image, linked to a Loxone control. Rectangle and circle shapes are supported, with the former being defined by the corner coordinates, and the latter by the centre coordinate and radius.
Lights can also reference a group which links to an additional Loxone control, such as an overall brightness dimmer for example. Each group control is defined in the 'groups' object.
Each detector is defined as one or more areas on the background image, linked to a boolean Loxone control (of type InfoOnlyDigital). The area shows the current on/off status of the detector. Rectangle and circle shapes are supported, as with a light.
Optionally, a CSS class name can be specified for the light or detector areas, to override default styling as needed. Example CSS to define custom off and on colours:
.classname {
background-color: pink; // Off colour
}
.classname.on {
background-color: red; // On colour
}
When the mouse is hovered over one of the shapes that represents a light, the relevant user interface elements appear, according to the type of control:
Switch: on/off button
Dimmer: fader + on/off button
RGB: colour picker
Lighting Controller: list of scenes + the element(s) for the subcontrol if specified
If a light is assigned to a group control then the relevant user interface elements for this will be appended.
external
Definition of each external tab.
external: {
<tab id>: {
url: <external url>, // URL of external user interface (required)
wol: { // Loxone control to send Wake-on-LAN to external device (optional)
room: <room name>, // (optional)
cat: <category name>, // (optional)
control: <control name> // (required)
}
unload: <timeout in seconds> // Unload timeout (optional)
}
}
External tabs host other browser-based user interfaces. This could be an external media server for example, or the primary Loxone interface. Optionally, a Loxone control can be specified which sends a Wake-on-LAN signal to the external device when loading the tab.
If the parameter 'unload' is present then the user interface is unloaded after the specified number of seconds when the tab is inactive. Otherwise, the interface will be left loaded in the background which may prevent the external device going to sleep.
Changelog for v2018-12-14: - INPUT and SELECT elements can now be added to general tabs to act as controls - Fixed bug where minichart with no data would block subsequent minicharts from loading - Fixed minicharts for newer Loxone versions that miss out data values where data hasn't changed - Added support for controls of type ValueSelector - Added "class" parameter for lights and detectors on lighting tabs - Pushbutton controls now work within lighting tabs (thanks to Jezierski.IT) Changelog for v2018-09-18: - Made connection to Miniserver more resilient/persistent in case of network errors Changelog for v2018-09-13: - Uses LxCommunicator library for secure/encrypted Miniserver communications - Will now work with Loxone Config 9.3+ Changelog for v2017-12-13: - Added parameter data-chartwidth to set width of mini charts - Added parameter data-chartcontrols to allow mini charts of past days to be displayed - Added Push-Button and Switch functionality within 'general' tabs - Added basic support for displaying Burglar Alarm armed status within 'general' tabs - Fixed bug where authentication of WebSocket could fail over a slow connection - Added basic support for touch screen control (some elements may still be on the small side) Changelog for v2017-11-07: - Improved minicharts of digital statistics Changelog for v2017-11-05: - Added support for Light Controller V2 controls - Added ability to show state of detectors (PiRs, etc.) on lighting tabs Changelog for v2017-05-27: - Fixed bug where details of config Errors weren't displayed properly - Added support for displaying value of Timer/Schedule controls in 'general' tabs Changelog for v2017-01-08: - Fixed bug with large charts of multiple value sets Changelog for v2017-01-06: - Added control of parent Lighting Controller as well as individual light - Added group controls for lights - Made each tab bookmarkable (i.e. URL hash changes with tabs) - Added Loxone favicon - Improved documentation for 'lighting' tab configuration - Added 'external' tab type with WOL trigger Changelog for v2017-01-04: - Fixed bug with minicharts if multiple value sets - Added scene select for Lighting Controller lights - Added on/off button for Dimmer lights Changelog for v2016-12-28: - Added parameter data-chartvalueset to specify which of multiple statistical value sets should be plotted - Added selection by category for lighting definitions Changelog for v2016-11-14: - Added larger charts when mini charts clicked on - Moved all user configuration into config.js and config.css - Moved all documentation into documentation.html - Charts now handle controls with multiple statistical value sets - Fixed bug where large chart wasn't shown unless there were multiple months of statistics available
- Implement colour picker lighting control - Improve support for mobile devices / touch control - Show values when hovering mouse over large charts - Add support for displaying values from Intelligent Room Controllers