SVG-Dashboards

Displaying text and statuses, interacting with an element

Introduction

The web interface of the Wiren Board controller lets you create interactive graphical dashboards. They are a convenient way to visualize automation control diagrams.

Features:

display text or logical values;
change the appearance of an SVG element depending on the received data: change the element style, replace the received value with your own, or hide/show elements;
control actuators: switch loads on and off, change device operating modes.

SVG dashboards work on mobile devices, but keep the image size in mind: elements that are too small are hard to use. A good approach is to split dashboards into desktop and mobile versions, with the mobile ones designed for the specifics of a mobile device.

Fullscreen and HMI modes

Some tasks require hiding the browser controls and the controller web interface panels from the user. For this, there are fullscreen and HMI modes.

In fullscreen mode, you can switch between dashboards via the side menu. In HMI mode, you have to implement switching yourself: add a button (an object) with the URL of the target dashboard to the SVG image.

Dashboard modes
Standard view
Fullscreen
HMI

Preparation

Changing the web interface access level

The access level depends on the account, users are authenticated by login and password. To change the controller settings, your account must have the access level Administrator. Account management is available in the section Settings → Users. For more information, see User authentication and authorization.

In releases prior to wb-2602, user accounts are not available, and access levels are configured in the Settings → Change access level section.

Image requirements

An SVG dashboard is based on an SVG image. We recommend creating it in Inkscape, which supports the SVG standard fully and without deviations.

You can output data to any text element and set up interactions with any shape or text.

All dashboards are stored in the /mnt/data/etc/wb-webui.conf file, which is loaded to the user's computer into the browser LocalStorage. For releases before wb-2609, this storage is limited to 4 MB depending on the browser. If the limit is exceeded, you will get an error when loading the dashboard into the editor, so keep an eye on the total size of your SVG images. In practice, if you draw dashboards in Inkscape without raster graphics and complex gradients, the images stay compact — tens or hundreds of kilobytes — so most users will never run into this problem.

Release wb-2307 and newer

Inside the SVG file, the content tag must not contain other tags. If you uploaded a file to the controller, set up bindings, downloaded the file back to your computer and it does not open in the editor, open the SVG file in a text editor and delete the contents of the content tag. After that, you can edit the file in an SVG editor.

The image can have any width and height and any number of elements.

Release wb-2304 and older

Limitations:

You cannot interact with a rectangle. If you need to, convert it to a path (Object to Path).
The SVG dashboard editor ignores grouping. If you need to set up interaction with a compound element, convert it into a single shape made of paths.
Inside the SVG file, the content tag must not contain other tags. If you uploaded a file to the controller, set up bindings, downloaded the file back to your computer and it does not open in the editor, open the SVG file in a text editor and delete the contents of the content tag. After that, you can edit the file in an SVG editor.

The image can have any width and height and any number of elements.

Creating an SVG dashboard

Example of creating a dashboard

Create a new SVG dashboard:

Go to Dashboards → List.
In the SVG dashboards section, click Add — the binding editor opens.
Click Upload SVG and select the SVG image file.

Once uploaded, the image is shown on the page:

Set up bindings and behavior of SVG elements in the link editor.
Save the changes and check the result by clicking Preview.

Don't forget to fill in the Id and Name fields: a unique machine ID of the new dashboard and a human-readable name.

The Fit fullscreen option fits the dashboard into the available space.

A library of openly licensed SVG images: svgrepo.com.

Syntax

In the Value fields of the link editor, you can write simple expressions with conditions and basic arithmetic operations.

MQTT topic value

The value of the MQTT topic selected in the Channel field is placed into the val variable.

Conditional expressions

Available operators:

> — greater than
>= — greater than or equal to
< — less than
<= — less than or equal to
== — equal to
!= — not equal to

Syntax:

(CONDITION) ? 'VALUE1' : 'VALUE2'

For example, if the MQTT topic value equals 1, output ON, otherwise OFF:

(val == 1) ? 'ON' : 'OFF'

Arithmetic operations

You can apply basic arithmetic operations to the value received from the MQTT topic:

+ — addition
- — subtraction
* — multiplication
/ — division

For example, output ALARM if the MQTT topic value multiplied by 0.1 is greater than 20, and NORMAL otherwise:

(val*0.1>20) ? 'ALARM' : 'NORMAL'

Rounding values

Sensors often report values with several decimal places. If you don't need that precision on the SVG dashboard, round them:

val.toFixed(n) //round val to n decimal places
val.toFixed(2) //round val to two decimal places 220.238 → 220.24

Link editor

The image is prepared in an external vector editor, while bindings are assigned to its elements in the controller web interface.

