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

Grid Frequency Out of Range Alarm

  • Alarm Rule
  • 0 installs
  • v1.0.1
  • Nov 16, 2026
  • MIT license
  • v4.3+

Raise an alarm when the grid frequency goes too high or too low and stays there, with the frequency in the alarm details. Watches mains frequency deviation, over-frequency and under-frequency on energy meters, generators, UPS outputs, microgrids and solar inverter sites. Works for 50 Hz and 60 Hz grids, with a smaller clear range so the alarm does not go on and off near the limit.

Type
  • Alarm
Category
  • Threshold
  • Energy
Use Cases
  • Smart Energy
  • Smart Metering
  • Solar Monitoring
  • Industrial Automation

Who it’s for

Electricians, energy managers and plant engineers asking “is the grid frequency drifting away from 50 Hz?”, “is the generator or UPS output running too fast or too slow?”, “is our microgrid or solar inverter site holding a stable frequency?” — when a frequency outside the normal range must reach someone before motors, drives and clocks start to misbehave.

What it does

Reads the device’s frequency telemetry and compares it with the nominal frequency, 50 Hz by default. When the frequency moves more than 1 % above or below nominal (below 49.5 Hz or above 50.5 Hz) and stays there for 1 minute, the rule raises a Major alarm with the frequency in the alarm details. The alarm clears when the frequency is back within 0.8 % of nominal (49.6 to 50.4 Hz) for 1 minute. The smaller clear range stops the alarm from going on and off when the frequency stays close to the limit.

A reading that is not a number, such as ERR, does not raise or clear the alarm, but the 1-minute wait starts again. A reading of 0 Hz is handled the same way, because a meter sends 0 Hz when it sees no voltage at all, and that is a power outage, not a frequency problem.

frequency-alarm

How to set up

The rule has default values for every setting, so it works as soon as it is installed. Install on a device profile so the alarm covers every meter of that type at once and automatically picks up any new meter added later. Single-device installs are also supported.

The default nominal frequency is 50 Hz. On a 60 Hz grid, such as in North America, set nominalFrequency to 60 on the meters, or change the Default value on the nominal argument to 60.

How to customize

  • To use a different frequency key — change the Time series key on the metric argument (e.g. frequency → gridFrequency).
  • To use different tolerance or hold-time attribute names — change the Attribute key on the nominal, tolerancePercent, clearTolerancePercent, holdMinutes and clearHoldMinutes arguments (e.g. frequencyTolerancePercent → freqLimitPercent).
  • To change the nominal frequency and tolerances used when no per-device attribute is set — change the Default value on the nominal, tolerancePercent and clearTolerancePercent arguments. Keep the clear tolerance smaller than the trigger tolerance.
  • To change how long the frequency must stay out of range before the alarm, or back in range before it clears — change the Default value on the holdMinutes or clearHoldMinutes arguments.
  • To tune the frequency settings at runtime without editing the rule — set the value on the entity as a regular server-side attribute. It can be edited directly from a dashboard using Update Multiple Attributes input widget:
    • Per device — set the attribute (e.g. nominalFrequency, frequencyTolerancePercent) on the meter itself. The per-device value overrides the Default value.
    • Per customer (in deployments that use customers) — change Entity type on the relevant argument to Current owner, then set the attribute on the customer. Every meter that customer owns picks up that value.
  • To make the alarm manual-clear-only — remove the Clear condition. The alarm then stays active until an operator clears it.
  • To check the frequency only during regular operating hours — in the Trigger conditions’ Schedule, choose Active at a specific time (or Custom for different hours per day). The schedule repeats every week. For different hours per site, add an argument that reads the schedule JSON from a server-side attribute on the device, and set its Default value to {} so a device without the attribute raises the alarm at any time. Then switch the Schedule to Dynamic and pick that argument in Argument.
  • To control where the alarm shows up — toggle the propagation flags under Advanced settings.

Share Your Alarm Rule with the Community

Built a reliable alarm rule? Export it as a JSON from ThingsBoard and publish it to the IoT Hub. Share it with thousands of ThingsBoard developers and help the community react to incidents faster.