Duty cycle

Who it’s for

Maintenance and operations teams ask “how much of this window was the machine actually running, and what ate the rest?” A time series chart of a state key shows every reading, but not how long each state actually held — a fault that lasted forty minutes can get lost next to thousands of RUNNING readings on the same chart. A ring sized by time in state answers the question directly.

What it does

A compressor reports RUNNING for most of a 24-hour window, FAULT for forty minutes around 3 a.m., and IDLE for the rest. The ring draws three segments sized by how long each state held, not by how many readings carried it — so the forty-minute fault stays visible next to thousands of RUNNING readings, while a value that flickered three times in one minute doesn’t outweigh a state that held for hours.

• Time-weighted shares, not reading counts — each reading holds until the next one arrives, so a value that stood for six hours outweighs one reported three times in a minute
• States detected automatically — every distinct value in the window becomes its own slice, labeled exactly as the device sent it and colored by meaning (green for running or ok, red for faults, amber for warnings, grey for off) — or mapped by hand, by exact value or numeric range, with your own labels, colors, and order
• The center shows the figure you care about — uptime for a state you nominate, the longest-running state, the state holding right now, or the total measured time
• Legend with percentages and durations, and a marker on the state holding right now
• Optional percentages drawn on the segments themselves, alongside the legend
• Reads one key’s state history; it does not predict future uptime or raise an alert on a state change by itself

How to set up

Data keys

Key	Role	Type	Description
State key (any name, user-configured)	State value	Timeseries — boolean, string, or numeric	Required — exactly one key, one entity, one datasource; the configuration form enforces all three. Values aren’t coerced, so RUNNING and 3 work as readily as true. Empty and null readings are skipped rather than treated as a state

Set the time window’s own Aggregation to NONE. Grouped data delivers one value per interval, which flattens exactly the transitions this widget exists to measure.

States

Setting	Default	Effect
How states are decided	Detect automatically	Automatic reads the distinct values in the window and assigns a label and a meaning-based color to each. Map them myself hands you full control over labels, colors, and order
Most states to show separately	8	Caps the slices; anything past this merges into one Other (n) slice. The state holding right now is always kept separate. Shown only in Automatic mode
States	Running (true, green), Stopped (false, grey)	Manual-mode list: each row matches an exact value or a numeric range (From inclusive, To exclusive), with its own label and color. Rows are checked top to bottom and the first match wins. A reading that matches no row still appears, labeled with its raw value. Shown only in Map them myself mode

How to customize

Ring

• To adjust how thick the ring is — set Ring thickness (1-40, drawn in a 100-unit box).
• To change the gap between segments — set Gap between segments (degrees).
• To print percentages inside the ring — turn on Show percentages on the segments; names stay in the legend, so nothing has to be truncated.
• To show more or fewer decimal places — set Percent decimals.

Center

• To choose what the middle shows — set Center of the ring to the longest-running state, one nominated state, the state holding right now, total measured time, or empty.
• To turn it into an uptime figure — with Center of the ring set to Share of one nominated state, set Nominated state to match a label from your States list exactly, for example Running. A state that never occurred reads 0.0% rather than falling back to the runner-up.
• To caption the total-time figure — with Center of the ring set to Total measured time, edit Caption under the total.
• To color the figure by its own state — turn on Color the center figure like its state (green for Running, grey for Stopped, and so on); turn it off and set one fixed Center figure color instead.
• To lock the figure to a fixed size — set Center figure size to Manual, then set the size in Center figure font. Leave it on Auto to have the figure fill the ring and shrink for a long value like 3 d 4 h.
• To match your dashboard’s fonts — set Center figure font and Center caption font; family, weight, and style always apply, and the size in Center figure font only takes effect in Manual mode.

Legend

• To hide the legend — turn off Show legend.
• To position it explicitly — set Legend position to beside the ring or under it, instead of Auto, which follows the widget’s own proportions.
• To hide durations next to the percentages — turn off Show durations next to percentages.
• To stop marking the current state — turn off Mark the state holding right now.
• To match your dashboard’s fonts and colors — set Legend font and Legend color.

How the ring’s time window works

Two rules decide what the ring adds up to, and neither is configurable.

The last reading holds to the end of the window — that’s what makes the ring cover the whole period instead of stopping at the last message. It also means a device that stops reporting shows its last state for the rest of the window; the widget can’t tell silence from a state that hasn’t changed. Pair the card with an inactivity alarm where that distinction matters.

The stretch before the first reading is left out of the total. The state before the window started isn’t knowable from the subscription, so percentages describe the measured stretch rather than inventing a value for the gap.

The ring redraws when a reading arrives, not on every interval tick, so between two reports it can be up to one reporting interval behind — that keeps a realtime window from re-animating every second.

When the window holds no readings, the ring isn’t drawn at all; the card shows one quiet line of text instead, so a dashboard of these doesn’t jump around as devices come in and out of reporting.

Tips

• Build an uptime card: map true to Running and false to Stopped, set the center to the nominated state Running, and the ring reads as availability for the period.
• For a numeric key like load or level, use ranges — Low / Normal / High — and the ring becomes a time-in-band breakdown.
• A state that took a sliver of the window still draws at a one-degree minimum so it stays visible. Read the legend or tooltip for its true share, down to <0.1%.
• Below about 260 px of card width the legend drops the duration column, and below 190 px the current-state marker, so the rows keep fitting instead of clipping — worth planning for on a small card.