Compute Cell Spread from Min and Max

Who it’s for

Battery and energy-storage operators asking “how do I raise an alarm on cell imbalance?” and “what counts as a normal difference between the highest and lowest cell?” - anyone monitoring a multi-cell battery pack, a LiFePO4 or Li-ion storage bank, an EV or e-bike pack, a telecom or solar backup string, whose BMS reports only the highest and lowest cell voltage rather than the full per-cell array. Plenty of controllers do: they publish two numbers and keep the rest to themselves. This turns those two numbers into the one figure that predicts pack failure, and fixes the unit problem once, on the server, so every widget, chart and rule downstream sees the same correct value.

What it does

Reads the minimum and maximum cell voltage a BMS reports, fixes the units, and writes the lowest and highest cell voltage plus the imbalance between them:

Because cellSpreadMv is a real telemetry key and not a number drawn on one card, an alarm rule can fire on it, a chart can trend it, and every dashboard reads the same value.

It also normalises units: if the readings arrive in millivolts (any value above 100), they are converted to volts before anything is computed, so cellSpreadMv is correct whether the device sends 3.472 or 3472. And if the two keys are mapped the wrong way round, the field sorts them rather than reporting a negative spread that would read as a fault that is not there.

What cell imbalance means, and why pack voltage will not show it

A pack can read a healthy total voltage and a confident 100 percent while one cell quietly drifts out of line. The pack total cannot show it, because the cells sit in series and one cell sagging by 300 mV moves a 48 V pack by less than one percent - well inside the noise of an ordinary reading. The spread shows it immediately, and a widening spread over time is the earliest sign of a failing pack.

How to set up

1. Add this calculated field on the device or asset that carries the pack. Install it on the device profile instead to run it for every pack of that type at once, which is the usual choice for a fleet. A single-entity install behaves identically.
2. Check the two arguments against your own key names. cmin defaults to cellVoltageMin and cmax to cellVoltageMax.
3. Post or wait for a telemetry update. Neither argument carries a default, so the field stays quiet until the device has published both keys at least once - it will not invent a reading from a key that has never arrived. Once both are in, the three output keys appear and update on every new reading.
4. Use them: bind cellMinV / cellMaxV to a pack widget, trend cellSpreadMv on a time-series or range chart, and raise an alarm when cellSpreadMv crosses your imbalance threshold.

Choosing an imbalance threshold

Derive it from the cell’s full voltage rather than picking one number for every chemistry: advisory at 3 percent of full capped at 120 mV, serious at 5 percent capped at 200 mV. For LiFePO4 that is about 110 / 183 mV, and for Li-ion / NCM, 120 / 200 mV. The direction of travel matters more than the absolute figure, so alarm on the threshold and trend the value alongside it.

How to customize

• To read this from different BMS keys - change the Time series key on the cmin and cmax arguments.
• To change what counts as a millivolt reading - open the script and change the 100. Raise it only if you monitor modules above 100 V reported in volts.
• To rename the outputs - open the script and rename the result.* keys.

No average is produced, because two extremes cannot give a pack mean. The spread is rounded to whole millivolts, so a difference finer than 0.5 mV reads as 0.

See also

Trend cellSpreadMv on a Range chart or Time series chart with the thresholds above to watch the imbalance over time.

If your BMS sends the whole per-cell array rather than only the two extremes, that is the other template - it reads every cell, so it also gives you the pack average:

Normalize Cell Voltages and Compute Spread verified Andrii Zaiko