Tank level monitoring

Who it’s for

Operators and site managers who monitor liquid or bulk storage, such as fuel, water, chemicals or grain, and need to know at a glance how full each tank is and whether any tank has crossed a low or high set point.

What it does

The widget draws each tank in its real shape and fills it according to the latest level reading. The fill height comes from the tank geometry, not from a straight line, so a half-full horizontal cylinder or sphere looks exactly as it does in the field. Each card shows the tank name, the current value, percent full, total capacity and the time of the last update. A status badge and the liquid colour change when a set point trips.

• One entity shows a single tank card; several entities switch the widget to a grid automatically
• Text scales with the card size, and is placed beside or below the tank, whichever leaves the tank larger
• 13 tank shapes: rectangular, vertical cylinder, vertical capsule, vertical with dished ends, vertical oval, sphere, cone, frustum, horizontal cylinder, horizontal capsule, horizontal ellipse, horizontal with 2:1 elliptical ends and horizontal with dish ends. An “Unknown” shape draws the fill linearly against a configured capacity.
• The level can arrive as volume, percent or liquid height. Values are converted between units automatically.
• Any number of set points, each with its own severity, direction (falls below / rises above), basis (percent, volume or height), deadband and hold time
• Optional threshold markers and scale ticks on the tank outline
• Tank shape, dimensions and set points can be constants or read per entity from attributes
• Grid sorting by name, level or status severity, and a limit on the number of tanks shown
• Smooth level animation, which can be switched off or limited to a number of tanks
• “On tank click” action, for example to open a tank details dashboard state
• Limitation: the widget takes one datasource. To show several tanks, use an entity alias that resolves to multiple entities.

How to set up

Data keys

Key	Role	Type	Description
Level key, e.g. level	Current level	Timeseries	The reading from the level sensor. Its meaning is set by Sensor reports: Volume (in Source units, e.g. L or m3), Percent (0-100 % of total volume) or Height (liquid height above the tank bottom, e.g. m). The first timeseries key on the datasource is used as the level.
Shape key, e.g. tankShape	Tank shape per entity (optional)	Attribute	Used only when Shape from is set to Attribute. Values: rectangle, verticalCylinder, verticalCapsule, verticalDished, verticalOvalPrism, sphere, cone, frustum, horizontalCylinder, horizontalCapsule, horizontalEllipse, horizontalElliptical2To1, horizontalDishEnds, unknown. Any other value falls back to the shape picked under Value.
Dimension keys, e.g. diameter, height	Tank dimensions per entity (optional)	Attribute	Used when a dimension’s source is set to Attribute. Positive numbers in Dimension units.
Set point keys, e.g. lowLevel	Set point value per entity (optional)	Attribute	Used when a set point’s source is set to Attribute. Interpreted in the set point’s Measured in basis.

Add every attribute key that a setting refers to the same datasource as the level key, otherwise the widget cannot read it.

Required dimensions by shape:

Shape	Dimensions
Rectangular, Vertical oval	Width, Depth, Straight height
Vertical cylinder, Vertical capsule, Vertical dished ends, Cone	Diameter, Straight height
Sphere	Diameter
Frustum	Bottom diameter, Top diameter, Straight height
Horizontal cylinder, capsule, 2:1 elliptical ends, dish ends	Diameter, Length
Horizontal ellipse	Width, Straight height, Length
Unknown	Total capacity

Edge cases:

• A missing or non-positive dimension, a missing level key or a non-numeric reading puts the card in the Configuration error state and shows the reason.
• A tank with no reading yet shows No data.
• For dish-end shapes, leave Volume per head empty to estimate each head as 0.0809 x diameter cubed (ASME F&D), or enter the value from the vessel datasheet for an exact result.
• With Clamp to tank on, readings above full or below empty are drawn as full or empty.
• Height mode needs a real shape and its dimensions. It does not work with the Unknown shape.

How to customize

• To show many tanks at once - point the datasource at an entity alias that resolves to several devices or assets; the widget switches to a grid on its own. Under Multiple tanks, use Fit columns or a fixed Columns count, and adjust Minimum card width and Card gap.
• To put the worst tanks first - under Multiple tanks, set Sort tanks by to Status, most severe first or Level, lowest first.
• To match a real vessel - pick the Shape, set Dimension units and fill in the dimensions listed for that shape.
• To support tanks of different shapes in one grid - set Shape from to Attribute and store the shape and dimensions as attributes on each entity.
• To change the alert levels - edit the rows under Set points. Set Trips when level to Falls below or Rises above, choose Severity and Measured in, and enable the row. Use Add set point for more rows.
• To stop the status from flickering - raise Deadband (percent of total volume) and Hold (ms) on the set point.
• To keep one liquid colour - turn off Colour by status and pick the Liquid colour under Appearance.
• To show the value in different units - set Source units to what the sensor sends and Display units to what users should see, e.g. source m3, display L.
• To control text size yourself - turn off Auto scale under Appearance and set the fonts for each line.
• To change the card background, corner radius or padding - use the standard card settings: Card appearance in basic mode, or the Widget card tab in advanced mode.
• To declutter the card - toggle Label, Value, Percent, Capacity and Timestamp under Appearance, and turn on or off Threshold markers and Scale ticks.
• To open details on click - add an action for the On tank click source in the widget’s Actions tab.
• To improve performance on large grids - lower Animate up to, or turn off Animate level.

Tips

• If you only know a tank’s capacity and not its dimensions, use the Unknown shape. Percent and volume are still exact, only the drawn height is linear.
• Store per-tank set points as attributes so the same dashboard works for tanks with different alarm levels.