Skip to main content

Configuring eGauge Alerts (Modern Interface method)

Firmware version 4.6 or newer is needed to set up eGauge device alerts in the Modern Interface. Please see this article for information on checking and upgrading your eGauge meter firmware.

To view and acknowledge triggered alerts, see the Alert Viewer article.

eGauge device Alerts

eGauge device Alerts allow the meter to log and send alerts that may be triggered off a variety of conditions, such as the meter's configuration being changed, a remote SunSpec device fault, or advanced custom alerts such as voltage being out of expected range.

Alerts are displayed in the Modern Interface using the Alert Viewer, and may be configured to be sent via email or HTTP POST with JSON-formatted data.

Accessing the Alert Setup

To access the Alert Setup page, from the main menu access Setup → Alerts:

Setup sections

There are 3 main sections to configure for alerts:

  • Custom Alerts: These are custom, user-specified alerts. For example, a custom alert may be configured to trigger if total usage averages over 50 kW for a period of 15 minutes.
  • Alert delivery: If emailing or sending alert data via HTTP POST, the destination and configuration may be set up here.
  • System Alert Priorities: There are a number of built-in system alerts including device configuration changes or device reboots.

Custom Alerts

The Custom Alerts allows users to set up flexible alerts based on register data and other functions provided by the eGauge firmware. For a full list of available alert functions, visit /fundoc.html?alert on the particular meter (e.g., https://egaugehq.egauge.io/fundoc.html).

Click for more information

New custom alerts may be added by clicking the "add" button (1) at the top, existing alerts may be deleted clicking the "delete" button (2) to the right of the message, and any existing alerts may be modified by clicking anywhere on the custom alert line.

Create or Modify Alert

Be sure to save updated or new alerts by clicking "Save" in the lower right-hand corner of the page!

When editing an existing alert or creating a new alert, you may set information about the alert and the conditions required for it to trigger:

When creating or modifying an alert, there are 7 required fields to enter:

  • Name: The unique name for an alert
  • Priority: Priority level for the alert. For SMTP email alerts, once an alert-destination has been notified, only alerts of higher priority result in a new notification to that destination until the alert has been acknowledged or deleted via the alerts page.
  • Check frequency: How often to check the alert condition. Note, the interval frequency starts at the top of the interval. E.g., hourly is evaluated at the top of the hour, daily is evaluated at midnight, monthly at midnight on the first of the month, and so on.
  • Left formula: The left-hand side of the comparison formula. This may utilize register values, static numbers, and eGauge alert functions or custom Lua functions.
  • Operator: The operator to compare the left and right formulas. This may consist of:
    • Less than (<): If the left formula is less than the right formula
    • Less than or equal to (≤): If the left formula is less than or equal to the right formula
    • Equals (=): If the left formula equals the right formula
    • Not equals (≠): If the left formula does not equal the right formula
    • Greater than (>): If the left formula is greater than the right formula
    • Greater than or equal to (≥): If the left formula is greater than or equal to the right formula
  • Right formula: The right-hand side of the comparison formula. This may utilize register values, static numbers, and eGauge alert functions or custom Lua functions.
  • Message: The alert message that is displayed in the Alert Viewer details and any email alert messages. Several special variables may be used in the message:
    • %l: evaluated value of left formula
    • %L: formula of left formula condition
    • %r: evaluated value of right formula
    • %R: formula of right formula condition
    • %o: comparison operator of formula
    • %%: percentage character

Alert Delivery

In addition to the Alert Viewer in the Modern Interface, the eGauge meter may send alerts via SMTP-direct email, HTTP POST, or email via the eGuard Alert Service. This is configured in the "Alert delivery" section of the Alert Setup.

Click for more information

  • Report alerts to an external server: If this is enabled, when an eGauge device alerts triggers, the meter will attempt to utilize the destination configured here.
  • Report alerts to...: Select the appropriate service here. See the section below for details on the different options.
  • Min. alert priority to report: Only alerts with a higher priority level than this will be reported when triggered. When using an SMTP email gateway, this option is set per-email destination.
Report alerts to....

There are currently 3 methods of externally reporting alerts. Click to expand information for a given external method:

eGuard Alert Service The eGuard alert service provides an alternative to configuring the eGauge with SMTP credentials. This is especially useful for individual users that may not have SMTP login information available, as well as users with a large number of devices. The meter must be in an eGuard group controlled by the user.

When alerts are triggered, the meter makes an outboune HTTPS POST to eGauge.net with the alert information, and in turn eGauge.net logs the alerts and sends an email to the user.

The only configuration option is Min. alert priority to report which is the minimum alert priority this destination should receive alerts for. For example, if all alerts are set to priority 0, an alert destination with a minimum alert priority of 1 will not receive any alert emails.

More information on eGuard is available here Also note that eGuard features built-in alerts - those are covered in this article.

Email Gateway (SMTP)

Valid SMTP credentials and server information is required for the email-direct method. Multi-factor authentication or other high-security network applications may prevent SMTP email alerts from functioning, so the eGuard Alert Service email method is recommended.

There are several options to configure:

  • Custom "From" address: The From address to send the email from. If omitted, the From address defaults to the "User" configured below. This may be required if the "User" below is not a fully qualified email address.
  • Relay host: The SMTP server to send the email through. If this is left blank, the eGauge will attempt to directly send the email to the alert destination's email domain. Warning: most email servers will reject emails sent directly without a relay host.
  • User: If a relay host is specified, this is the username that should be sent to the relay for authentication. Note: some servers require the full email@domain user format, while others may only require the email user format.
  • Password: If a relay user is specified, this is the password that should be used to authenticate.

After configuring the server information, Alert destinations should be configured. Click on an existing destination to edit the information, or click the "Add" button in the upper right-hand corner of the table to add a new alert destination email.

When configuring a destination email, there are 3 options to configure:

image-1714423531345.png

  • Email address: The email address to send triggered alert information to. This may or may not be the same as the SMTP relay user information configured previously.
  • Min. alert priority: The minimum alert priority this destination should receive alerts for. For example, if all alerts are set to priority 0, an alert destination with a minimum alert priority of 1 will not receive any alert emails.
  • Email format: The length of the email to send to the destination. The "full" format provides a fully detailed alert email, while "short" only provides the highest-priority limit to stay within 140 characters, such as for use with email-to-SMS gateway addresses.

A "Send email" button allows the testing of an outbound email to that particular email destination. If successful, the destination email will receive a test email from the meter. Warning: if no Relay Host and credentials are configured, outbound emails may not work all the time, even if an initial "Send email" test is successful.

custom Custom alerts may be utilized by advanced users to send JSON-formatted data as an HTTP POST to a user-provided URL.

Several configuration options are available:

  • Min. alert priority to report: The minimum alert priority this destination should receive alerts for. For example, if all alerts are set to priority 0, an alert destination with a minimum alert priority of 1 will not receive any alert emails.
  • Custom URL: The URL to POST alert information when triggered.
  • Alert options: Any options to use when sending alerts. The available options are currently:
    • deflate: Use "deflate" content-encoding compression when posting alerts.
    • gzip: Use "gzip" content-encoding compression when posting alerts.
    • secure: For HTTPS connections, fail if the alert provider server's certificate cannot be verified.
Click for JSON format and example data
{
  "now": "1568419537.35",
  "alerts": [
    {
      "id": 1804290019,
      "priority": 7,
      "occurrences": 12,
      "first_occurence": 4462.5,
      "last_occurence": 389.31,
      "name": "Device-configuration changed",
      "detail": "By owner."
    },
    {
      "id": 1804290035,
      "priority": 0,
      "occurrences": 1,
      "first_occurence": 0,
      "last_occurence": 0,
      "name": "Device rebooted by firmware",
      "detail": "Howdy do?"
    }
  ]
}
  • now is a 64-bit UNIX timestamp, possibly with a fractional (sub-second) part, formatted as a decimal integer string.
  • alerts is a list of reported alerts:
  • id is a number that uniquely identifies an alert. It is used, for example, to acknowledge or clear an alert.
  • priority is the user-assigned priority level of the alert (0 being the lowest priority and 7 the highest priority).
  • occurrences gives a count of how many times the alert has occurred since it was last cleared.
  • first_occurence and last_occurence specify how many seconds ago the alert occurred for the first time and the last time, respectively, relative to now. That is, the specified number should be subtracted from now to get the absolute UNIX timestamp of when the alert occurred first and last, respectively.
  • name is the name of the alert that occurred.
  • detail provides additional detail on the alert that occurred.

System Alert Priorities

System alerts are always logged and can be viewed in the Alerts View. Priorities may only need to be changed if alerts are being sent to an external server configured in the Alert Delivery section.

There are a number of built-in system alerts including device configuration changes or device reboots.

In this section, the priority level of each system alert may be configured. For example, a user may have an unstable internet connection and may not want to be alerted whenever the proxy-connection is lost or re-established, but may want to be alerted about a remote device fault. In this case, the "Remote device fault" may be set at priority 1, while "Proxy-connection established" and "Proxy-connection lost" are set to priority 0. The alert destination, if set to a minimum priority level 1 will receive alerts for the remote device fault, but not for proxy-connection events.

Custom Alerts

For a full list of available alert functions, visit /fundoc.html?alert on the particular meter (e.g., https://egaugehq.egauge.io/fundoc.html).

eGauge Support has limited support for creating and troubleshooting custom alerts.

General Syntax

Custom alert formulas follow a logical expression format.

$"REG NAME" returns the instantaneous value of the register REG NAME, while "REG NAME" points a function at a specific register (but doesn't return the register's value).

When using functions such as avg() or others listed in the function documentation, be sure to use the correct format. E.g., a function expecting a "string" will expect a quoted register name (e.g., "REG NAME") while a function expecting a number (instantaneous register value) will expect the register's current value (e.g., $"REG NAME", with the prefixed $).

Generic syntax examples:

Expression Description
3+4*5 Equals 23
(3+4)*5 Equals 35
sqrt(9) The square-root of 9 (i.e., 3)
$"Grid" The instantaneous value of register Grid (e.g., 500 W)
(3>4) ? 3.14 : 10 Conditional expression evaluating to 10 (as 3>4 is false)

As this table shows, basic arithmetic operations with normal precedence rules are supported: multiplication/division have higher precedence than addition/subtraction. Parentheses can be used to override the normal precedence-rules. Various functions such as sqrt() (square-root) are also supported. The exact functions supported depends on the context.

Basic functions are supported in any expression, whereas certain Alert functions are available only in alert conditions. The value of a register can be obtained by enclosing its name in quotes (") and prefixing it with a dollar sign ($). Conditional expressions consist of 3 parts: the control-expression before the question-mark, the if-true-value after the question-mark, and the if-false-value after the colon. If the control-expression has a non-zero value, the conditional expression evaluates to the if-true-value, otherwise, to the if-false-value. All numeric values are represented as IEEE-754 single-precision (32-bit) float values. Limited recursion is supported with the depth of the evaluation stack limited to 128 entries.

L1 Voltage High

The following example checks every 1-second whether the register "Voltage L1" is greater than or equal to 126. Note, this is a simple numerical calculation without any functions, so we get the instantaneous value of the Voltage L1 register by prefacing it with an $ as $"Voltage L1".

Daily Grid High

The following example checks every 1-day whether the Grid's previous day (1440 minutes) usage averaged 50 kW (50000 watts) or more. Note, the avg() function requires a register name, so we do not preface the register name with an $.