To bind an SVG element of the image to values or events, click it with the mouse: the element behavior settings appear next to the image.

Besides a single element, you can select a group. To do this, hold down the Alt key and click one of the group's elements: the group containing the element is selected. Clicking again with Alt held down selects the parent group, and so on up to the top of the hierarchy.

Groups are handy for making buttons: combine a rectangle and an icon in the editor, and you have a button.

When all bindings are set up, click Save.

Read

Displays values from a source in a text field.

The value from the source selected in the Channel field is placed into the val variable, which you specify in the Value field.

To display the value, just specify the variable:

val

You can append arbitrary text to the value, such as a unit of measurement:

val + ' °C'

You can also replace the received value, for example with a human-readable status:

(val == 1) ? 'ON' : 'OFF'

Write

This setting writes a value to a topic when the user clicks the element.

There are two states, ON and OFF. Each time the user clicks the element, the value in the MQTT topic toggles to the opposite one.

In the Channel field, select the MQTT topic to write to, and in the Value on and Value off fields specify the values that correspond to each state.

For example, to toggle a relay, specify:

Value on = 1
Value off = 0

Navigation and swipes

Navigation lets you build multi-page interfaces:

Draw a separate image for each page.
Upload these images to the controller.
For one of the events, select the dashboard to navigate to.

Available events: single click, long press, and swipe left or right.

A single click or long press can navigate to SVG and text dashboards, while a swipe can navigate only to SVG dashboards. This is an architectural limitation that we cannot remove yet.

Visible

Here you specify the condition under which an image element is shown. By default, the element is hidden and is displayed only while the condition is met.

In the Channel field, select the MQTT topic the element reacts to, select a condition in the Condition field, and enter a value in the Value field.

Style

Changes the style of image elements. Use it to give feedback on actions, notify the user about an event, and so on.

Element properties available for styling:

fill — fill color;
fill-opacity — fill opacity, from 0.0 to 1.0 or in percent;
stroke — stroke color;
stroke-width — stroke width;
stroke-dasharray — dash pattern of the stroke, in length units or percent;
stroke-opacity — stroke opacity, from 0.0 to 1.0 or in percent;
pointer-events:none — disable clicks.

Colors can be set by name, such as black, red, yellow, or as hex values, such as #ffe680ff, #4f4f4dff.

Let's change the element color depending on the relay state: if the topic value is 1, fill the object yellow, otherwise gray:

(val == 1) ? ';fill: yellow' : ';fill: gray'

Let's make the element stroke red, dashed and 2px wide when the value is greater than 20. For values less than or equal to 20, the element keeps its default style:

(val > 20) ? 'stroke: red; stroke-width:2px; stroke-dasharray:2,1' : ''

You cannot set a style for a group of elements, but sometimes you need to — for example, to style an icon. In that case, combine the icon elements into a single shape:

Ungroup all elements: context menu Ungroup.
Then Path → Union.

Now you can set the style.

Editing

Dashboard

To make changes:

Open the SVG dashboard.
Click Edit.
Make the changes and save them by clicking Preview.

SVG image

Release wb-2307 and newer

SVG dashboards use IDs embedded in the file (the id attribute), so to edit a dashboard, just change the image and upload the new version to the controller.

Important! If you bound an action to a group of elements, do not ungroup it. If you need to change the group, enter it in Inkscape and add or remove elements.

Release wb-2304 and older

When you bind actions to an element, the SVG dashboard editor writes a data-svg-param-id attribute into it. So to edit the image, download it from the controller to your computer:

Open the SVG dashboard for editing.
At the top of the window, click Download — the SVG file is downloaded to your computer.
Edit the file in Inkscape. We do not recommend editing such files in Adobe Illustrator — the bindings get lost (in Russian); there is no information about other editors.

Keep in mind when editing: an SVG element that has a binding contains a hidden data-svg-param-id, and duplicating it creates a new element with the same data-svg-param-id.

Edit the downloaded SVG file and upload it back to the controller:

In the editing window, click Choose file.
Once the Change button becomes active, click it.

Fonts

Available in release testing

You can upload your own fonts for SVG dashboards in the controller web interface (by default, non-standard fonts are replaced with system fonts).

To upload a font, go to Settings → Web UI.
In the «Fonts for SVG dashboards» section, click Upload font.
Select the font file (.ttf, .otf, .woff or .woff2). The file name must match the font-family used in your SVG dashboard. For example, if the SVG specifies font-family: "Roboto", upload the file Roboto.ttf.
Done! The font is applied automatically if your dashboard uses it.

Moving to another controller

Sometimes you need to back up an SVG dashboard, for example to move it to another controller. To do this, save the SVG file converted by the editor together with the description of its bindings, and upload them to the other controller.

