eGauge Meter API
License Common Documentation License 1.0
eGauge Meter API
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.
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.
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:
| Timestamp [µs] | Channel 0 value [V] | Channel 1 value [A] |
|---|---|---|
| 495514564 | 135.059 | |
| 495514646 | -0.01462390 | |
| 495516000 | 105.454 | -0.00731193 |
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 trigger mode to use. any triggers immediately, rise triggers when a rising edge crosses the trigger level, fall triggers when a falling edge crosses the trigger level, gt triggers when the trigger channel's sample value is greater than the trigger level, and lt triggers when it is less than the trigger level.
If present, this query parameter cancels a pending capture and resets the state to available. If a value for query parameter n is also specified, only the matching capture is canceled. Otherwise, any pending capture is canceled.
Trigger timeout in milliseconds. After starting a capture, if the trigger condition is not satisfied within this timeout period, the capture is auto-triggered.
Channel number to be captured. This query parameter can be specified multiple times to capture multiple channels. If not specified, all configured channels are captured by default.
Capture duration in seconds. If less than or equal to 0, the maximum number of samples are acquired. This maximum is implementation dependent but, generally, a fixed size buffer is used to store all samples of all channels, so the more channels are being captured, the lower the upper bound for this value. If the value is greater than this upper bound, it is automatically capped at that value.
Return a channel info object, describing each channel that may be captured, its name and its physical unit.
Non-blocking operation. If the query parameter has no value or an empty string value, this requests that a capture is initiated without waiting for the result to be available (asynchronous operation). In this case, a cookie object is returned which contains a token. The token can be used in subsequent requests to fetch the result of the capture or to check on its status.
If a value is specified, it must be a token returned in an earlier cookie object response. In this case, the capture status is reported via a progress object if it is still pending or a capture result object if the capture is complete.
Pre-trigger duration in seconds. Specifies how many seconds of samples before the trigger point should be acquired. If omitted, this defaults to 0 seconds of pre-trigger data.
If present, this query parameter requests that the sample values should be returned as raw (digital) sample values rather than as values converted to the channel's physical unit.
curl -i -X GET \ 'https://webapi.egauge.net/_mock/webapi/4.6/openapi/capture?C=0&L=0&M=any&R=true&T=0&c=0&d=0&i=true&n=0&p=0&r=true&t=true' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
{ "channels": { "0": { … }, "4": { … } }, "error": "Error message (present if an error occurred)." }
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).
An eScript expression that returns the value to use on the left hand side of the comparison.
The comparison-operator to use for comparing the left-hand-side expression lhs against the right-hand side expression rhs. It may be one of:
<: Condition is true if lhs is less than rhs.<=: Condition is true if lhs is less-than-or-equal to rhs.=: Condition is true if lhs is equal to rhs.!=: Condition is true if lhs differs from rhs.>=: Condition is true if lhs is greater-than-or-equal to rhs.>: Condition is true if lhs is greater than rhs.An eScript expression that returns the value that to use on the right hand side of the comparison.
Alert detail message. This may be up to 255 bytes in length. The following sequences within this string get replaced as follows:
%% is replaced by a single percent character.%l is replaced by the value of the lhs expression.%r is replaced by the value of the rhs expression.%L is replaced by the lhs expression string.%R is replaced by the rhs expression string.The frequency with which this custom alert should be checked. Possible values are:
sec: The alert will be checked once a second.min: The alert will be checked once a minute.hr: The alert will be checked once an hour.dy: The alert will be checked once a day.wk: The alert will be checked once a week.mon: The alert will be checked once a month.an: The alert will be checked once a year.The configuration for reporting alerts via email server. If alert reporting via web server is enabled (/config/alert/reporter/web/uri is not empty), reporting via email server is disabled.
The hostname of a mail server that speaks the SMTP protocol. If this is set to an empty string, the meter will attempt to deliver mail directly to the destination host. Many Internet service providers block direct mail delivery, so leaving this string empty generally results in alert emails getting blocked.
The options to use when sending an alert report to the web server.
This resource is available only if /config/alert/reporter/web/service is an empty string.
Multiple options can be specified in the string by separating them with a comma. Supported options are:
deflate: Use HTTP Content-Encoding deflate when transmitting the alert report.
gzip: Use HTTP Content-Encoding gzip when transmitting the alert report.
secure: Only send the alert report if the server's HTTP certificate can be verified by the meter. This option is ignored if /config/net/http/client/insecure is true.
The name of the alert service provider to use for reporting alerts.
To set this to a non-empty value please use the service activation command since that ensures the service provider knows to expect alerts from this meter. The body of the activation request should contain member service set to the string alert and provider set to name of the desired service provider.
The URI of the web server to use for reporting alerts.
This resource is available only if /config/alert/reporter/web/service is an empty string.
The user name to provide to the web server for authentication purposes. If this string is not empty, the user name and the password are both sent to the web server using HTTP Basic authorization. For security reasons, this should only be used when connecting to the server via an encrypted connection (https).
This resource is available only if /config/alert/reporter/web/service is an empty string.
The priority of each system-generated alert. /sys/alert provides a description of these alerts.
The BACnet configuration.
The BACnet server configuration.