Advanced eGauge Operation

Covers advanced operations, such as working with Alerts and other advanced software features

USB thumb-drive functionality

eGauge Core/Pro have USB and thumb-drive storage functionality

USB thumb-drive functionality

Automated USB Export and Upgrade scripting file

Introduction

Starting with firmware v3.4, eGauge firmware supports USB Mass-Storage devices on hardware with USB ports (e.g., EG4115 (Core) and EG4130 (Pro)).  Both Windows VFAT and Linux EXT3 filesystems are supported.  When the eGauge device detects a valid storage device, it will automatically bring up a USB Storage menu on the LCD screen.  From there, it is possible to select various operations, such as:

For flexibility and to simplify operations when it is necessary to perform the same USB Storage task on multiple devices, the firmware also supports a script file called auto.run.  When this file is present in the top-level directory (root folder) of the USB storage device, it will be executed as soon as the USB storage device is detected by the firmware.  The details of how this file is executed are specified below.

 

Scripting Language

The auto.run file consists of a sequence of text lines, each line containing a command.  Commands are executed in sequence, one by one.  If a command fails for any reason, script execution stops and the most recent error is displayed on the LCD screen.  The operator needs to acknowledge the error by pushing the multiswitch button and, once that is done, the USB Storage menu is displayed.

In the absence of errors, script execution stops upon reaching the end of the script file or after execution of an "eject" command (see below).  After reaching the end of the script, the USB storage menu is displayed on the LCD.  After an "eject" command, the LCD screen reverts to normal operation.  The USB storage device is then no longer accessible until the USB storage device is removed and reinserted into the USB port or the device is rebooted (e.g., power cycled or rebooted via firmware).

Script files may contain line-comments that start with a hash character (#).  The hash character and any following characters up to the end of the line are ignored.

 

Script Commands

In the following descriptions, square brackets are used to indicate optional parts of a command. Italics is used as place-holders for variable content.


backup [FILENAME_TEMPLATE]

Backup the eGauge device data to the file specified by FILENAME_TEMPLATE.  This string may contain references to variables that are expanded as follows:

Variable Reference

Expands to

Example

${DEVNAME}

eGauge device name

eGauge1234

${SN}

eGauge serial number

1701260002

${TIME}

current date and time

20180411-1310

 

If FILENAME_TEMPLATE is omitted, the template:

backup-${DEVNAME}-${TIME}.bin

is used by default.


export [PERIOD [GRAN [FILENAME_TEMPLATE]]]

Export eGauge device data to the file specified by FILENAME_TEMPLATE.  The data is saved in comma-separated-values (CSV) format.  The file-name template may use the same variables as the backup command.  In addition, the following variables are supported:

Variable Reference

Expands to

Example

${PERIOD}

export time-period

ytd

${GRAN}

export granularity

hour

PERIOD specifies the time period of the data to be exported:

Period specified

Time range covered

day

Most recent 24 hours of data are exported.

month

Most recent 31 days of data are exported.

year

Most recent 366 days of data are exported.

all

All data is exported.

dtd

day-to-date: export data from midnight up to current time

mtd

month-to-date: export data from start of month up to current time

ytd

year-to-date: export data from start of year up to current time

GRAN specifies the granularity (resolution) with which the data is exported:

Granularity specified

Resolution

sec

Second resolution (or best available).

min

Minute resolution (or best available).

quarter

15-minute resolution (or best available).

hour

Hour resolution (or best available).

day

Day resolution.

Note that the eGauge device database internally uses varying granularity to balance storage requirements with the ability to retain data for long time periods.  Specifically, second-by-second data is typically retained only for the most recent hour, then dropping to minute-granularity, until at last day-by-day data is available for the longest amount of time (e.g., 60 years).  The granularity specified in the export command is the finest resolution to be used during the export.  If the database doesn't have the data available in the desired resolution, it will automatically exported in the best available resolution.

Also worth mention is that day-granularity data is captured every day at midnight UTC.  The date and time exported in the CSV file is converted to the device's time-zone, which means the hour seen in the exported data may be one or the other, depending on whether or not daylight savings is in effect.  For example, in US/Mountain time-zone, day-granularity data is captured at 6pm (18:00) during the summer months and at 5pm (17:00) during the winter months.


update_fw [[PATH] force]

Update the device firmware using the file specified by PATH.  If PATH is omitted, the file fw.bin will be used.

The update will be performed only if the file contains a firmware newer than the one that is currently installed.  However, if option "force" is specified after the file path, the update will be performed regardless of the version currently installed on the eGauge device.

After a successful update, the LCD screen will indicate that the device needs to be rebooted.  The operator needs to confirm this by pushing in the multiswitch button and that point, the eGauge device reboots itself to activate the new firmware.


eject

This command ejects (unmounts) the USB storage device and stops script execution.  Once the command has finished, the LCD screen returns to normal operation and it is safe to remove the USB storage device from the USB port at that point.

 


 

Example Script

In the following example, let's assume the device name is "eGauge1234" and the commands are all executed on April 1st, 2018, at 1:14pm (13:14).

# This is a comment.  It has no effect on execution.

# OK, let's do a backup first:
backup # will be saved in "backup-eGauge1234-20180401-1314.bin"

# Export data to "data-eGauge1234-ytd-hour.csv":
export ytd hour data-${DEVNAME}-${PERIOD}-${GRAN}.csv

# Eject USB storage and return eGauge device to normal operation:
eject

 

USB thumb-drive functionality

USB Data Exports through LCD

Data can be exported directly from eGauge 4xxx meters using a USB mass storage device. These exports automatically contain day-granular data. All data from epoch (the date set in "Date and Time Recording Started" under Settings -> General Settings) until the date and time the export was initiated is copied. 

To select a specific granularity or time range (or otherwise automate USB exports), an auto.run file must be created and loaded on the USB mass storage device (this article has more information).

To begin the process, insert a mass storage device formatted as EXT3 or VFAT. The "Storage Menu" will appear. Menu navigation is performed using the multiswitch button. Moving the switch left or right will change the selected option. Pushing the multiswitch in will confirm the selection. "Export data" should be highlighted by default. To begin the export, push the multiswitch in:

Once the export has begun, the screen will read "export started". The export process takes a variable amount of time depending on the amount of data present on the eGauge.

Once the export has finished, the screen will read "export finished". The "OK" option will be highlighted. Push the multiswitch in to acknowledge.

After acknowledging the export, the "Storage Menu" will appear again. Move the switch left or right until "Exit & Eject" is highlighted. Push the multiswitch in to select this option.

Once the main LCD menu appears, the USB mass storage device can be safely removed.

USB thumb-drive functionality

Formatting a USB stick on Windows 10

These instructions may not work for all versions of Windows and are provided as-is. eGauge Support cannot provide additional troubleshooting or support on formatting USB sticks. An adequate understanding of using the Windows operating system and file explorer may be necessary to complete these instructions.

This will permanently erase all data on the selected drive or USB stick. Incorrect usage can cause permanent data loss on the wrong drive.

1) Connect a USB stick to a PC running the latest version of Windows 10.

