eGauge WebAPI (4.6)

eGauge Meter API

Download OpenAPI description
Languages
Servers
Mock server
https://webapi.egauge.net/_mock/webapi/4.6/openapi/
The WebAPI server
https://{devname}.egauge.io/api/

Introduction

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.

/auth

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.

Operations

/capture

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

Operations

/cmd

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).

Operations

/config

The meter configuration service.

The endpoints under /config provide common method semantics and atomicity guarantees as described below.

Operations

/config/alert

The alert configuration of the meter.

Operations

/config/alert/custom

Up to 32 custom alerts.

Custom alerts consist of an arbitrary boolean condition that is checked at certain times. When the condition evaluates to true, the alert is triggered.

Operations

/config/alert/custom/{idx}

The custom alert.

Operations

/config/alert/custom/{idx}/cond

The boolean condition consists of three parts: lhs op rhs. lhs and rhs are arbitrary expressions and op must be a comparison operator.

Operations

/config/alert/custom/{idx}/cond/lhs

An eScript expression that returns the value to use on the left hand side of the comparison.

Operations

/config/alert/custom/{idx}/cond/op

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.
Operations

/config/alert/custom/{idx}/cond/rhs

An eScript expression that returns the value that to use on the right hand side of the comparison.

Operations

/config/alert/custom/{idx}/detail

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.
Operations

/config/alert/custom/{idx}/frequency

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.
Operations

/config/alert/custom/{idx}/name

The user-selected name of this custom alert.

Operations

/config/alert/custom/{idx}/priority

The priority of this custom alert. Zero is the lowest, seven the highest priority.

Operations

/config/alert/reporter

The alert reporting configuration. Alerts may be reported via a web server or via an email server.

Operations

/config/alert/reporter/mail

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.

Operations

/config/alert/reporter/mail/server

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.

Operations

/config/alert/reporter/mail/user

The user name to provide to the email server for authentication purposes.

Operations

/config/alert/reporter/mail/password

The password to provide to the email server for authentication purposes.

This resource is write-only.

Operations

/config/alert/reporter/mail/from-address

The "From" email address to use when sending an email alert. If set to an empty string, the email server will use a default address.

Operations

/config/alert/reporter/mail/to

The email destinations to send the alerts to.

Operations

/config/alert/reporter/mail/to/{idx}

An email destination to send the alerts to.

Operations

/config/alert/reporter/mail/to/{idx}/address

The destination email address to send the alert to.

Operations

/config/alert/reporter/mail/to/{idx}/format

The reporting format to use for this destination. Valid values are:

  • short: Report only the newest alert with the highest priority.

  • full: Report all unacknowledged alerts that are pending in order from highest to lowest priority.

Operations

/config/alert/reporter/mail/to/{idx}/min-priority

The minimum priority that is required for a new alert to generate an email. When an email is generated, other lower priority alerts may also be included if they are unacknowledged and the reporting format allows it.

Operations

/config/alert/reporter/web

The configuration for reporting alerts via web server.

Operations

/config/alert/reporter/web/min-priority

The minimum priority that is required for a new alert to generate a report to the web server. When a report is generated, all other unacknowledged alerts are also reported, even if they have a priority lower than the value indicated by this resource.

Operations

/config/alert/reporter/web/options

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.

Operations

/config/alert/reporter/web/password

The password to be provided to the web server for authentication purposes.

This resource is write-only

Operations

/config/alert/reporter/web/service

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.

Operations

/config/alert/reporter/web/uri

Operations

/config/alert/reporter/web/user

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.

Operations

/config/alert/sys-prio

The priority of each system-generated alert. /sys/alert provides a description of these alerts.

Operations

/config/alert/sys-prio/{idx}

The priority of this system alert.

Operations

/config/bacnet

Operations

/config/bacnet/server

The BACnet server configuration.

Operations

/config/bacnet/server/bip

Operations

/config/bacnet/server/bip/port

Operations

/config/bacnet/server/enable

The list of BACnet protocols that are enabled. An empty list indicates that the BACnet server is disabled. The meter is currently restricted to supporting a single protocol at a time, so this array may have at most one element.

Operations

/config/bacnet/server/enable/{idx}

The name of an enabled BACnet protocol. Possible values are:

  • ethernet: BACnet over raw Ethernet.

  • bip: BACnet over the UDP/IP.

  • mstp: BACnet over MS/TP (RS-485).

Operations

/config/bacnet/server/epoch-relative

If true, the BACnet server reports cumulative values relative to the meter epoch. If false, raw absolute values are reported relative to when the meter was manufactured.

