Gauge

Who it’s for

Anyone reading a value that has a known range — a tank between empty and full, a motor between idle and rated speed, humidity between 0 and 100. The number alone does not say whether 62 is comfortable or nearly at the limit; an arc with its ends marked does.

What it does

The Gauge draws a reading as a filled arc between a minimum and a maximum, with the value, the label and both end points printed. Set to the default 0–100 range, a reading of 62 fills just under two thirds of the arc on a light gray track, so the headroom left is as visible as the value itself.

• Position within a range, not just a number — the arc turns “62” into “62 out of 100” without the reader doing the arithmetic.
• The bar color can follow the value through a set of levels, so an approaching limit changes the gauge’s appearance before anyone reads it.
• Minimum and maximum are printed at the arc’s ends, which keeps the scale honest when the range is not the obvious one.
• Tick marks can be added at values that matter, marking a target or a limit on the scale itself.
• A units caption and a timestamp can sit under the value, so the gauge states what it is measuring and how fresh the reading is.
• Units are converted, not just appended — the gauge respects the unit set on the key and converts to the unit chosen on the widget.
• The Gauge shows one current reading: it plots no history, so a value that matters as a trend belongs on a chart beside it.

How to set up

Data keys

The Gauge takes one datasource, one entity and one data key.

Key	Role	Type	Description
Any numeric key	The value the arc fills to	Timeseries	Numeric only. An attribute works equally well. The key’s own units and decimals override the widget-level ones.

Range

Setting	Default	Effect
Min value	0	The arc’s empty end
Max value	100	The arc’s full end; must be greater than the minimum
Min and max label	On	Prints both end points beside the arc

Set the range to what the equipment can actually do rather than to round numbers — the arc’s whole meaning is the fraction of that range in use, so a gauge with an invented maximum reports a fiction convincingly.

How to customize

• To change the gauge’s shape — set Type to Arc, Donut, Horizontal bar or Vertical bar; all four are the same gauge drawn differently.
• To make the fill change color as the value rises — set the Bar color levels, so the arc moves from calm to alarming on its own.
• To mark a target on the scale — turn on Ticks and add the tick values that matter, then set their width and color.
• To say what is being measured — turn on Units title and set its text, or turn on Label for a caption above the value.
• To show how fresh the reading is — turn on Timestamp and pick a format.
• To make the arc heavier or lighter — adjust Relative bar width, and turn on Rounded line cap for a softer end.
• To change the empty track — set Gauge bar background to suit a light or dark dashboard.
• To animate the needle’s movement — turn on Animation and set its duration and easing rule.

Tips

• Put the tick marks where decisions happen rather than at even intervals. A tick at the pressure the relief valve opens tells an operator something; ticks every ten units only restate the scale that is already printed at both ends.
• Set the maximum to the equipment’s rating, not to the highest value ever seen. A gauge scaled to observed data always reads about half full, and it stops being able to show that anything is unusual.