eGauge WebAPI (latest)

The eGauge WebAPI is a JSON-based API that provides access to eGauge meters. It offers secure means to read device data, configure the device, and perform various control operations.

The WebAPI is intended to eventually replace the eGauge XML API. For new applications, developers are encouraged to use WebAPI rather than the legacy XML API.

This document and the API it describes may be amended and modified by eGauge Systems LLC at any time with or without notice. eGauge Systems LLC strives to avoid changes that break backwards-compatibility, but reserves the right to do so at its sole discretion.

With Python

To make it easy to get started, eGauge provides an open source Python package. It can be installed with the command:

pip install egauge-python

With this package installed, accessing an eGauge meter becomes very simple. For example, to fetch the hostname of the meter, you could use:

from egauge import webapi

URI = "https://DEV.egaug.es"      # replace DEV with meter name
USR = "USER"                      # replace USER with user name
PWD = "PASS"                      # replace PASS with password

dev = webapi.device.Device(URI, webapi.JWTAuth(USR,PWD))

print("hostname is " + dev.get("/config/net/hostname")["result"])

The package also contains various convenience classes to read meter data, capture waveform samples, convert between physical units, and so on.

The official GIT repository for this package is at https://bitbucket.org/egauge/python/. Various code examples can be found in the examples directory.

The authentication service. Clients can use this to obtain and manage tokens that grant access to the other resources in this API.

The meter uses JSON Web Tokens (JWT or simply token) to restrict access to protected resources. Clients must include such tokens in requests via the HTTP Authorization header. This header must have the form:

Authorization: Bearer JWT

where JWT is a valid token.

Tokens are valid for a limited time; typically for about 10 minutes. However, a meter may revoke a token earlier, e.g., due to a reboot.

The capture service allows collecting waveform data for configured input channels.

GET /capture&i returns information about the channels for which waveform data can be captured. The returned object might look like this:

{
  "channels": {
    "0": {"name": "L1", "unit": "V"},
    "1": {"name": "L2", "unit": "V"},
    "4": {"name": "S1", "unit": "A"}
    }
}

This response indicates that three channels are available. The meter-internal channel numbers are 0, 1, and 4. As the name values indicate, those channels correspond to meter inputs L1, L2, and S1, respectively. The first two channels return samples as volts (V) and the third returns samples as amperes (A).

GET /capture?n&d=1e-3&c=0&c=4 initiates a capture for 1ms of samples on channels 0 and 4 and returns a cookie (token) to be used to retrieve the capture samples. The response for this request might look like this:

{"state": "armed", "cookie": 1875353535}

State armed indicates that the meter successfully processed the capture request and is waiting for the trigger to occur. Cookie 1875353535 is a random integer to be used when retrieving the sampled data, as shown next.

GET /capture?n=1875353535 can now be used to fetch the samples. The response might look as shown below:

  {
    "state": "full", "ts_freq": 1000000, "first_sample": "1619637288.061",
    "ch_mask": [17, 0],
    "r": [
      {"t": 495514564, "d": [135.059]},
      {"t":        82, "d": [-0.0146239]},
      {"t":      1354, "d": [105.454, -0.00731193]}
    ]
  }

State full indicates that the capture buffer is full and therefore the response contains sample values. The frequency of the counter used to generate the timestamps is 1MHz ("ts_freq": 1000000) and the realtime Unix timestamp of the first sample is 28 April 2021, 19:14:48 UTC (first_sample": "1619637288.061"). The ch_mask member is an array of 32-bit integers. If a bit is set in this mask, data for that channel is included in the response. In our case, the channel mask has only bits 0 and 4 set in the first integer (17), indicating that channels 0 and 4 are contained in the sampled data (in order from smallest to largest channel numbers). The timestamp t of the first sample is 495514564 and the subsequent samples were acquired 82 and 1354 timestamp ticks after the corresponding previous sample. Thus, the reconstructed sample values for the channels are:

Note how the sample values are returned strictly in order from lowest number to highest numbered channel: 0, 4, 0, 4. Also note how there is a separate entry in the result array r for each unique timestamp. Each data array (d) may have just a single entry or multiple entries if there are multiple sample values with the same timestamp.

A Python program illustrating the use of this service can be found here. This program takes advantage of class egauge.webapi.device.Capture to handle the details of encoding the HTTP requests and decoding the responses.

The service provides the ability to execute various operations for their side effects, such as rebooting the meter. Unless stated otherwise, the resources in this service are available only to users with the save right (see /auth/rights).