Guides

Real Time Power Alerts

Suggest Edits

Introduction

EnergyAI provides customizable power alerts that notify users when total power off-take or feed-in exceeds or drops below specified thresholds. These alerts help users manage their energy consumption, prevent fuse blowouts, and optimize self-consumption of excess solar energy.

With Power Alerts, users can:

  • Set Power Thresholds – Define limits for power consumption and feed-in.
  • Receive Notifications – Get alerts when thresholds are exceeded.
  • Manage Thresholds – Modify or disable thresholds via API requests.

👍

Regularly monitor solar feed-in and off-take to optimize energy usage and minimize grid reliance.


Example User Journey (App)




👍

In this example the implementation follows a simple strategy where users can set just one threshold, which once surpassed, a notification will be triggered.

  • The Configuration Setting functionality section can be utilized to build various solutions from simple and straight-forward as this, to more user-engaging solutions, where various thresholds are set, renamed, monitored and adjusted by users.

Implementation considerations

  • Positive thresholds are set for users to be notified about electricity off-take, while negative thresholds are set for users to be notified about electricity feed-in.
  • The end-user can configure up to four thresholds for the MAIN phase, while up to two thresholds can be set for each individual phase (Phase 1, Phase 2, Phase 3) in the case of multi-phase installations.
  • The Power Thresholds functionality needs to be enabled on EnergyAI instance (Customer Platform) level.

API Endpoints

Response structure

GET Config

{
  "status": "ok",
  "data": {
    "mains": {
      "threshold_0": {
        "enabled": true,
        "threshold_value": 20,
        "alert_type": "upper",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      },
      "threshold_1": {
        "enabled": false,
        "threshold_value": 20,
        "alert_type": "none",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      }
    },
    "phase_1": {
      "threshold_0": {
        "enabled": true,
        "threshold_value": 20,
        "alert_type": "upper",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      },
      "threshold_1": {
        "enabled": false,
        "threshold_value": 20,
        "alert_type": "none",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      }
    },
    "phase_2": {
      "threshold_0": {
        "enabled": true,
        "threshold_value": 20,
        "alert_type": "upper",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      },
      "threshold_1": {
        "enabled": true,
        "threshold_value": 20,
        "alert_type": "lower",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      }
    },
    "phase_3": {
      "threshold_0": {
        "enabled": false,
        "threshold_value": 20,
        "alert_type": "none",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      },
      "threshold_1": {
        "enabled": true,
        "threshold_value": 20,
        "alert_type": "lower",
        "cooldown": 3600,
        "aggregation_method": "mean",
        "aggregation_sample_count": 10,
        "aggregation_sample_interval": 10,
        "last_updated": "2022-02-17T11:07:08+01:00"
      }
    }
  }
}

PUT Config

{  
	"mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1
         }
      }
}'

Field definitions

JSON objectsNotesDescription
mainsThe object that contains the various sets of configurations under MAINSThe power thresholds configuration map for mains. The map keys are the thresholds/configuration settings that are going to be updated.
Valid keys are "threshold_0", "threshold_1", "threshold_2", and "threshold_3".
phase_1The object that contains the various sets of configurations under phase 1The power thresholds configuration map for phase 1. The map keys are the thresholds/configuration settings that are going to be
updated. Valid keys are "threshold_0" and "threshold_1".
phase_2The object that contains the various sets of configurations under phase 2The power thresholds configuration map for phase 2. The map keys are the thresholds/configuration settings that are going to be
updated. Valid keys are "threshold_0" and "threshold_1".
phase_3The object that contains the various sets of configurations under phase 2The power thresholds configuration map for phase 3. The map keys are the thresholds/configuration settings that are going to be
updated. Valid keys are "threshold_0" and "threshold_1".

The specific configuration set by the user is indicated by the threshold_#index JSON object

Valid keys for the aforementioned JSON objects are:

  • threshold_0
  • threshold_1
  • threshold_2
  • threshold_3

❗️

Four thresholds for the MAIN phase, while up to two thresholds can be set for each individual phase (Phase 1, Phase 2, Phase 3) in the case of multi-phase installations.