2) Click on the Start Menu and type in "this pc" and open the "This PC" app.

image-1622141210699.png

3) In the "This PC" window, right-click the USB stick and choose "Format..."

image-1622141320231.png

4) Ensure the "File system" is set to FAT32, and "Quick Format" is checked. The "Volume label" does not matter. Press "Start".

image-1622141347791.png

5) When complete, the USB stick is ready for use with an eGauge.

If copying files such as auto.run and fw.bin, open another explorer window to where the files are downloaded on your computer, and open the USB drive. Select the file(s) and drag the files to the explorer window of the USB stick.

image-1622141555421.png

6) After the files are copied, click the "back" button on the USB stick window, right-click the USB stick drive and choose "Eject".

image-1622141610887.png

7) Remove the USB stick. It is now ready for use with the eGauge meter.

Alerts

All about eGauge Alert functionality

Alerts

Alerts and Email Gateway with SendGrid

Introduction

If delivering email to only one recipient, consider using the eGuard Alert Service to send device alerts as it is the easiest method for delivering email alerts.

You will need your own website's email address to send email from; Gmail, Yahoo, AOL and other public email services may not work with this method.

SendGrid is a free third party service unaffiliated with eGauge which provides a consistent outbound email delivery service. It can be used for eGauge alert delivery, and is more reliable than not having any "Email Gateway" information entered. Without an "Email Gateway" configured, alert emails may be rejected, dropped, or fail inconsistently.

It is intended as a commercial service for businesses rather than individual end users.

SendGrid allows up to 100 emails daily with the free plan.

SendGrid provides delivery information and monitoring such as email delivery failures, number of emails sent and other features.

 

Disclaimer

SendGrid is a third party email delivery service with no affiliation with eGauge Systems. eGauge Systems cannot guarantee email delivery, uptime, or security of using SendGrid.

Information on this page will be updated on best effort level. Information including pricing, set up instructions, screenshots, and locations of items are not guaranteed to be up to date or consistent.

eGauge Systems does not provide any support for SendGrid's services, and cannot assist with account creation, password recovery, or similar issues.

Pre-setup notes

Ensure the eGauge meter used is on firmware v4.0 or greater, click here for information on checking and upgrading firmware.

Email can be delivered from the eGauge meter using SMTP server smtp.sendgrid.com and a sendgrid API key.

API keys are passwords and are displayed only once after creation.

Setup

  1. Set up API keys:
    Initial account creation and setup wizard for first email
        or
    Adding a second API key, or adding without the wizard from the main dashboard
  2. Verify a sender identity
  3. Configure the eGauge meter

 

Initial account creation and setup wizard for first email

  1. Create an account at https://sendgrid.com/

  2. Click "Start" to the right of "Integrate using our Web API or SMTP relay"

  3. In "Choose a setup method", choose "SMTP relay"


  4. Give the API key a name, like "eGauge Alerts Emails" and press "Create Key"


  5. You will now be given the SMTP server (smtp.sendgrid.net), the username (apikey), and password (hidden). This is the only time the password will be displayed, it should be saved somewhere securely like an encrypted keychain if it will be used more than once. Keep this page open or copy the password as it will be used in a later step.