Note that the MQTT topic names on both controllers must match. Otherwise, you will have to bind the SVG elements to the new MQTT topics.

Saving

Save the SVG file and the bindings description:

Download the file from the controller to your computer by clicking the down arrow button.
In the SVG dashboard editor, click Edit as JSON, then copy the text and save it to a file.

Uploading

Create a new SVG dashboard as described in Creating an SVG dashboard.
In the SVG dashboard editor, click Edit as JSON, copy the bindings description from the saved file and paste it into the field.
Click Save at the bottom of the page.

Animating SVG dashboard elements

SVG dashboard elements can be animated with CSS.

To do this:

Draw the SVG dashboard in a vector editor, such as Inkscape.
Open the SVG file in a text editor and add a style block enclosed in <style></style> tags.
Add a @keyframes rule to the style block.
Save the file and upload it to the controller.
Open the SVG dashboard editor in the controller web interface.
Enable the Style parameter and set the animation property in the Value field. You also need to set the condition under which the animation runs.

CSS animation is done with the animation property and the @keyframes rule.

@keyframes describe how the element should look at each point in time.

A rule with two keyframes looks like this:

@keyframes <keyframe name> {
from: { initial state of the element }
to: { final state of the element }
}

Here from and to are keywords for the start and end points of the animation. You can use 0% and 100% instead, and add intermediate steps.

The keyframe name is an identifier used to reference the rule from the style declaration.

To make the animation work, set the animation property in the element style.

The animation property sets the animation parameters (duration, repetition, direction, timing, steps), while the @keyframes block defines the animation itself step by step (changes in appearance and position).

Here is an example of an animation that changes the text color from red to green and back. In SVG, text is rendered as a fill, so we need to change the fill property.

The **animation** property is set in the **Value** field of the **Style** parameter

Create a new SVG document in Inkscape and add a Text element to it.
Save the file and open it in a text editor.

Add a style block like this:

  <style>
@keyframes changecolor {
   0% {fill:red}
   50% {fill:green}
   100% {fill:red}
   }
  </style>

Save the SVG file and upload it to the controller.
In the dashboard editor, select the text element you created and set its animation property as follows:
```
(val > 20) ? 'animation: changecolor 3s infinite linear;' : ' '
```
An element style can change only by a condition on an MQTT topic value, so we selected the CPU Temperature topic and set the condition >20. This means the animation runs only while the CPU Temperature value is greater than 20.
Save the dashboard and switch to viewing it.

Rotating elements

To make SVG dashboard elements rotate, add the following expression to the Style field:

'transform-box: fill-box; transform-origin: 50% 50%; animation: rotate 1s infinite linear;'

Adding external links

External links are set up when you create the image in Inkscape.

To create a hyperlink:

Select the element that will act as the link, then choose Create link (hyperlink) in the context menu.
Paste the link into the field that opens.
Save.

Now upload the image to the controller and check it.

Setting an element color stored in a topic

In CSS, colors are written as a hex value #ffffff or in rgb notation rgb(255,255,255).

To pass the topic value to CSS as the fill, in the Style section select the topic that holds the color and enter `;fill: ${val}` as the value. Note the backtick quotes.

If you want to color an element on the dashboard to match an LED strip connected to a WB-LED dimmer, convert the dimmer topic value into a CSS value, for example like this:

defineVirtualDevice("hmi-demo", {
    title: {'en': 'HMI Demo', 'ru': 'Демопанель'} ,
    cells: {
      rgb_css: {
        title: {'en': 'RGB CSS', 'ru': 'RGB CSS'},
        type: "text",
        value: "",
      },
      rgb_pallete: {
        title: {'en': 'RGB Palette', 'ru': 'RGB Палитра'},
        type: "text",
        value: "",
      },      
    }
});

defineRule({
  whenChanged: "wb-led_1/RGB Palette",
  then: function (newValue, devName, cellName) {
	dev["hmi-demo"]["rgb_pallete"] = newValue;
    dev["hmi-demo"]["rgb_css"] = convertPalleteToRgbCSS(newValue);
  }
});

function convertPalleteToRgbCSS(rgb_pallete){
  var colorComponents = rgb_pallete.split(';') // get the r, g, b color components
  
  return "rgb("+colorComponents.join(',')+")"; // build the string to write to CSS
}

Useful links and resources

Archive of SVG dashboard examples
Dashboard examples in the wb-dashboards-demo repository
How to add a link to a chart or another page to an SVG dashboard (in Russian)
Article about the Wiren Board controller web interface (in Russian)
Controller web interface description on the wiki
Inkscape, a free SVG editor
Example of a pop-up window (in Russian)
Restoring dashboards from a backup (in Russian)