Battery level

Who it’s for

Operations and field-service teams running battery-powered devices — wireless sensors, trackers, remote meters — who need to know which units are close to going dark before they plan a site visit. The question is a practical one: does this device need a fresh cell now, or will it survive until the next scheduled round? A row of these cards answers it for a whole fleet without anyone reading a single number.

What it does

The Battery level card turns one reading into a shape and a color. A device reports batteryLevel = 18: the card fills a battery outline to 18% of its height, paints it red because the value sits below the first threshold, and prints 18 % inside the shape. When the same device recovers to 64, the fill grows past halfway and turns green.

• Charge state is readable at a glance — the fill height and the color both carry the value, so a wall of cards works as a traffic-light board even when the text is too small to read.
• Color follows thresholds you control — out of the box, red below 25, amber from 25 to 50, green from 50 up. Each band is editable, and the color can instead be a flat tone or a gradient across the range.
• Four shapes to choose from — vertical or horizontal, drawn as one solid fill or split into 2 to 20 segments, so the card can be as coarse or as precise as the reading deserves.
• Out-of-range readings still render — the fill is clamped to 0–100, so a device reporting 105 draws a full battery while the printed text keeps the value the device actually sent.
• A key that has never reported leaves the outline empty and prints N/A, so a silent device looks different from a flat one.
• The card shows one live value for one device: no history, no trend line, and no estimate of remaining runtime.

How to set up

Data keys

The Battery level card takes one datasource and one data key.

Key	Role	Type	Description
batteryLevel	The charge drawn and printed on the card	Timeseries	Charge as a percentage from 0 to 100. A server or shared attribute works equally well for devices that report charge as an attribute rather than telemetry.

The widget ships with a demo f(x) generator in place of a real datasource — replace it with the device and key you want to watch. Until the key reports a value the card renders the empty outline and prints N/A. Values above 100 or below 0 are clamped for the fill only; the printed number is left as sent.

How to customize

• To change how the battery is drawn — pick one of the four Layout options: Vertical. Solid, Horizontal. Solid, Vertical. Divided or Horizontal. Divided.
• To read the charge in steps instead of a continuous bar — choose a divided layout and set Sections count (2 to 20, four by default). A segment lights up once the value passes its share of the range.
• To use your own thresholds — edit the ranges under Battery level color. The same control also offers a single constant color or a gradient if bands are the wrong model for your hardware.
• To tint the empty part of the shape — edit Battery shape color. It ships with the same three bands at lower opacity, so the unfilled area still hints at the state.
• To leave only the shape — turn off Value.
• To keep the number legible at any card size — leave Auto scale on. Turn it off to pin an exact size and weight in Value font.
• To color the number independently of the fill — set Value color, which accepts a constant, ranges or a gradient just like the fill does.
• To show a different unit or precision — set the widget’s Units (% by default) and Decimals (0 by default).

Tips

• Match Sections count to the resolution your device actually reports. A node that sends charge in 10% steps reads cleanly with ten sections, while twenty sections on the same node leave half the segments permanently dark.
• If the device reports raw cell voltage rather than a percentage, convert it before it reaches the card. The fill is clamped to 0–100, so a 3.7 reading would otherwise draw as a full battery. A calculated field that maps the pack’s discharge curve onto a 0–100 scale gives the card the value it expects, and keeps the same thresholds meaningful across different chemistries.