Adding a second API key, or adding without the wizard from the main dashboard

  1. In the main dashboard on the left-side menubar, expand Settings and click API keys.

    image-1657573543458.png

  2. Click "Create API Key" in the upper right-hand corner:
    image-1657573663515.png
  3. Choose "Restricted Access" as the API key permissions, expand the "Mail Send" section, and click the dot on the right side of the bar next to "Mail Send" to grant that permission


  4. Click "Create and View", and copy the API key displayed on the next screen. This will be used to configure the eGauge meter in a later step.

Verify Sender Identity

You will need to set up Sender Authentication so the receiving email server trusts and accepts the email the eGauge meter delivers. Follow the instructions for Single Sender Authentication (simple: sends an email link to verify email address) or Domain Authentication (advanced: requires modifying DNS entries on your website).

Without sender authentication, you will see an error such as The from address does not match a verified Sender Identity when sending a test email without verification completed. It will contain a link with information to set up sender authentication.

The email address you verify will be used in the Custom "From" address setting in the eGauge meter alert settings.

 

Configure the eGauge Meter

  1. Navigate to Settings -> Alerts, ensure "Alert Provider" is set to "SMTP Gateway" and click on "View/Edit Gateway & Alert Destinations". Enter the mail server hostname (smtp.sendgrid.com), username (apikey), and the API key / password that was created previously. For the Custom "From" Address, enter an email identity verified in the previous step.

    image-1657575198734.png
  2. Enter the email address(es) that should receive alerts from the meter under Alert Destinations.

    image-1657575742987.png

  3. Press "Save" at the bottom of the page, and then "Send Test Message" to the right of each Alert Destination to ensure the delivery works.

 

Alerts

Configuring eGauge Alerts

Overview

The eGauge can be configured to send alerts based on a variety of trigger conditions. Alerts must be configured through the eGauge interface, and the eGauge needs to be powered on and connected to the internet in order to send alerts. There are three possible alert destinations: SMTP (email or SMS-capable phone numbers via an email-to-SMS gateway if the cellular provider supports), the eGuard alert service, or a custom URI for a JSON POST (advanced users).

SMTP emails credentials may be supplied, and the eGauge will use this email account to generate alerts. Some services such as Gmail may restrict logins to browsers, or disallow the login if devices in different locations are attempting to all log in to send alerts. For large larger deployments a service such as SendGrid may be used.

The eGuard Alert Service is a more simplified email alert delivery service and only requires you have an eGauge.net account.

The following article covers basic alert configuration and provides some sample alerts. Additional information is available on an eGauge-specific basis by navigating to http://DEVNAME.egaug.es/fundoc.html?alert where DEVNAME is the device name of your specific eGauge. To take advantage of all alert features, the eGauge should be on the latest firmware.

 

Contents

Alert Basics

Configuring the Alert Service Provider

          SMTP Gateway

         Using SendGrid

         eGuard Alert Service

         Custom Alert Destinations

Configuring Alerts

         System Alerts

         User Defined Alerts

Viewing and Acknowledging Alerts

User-defined Alert Examples

Example and description of POST data

 

Alert Basics

Alerts may be configured from the Settings → Alerts page and viewed from View → Alerts. There are two types of alerts: system alerts and user-defined alerts. System alerts can report conditions such as when the device configuration is changed or when the connection to a remote device has been established. User-defined alerts are built arbitrary conditions that, when true, trigger the alert. For example, you could define an alert that triggers when solar production for a period is below a certain threshold value, or an alert that triggers when the register monitoring Oven usage has been above a certain value for a certain time. More examples are available here.

 

Configuring the Alert Service Provider

Choose the View/Edit Gateway & Alert Destinations button from the top of the Alerts page to configure how alerts are sent. The page will request credentials in order to make changes if none have been previously cached. 

 
SMTP Gateway

image-1598029453892.png

The SMTP Gateway Alert Service Provider allows the eGauge to send alerts directly to email addresses, SMS-enabled phones, or a mixture of the two. This functionality requires an internet connection, but does not require the eGauge to be connected to the proxy server at d.egauge.net. The following fields are required:

Hostname of mail server

Normally, eGauge attempts to deliver email directly to the destination address. Similarly, it attempts to deliver SMS directly to an SMS-gateway. However, if a firewall prevents the device from directly establishing such connections, as is commonly the case for consumer-grade Internet-service, you will have to set the value of this setting to the hostname of a mail server which can forward the messages to the final destination. The mail server may either be a host on the same LAN (e.g., within a company or school network) that will accept email delivery without authentication or it may be am external mail server where you have  a valid user account. By specifying the username and password for that account, the device is then able to deliver email through that mail server (ie, the alert messages from the eGauge will originate from your username on that mail server). As an example, if you have a Gmail account, you can set the hostname to smtp.gmail.com. By specifying your Google account’s username and password, you can then have alerts delivered via Gmail. 

Username for mail server

When non-empty, this setting specifies the username the device uses to authenticate itself to the mail server. If empty, mail is delivered without authentication or encryption. Note that this option is required for almost all mail servers.

Password for mail server

This setting specifies the password the device uses to authenticate itself to the mail server. It is used only if Username is not empty.

