Gauge Documentation

Table Of Contents

Overview

These Gauges are a great way to display values in an attractive and easy to read manner. Perfect for your IOT project to display live values, or even historical information.

The range of styles and designs provide choices to go with many themes - from nautical to industrial - from modern to spooky olden days.

They are designed to be easy to implement in any web page. It is easy to configure the appearance and operation of each gauge, and you can choose from several real-world designs.

An important part of the code design is to make it easy to implement real-time display of remote data. With just a few lines of code in your web page, you can retrieve and display data. Another aspect of the design is the speed of rendering. This allows for rapid updating and a smooth viewing experience for your visitors.

Adding a gauge is very simple. Just include two JavaScript files in the head of the page, and place the canvas element in your web page where you want it displayed.

Gauge Styles

There are several designs to choose from, some from an older era, and some that can be seen on modern equipment.

Gauges 1 left and right are well suited to stereo VU meters, while gauge 2 might do well in a nautical theme. Gauge 3 is a design often seen in the 1970's through the 2000's, as are gauges 5-7. Gauge 4 might be seen in an expensive piece of equipment from the 1950's. Your own imagination will be your best guide.

All of the gauges allow you to customize the scale and needle. You can even specify different colors for parts of the scale background.

Including Gauges In Your Web PageTOC

To include a gauge in your web page, you need to link the Javascript code in the page header and place a canvas element where you want the gauge to appear.

In the head section, you will add a script tag for each gauge style you want to display, and a script tag for the gauge code.

<script src="js/jiotPlgGauge_1l.js" type="text/javascript"></script>
<script src="js/jiotPlgGauge.js" type="text/javascript"></script>

You will need to replace the path with what is used on your system. In the example above, the first line is used when you want to display the gauge Gauge 1L. If you want to display a different style, use the matching filename.

The second line above should be added last, after the gauge specific JavaScript file or files. It should only be included once.

Resizing Considerations

All gauges have an "original size", that is, the size of the image used to create the gauge. These usually have a maximum width or height (whichever is greater) of about 200 pixels. When you specify the size in the canvas tag, the gauge will calculate a magnification factor based on the ratio of the original size to the desired size. When it calculates the actual size to be displayed, it maintains the original aspect ratio. All of the configuration parameters that convey a size (font sizes, lengths, position, etc.) have this magnification factor applied.

For example, if we use a gauge whose original size was 200 px tall by 200 px wide, and display it at 400 by 400, all of these measurements will be doubled.

This allows you to define parameters to your liking, and then display the gauge at whatever size you choose, and all of the parts of the gauge will be proportional to the original size.

Minimum Configuration Parameters

You need to specify the following in the canvas element's definition. The rest of the configuration values will default to the gauges initial configuration values.

ID A unique string used to identify the specific gauge. No two elements (gauges or not) should have the same value for the ID attribute.
Class Must be gauge. This is how the gauge code identifies the canvas elements to attach to the code. Case sensitive.
Data-Type Must be "st_gauge". Case sensitive.
Data-Gauge-Type Must be the proper value for the gauge you want displayed. Case sensitive.
Example:
<canvas
id='mygauge'
class='gauge'
data-type='st_gauge'
data-gauge-type='st_gauge_2'
/>

All Configuration Parameters

There are quite a few configuration parameters you can set in the canvas tag. Each can also be read and set via JavaScript at run-time. They are grouped below by the part of the gauge they affect.

Text

There are two text elements on the gauge: Title and Sub-Title. You can set several parameters to control the appearance and location of each of the Text Elements. All measurements are in pixels relative to the original size of the gauge and will be scaled to the size set for the gauge. Font sizes are in points, and are also scaled.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Title data-title title The text displayed as the gauge title. Usually larger than the sub-title, and indicates what is being measured and displayed by the gauge.
Title Font data-title-font titleFont The font used for the Title text element. Must be a font that is available on the user's browser.
Title Font Size data-title-font-size titleFontSize Size in points for the Title text element. This will be re-sized based on the original size and the displayed size.
Title Horizontal Align data-title-align-h titleAlignH Determines the relative position of the text to the titlePositionX value below. Choices are left, right, and center. Setting this to Left will position the text so the left-most part is at the titlePositionX location. Setting this to Right will position the text so the right-most part is at the titlePositionX location. Setting it to center will center the text at the titlePositionX location.
Title Vertical Align data-title-align-v titleAlignV Determines the relative position of the text to the titlePositionY value below. Choices are top, middle and bottom.
Title Color data-title-colot titleColor Color for the title text. Can be entered in hex, rgb, or rgba formats.
Title Position X data-title-position-x titlePositionX The horizontal position of the text.
Title Position Y data-title-position-y titlePositionY The vertical position of the text.
Sub-Title data-sub-title subTitle The text displayed as the gauge sub-title. Usually smaller than the title.
Sub-Title Font data-sub-title-font subTitleFont The font used for the sub-title text element. Must be a font that is available on the user's browser.
Sub-Title Font Size data-sub-title-font-size subTitleFontSize Size in points for the sub-title text element. This will be re-sized based on the original size and the displayed size.
Sub-Title Horizontal Align data-sub-title-align-h subTitleAlignH Determines the relative position of the text to the subTitlePositionX value below. Choices are left, right, and center. Setting this to Left will position the text so the left-most part is at the subTitlePositionX location. Setting this to Right will position the text so the right-most part is at the subTitlePositionX location. Setting it to center will center the text at the subTitlePositionX location.
Sub-Title Vertical Align data-sub-title-align-v subTitleAlignV Determines the relative position of the text to the subTitlePositionY value below. Choices are top, middle and bottom.
Sub-Title Color data-sub-title-color subTitleColor Color for the sub-title text. Can be entered in hex, rgb, or rgba formats.
Sub-Title Position X data-sub-title-position-x subTitlePositionX The horizontal position of the text.
Sub-Title Position Y data-sub-title-position-y subTitlePositionY The vertical position of the text.

