Battery State of Charge from Voltage

Who it’s for

Teams running battery-powered field devices ask “is this battery fine, or does it need attention?” Their hardware reports a raw battery voltage in volts, not a clean 0-100 percent — common on LoRaWAN and NB-IoT sensors, solar and off-grid nodes, multi-cell packs with a small BMS, and lead-acid backup power. If a device sends a batteryVoltage telemetry key, this card turns that number into an answer, without a rule chain in between.

What it does

A 4S LiFePO4 pack reporting 13.2 V reads as 3.3 V per cell, about 80%. Now say one cell drops to 2.9 V. The pack average still looks healthy, but the card raises an Imbalance verdict, because a spread that size predicts failure before the pack total does.

• Shows the voltage as the main reading, inside a battery glyph that fills between the empty and full points you set
• A color-coded verdict — OK, Low, Critical, Charging, Imbalance or Stale — names the state at a glance. Nobody has to read the number to know whether to act
• Chemistry-aware. Choose Li-SOCl2, CR2032, Li-ion / NCM, LiFePO4, Alkaline, NiMH or Lead-acid 12 V — or set your own voltages on Custom
• On flat chemistries, one voltage reading barely predicts charge. Li-SOCl2 cells in most long-life LoRaWAN sensors are a good example. So the percentage is hidden by default, and the card can read “on plateau” or “past the knee” instead
• Detects cell imbalance from a minimum and maximum cell voltage. This flags a failing pack before its average voltage looks wrong
• Replaces the built-in Battery level widget for a device that reports volts instead of percent. That widget needs a 0-100 value, which usually means a chemistry-specific conversion in a rule chain before anything shows
• Reads one device’s battery. It does not track a fleet of devices or chart the voltage trend over time — see Tips for both

How to set up

Data keys

Key	Role	Type	Description
Battery voltage key (batteryVoltage by default)	Main value	Timeseries	Required — the hero reading; nothing renders without it. Read as volts or millivolts, auto-detected unless Device reports voltage in says otherwise
Temperature key (temperature by default)	Ambient temperature	Timeseries	Optional — shown in the footer and used to mark the reading cold outside the chemistry’s operating window
Current key (current by default)	Charge direction	Timeseries	Optional — its sign drives the Charging verdict and the bolt; positive is charging
Cell imbalance: lowest cell voltage key (cellVoltageMin by default)	Min bound	Timeseries	Optional — bind together with the key below to turn on the imbalance check
Cell imbalance: highest cell voltage key (cellVoltageMax by default)	Max bound	Timeseries	Optional — bind together with the key above; both must be set before the check runs

Every optional key works the same way. None has a separate on/off switch: a name in the box turns that part of the card on, and an empty box turns it off. If the battery voltage key gives no number, the card names the reason instead of showing a generic error. It checks four things: no key is bound, the datasource uses a different name, the key is bound but has never reported, or the last value was not a number.

Device reports voltage in decides how the card reads a raw value, before any threshold is applied. That is why it lives here, not under Appearance. Auto-detect treats anything above roughly ten times the full cell voltage as millivolts, so 3600 and 3.6 both work. Use the explicit Volts or Millivolts option if auto-detect gets your device wrong.

Battery

Setting	Default	Effect
Chemistry preset	Li-ion / NCM	Supplies the full and empty voltages, the warning and critical points, the discharge curve, and the operating temperature window. Choose Custom to set all eight yourself
Cells in series	1	Divides the bound voltage by the cell count to get one cell’s voltage. A 4S LiFePO4 pack reading 13.2 V becomes 3.3 V per cell

How to customize

Thresholds (Custom preset only)

• To set your own full/empty range — switch Chemistry preset to Custom, then set Full voltage, per cell and Empty voltage, per cell (these start at 3.7 V and 3.0 V, so you have a starting point).
• To move where Low or Critical fires — set Warning voltage, per cell and Critical voltage, per cell. Leave either blank to turn that verdict off.
• To change when a reading is marked cold — set Operating temperature min, C and Operating temperature max, C. Leave either blank, and the card skips that check.
• To tune the imbalance alert — set Imbalance advisory, mV and Imbalance serious, mV. Leave them blank, and the card works them out from the full voltage: 3% and 5%, capped at 120 and 200 mV.

Estimate

• To turn the percentage on or off regardless of chemistry — set Estimated percentage to Show or Hide instead of Auto.
• To show a position instead of a percentage on a flat chemistry — turn on Plateau / knee phrase (only available on Li-SOCl2, CR2032 and LiFePO4).
• To relabel the estimate badge — edit Estimate marker text. It is drawn after the percentage, so the number reads as an estimate, not a measurement.
• To keep the estimate running past full voltage instead of pausing — turn off Pause estimate above full voltage.

Display

• To hide the glyph, the verdict chip or the chemistry line — turn off Show battery glyph, Show verdict chip or Show chemistry in footer.
• To stop a healthy, infrequent reporter from being dimmed as stale — raise Stale after (minutes) above the device’s reporting interval. 0, the default, turns the check off.
• To match your dashboard’s fonts — set Value font, Estimate line font and Title font.

Reading the bar and the verdicts

The bar is a voltage window, not a charge gauge. It shows where the reading sits between the empty and full voltages you set, and both ends are printed underneath, so there is no guessing. This is not the same as the percentage. The estimate follows the chemistry’s discharge curve, but the bar is a straight line in volts. On a curved chemistry, the two numbers can honestly disagree — read the bar for the reading’s position, and the estimate for the state of charge.

Sometimes a reading falls far outside that window — above 115% of full, or below half of empty. When that happens, the card stops trying to interpret it. The verdict chip reads Check setup, the bar stays empty, and the line underneath names the window the reading is outside — for example, above the 3.00-4.20 V window. This almost always means the preset does not match the battery: a pack voltage read against a per-cell preset, the wrong chemistry, or Cells in series left at 1. Fix the preset or the cell count, and the card returns to a normal verdict. It will not show a confident, full, green battery for a reading it cannot place.

The estimate pauses for its own reasons too, and it names them: estimate paused, charging while current is flowing, and estimate paused, above full for a reading off the top of the curve.

Tips

• Pair this card with the fleet-wide view when the real question is which device, out of many, needs a visit this week — not how one device is doing right now:

Device Health Card verified Andrii Zaiko

• If your pack reports every cell voltage as an array rather than a ready-made minimum and maximum, the imbalance check needs those two numbers computed first. This calculated field produces them, and normalizes millivolts to volts on the way:

Normalize Cell Voltages and Compute Spread verified Andrii Zaiko

• Raise an alarm on the same battery voltage key, at the chemistry’s critical point. Then a dying pack gets noticed even by someone who is not watching a dashboard.
• Put the two cell-voltage keys on a time-series chart together. This card shows today’s spread. The chart shows the month it started widening.