Caution: This password is transmitted to the eGauge over an unencrypted channel. Only change this password from a computer that’s connected to the same LAN as the eGauge and only after clicking on the LAN Access link on the eGauge main page. As an added security measure, create a dedicate email account at the mail server for sending eGauge alerts.

 
Using SendGrid

SendGrid credentials are entered in the SMTP Alert Service Provider fields. For more information on using SendGrid or a similar service, please refer to this article.

 
Setting Alert Destinations

image-1598030888514.png

Message Format: select the appropriate SMS carrier or email format.
Email address or phone number: enter the appropriate destination for the alert.
Min. Alert Prio (Minimum Alert Priority): minimum level of alerts this destination should receive (see below).

Up to four alert-destinations can be defined. Alerts are prioritized. For each alert-destination, a minimum priority can be defined. Only alerts whose priority is equal to or greater than the minimum priority are reported to an alert-destination. 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, or after 24 hours have passed. 

 

eGuard Alert Service

image-1598030496087.png

The eGuard alert service provides an alternative to configuring the eGauge with SMTP credentials. This is especially useful for users with a large number of devices. The meter must be in an eGuard group controlled by the user. More information on eGuard is available here. Also note that eGuard features built-in alerts - those are covered in this article.

To use the eGuard Alert Service, simply select "eGuard Alert Service" and click the "Activate" button. A new window will open, and you will be prompted to log in to eGuard. Once logged in (or if you are already logged in), eGuard will confirm you want to register this device for alerts. Click "Register for Alerts" to confirm.

image-1598030729373.png

Minimum priority to report: Setting this to a value other than zero will omit any alerts with a priority set lower than that value. This can be useful when certain alerts are not required (eg, set all system alerts to zero, set minimum priority to report to 1, then set all user-defined alerts to 1).

 

Custom Alert Destinations

image-1598031072095.png

Custom alerts may be utilized by advanced users to send JSON-formatted data as a POST to a user-provided URI (alert destination).

Alert Provider: Must be set to "custom".

URI: The URI to send the JSON POST to. Should be unique to the device, such as with a GET token to uniquely identify the device making the POST.

Options: A comma separated list of options available below:

Do not use multiple compression schema, i.e., do not use gzip AND deflate on the same device.

Minimum priority to report: All alerts with a priority level equal to or greater than this will be POSTed to the URI when triggered. To prevent some or all system alerts from being reported, this may be set to "1" or greater. When alerts below the minimum priority level are triggered, they are only logged on the device locally and do not create a POST.

An example of the JSON post contents is available here.

 

Configuring Alerts

Alerts are reported with a delay of approximately 30 seconds and are automatically acknowledged 24 hours after reporting them. These rules ensure you will be promptly informed of any alert conditions for a device without a deluge of SMS or email messages. Alerts of higher priority are reported even if there are pending alerts of a lower priority.

There are two types of alerts: System alerts and User-defined alerts

 

System Alerts

System alerts are predefined but you can choose the priority with which they are reported. This allows control over which recipients receives which system alerts (if any) and which alerts are more important. To set an alert priority, use the dropdowns in the "Prio" column. If there are certain system-alerts that you do not wish to have reported at all, select priority 0 and ensure that all alert destinations have a minimum alert priority of at least 1. Note that alerts with a priority of 0 will still be logged on the Alerts page, but no notifications will be sent for those alerts if all alert destination priorities are higher than 1.

image-1598035794750.png

Proxy-connection established/lost: tracks when a connection to the proxy server at d.egauge.net is opened or closed. If this occurs frequently it can indicate an unstable network connection.

Device-configuration changed: reports when a device’s configuration is changed, and which account has made the modification.

Date and/or Time changed: reports when the device date or time is changed (either by the user or automatically).

Device running hot: reports if the eGauge’s internal temperature reaches a significantly high temperature.

Device temperature OK: reports when the eGauge’s temperature returns to a safe level.

Remote-device connected: tracks when a connection is established to a remote device (including Modbus devices and remote eGauges).

Remote-device lost: tracks when a connection to a remote device is lost (including Modbus devices and remote eGauges).

Failed to push data: reports if a data push is set, and the eGauge is unable to successfully push data.

Device up and running/Device rebooted by firmware: tracks when the meter is rebooted, and when the meter comes back online from a reboot or power outage.

Network interface changed: tracks when the meter switches from an Ethernet (ETH) to HomePlug (PLC) connection. This may happen immediately after a reboot and can generally be ignored.

Database error: typically reports when the device configuration is changed. The occasional database error is considered normal, but if this alert triggers multiple times per day and no configuration changes are being made it may indicate an issue. If this happens, contact eGauge support at support@egauge.net.

Web server down/Web server up: reports when the eGauge's internal webserver stops and starts. This will generally happen as the result of a reboot, and may happen as a normal occurrence during regular operation (for example, watchdog resets). If this alert triggers multiple times per day for several days it may indicate an issue.

Remote device fault/Remote device fault cleared: reports when Sunspec fault codes trigger on a remote Modbus device, and when those fault codes are cleared.

Failed to connect to server: reports when certain outbound connections fail, typically alert POSTs when using a custom alert destination.

 

User Defined Alerts

User-defined alert patterns allow the flexible detection and reporting of various conditions. For example, an alert could be defined which, on a second-by-second basis, checks whether a register value is outside of its permitted range (e.g., whether a voltage or frequency is above or below a certain threshold).

