Vermont Energy Control Systems

Graphical User Interface

This document is a guide to using and creating Graphical User Interfaces (GUIs) for the Vesta monitoring and control system.

Out of the box, Vesta provides a simple web-based user interface that's used to set up and program the system:


Figure 1: Standard Web Interface

This interface allows creation of data elements, creation and editing of rules, monitoring of all inputs and outputs, and a variety of system management functions.

In addition to this simple web interface, the Vesta controller has the ability for users to define a customized user interface that's more relevant to their needs. This interface updates automatically and provides the ability to directly set Vesta internal elements (variables and outputs). The interface supports a variety of graphical elements (widgets) and allows them to be placed arbitrarily on an image background of the user's choice:

Figure 2: Custom Web Interface

In the example above, a variety of display widgets were placed on top of a system plumbing schematic.

By default, all widgets update every 5 seconds. That means that dial pointers move, digitial displays refresh, and indicators change color automatically. This is done 'behind the scenes' so the page doesn't have to be refreshed.

In addition to real-time display, some widgets allow interaction. For instance, a pushbutton can be defined which will set or toggle a discrete output on Vesta. A numeric display widget can also allow the value to be changed, and set an Vesta variable to the new value.

Creating and modifying this interface requires some familiarity with web pages and web server terminology.

Vesta Address Used In Examples

Throughout this document, examples assume that your controller is at the standard address of 192.168.1.8. Change as necessary to match your configuration.

This interface is based on AJAX and SVG (Scalable Vector Graphics). It works with Google's Chrome browser, Firefox, and Safari (including iPhone). At present, it does not work with Internet Explorer or with some Android browsers.

The User Defined Interface is composed of multiple parts. All the components can be on Vesta, or they can reside on different web servers. The key components are as follows:

  1. A skeletal HTML file loaded by the user's browser. This file provides the framework for the page. This HTML file in turn loads...
  2. Javascript files containing the widget code and other function libraries. When the javascipt is all loaded, it in turn performs an initialization which loads...
  3. A text file containing definitions for all of the desired widgets, and...
  4. Optionally, a background image

All required files are delivered with the system. To create a custom page, the user needs to create a new skeletal HTML file and a new text file with widget definitions along with a background image file if desired.

Default Pages

There are two default GUI pages that are built automatically by the system. Both display all system inputs, outputs, and variables. One is intended for 'internal' use - that is, use by the system owner. It allows the user to set any output or variable in the system. The other version is intended for 'external' use - perhaps to be displayed to the outside world. This version is read-only.

Figure 3: Custom Web Interface, Auto-Generated Private Version

The above example allows the user to set any outputs or variables. The GUI Button can be toggled by clicking on it, for instance.

The password protected private version is at http://192.168.1.8/private/index.html, while the public version is at http://192.168.1.8/private/index.html.

There are links to both on the Home Page of the standard web interface.

HTML File

The HTML file contains references to the files and the background image. It also contains variable definitions that will be discussed below. A typical HTML file would look like the following:



Figure 4: HTML File for custom page

This is one of two files that MUST be edited by the user to create a user interface. If it's hosted on Vesta, then it should be in either the public or private directories (/www/apache/htdocs/public/ and /www/apache/htdocs/public/ respectively). We'll go through it line by line.

Lines 3 and 4 contain references to the javascript source files. That reference has to be valid. In most cases, you can simply use the version that's shipped with your Vesta. If your HTML file is also on Vesta, then these lines are correct as shown. If your HTML file is on a different web server, then you must specify a path to valid copies of the javascript files. In this example, src="http://192.168.1.8/ctlpanel.js" and src="http://192.168.1.8/jquery-latest.min.js" would work. This becomes more complex when access is desired through a firewall. See the section on firewalls and routers below.

Line 6 contains the TCP port number for communication with Vesta. It should be 7280 except when accessing the system from outside a firewall.

Line 7 specifies the delay between updates of the widgets in the interface. The delay is in milliseconds, so a value of 5000 means that all the widgets will update every five seconds. If you have a lot of widgets (50 or more) specifying too small a delay can overload the Vesta controller. This can cause delayed rule execution. A good rule of thumb is to take the number of widgets multiply by 5 to get the minimum delay in milliseconds. For a display with 50 widgets like the example above, the delay should be about 50 * 5, or 250 milliseconds. With this delay on the standard CPU, a single display instance on a single browser will use about 4% of CPU capacity. This allows several instances (iPad? Smart Phone? Computer in den?) to be updated simultaneously without affecting system performance. At total rates above 1000 widget updates per second, system performance may start to be affected.

NOTE: If you are running an older version of the system software (earlier than 2.0.1451), then you need to use much longer delays. Multiply the number of widgets by 50 rather than 5 to get the minimum delay. With the older software, a 50 widget display should have a delay of at least 2500 milliseconds.

Line 8 specifies the widget configuration file - in this case, "/private/gaugepanel.txt". This file contains a list of widgets to be displayed. In addition to the HTML file, this file must be created by the user.