Size

These control the height and width of the gauge. The guage will be resized, maintaining it's aspect ratio, to fit within these boundaries. All measurements are in pixels relative to the original size of the gauge and will be scaled to the size set for the gauge.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Width data-width width The maiximum width of the displayed gauge in pixels
Height data-height height The maiximum height of the displayed gauge in pixels

Scale

These parameters control the appearance of the scale and the values displayed on the scale. All measurements are in pixels relative to the original size of the gauge and will be scaled to the size set for the gauge. Font sizes are also scaled.

Property Name Canvas Element Attribute JavaScript Config Name Description
Minimum Value data-min-value minValue Smallest value to display on the scale. Usually on the left.
Maximum Value data-max-value maxValue Largest value to display on the scale. Usually on the right.
Major Scale Step data-major-scale-step majorScaleStep For a linear scale: Number of units between the Major Ticks on the scale. Usually an integer, but decimal values are allowed.
For a log scale: Number of divisions in the scale.
Minor Scale Step data-minor-scale-step minorScaleStep Number of units between the Minor Ticks on the scale.
Band Background Colors data-scale-band-bg-colors scaleBandBgColors A list of value and color specifications for the colors behind the scale. Each value/color spec has the max value for the color and the color. The color can be specified using hex, rgb or rgba. The specs should be in ascending order from lowest value to highest. The first spec will span from the Minimum Value of the scale to the value in the spec. The second will span from the first value to the value in the spec. -- and so on.
Each specification is separated with a vertical bar "|", and the value and color are separated by a colon ":".
Example:
10:rgba(255,255,0,0.8|30:rgba(255,255,255,0.5)
The scale will have a yellow background at 80% opacity from the scale start to 10. Then it will have a white background at 50% opacity from 10 to 30.
Band Border Color data-scale-border-color scaleBandBorderColor Sets the color of the band around the scale (top and bottom). Can be a hex color, rgb or rgba specification.
Band Border Width data-scale-band-border-width scaleBandBorderWidth Sets the width of the band around the scale.
Major Tick Color data-scale-major-tick-color scaleMajorTickColor Sets the color of the Major Ticks. Can be a hex color, rgb or rgba specification.
Major Tick Width data-scale-major-tick-width scaleMajorTickWidth Sets the width of the Major Ticks.
Minor Tick Color data-scale-minor-tick-color scaleMinorTickColor Sets the color of the Minor Ticks. Can be a hex color, rgb or rgba specification.
Minor Tick Width data-scale-minor-tick-width scaleMinorTickWidth Sets the width of the Minor Ticks.
Major Tick Label Color data-scale-major-tick-label-color scaleMajorTickLabelColor Sets the color of the Major Tick Labels. Can be a hex color, rgb or rgba specification.
Label Font data-scale-font scaleFont Sets the font used for the Major Tick Labels. Must be a font available on the user's computer.
Label Font Size data-scale-font-size scaleFontSize Sets the font size in points.
Label Position data-scale-label-position scaleLabelPosition Sets the placement of the Major Tick Labels. One of inside or outside.
Label End Position data-scale-end-label-position scaleEndLabelPosition Sets the placement of the first and last Major Tick Labels. One of inside or outside.
End Lable Size data-scale-end-label-size scaleEndLabelSize Sets the relative size of the first and last Major Tick Labels. 1 = 100% of Major Tick label size, 1.1 = 110%.

Needle

These parameters control the appearance of the needle (indicator). All measurements are in pixels relative to the original size of the gauge and will be scaled to the size set for the gauge.

The needle consists of three parts: Main Line, Symbol, and Tip. The main line part begins at the pivot point and extends to where the symbol or line tip starts. The symbol is between the main line and line tip. The line tip is the outermost part of the needle.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Needle Type data-needle-type needleType Type of needle to display. One of line, diamond, or spade.
Main Line Width data-line-main-width needleLineMainWidth Width of the main part of the line,
Line Tip Width data-needle-line-tip-width needleLineTipWidth Width of the line tip.
Symbol Width data-needle-symbol-width needleSymbolWidth Width of the symbol - applies only to line type diamond.
Line Color data-needle-line-color needleLineColor Color of the main line part of the needle.
Line Tip Color data-needle-tip-color needleTipColor Color of the tip of the line.
Spade Color data-needle-spade-color needleSpadeColor Color of the interior of the Spade -- applies only to line type Spade.
Jewel Color data-needle-jewel-color needleJewelColor Color of the interior of the diamond -- applies only to line type Diamond.
Jewel Border Color data-needle-jewel-border-color needleJewelBorderColor Color of the border around the diamond. -- applied only to line type Diamond.

Animation

When the value of the gauge changes, the needle is moved using one of several animations. You can set three parameters to control how the needle animation appears.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Delay data-anumation-delay animation.delay Amount of time in milliseconds after value change and before movement begins.
Duration data-animation-duration animation.duration Amount of time for movement of needle
Function data-animation-fn animation.fn Type of animation. One of linear, quad, quint, cycle, bounce, or elastic.

Shadow

Some gauges allow for a shadow to be cast. These parameters control the appearance of the shadow.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Shadow Enabled data-show-shadow showShadow Enable/Disable shadow. One of "yes" or "no"
Angle data-shadow-angle shadowAngle Angle in degrees for the shadow. 0-359
Size data-shadow-size shadowSize Size of the shadow in pixels.
Blur data-shadow-blur shadowBlur Amount of blur in pixels.

Data Polling

The gauge can do simple polling to get new values to be displayed. If you are only using one gauge, this might be useful. If you are displaying multiple gauges which retrieve data from the same source, custom JavaScript is a better choice.

PropertyName Canvas Element Attribute JavaScript Config Name Description
Poll Enabled data-poll-enabled pollEnabled Enable/Disable poll. One of "yes" or "no".
URL data-poll-url pollUrl Full URL to server script that will return the value. Include any parameters needed in the url. Must be on the same domain as the page hosting the gauge to avoid cross-domain blocking by the browser.
Delay data-poll-delay pollDelay Time in milliseconds to wait after data is returned to get next value.
Variable Name data-poll-var-name pollVarName Name of variable returned from server with the value to display.

Controlling The Gauge With Javascript

Get a Reference To A Specific Gauge

During the page onload event, the gauge creates an array of gauges found on the page. This array object has a get method that returns the gauge object for a specific gauge based on the id of the canvas tag. This object provides access to the properties and methods of the gauge.

The first thing your code should do is to get a reference to the particular gauge you want to interact with. For instance, if you have an gauge with an ID of "temperature_gauge", you would use code like:

var g = st_gauges.get('temperature_gauge');
After that, g would provide access to the parameters and methods of that gauge.

Gauge Object Properties

All configuration properties are found under the config property and are listed above. For instance, to set the title:

var g = st_gauges.get('temperature_gauge');
g.config.title = "Temperature (F)";

You can also read the current values.

var g = st_gauges.get('temperature_gauge');
var mytitle = g.config.title;

Gauge Object Methods

There are several methods available from the gauge object.

Method Description
setValue(val) Sets the value displayed on the gauge and redraws the gauge with animation.
draw() Redraws the gauge with animation.
forceRedraw() Redraws the gauge with animation, including redrawing parts of the gauge that are cached.
setRawValue(val) Sets the value displayed without animation.
clear() If animation is in progress, completes the animation immediately. Needle is moved to the value without animation.
loadXMLDoc() Used internally normally when polling for data is enabled. Initiates loading the data from the polling source.

Connecting An Arduino (or other MCU) To A Web Page

Overview Of The Process

In order to show values from an Arduino (or other MCU), you have to have a communications path between the MCU and the user's browser. This can be done in a number of ways, but the easiest to implement is when the MCU has access to Ethernet.

Basically, the process is to have the MCU send the data to a server which records the data. The browser can then contact the server to retrieve the data.

The server can also poll the MCU for data, but most hosts would balk at allowing this since it would put a undue burden on the server.

The connection between the MCU and the server can also be implemented using a serial connection to a PC/MAC/Linux computer which then sends the data on to the server.

In the examples below, we will focus on the first case where the Arduino has an Ethernet shield that is then connected to the internet.

Requirements For The Arduino Code

The Arduino must be able to colllect the data and send it to a server. This can be done with a simple HTML get or post. If you want two-way communication (to allow the server to set values on the Arduino), you can still use a simple get or post, and then process the response from the server.

Requirements For The Web Server Code

You will need at least two scripts on the server in addition to the web page with the gauges. The first script is called by the code on the Arduino and saves the data in some way. That could be in a file or to a database. The second script is called via AJAX from the web page to load the data to be displayed.

Requirements For The Web Page Code

The web page should have JavaScript code that calls the server to retrieve data. It might also have code that sends information that the server passes along to the Arduino.

This code might be called on a timed basis or when the user clicks a "refresh" button or similar.

Sample IOT Projects

Notes:

All of the example projects use an Arduino, and the server code is written in PHP. The browser code uses JavaScript, AJAX and JSON.

Soldering Reflow Oven Monitor

Requirements:

Parts List:

Download the Example Code

Weather Monitor

Requirements:

Parts List:

Download the Example Code

AC Usage Monitor

Requirements:

Parts List:

Download the Example Code