image-1598041425850.png

The alert fields are described below:

Name: The name of the alert. This should be short but informative enough to convey the nature of the alert.

Trigger Condition: The trigger condition consists of three parts: left-hand-side (lhs), comparison operator, and right-hand-side (rhs). The comparison operator may be one of less-than (<), less-or-equal (<=), equal (=), not-equal (!=), greater-orequal (>=), or greater-than  (>). The lhs is compared to the rhs based on this operator and, if true, the alert is triggered.

Chk Freq (Check Frequency): select the frequency with which the trigger condition is to be checked. eGauge evaluates all alert conditions whenever the device starts up and hence may evaluate the conditions more frequently than requested. Apart from the first time a condition is checked on start up, hourly conditions are evaluated during the first minute of each hour, daily conditions during the first hour after midnight, weekly conditions during the first hour of Sunday, monthly conditions during the first hour of the first day of the month, and annual conditions during the first hour of the first day of the year. “Every second” conditions are evaluated each second, “Every minute” conditions once a minute.

Choose the lowest check frequency possible as evaluating too many conditions too often may slow down the device. If a slow-running condition (eg, a condition using the peak_risk() function) is evaluated, evaluation of other conditions may be delayed until the evaluation of that condition is completed.

Msg (Message): use this field to define a custom-message to be displayed along with the alert name. If left empty, a default message is included which shows the value of the lhs, the operator, and the rhs of the trigger-condition. A well-written message will explain the alert - for example, on a "Low Production" alert the message might be "Caution: Low production on Inverter 1 (north side)". The placeholders %l and %r can be used in the message field to include the calculated value for the lhs and rhs of the equation.

Examples of user-defined alerts are available in the User-defined Alert Examples section near the end of this document. Click here to jump to that section.

 

Viewing and Acknowledging Alerts

You can view and acknowledge alerts on your device under View → Alerts. By default, a list of triggered alerts will be visible. For more information on each alert and the option to acknowledge or delete an alert, click the "View Privileged Details" button.

image-1598384378068.png

Ack (Acknowledged): indicates if this alert has been acknowledged. Once acknowledged, the alert will be reported again should it reoccur and its priority is sufficiently high. Alerts are automatically acknowledged after 24 hours. To ensure new alerts are reported, alerts should be acknowledged when they are received.

Prio (Priority): the priority of the corresponding alert.

Time: date and time of the most recent occurrence of the alert.

#: number of times this alert has occurred (note that this isn't necessarily the number of times the alert has occurred since the device was installed).

Name: name of the alert.

Last Reported: date and time when the alert was last reported to at least one of the alert-destinations.

To view detailed alert information as well as acknowledge and delete reported alerts, click the "View Privileged Details" button. Valid credentials are required to see this information and acknowledge/delete alerts.

image-1598384643646.png

The Detail column contains additional information about each alert. For example, one instance of the "Network interface changed" alert provides the additional detail that the network interface was changed from "none" to "eth0" (this happens immediately after a reboot) while the other (newer) instance of the "Network interface changed" alert provides the additional detail that the network interface changed from eth0 to qca0. This happened very quickly (within the same minute), and is normal behavior for a meter coming back online after a reboot.

To modify alerts, check off any alerts you wish to delete or acknowledge, and click the appropriate button. Deleting alerts here
will remove them from the reported alert page until it occurs again.

 

User-defined Alert Examples

For available functions on your particular firmware version, visit http://DEVNAME/fundoc.html?alert where DEVNAME is  your eGauge device name.

 
General Notes

$"REG NAME" returns the instantaneous value of the register REG NAME, while "REG NAME" points a function at a specific register (but doesn't necessarily return the register's value). When using functions such as avg() or others listed in the function documentation, do not include the dollar sign.

When creating a message (Msg), there are several shortcuts which can be used to include values from the alert condition itself:

%l will return the value of the left–hand–side
%L will return the formula of the left–hand–side
%r will return the value of the right–hand–side
%R will return the formula of the right–hand–side
%% will return a single percent sign (eg, %l %% would read as <value from left side of the comparison> %)

 
Basic Examples

In the following example, "Grid Average" will return the daily average of the Grid register if that value is less than or equal to 5000W, while "Grid Instantaneous Usage" will return the instantaneous reading of the Grid register if that value is less than or equal to 1000W.

image-1598385221466.png

 

The next example will trigger if the value of the L1 voltage register is greater than or equal to 130V (which could indicate a dangerous condition for devices connected to that service).

image-1598388200742.png

 

More complex math can also be performed on either side of the alert expression. For example, the following alert obtains the average voltage from two references, and triggers if that value is greater than or equal to 130V.

image-1598388449822.png

 

It's also possible to calculate cumulative values (kWh) over a period and trigger an alert based on those values. In the following example, let's assume an outdoor hot tub has a 6kW pump/heater, which cycles every 3 hours for 30 minutes at a time. Thus, every 6 hours there should be 6 kWh of energy used. Any less could indicate a pump or heater failure, and the hot tub could freeze.

