Skip to main content

eGauge Data Source

The eGauge data source reads energy monitoring data from eGauge metering devices by interpreting their XML API data stream. eGauge devices are widely used for power monitoring, energy management, and sub-metering in commercial and residential buildings. This data source supports the v1.32 revision of the eGauge XML API, handling both real-time polling and historical data retrieval with automatic gap detection and backfill.

The data source communicates with eGauge devices over HTTP/HTTPS, reading register values that represent energy consumption, power generation, and other metered quantities. It supports physical registers, computed virtual registers, and rate-of-change (instantaneous power) values.

Overview​

PropertyValue
ModulemangoAutomation-eGauge
ProtocoleGauge XML API
DirectionPolling
Typical UseEnergy monitoring from eGauge meters

Prerequisites​

  • An eGauge device accessible over the network from the Mango server via HTTP or HTTPS.
  • The IP address or hostname of the eGauge device.
  • Knowledge of which registers the eGauge device is configured to report (e.g., Grid, Solar, HVAC, Lighting).
  • Network connectivity between the Mango server and the eGauge device on the configured HTTP/HTTPS port.

Configuration​

Data Source Settings​

SettingDescription
NameA descriptive name for the data source.
URIThe HTTP path to the eGauge device. Format: https://12.34.56.789:555. Do not include a trailing slash.
Update periodHow frequently the device is polled for new data.
TimeoutMaximum time (in milliseconds) to wait for a response from the eGauge device.
RetriesNumber of retry attempts when a connection fails.

Gap Detection and History Backfill​

When enabled, the data source automatically detects gaps in the data stream and attempts to retrieve missing data.

SettingDescription
Gap detection(Enable/disable) When a gap larger than the configured threshold is detected, the data source attempts to retrieve missing data.
Gap thresholdThe minimum time gap that triggers a backfill request.
Backfill resolutionThe resolution (time interval) at which missing data is retrieved during backfill.
Buffer sizeThe fixed-size buffer for backfill data. If you receive JAXB exceptions during history queries, increase this value. Large history queries (especially from the History Query tool) may require a larger buffer than normal gap-fill operations.

API Parameters​

SettingDescription
Include totalsWhen enabled, includes computed total and virtual registers (derived from physical registers) in the response.
Exclude sub-devicesWhen enabled, excludes information collected from devices coordinated by this eGauge.
Include sub-device detailsProvides additional details about coordinated devices. Note: as of eGauge module version 1.0.0, this feature is not actively used.
Include ratesIncludes computed rate-of-change values in the returned data.
Convert to kWhAutomatically transforms Watt-second (Joule) readings to kilowatt-hours by dividing by 3,600,000 (3.6e6).
Calculate power during history queryWhen enabled, the data source calculates instantaneous power values from stored energy values during historical data retrieval.

Data Point Configuration​

SettingDescription
Register nameThe name used to identify register values returned from the eGauge device (e.g., "Grid", "Solar+", "HVAC").
VirtualA read-only property indicating whether the data point represents a virtual (computed) register.
Use rateWhen checked, the point uses the instantaneous rate-of-change value rather than the accumulated register value. This is the difference between energy (kWh) and power (kW).
MultiplierA scaling factor applied to each new value before storage.
OffsetA value added to each new data point value before storage.
note

Both the multiplier and offset are applied after the kWh conversion, if the data source is configured to perform that conversion.

History Query Tool​

The History Query tool retrieves historical data from the eGauge device using relative time frames.

SettingDescription
History beginsHow far back to start retrieving data (e.g., "9 weeks ago").
Relative endHow far back to stop retrieving data, relative to the start. A value of 0 retrieves up to the current moment.
Sequential queryWhen enabled, breaks large time ranges into one-week increments to keep individual requests small.

Example: If history begins 9 weeks ago and the relative end is 4 weeks, the last sample will be from 5 weeks ago (9 - 4 = 5 weeks ago).

tip

Querying very long periods can take significant time, especially at high resolution. Use sequential queries to avoid timeouts and manage the load on both the eGauge device and Mango.

Common Patterns​

Building Energy Monitoring​

Configure the eGauge data source to read all physical registers from a building's main electrical panel. Create points for each register (Grid, Solar, HVAC, Lighting, Plugs, etc.) using the accumulated value mode. Enable Convert to kWh for easy interpretation. Build dashboards showing energy consumption by circuit with trend charts and daily/monthly totals.

Solar Production Tracking​

Use the eGauge data source to monitor solar panel output. Create one point for solar production using the accumulated (energy) value and another using the rate-of-change (power) mode. The energy point tracks total production over time, while the power point shows instantaneous generation in kW.

Demand Monitoring​

Create rate-of-change points for the main grid register to monitor instantaneous power demand. Configure event detectors to alert when demand exceeds utility-imposed limits, helping avoid demand charges.

Multi-Site Deployment​

For buildings with multiple eGauge devices, create a separate eGauge data source for each device. Use consistent register naming across sites to enable cross-site comparison dashboards.

Historical Data Import​

When first connecting an eGauge device that has been collecting data for weeks or months, use the History Query Tool to backfill Mango with the historical data. Start with sequential queries to avoid overwhelming either system.

Troubleshooting​

Connection Failures​

  1. Verify the eGauge device is accessible from the Mango server by opening the URI in a web browser.
  2. Check that the URI format is correct -- include the protocol (http:// or https://) and port but no trailing slash.
  3. Increase the Timeout value if the device is on a slow or congested network.
  4. If the eGauge device is behind a firewall, ensure the appropriate port is open.

JAXB Exceptions​

  1. JAXB exceptions typically occur when the XML response from the eGauge device exceeds the configured Buffer size. Increase the buffer size in the data source settings.
  2. This is most common during large history queries. Use sequential queries to reduce individual response sizes.

Missing or Incorrect Register Data​

  1. Verify the Register name on each data point matches exactly what the eGauge device reports. Register names are case-sensitive.
  2. If virtual registers are not appearing, enable the Include totals option.
  3. If rate-of-change values are not available, enable the Include rates option.

kWh Conversion Issues​

  1. The conversion divides raw Watt-second values by 3,600,000. If your eGauge device reports values in units other than Watt-seconds, the conversion will produce incorrect results.
  2. The Multiplier and Offset are applied after the kWh conversion. If you need to apply scaling before conversion, you will need to adjust the multiplier to account for both operations.

Gap Detection Not Backfilling​

  1. Verify that gap detection is enabled and the gap threshold is appropriate for your polling frequency.
  2. Check that the eGauge device retains historical data for the gap period -- some devices have limited storage.
  3. Review the data source events for any errors during backfill operations.