Operations

/config/bacnet/server/id

The object id of the BACnet server.

Operations

/config/bacnet/server/mstp

The BACnet over MS/TP configuration. This is used only if the mstp protocol is enabled.

Operations

/config/bacnet/server/mstp/mac

The MS/TP address of the meter's BACnet server.

Operations

/config/bacnet/server/mstp/max-mac

The maximum address used by any device connected to the same MS/TP network as this meter. A value of 127 is safe, but setting it to the lowest address in use significantly increases MS/TP performance.

Operations

/config/bacnet/server/mstp/port

Operations

/config/db

The database configuration.

Operations

/config/db/epoch

The time when the meter started recording data. This is a decimal Unix timestamp string.

The relevance of this resource is that other services in this API by default return accumulated register values relative to this time so that, at the time of the epoch, they all read 0. Changing this value therefore changes the values reported by those services. Similarly, user interfaces that use this API generally do not present data before the epoch, effectively providing a limit to the history visible to the user.

Writing this resource does not change the data stored in the database. In other words, the epoch generally can freely be moved forward or backward in time. The only constraint is that the new epoch does have to be within the time range covered by the database. If a future time is specified, it will automatically be capped to the time of the most recent row in the database. If a time is specified that is older than the oldest row in the database, an error object is returned. If this error occurs, check the device time (/sys/time) and database configuration (/sys/db) to confirm that they have the expected values.

Operations

/config/display

The display (LCD) configuration of the meter.

Operations

/config/display/backlight

The backlight configuration of the display.

Operations

/config/display/backlight/brightness

The brightness of the backlight. Zero is darkest (backlight off), 255 is the brightest.

Operations

/config/display/backlight/duration

The number of seconds the backlight should remain on after the last activation of the display navigation buttons. Zero means the backlight is always off. The special value -1 indicates that the backlight remains on at all times.

Operations

/config/display/contrast

The LCD contrast Zero means no contrast (display is blank), 127 means maximum contrast (display is all black). A value of around 65 usually provides a good contrast.

Operations

/config/display/fontset

The fontset to use for the display. Possible values are:

  • small: Smaller than the normal fontset, this is a lower quality fontset that can fit more text on the display.

  • normal: This fontset provides a good tradeoff between font quality and the amount of text that can fit on the display. This should work well for languages with relatively simple characters, such as English or French.

  • large: This fontset should work well for languages with more complex characters such as Korean or Chinese.

Note The value of this resource needs to be localized (translated) before presenting it to a user.

Operations

/config/display/orientation

The angle in degrees by which the orientation of the display should be rotated in the counterclockwise direction. An angle of 0 degree results in the display being aligned with the label on the meter. The value of this resource is rounded to an integer multiple of 90 degrees.

Operations

/config/display/screen

Screen configurations. At this time, only the registers screen is configurable.

Operations

/config/display/screen/registers

The configuration of the registers screen - a screen that cycles through a list of registers, displaying their values.

Operations

/config/display/screen/registers/{name}

Specifies how the named register is to be displayed. The following characters may appear in this string:

  • i: The instantaneous (rate of change) value of the register should be displayed.

  • c: The accumulated (cumulative) value of the register should be displayed.

Note that an empty string imples that the register is not displayed at all

For the special keyword .default, this establishes how registers should be displayed that are not mentioned otherwise.

Operations

/config/language_code

The code of the preferred language for the meter. When the meter needs to generate a message (e.g., as a result of an alert triggering), it will generate the message in the language selected by this code whenever possible. The code should be in a format acceptable to the setlocale() function. Language codes currently supported include:

  • de: German.

  • en: US English (defaults to 12-hour clock and imperial units).

  • en_GB: British English (defaults to 24-hour clock and metric units).

  • es: Spanish.

  • fr: French.

  • he: Hebrew.

  • it: Italian.

  • ko: Korean.

  • pl: Polish.

  • zh_Hans: Simplified Chinese (Mandarin).

  • zh_Hant: Traditional Chinese (Cantonese).

See eGauge Internationalization Instructions for information on adding other languages or improving an existing translation.

Note When accessing the meter from a web browser, the value of this resource has normally no effect as the user interface is presented in the language selected by the browser.

Operations

/config/local

The configuration of directly attached sensors.

Operations

/config/local/gain

The amplifier gain to use for the local sensor inputs (S1 and up). All meters support the value normal. Model EG4xxx meters also support the value high. This gain increases the input gain to approximately ten times of the normal gain. That is, the sensors are approximately 10 times more sensitive than normal, at the expense of having a 10 times smaller range.

Operations