(avg("Hot Tub Pump/Heat",360)*6) / 1000 will take the average power (W) read on the register Hot Tub Pump/Heat over the last 360 minutes (60 minutes in an hour, 6 hours). Then, the average power is multiplied by 6 hours to get Wh, the total energy used over the 6 hour period. Finally, we divide by 1000 to convert Wh to kWh.

That value is then compared to the value on the right-hand-side, in this case 6. If the alert is triggered the alert will be sent.

image-1646775756987.png

 

Ternary operator

The syntax of the “?” ternary operator (also referred to as a conditional or conditional test) is condition?value_if_true:value_if_false and can be nested. This is a fundamental component of many alerts, especially more complex alerts.

 
Boolean expressions

Simple boolean expressions may be used within an alert:

(5 > 4) will return 1. Conversely, (5 < 4) will return 0.

The boolean value can be multiplied by another value (including a register value). For example, ($"Grid" < 7000) * $"Grid" returns the value of “Grid” if “Grid” is greater than 7000 W, and returns 0 if the value of "Grid" is less than 7000W.

To break this down: if $"Grid" < 7000 is true, it will return a 1. 1 * $"Grid" returns the value for the "Grid" register. If $"Grid" < 7000 is false, it will return a 0. 0 * $"Grid" is 0. Remember, $"REGNAME" returns the instantaneous value of the register.

 

Let's look at how the time() function can be used with the ternary operator and boolean expressions to trigger an alert at a specific time:

image-1598387960751.png

These two alerts work together to trigger if the Grid value is greater than 5000W during daytime hours and greater than 3000 during nighttime hours. 

time() returns the current time as a number from 0 up to (but not including) 24 with minutes as a fractional value. For example, 11:30am would be 11.5. We use two booleans here:

time() > 8 * time() < 18

If the time is > 8 (8am) and less than 18 (6pm), the booleans work out to 1 * 1 or 1.

If either boolean is false, the output from the booleans is 0. 0 * 1 or 1 * 0 both equal 0.

This gives us a ternary expression of either 1 ? $"Grid" : 0 or 0 ? $"Grid" : 0 (remember ternary expressions work out as condition?value_if_true:value_if_false). Thus, if the booleans evaluate to 1, the left side of the formula returns the value of $"Grid". If the booleans evaluate to 0, the left side of the formula returns 0.

Moving on to the alert expression: if the booleans work out to zero (ie, if the time range is not correct), the left side of the alert returns 0. This can never be greater than 5000, so the alert never triggers. If the booleans work out to 1, the left side of the alert returns the value of the "Grid" register. If the value of the "Grid" register is >= 5000, the alert triggers.

 

 

Example and description of POST 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?"
    }
  ]
}
Generic

Zero out data/spikes tutorial

Devices on firmware older than version 3.01 may experience a phenomenon where register configuration changes that require a reboot cause unusually high readings to appear in the minute following the change. These readings are referred to as spikes, since they tend to "spike" far above the actual device readings. Spikes are almost always at least 100x the expected reading, and may be even higher.

Since spikes can cause cumulative readings to display incorrectly, the eGauge has a tool that can permanently clear data from the device database. Extreme caution should be exercised when using this tool. Once data is erased, it cannot be recovered. The video tutorial below provides a walkthrough of the tool's functionality.

Note that this tool may be used in other situations where clearing data is necessary (for example, removing bad data due to a configuration issue). However, this tool will always permanently clear data when used.

 

 

eGauge language options and adding new languages

The EG30xx and EG4xxx have support for different locales. The eGauge will use the language associated with the locale that is requested by the user's browser. If the locale does not exist or is not supported, it will default to English.

New locales and improvements upon existing ones are welcome. Please see our internationalization (I18N) page at https://www.egauge.net/i18n/ for full details. This page also shows the completion percentage of any supported language. Anyone is welcome to download and improve upon the PO files and submit them to i18n-team@egauge.net for review and implementation. 

A specific locale can be forced to display in the browser by changing the browser's language/locale setting. Check your browser's help menu for information on changing your its language settings.

High Gain Mode

High-gain mode is available on the EG4xxx hardware only. To enable high-gain mode, navigate to Settings -> Installation. Check the "Use high-gain mode" option just above the dropdown menus for CT selection.

High-gain mode selection box

 

High-gain mode amplifies the incoming signal from all CTs by a factor of ten. From a practical standpoint, this means a CT with a higher amperage rating can be used to accurately measure much lower amperages. For example, with high-gain mode enabled a 100A CT could be used in place of a 10A CT. 

High-gain mode does not require any changes to standard installation or wiring procedure. When high-gain mode is enabled, the CT amperages displayed in the drop down menus will decrease by a factor of ten (for example, an 800A CT will be listed as an 80A CT). For the simplest configuration, it is recommended to set actual CT amperages first and then enable high-gain mode. Note that high-gain mode is a global setting - when enabled, it applies to all configured CTs. As with most other installation settings, enabling high-gain mode will only impact data recorded from that point moving forward.

Connecting via the eGauge proxy server using IE 10/11

Users with Internet Explorer 10 and 11 may require some additional steps to function properly with the eGauge proxy server. These steps are covered in the document below.

 

IE 10/11 PROXY SETTINGS

 

Monitoring High Voltage Systems