Line 12 contains the background image - in this case, "/public/gaugepanel.gif". This line is required, and must specify a valid image. The size of the image defines the area available for display widgets. The image can reside anywhere as long as the browser can access and display it. If the user does not wish to provide an image, Vesta is distributed with a transparent image that can be used instead. In this case, the width and height must be specified as in this example:

<img id=MyImage style="position: absolute; top: 0; left: 0;" width=1280 height=1024 src=/images/pxclear.gif>

In each case, only edit the parameters and file references. All of the other content is required and should not be changed.

Widget Configuration File

The widget configuration file is a plain text file that can be created and edited with any text editor. It contains a series of one line widget definitions as well as optional comments. A portion of a widget configuration file might look like this:

Comments are C++ style (double slash). Blank lines are allowed. Each widget definition takes a single line.

Widget Definitions

There are several widget types, all with different capabilities and options. Widget definitions specify the type of widget and a list of parameters that determine details of appearance and behavior.

One key specification is widget position. Widget position is specified in pixels from the left edge and top edge of the page. In most cases, the specified point will be the top left corner of the widget.

In the Vesta controller, all inputs, outputs, and variables are collectively known as data elements. Any active widget must be connected to an Vesta data element. This is accomplished by specifying the ID number of the desired data element. Element ID mumbers can be obtained by going to the Vesta 'System' tab. Near the bottom is a list of files. Click on 'elements.csv' and print the resulting page. For each element, the element ID is the number at the beginning of the line. In the excerpt below, the element ID for 'Wood In' is 3.

"Element","owner","physio","p/v/c","io","value","name"
0,0,0,"c","i",1,"TRUE"
1,0,0,"c","i",0,"FALSE"
2,1,0,"p","i",166.299530,"Wood Out"
3,1,1,"p","i",147.707291,"Wood In"

Required Parameters

The first five parameters are required, and are the same for every widget type:

  1. Widget Type - quoted text. Must be a valid widget type.
  2. Left Pixel coordinate - numeric. Left edge position of this widget
  3. Top Pixel coordinate - numeric. Top edge position of this widget
  4. Vesta IP address - quoted text. Enter an empty quoted string (pair of double quotes) to use the default from the HTML file.
  5. Element ID - the ID number of the element that this widget is connected to.

Consider this widget definition from the example above:

"text",220,328,"",3,"lightgrey","","black",80,"yellow",84,"green"

This defines a widget of type "text". It's top left corner is 220 pixels from the left edge and 328 pixels from the top edge of the page. The double quotes in the next position indicate that it's connected to the default Vesta. Finally, it's connected to element 3. The additional parameters specify characteristics that are specific to 'text' widgets.

Optional Parameters

In almost all cases, any parameters after the first five are optional. Optional parameters can be left out and the widget will still display and function. However, parameters are position-specific. If you want to skip the sixth and seventh parameters but specify a value for the eighth, you must use a pair of quotes as a placeholder for each empty parameter. In the example above, the seventh parameter (border style) is left blank. The next chapter will discuss optional parameters for each widget type.