Each configuration set mapping (mains/phase - Threshold_#) can have the following fields:

FieldtypeDescriptionNotes
enabledbooleanIndicates the status of power alerts configuration.Required in PUT call
threshold_valueintegerContains threshold value in Watts.Required in PUT call
alert_typestringIndicates whether the threshold is upper (the alert triggers when power exceeds the threshold), lower (the
alert triggers when power falls below the threshold) or both upper and lower.

Important note: In cases where an existing configuration is disabled (enabled = false) this field will always return the none value. For reactivating a previously activated and disabled configuration setting, the relevant correct value should be redefined in the PUT call (upper, lower or both)		Required in PUT call
cooldownintegerIndicates the cooldown period, in seconds, between two consecutive reported alerts.
The default cooldown period is 15 seconds.
aggregation_methodstringIndicates the aggregation method to use (mean, mode, median, or none). The default aggregation method is mean. Allowed values are mean,mode, median,none
aggregation_sample_countintegerIndicates the number of samples to consider for aggregation, with a default configuration of 5 samples.
`aggregation_sample_intervalintegerIndicates the interval between samples, in seconds, for aggregation, with a default configuration of 1 second.

Error Handling


ErrorDescription
117Gateway is processing the last configuration. Please try again in a few seconds.
152User does not have a valid household object.
153No valid meter found for user.
422Invalid input.
425Real Time power alerts are disabled.
999Unspecified error.

Configuration setting functionality

1. Retrieve thresholds' configuration

When a completely new device is used (i.e. one for which no thresholds have ever been set), the GET /power-thresholds/config request will return an empty response like the following:

{
  "status": "ok",
  "data": []
}

2. Configure 2 thresholds

Executing the below PUT /power-thresholds/configcall sets 2 thresholds for the "mains" phase, one positive and one negative.

{ 
	"mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1
         }
      }

3. Retrieve thresholds' configuration after setting 2 thresholds.

Executing a GET /power-thresholds/config call after we have configured two thresholds, returns:

{
   "status":"ok",
   "data":{
      "mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10,
            "last_updated":"2025-02-17T12:54:26"
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T12:54:26"
         }
      }
   }
}

📘

At this point, the user will receive separate notifications if their power exceeds 800W or their feed-in drops below -250W (e.g., from -250W to -251W)

4. Disable an active threshold including optional request body fields

The following PUT /power-thresholds/config call disables threshold_1:

{  
	"mains":{
         "threshold_1":{
            "enabled":false,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10
         }
      }
}

5. Retrieve thresholds' configuration after disabling a threshold

Executing a GET /power-thresholds/config call after disabling a threshold (threshold_1) we get the following response:

{
   "status":"ok",
   "data":{
      "mains":{
         "threshold_1":{
            "enabled":false,
            "threshold_value":-250,
            "alert_type":"none",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10,
            "last_updated":"2025-02-17T17:01:32"
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:01:32"
         }
      }
   }
}

6. Re-enable disabled thresholds with all the threshold config fields

Executing the following PUT /power-thresholds/config call re-enables the disabled threshold_1 threshold.

{  
	"mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10
         }
      }
}'

7. Retrieve the two enabled thresholds' configuration

Performing a GET /power-thresholds/config call after re-enabling threshold_1, we get the following response:

{
   "status":"ok",
   "data":{
      "mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":60,
            "aggregation_method":"mean",
            "aggregation_sample_count":10,
            "aggregation_sample_interval":10,
            "last_updated":"2025-02-17T17:05:43"
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:05:43"
         }
      }
   }
}

misc. 1: Disable a threshold using only the required fields

The following PUT /power-thresholds/config can be used to disable a threshold (threshold_1) using only the required fields:

{ 
 	"mains":{
         "threshold_1":{
            "enabled":false,
            "threshold_value":-250,
            "alert_type":"lower"
         }
      }

Performing a GET /power-thresholds/config call now, the result is:

{
   "status":"ok",
   "data":{
      "mains":{
         "threshold_1":{
            "enabled":false,
            "threshold_value":-250,
            "alert_type":"none",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:18:18"
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:18:18"
         }
      }
   }

threshold_1 is disabled (enabled: false and alert_type: none) but also has the aforementioned default values for the optional fields.

misc. 2: Re-enable a threshold using only the required fields

The following PUT /power-thresholds/config re-enables the previously disabled threshold using only the required fields:

{  
	"mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower"
         }
      }
}

Performing a GET /power-thresholds/config call now:

{
   "status":"ok",
   "data":{
      "mains":{
         "threshold_1":{
            "enabled":true,
            "threshold_value":-250,
            "alert_type":"lower",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:18:18"
         },
         "threshold_2":{
            "enabled":true,
            "threshold_value":800,
            "alert_type":"upper",
            "cooldown":15,
            "aggregation_method":"mean",
            "aggregation_sample_count":5,
            "aggregation_sample_interval":1,
            "last_updated":"2025-02-17T17:18:18"
         }
      }
   }
}

The re-enabled threshold (threshold_1) now has the default values in the optional fields.

❗️

Important note:

If the original, user-configured optional field values need to be kept when disabling and re-enabling a threshold, then they should be specified in the PUT /power-thresholds/config call in which the thresholds are disabled.


Notification functionality

Check the relevant Notifications guide to establish all the preliminary steps needed to incorporate the Power Alerts notifications' functionality.

Power Alerts can be sent through all the available Notification Channels

Notification codes/types

Notification typeNotification message
PT001.1Total power off-take has exceeded the defined upper threshold
PT001.2Total power off-take has dropped below the defined lower threshold
PT002.1Total power feed-in has exceeded the defined upper threshold
PT002.2Total power feed-in has dropped below the defined lower threshold

❗️

When an installation feeds energy back to the grid, the power level has negative values, thus negative thresholds need to be defined for grid injection.

  • PT002.2 can be used for alerts about excessive energy fed to the grid.
  • PT002.1 can be used for alerts about low performance of a solar installation.

Consistently low performance in solar installations may indicate the need for maintenance or permanent shadowing.

The PT002.1 threshold can serve as a useful indicator during periods of high solar generation and low consumption, with a practical setting being the installed capacity minus the consumption of energy-intensive appliances.

Notification attributes & JSON message

Below there is a sample JSON message that the App will receive when a notification is fired by EnergyAI. Based on the included attributes the notification message within the App can be modified and personalized accordingly.

{
  "msg_code": "PT001.1",
  "power_threshold": 120, // the threshold set by the user
  "gateway_eui": 9574384526958817692,
  "timestamp": 1737102640216,
  "phase": 0,  // values can be 0, 1, 2, or 3 // phase may have been set by the user or specific phase can be used by default from the Apps for all configurations.
  "threshold_index": 0,  // values can be 0, 1, 2, or 3 // the specific set of configurations - this works as an ID for the specific set of configs set by the user.
  "trigger_value": "<value>",  // contains the IDD value that caused the threshold violation
  "msg_identifier": "PT001.1", // The notification code
  "external_installation_id": "OPTOLAB3016"
}

Supported devices

These notifications are currently supported by the following list of devices

Hardware TypeNumber of phases
SBWF46021 & 3
SBWF46121 & 3
SBLR49121 & 3
DNWF39133
SBWF10011

Updated 21 days ago