Warning: Systems greater than 600V phase-to-phase are not fully supported by eGauge Systems. Supported CTs are rated for up to 600Vac, systems at higher voltages will need to source alternate CTs.

Amperage-output CTs (e.g., 5A output, or 100:5 ratio, etc) can cause serious shock or electrocution. Use appropriate protection when installing and handling equipment. Amperage-output CTs must not be connected directly to the eGauge meter and may cause damage.

Monitoring High Voltage Systems

First, a disclaimer: although it's technically possible to monitor a high voltage system (greater than 480Vac phase to phase or 277Vac phase to neutral, or 600Vac phase to phase using EV1000 sensors), eGauge Systems doesn't officially support this and doesn't offer hardware  capable of doing so directly. eGauge support can assist with eGauge configuration, but cannot offer any guarantees regarding accuracy. Note that a wiring mixup during installation can damage or destroy the eGauge - this damage is not covered under warranty.

In order to calculate real power, the eGauge meter needs two measurements - a voltage reference and an amperage reference (technically the meter also captures amperage and voltage waveforms, which lets the meter calculate power factor and thus real power).

Voltage Reference

eGauge Systems cannot guarantee meter accuracy when third party potential transformers are used. It is recommended to use the EV1000 high voltage sensor when measuring a system with higher voltage than the eGauge meter rating, or on a different side of a transformer from where the eGauge voltage taps are connected.

In most installations, the eGauge can tap directly into the line voltage at the site (up to 277Vac Ph-N). Connecting the eGauge directly to higher voltages will damage or destroy the meter. However, it is possible to use stepdown transformers to reduce higher voltages to something the eGauge can safely read. These stepdown transformers are referred to as Potential Transformers (PTs) or Instrument Transformers. Most will take a common service voltage (eg, 480V, 600V, 4160V) and reduce it to 120Vac.

 

With the release of the EV1000 High Voltage Sensor, it's now possible to monitor high voltage services without the use of bulky stepdown transformers. The EV1000 can be used to measure up to 707Vac, making it ideal for 600V services. Note that the EV1000 is only supported on EG4xxx and newer meters - the EV1000 cannot be used with EG30xx and older meters.

Amperage Reference

To obtain an amperage measurement, the eGauge uses Current Transformers (CTs) with a 333mV output. These CTs clamp directly around conductors, and as such are rated for the voltage used by those conductors (a 600V rating is typically adequate for most installation scenarios). 333mV output CTs are the only CTs which can be connected directly to the eGauge. Connecting any other CT output type (eg, 4-20mA, 5A) will damage or destroy the meter.

Necessary Hardware

eGauge Systems currently stocks and supports one PT (Functional Devices TR50VA008, 480V to 120V) and several CT lines rated for use on up to 600V services. The EV1000 High Voltage Sensor can be used on measurements up to 707Vac (for example, the phase to neutral voltage on a 347/600V service is 347V, so the EV1000 would work well here). For a service at a higher voltage, the customer will need to identify and purchase:

1. Potential Transformers or Instrument Transformers which can take a higher voltage down to <277V (preferably 120V). The transformer should have a relatively low VA rating to minimize phase shift (we suggest <=50VA, although up to 100VA is acceptable). Stepdown transformers intended for high accuracy measurements are generally referred to as Instrument Transformers. The transformer may require a larger enclosure or additional mounting hardware as well - they tend to be bulky and heavy. The total number of conductors on a service will determine the number of transformers required. A three phase four wire (wye, with neutral) service needs three transformers; a three phase three wire (delta, no neutral) needs two transformers.

2. A CT which can be installed around conductors carrying the service voltage (or overrated depending on code and installation requirements). The CT should either have 333mV output or 5A output (more on that below). Solid core CTs are recommended, although rope CTs are acceptable.

There aren't many (if any)  333mV output CTs rated for use on a 600V+ systems. The 5A output profile is much more common. A 5A output CT cannot be connected directly to the eGauge. However, it is possible to read from a 5A output CT using one of a supported CTs. Essentially, the output from the 5A CT is shorted (wires connected together). One of the standard 333mV output CTs is clipped around this new loop, and the eGauge measures the output current of the CT (0-5A). A custom scale factor is used to for the eGauge to treat this as a reading from the larger CT. In a similar manner, a custom scale factor is set on the line voltage readings to force the eGauge to treat the 120Vac as the voltage on the primary side of the transformer.

eGauge support can assist with this part of the device configuration, but cannot offer specific CT or transformer suggestions.

Summary

It is technically possible to measure power used/generated on services over 600Vac (phase to phase), although not officially supported. The customer will need to find suitable hardware (CTs and PTs). eGauge support can offer advice on the suitability of a given piece of hardware but cannot provide specific hardware recommendations. eGauge support can also assist with configuration and testing, although it's not possible to guarantee any specific level of accuracy.

Formula registers and remote devices

Physical registers represent any single data point recorded by an eGauge meter. These can come from locally-obtained raw measurements (eg, amperage or voltage), locally obtained calculations (eg, real power and other power register subtypes), and even registers imported from remote devices (remote eGauge or third party devices connected via Modbus TCP/RTU).

Formula registers are a type of physical register which can be used for a variety of calculations. Typically, a formula register will read data from one or more physical registers on a device, perform some calculation, and then store a new value. This is commonly used for advanced calculations such as power factor or reactive power.