function textwidget(wid,lp,tp,ip,eid,c1,bstyle,bcolor,c1val,c2,c2val,c3,ltext){

This chapter contains the details of appearance and behavior for each widget type. Some widgets are passive. These can only display a value. Others are active - they can also set an element value in the Vesta controller.

In each case, the first five required parameters are not discussed. They are covered in the previous chapter and are the same for all widget types.

For each widget type, one or more examples will be shown along with the corresponding specification.

Color Specifications

Most widgets allow colors to be specified. In those cases, any valid HTML color specification may be used.

Multicolor Widgets

Many widgets can use multiple colors. In general, they all follow the same approach. If only a single color (Color 1) is specified, that color will be used - as the background color for a text widget, scale color for a dial widget, for example. A 'color boundary' and second color value can be specified. In that case, if the displayed value is above the color boundary, the second color will be used for the widget background. In a similar way, a second boundary and third color can be specified.

In this example, three colors have been specified: lightgrey, yellow, and green. The two color boundaries have values of 5 and 10. That leads to the following behavior:

  • For display values up to 5, the background is light grey
  • For display values above 5 and up to 10, the background is yellow
  • For display values above 10, the background is green

Bar and Setbar Widgets

Both these widgets look the same and have the same parameters. The bar widget is passive and simply displays values graphically relative to a fixed minimum and maximum. The setbar widget will set the value of the associated data element to a value determined by where the bar is clicked. In both cases,there is no numeric value displayed. If a numeric value is desired, place a text widget adjacent to the bar or setbar widget.

Bar graphs have a specified height and width. If the width is greater than the height, then the bar graph is horizontal, increasing to the right. If the height is greater than the width, then the bar is displayed vertically with values increasing upwards.

Besides the normal five required parameters, the bar widget has seven additional parameters. The first five are required.

Parameter Value in example Description If not present
Height 20 Bar height in pixels Required
Width 100 Bar width in pixels Required
Minimum 0 Minimum scale value Required
Maximum 200 Maximum scale value Required
Bar Color red Color for the bar Required
Background Color white Color for the background Transparent
Label text 'Horizontal' Label text to be displayed at left of widget No label

Dial Widget

The dial widget displays the value of an element as a needle position and as a numeric value. The size of the dial can be specified. The dial scale can have up to three colors. Normally the height and width are the same, but dials can be made with the width greater than the height.

The dial widget has ten parameters. The first four are required.

Parameter Value in example Description If not present
Height 72 Height of the dial face Required
Width 72 Width of the dial face Required
Minimum 50 Minimum scale value Required
Maximum 80 Maximum scale value Required
Color1 yellow First scale color Transparent
Color Boundary 1 62 Boundary value between displaying color 1 and color 2. Use color 1
Color 2 lightgreen Second color Use color 1
Color Boundary 2 75 Boundary value between displaying color 2 and color 3. Use color 1 (or 2 if present)
Color 3 yellow Third color Use color 1 (or 2 if present)
Label text 'Larger:' Label text to be displayed below dial No label

Label Widget

The label widget only serves to place text on the panel. It does not connect to an element and does not update. The size of the text can be specified.

Because the label widget does not connect to any element, the element field can contain any element number - the value is not used. The label widget has three additional parameters, all required.

Parameter Value in example Description If not present
Font size 16 Height of font in pixels Required
Position e Position of label relative to specified coordinates n, e, s, or w for north, east, south, and west Required
Label text 'Dials:' Label text to be displayed at left of widget Required

Light Widget

The light widget is a passive widget that displays status for discrete (on/off) elements. It is rectangular in shape and can display user-selected colors for the on and off states.

Besides the normal five required parameters, the light widget has five additional parameters. The first four are required.

Parameter Value in example Description If not present
Height 20 Height in pixels Required
Width 20 Width in pixels Required
Off Color lightgreen Color for 'off' state Required
On Color green Color for 'on' state Required
Label text 'Status' Label text to be displayed at left of widget No label

Set Widget

The set widget is an active widget. In addition to displaying a numeric value, it allows that value to be set, sending the new value to the Vesta controller. It provides all the same options as the text widget, and is identical in appearance.

There are some special behaviors associated with the set widget. When it has focus (when you click on it) the border chenges to the 'inset' style. This provides a visual clue that the widget is selected and ready for editing. While it is selected, it will not update. Once you're done entering data, tab (or press enter) to leave the field. The new data will be sent to the Vesta controller and the widget will update.

Just as with the text widget, a set widget has eight optional parameters:

Parameter Value in example Description If not present
Color 1 lightgrey Color 1. Background color if additional colors are not specified Transparent
Border Style solid Can be any valid CSS border style. 'Inset' should not be used as a style because this widget uses the inset border to indicate focus. No border
Border Color blue Border Color Black
Color Boundary 1 5 Boundary value between displaying color 1 and color 2. Use color 1
Color 2 yellow Second color Use color 1
Color Boundary 2 10 Boundary value between displaying color 2 and color 3. Use color 1 (or 2 if present)
Color 3 lightgreen Third color Use color 1 (or 2 if present)
Label text 'Set Value' Label text to be displayed at left of widget No label

Text Widget

The text widget is a passive widget. It displays a numeric value with one decimal place. It provides a choice of border style and color as well as up to three background colors. A label can be specified. If present, it will be scaled to approximately the same text height as the numeric value, and positioned to the left of the text widget.

In addition to the five required parameters, a text widget has eight optional parameters:

Parameter Value in example Description If not present
Color 1 lightgrey Color 1. Background color if additional colors are not specified Transparent
Border Style solid Can be any valid CSS border style. 'Inset' should not be used because it has special meaning for the 'Set' widget. No border
Border Color black Border Color Black
Color Boundary 1 5 Boundary value between displaying color 1 and color 2. Use color 1
Color 2 yellow Second color Use color 1
Color Boundary 2 10 Boundary value between displaying color 2 and color 3. Use color 1 (or 2 if present)
Color 3 green Third color Use color 1 (or 2 if present)
Label text 'Tricolor' Label text to be displayed at left of widget No label

Toggle Widget

The toggle widget is an active widget intended to be used with discrete (on/off) elements. By default, it displays a red button if the element is true, and a grey button if the element is false. In addition to displaying status, it allows that value to be controlled.

There are three possible behaviors: Clear, Set, or Toggle. 'Clear' sets the Vesta element to false (or zero). 'Set' sets the element to true (or 1). 'Toggle' inverts the current value, changing true to false and vice versa.

If the element is changed by some other mechanism (such as a rule on the Vesta controller) the toggle widget will update to display the correct state.

Besides the normal five required parameters, the toggle widget has four additional parameters. The first is required - it specifies the desired behavior.

Parameter Value in example Description If not present
Toggle Type 2 Selects behaviors. 0=clear, 1=set, 2=toggle Required
Off Image -blank- Image to be displayed for 'Off' (false) condition Grey Button
On Image -blank- Image to be displayed for 'On' (true) condition Red Button
Label text 'Toggle' Label text to be displayed at left of widget No label

This document is part of the Vesta Control System Software, Copyright Vermont Energy Control Systems LLC.

VestaS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

VestaS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the Vesta system. If not, see http://www.gnu.org/licenses/.