Skip to content

Cookie preferences

We use cookies for our own analytics, to see how our campaigns perform and, if you allow it, to load content from other services such as the Google site search. We never sell your data. Necessary cookies keep the site working and cannot be switched off. See our Cookie Policy for details and our Privacy Policy for how we handle personal data.

Security, load balancing and remembering your cookie choice.

Show us which pages people read, how they find the site and where they get stuck, so we can improve it (Google Analytics, Microsoft Clarity).

Show us which of our ad campaigns bring visitors to the site and remember the campaign or partner link you arrived from (Google Ads, LinkedIn, Meta, partner program). We do not use these cookies to build advertising profiles.

Load the site search from Google when you use it. Google sets its own cookies and shows ads in the search results.

© 2026 The ThingsBoard Authors

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

Rather run it yourself? Install on your own servers

Calculate Three-Phase Voltage Imbalance Percentage

  • Calculated Field
  • 0 installs
  • v1.0.1
  • Nov 13, 2026
  • MIT license
  • v4.3+

Calculate three-phase voltage unbalance in percent from L1, L2 and L3 phase voltages with the NEMA method: the largest deviation from the mean, divided by the mean. For motor protection, power quality checks, energy meters, power analyzers, pumps, compressors and switchboards. Writes one key for dashboards and unbalance alarms.

Type
  • Script
Category
  • Energy
  • Custom Formula
Use Cases
  • Industrial Automation
  • Predictive Maintenance
  • Smart Energy
  • Smart Metering

Who it’s for

Maintenance engineers, electricians and energy managers asking “how unbalanced is the supply voltage on this motor?”, “is one phase of the feeder lower than the others?”, “is the voltage unbalance above 1 % or 2 %?” — when the meter reports each phase voltage on its own and nobody sees the unbalance until a motor runs hot or trips.

What it does

Reads the latest voltageL1, voltageL2 and voltageL3 telemetry, finds the mean of the three, and writes the largest deviation of a phase from that mean as a percent of the mean, as voltageImbalancePercent:

voltage-imbalance

This is the NEMA MG 1 definition of voltage unbalance. It uses only the voltage magnitudes, so any three-phase meter can feed it. The IEC method uses phase angles too and can give a slightly different number. NEMA MG 1 and the usual limits of 1 %, 2 % and 5 % are for line-to-line voltages. Phase-to-neutral voltages work too, but for the same supply they give a higher number, often about twice as high, so set your limits for the kind of voltage you feed it. Feed it three values of one kind: all line-to-line or all phase-to-neutral voltages.

Some examples with line-to-line voltages: 408, 400 and 392 V give 2.0 %, and 420, 400 and 380 V give 5.0 %. With phase-to-neutral voltages, 234.6, 230 and 225.4 V give 2.0 %, while the line-to-line voltages of the same supply give 1.0 %. A lost phase (0, 230 and 230 V phase-to-neutral) gives 100.0 %. One decimal lets you tell 1.9 % from 2.1 % near those limits.

The field works best when the meter sends the three voltages in one message. When they arrive one by one, the field computes after each of them with the last values of the other two. A supply loss then writes 100.0 % and 200.0 % first, and 200.0 % stays the latest value until the supply comes back.

How to customize

  • To use this on your meter’s keys — change the Time series key on the phaseL1, phaseL2 and phaseL3 arguments (e.g. voltageL1 → Ua).
  • To rename the output — open the Script and replace voltageImbalancePercent in the returned object with your own key (e.g. voltageUnbalance).
  • To show two decimals — open the Script and change the 1 in toFixed(…, 1) to 2.
  • To timestamp the result with server time — open the Script and return { voltageImbalancePercent: … } at the top level instead of inside values.
  • To filter, transform, or forward the result to external systems — switch Strategy to Process via Rule Chains. Rule nodes then receive the value and can drop it, change it, save it conditionally, or push it to an external system.

See also

Unbalanced phase currents are the other half of the picture. To raise an alarm when the current of one phase moves away from the others:

Motor Phase Current Imbalance Alarm Dmytro Shvaika

To raise an alarm when the voltage unbalance stays above the limit:

Three-Phase Voltage Imbalance Alarm Dmytro Shvaika

Share Your Calculated Field with the Community

Built a useful data transformation? Export it as a JSON from ThingsBoard and publish it to the IoT Hub. Share it with thousands of ThingsBoard developers worldwide.