However, when using a formula register with a remote register, some additional consideration must be taken to avoid incorrect values when the remote register is not available (eg, the remote device has been disconnected from the network, dropped offline, etc). When this happens, the remote register may return a "NaN" value (Not a Number) instead of a numerical value, which can "break" the formula register. Consider the simple example below:

image-1584633859943.png

In this example, a formula register is used to add together the physical registers "Local_Power" and "Remote_Power". "Local_Power" is a power register measured by the meter itself, while "Remote_Power" is a power register imported via Modbus from an external source.

Normally, this is simple addition: if "Local_Power" = 10 and "Remote_Power" = 20, the value of "Remote and Local Power" would be 30. However, if the remote device which provides a value for "Remote_Power" goes offline, the eGauge is now reading 10 + NaN, which returns NaN. This behavior isn't desirable - it would be much better to at least return the value of "Local_Power" (10).

To achieve this, we can use a conditional and a function to convert any returned "NaN" into a 0.

conditional is expressed as X?Y:Z, where X is something that evaluates to True or False, Y is the value returned if X is true, and Z is the value returned if is false. For example, (3=4)?0:1 would return 1, because 3=4 is false (3 does not equal 4). 

The function isnan() takes one value in the parenthesis and returns a "True" if the value is NaN and "False" if the value is a number. For example, isnan(1) would return "False", because 1 is not a NaN. isnan(sqrt(-1)) would return "True", because sqrt(-1) (square root of -1) isn't a number (and is therefore NaN).

As you can see, isnan() will return either a "True" or "False". We can feed that into our conditional and dictate which value is returned. The basic form for this is:

isnan($"registername")?0:$"registername"

If the value of the register "registername" is a NaN, isnan() returns "True" and the conditional returns 0. If the value of the register "registername" is not a NaN, isnan() returns "False" and the conditional returns the value of "registername".

Using our original example:

image-1584635636515.png

 

Register ID and location

The eGauge uses "registers" to record data. Each register is an independent data point. For example, one register may be recording the voltage of L1, and another register can be recording the power of CT1*L1. Data is only recorded and stored if a register is configured to record it.

Each register has an ID which can be found in the Settings -> Installation page by hovering the mouse over the [x] delete button to the right of the register name:

register-id-mouse.png

This shows register "Oven" is recording in ID #4.

 

If there are multiple power sub-types selected, multiple IDs will appear in order:

register-id-multiple-mouse.png

Grid is recording net power (=), positive-only (+) and apparent power (*). They are recording in ID #0, #7, and #8 respectively.

 

Adding a new register will use the first available unused ID, so if register ID #0 is removed and a new register is added, the new register will record in ID #0. Historical data is not erased when a register is removed, so historical data from ID #0 will always show in ID #0 even if the register is deleted and a new register records data in it.

To permanently erase data from a register, you can use the Zero-out data tool in the Tools menu.

Working With Max Demand Export Data

Overview

As of firmware version 3.1.10, the eGauge supports rolling max demand exports through the CSV export function built into the main graph page. These exports contain a rolling average over the past X minutes with a data point presented at the interval requested when creating the export.

Many utilities bill based on rolling max demand averages in additional to total kWh consumption. While it's possible to obtain a rolling max demand average using minute-granular data from a meter, the process is involved and the data overhead is quite large (data for every minute over the period must be downloaded, then the user must calculate a set of rolling averages for each interval, and record the maximum average for an interval). For example, a rolling max demand export over the past 30 days would return 2880 data points (one point every fifteen minutes), while a minute-granular export for the same period would contain 43200 data points (one point every minute).

eGauge Systems cannot assist with utility reconciliation or questions about the billing process used by a specific utility. You'll need to reach out to your utility for assistance with this.

 

Verifying Settings

The max demand export calculates a rolling average which is X minutes long. X is defined by the value selected for "Length of a demand interval" under Settings -> Preferences

Screenshot-from-2021-02-05-11-56-11.png

This value can be adjusted in one minute increments, from 15 to 60 minutes. Your utility should make their demand interval public (although it may be necessary to contact the utility directly to get this information). eGauge Systems cannot advise as to the correct value to select for this option.

 

Performing An Export

To perform a max demand export, use the dropdown menu in the top left corner of the main graph page. The export window should look something like the following image. Note that the export type is set to "Max. Demand Value" and the interval is set to 15 minutes.

image-1612551572235.png

The export interval setting is not the same as the length of a demand interval setting. The former determines how often a data point is returned (eg, one data point for every 15 minute period) while the latter determines the length of the demand interval (eg, how many data points are included when calculating an average).

In other words, a single data point in a max demand export can be described as "the average peak demand over the past N minutes for the time period from XX:XX to YY:YY with a data point every Z minutes", where N is the "Length of a demand interval" setting, XX:XX is the starting time of the export, YY:YY is the ending time of the export, and Z is the export interval.

 

Example Data

In the example below, two data sets were obtained from the same meter. The first data set (columns A and B) is a minute-granular average value export. The second data set (columns G and H) is max demand data from the same period, with a 15 minute demand interval and a 15 minute export interval.