eGauge WebAPI (4.6)

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.

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

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

The meter configuration service.

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

The alert configuration of the meter.

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.

The custom alert.

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

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 user-selected name of this custom alert.

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

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

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 user name to provide to the email server for authentication purposes.

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

This resource is write-only.

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.

The email destinations to send the alerts to.

An email destination to send the alerts to.

The destination email address to send the alert to.

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.

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.

The configuration for reporting alerts via web server.

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.

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 password to be provided to the web server for authentication purposes.

This resource is write-only

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 priority of this system alert.

The BACnet configuration.

The BACnet server configuration.

The BACnet over IPv4 configuration.

The IPv4 port number used by the server when bip is enabled in /config/bacnet/server/enable. The default value is 0xBAC0 (47808).

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.

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

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.

The object id of the BACnet server.

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

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

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.

The serial-port to use for the MS/TP protocol.

The database configuration.

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.

The display (LCD) configuration of the meter.

The backlight configuration of the display.

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

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.

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.

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.

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.

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

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

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.

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.

The configuration of directly attached sensors.

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.

The sensor configurations.

The sensor configuration.

The A/D converter channel configuration of the named sensor.

The bias value (offset) to be added when converting an A/D converter sample to a physical quantity.

The channel's acquisition mode. Possible values are:

• integrate: The sample values are integrated over time.

• normal: The sensor is operating in normal mode.

• off: The sensor is not in use.

The scale value by which an A/D converter sample is to be divided to convert a sample to a physical quantity (the bias value is added to the sample before the scale is applied).

The attached sensor's relative output error (ratio error) in percent. For example, a value of 2.5 would indicate that the sensor is reading 2.5% higher than nominal. This value is ignored if member model is CTid.

The model name of the attached sensor. If this is CTid, a CTid®-enabled sensor is attached and the /ctid service should be used to obtain details about the attached sensor.

The phase (timing) adjustment required by the attached sensor. This value is ignored if member model is CTid.

The format of this string is a colon-separated list of phase- and amplitude-level pairs of the form p@l, where p is the phase-adjustment in degrees at 60Hz, and l is a percentage of the sensor's full scale value. For example, for a 100A current sensor, the phase string 1@1:0.75@50 would indicate that the phase needs to be adjusted by 1 degree at 1A and by 0.75 degrees at 50A.

The interval in milliseconds between measurement updates. The default is 1000ms (one update per second) but some meters support smaller values. The rate of change values are averaged over this period of time.

The geographic location of the meter.

The latitude of the meter's location in degrees. Positive values are north of the equator, negative values south of it.

The longitude of the meter's location in degrees. Positive values are east of the prime meridian, negative values are west of it.

The system log configuration.

The size of the system log buffer in bytes. When writing this value, it is rounded up to the nearest kilobyte boundary. A size of 0 disables the system log. Otherwise, the size is rounded up to a minimum of 4KiB.

Lua scripting configuration.

Lua scripts.

The Lua script loaded by alert reporting daemon. This script can be used to define helper functions that can then be called from the alert conditions.

If loading this script takes longer than 15 seconds or evaluating any custom alert condition takes longer than 60 seconds, an alert is raised.

The Lua script used to calculate energy cost. This script can be modified only if server-storage variable global.billing.tariff_uri is empty or unset.

If loading this script takes longer than 15 seconds or evaluating the register formulas takes longer than half the update-interval, an alert is raised.

The Lua script loaded by the register calculator. This script can be used to define helper functions that can then be called from register formulas.

If loading this script takes longer than 15 seconds or evaluating the register formulas takes longer than half the update-interval, an alert is raised.

The control scripts. Control scripts generally run indefinitely. The more control scripts exist, the slower they will execute. If a control script voluntarily terminates execution, it is restarted automatically after five seconds. If a control script is updated, its execution is automatically restarted.

The control script.

Modbus-related configurations.

Modbus client configuration. This is used by the meter to communicate with other Modbus devices.

User-defined Modbus address maps. The builtin, read-only system maps are available at /sys/modbus/client/map. If a user-defined map with the same name as a system map exists, it will shadow (mask) the system map with them same name.

Modbus map consisting of a list of register definitions and a set of options.

A set of options. The meter currently supports the following options:

• default-modbus-addr: The Modbus unit-number to use by default. This must be a decimal string. For example: 1.

• default-serial-params: The default serial parameters to use when the remote device is connected via a serial port (Modbus/RTU). This must be a string. For example: 9600/8n1 for 9600 baud, 8 databits, no parity, 1 stop bit.

• default-tcp-port: The default TCP port number to use when the remote device is connected via Modbus/TCP. This must be a decimal string. For example: 6001.

The value of the Modbus map option.

A list of Modbus register definitions.

A Modbus register definition.

The name of the register. The user can choose this name freely so long as each register within a map has a unique name.

The Modbus address of the register.

The type of the register value. This may be one of the following:

• bit: One-bit value (a coil, in Modbus terminology).
• s16: Signed 16-bit integer.
• u16: Unsigned 16-bit integer.
• s32: Signed 32-bit integer.
• u32: Unsigned 32-bit integer.
• s32l: Signed 32-bit integer, word-swapped.
• u32l: Unsigned 32-bit integer, word-swapped.
• s64: Signed 64-bit integer.
• u64: Unsigned 64-bit integer.
• float16: IEEE-754 half-precision float.
• float16l: IEEE-754 half-precision floating point, little-endian (byte-swapped).
• float: IEEE-754 single-precision float.
• floatl: IEEE-754 single-precision float, word-swapped.
• double: IEEE-754 double-precision float.

The kind of the register. Possible values are:

• analog: The value is continuous (the average of two values is meaningful).

• enum: The value is discrete (the average of two values is not meaningful). An example for this would be a numeric error code.

• bitset: Each bit in the value is a discrete on/off value. An example for this would be a set of error flags.

For register of the analog kind, this defines the physical unit of the register value. This must be one of the following:

• #3: Unit-less number with 3 decimal digits of precision.
• %: Percentage.
• A: Electric current in amperes.
• Ah: Electric charge in ampere-hours.
• As: Electric charge in ampere-seconds.
• C: Temperature in degree celsius.
• Degrees: Angle in degrees.
• Hz: Frequency in hertz.
• Ohm: Resistance in ohm.
• Pa: Pressure in pascals.
• Pct: Percentage.
• RH: Relative humidity.
• Tmd: Time in days.
• Tmh: Time in hours.
• Tms: Time in seconds.
• VA: Apparent power in volt-amperes.
• VAh: Apparent energy in volt-ampere-hours.
• V: Electric potential in volts.
• W/m2: Irradiance in watts-per-square-meter.
• W/m^2: Irradiance in watts-per-square-meter.
• W: Power in watts.
• Wh: Energy in watt-hours.
• degC: Temperature in degree celsius.
• deg: Angle in degrees.
• g: Mass in grams.
• hPa: Pressure in hecto-pascals.
• h: Time in hours.
• kAh: Electric charge in kilo-ampere-hours.
• kO: Resistance in kilo-ohms.
• kPa: Pressure in kilo-pascals.
• kVAh: Apparent energy in kilo-volt-ampere-hours.
• kW: Power in kilo-watts.
• kWh: Energy in kilo-watt-hours.
• kg: Mass in kilo-grams.
• kvarh: Reactive energy in kilo-volt-ampere-hours.
• m/s: Speed in meters-per-second.
• m3/s: Volume flow in cubic-meters-per-second.
• m3: Volume in cubic-meters.
• mA: Electric current in milli-amperes.
• mAh: Electric charge in milli-ampere-hours.
• mSecs: Time in milli-seconds.
• mV: Electric potential in milli-volts.
• mV: Electric potential in milli-volts.
• m^3/s: Volume flow in cubic-meters-per-second.
• m^3: Volume in cubic-meters.
• meters: Distance in meters.
• mm: Distance in milli-meters.
• mps: Speed in meters-per-second.
• ms: Time in milli-seconds.
• ohms: Resistance in ohm.
• ppm: Parts-per-million.
• s: Time in seconds.
• secs: Time in seconds.
• var: Reactive power in volt-ampere.
• varh: Reactive energy in volt-ampere-hours.
• °C: Temperature in degree celsius.

An offset value that is used to convert the Modbus register value to a value in the specified physical unit. Specifically, when the Modbus value of the register is reg, then corresponding physical value phys is calculated as:

phys = (reg + offset) * scale

where offset is the value defined here and scale is the value defined for member scale.

A scale value that is used to convert the Modbus register value to a value in the specified physical unit. Specifically, when the Modbus value of the register is reg, then corresponding physical value phys is calculated as:

phys = (reg + offset) * scale

where scale is the value defined here and offset is the value defined for member offset.

The access-mode of the register. It must be one of:

• ro: read-only
• rw: read-write

Modbus server configuration. This configures the server-side of the meter. That is, it defines how the meter provides its own data to other Modbus devices.

The list of protocols (if any) that are enabled in the Modbus server. An empty list indicates that the Modbus server is disabled.

Valid protocol names are:

• rtu: The Modbus/RTU protocol.

• tcp: The Modbus/TCP protocol.

The name of a protocol that is enabled.

The address of the meter on the Modbus/RTU network. Every Modbus device must have a unique address. The default unit id is 1.

Note Address 0 is the broadcast address and addresses 248..255 are reserved for future use.

The RTU protocol configuration.

The serial-port to use for the RTU protocol.

The TCP protocol configuration.

The IP port of the Modbus server. The default value is 502.

The network configuration.

The current state of the network is available at /sys/net.

The Ethernet configuration of the meter.

Whether or not the Ethernet watchdog is enabled. If enabled, the watchdog will reset the Ethernet's PHY chip and/or reload the Ethernet driver if it appears that the Ethernet link was lost.

This should normally be set to true.

The Go proxy configuration of the meter.

If true, the meter will connect to the Go proxy server.

The hostname of the Go proxy server.

HomePlug configuration. This is used only by devices with built-in HomePlug power-line communication (egauge2, EG3x10 and EG41xx).

The jurisdiction the meter is operating under. The possible values are:

• CE: European Union region.
• NA: North American region.

This resource controls the frequency bands used by the HomePlug communications interface that is built into some meters. For those meters, this resource must be set to the correct geographic region to ensure compliance with local laws.

The hostname of the meter. Must consist of ASCII letters, digits, and dashes only.

Web (HTTP) related configurations.

Modification requests (PUT, POST, and DELETE) to this resource are not executed transactionally.

The certificate used by the web server to identify itself over HTTPS connections.

This resource is write-only.

The string is in PEM format and must contain both a private key as well as the matching certificate chain.

Configuration for meter-initiated HTTP connections.

If true, meter-initiated secure HTTPS connections will accept servers whose certificate cannot be validated by the meter. This should normally be set to false.

Controls access to CGI-BIN programs. The following values are supported:

• disable: Completely disable access to CGI-BIN programs. Warning This will render the classic user-interface of the meter inoperable.

• user-required: Allow authenticated users to access CGI-BIN programs.

• user-optional: Allow even unauthenticated users to access CGI-BIN programs that are not considered security critical.

The Internet Protocol v4 (IPv4) configuration.

Whether or not to use DHCP to automatically provision the IPv4 address. If true, DHCP is enabled. If false, the manually configured IPv4 settings are used.

An IPv4 address in dotted decimal notation.

An IPv4 broadcast address in dotted decimal notation.

The address of the IPv4 gateway in dotted decimal notation.

The IPv4 network mask in dotted decimal notation.

The IPv4 network number in dotted decimal notation.

The name server (DNS) configuration.

The IP addresses to use as name servers. If multiple name servers are specified, they are queried in the order in which they appear here.

The IPv4 or IPv6 address a DNS server.

The Network Time Protocol (NTP) configuration.

The NTP servers to use.

The hostname or an IPv4 or IPv6 address of an NTP server.

Options that have a system-wide effect on the network services.

If true, network services which do not encrypt data are disabled. At present, turning on this option disables the following services:

• The web-server's plain HTTP service (port 80).

• The service that provides the meter data via link-type udp. Thus, it other meters will not be able to read this meters data via this link type anymore.

This resource is not updated transactionally and after changing its value, the web server will be unavailable temporarily.

The proxy configuration of the meter.

If true, the meter will connect to the proxy server.

The hostname of the proxy server.

The Precision Time Protocol (PTP) configuration. NTP should normally be disabled when using this protocol. This can be achieved by deleting resource /config/net/ntp/server.

Only model EG4xxx or newer meters support this resource.

The following properties of the PTP service are currently fixed:

• Update method: Two Step
• Delay Mechanism: End to End
• Domain Number: 0
• Priority 1: 128
• Priority 2: 128
• Transmission Method: Multicast
• Log Announce Interval: 1 (2 seconds)
• Log Sync Interval: 0 (1 second)
• Log Min Delay Request Interval: 0 (1 second)
• Log Min PDelay Request Interval: 0 (1 second)
• PTP Destination MAC: 01:1B:19:00:00:00
• PTP Destination MAC: 01:80:C2:00:00:0E
• Transport Specific Field: 0

If true, the meter will only act as a client. Otherwise, the meter will also act as a server if the PTP algorithm selects it as the best clock.

The network interface configurations for PTP. If empty, PTP is disabled.

The configuration to use for the named interface.

The network transport to use for the interface. Possible values are:

• UDPv4: UDP over IPv4.
• UDPv6: UDP over IPv6.
• L2: Layer-2 transport (e.g., Ethernet).

The Time-to-live (TTL) value for IPv4 multicast messages and the hop limit for IPv6 multicast messages. This value is ignored unless transport is either UDPv4 or UDPv6. The default is 1, which restricts the messages to the same subnet.

The push service configuration. This service is used to share the meter data with a remote web server. The data is sent via an HTTP POST request.

The interval in seconds between push updates. A value of 60, for example, would cause the push service to attempt to send data to the remote web server once a minute.

The options controlling how data is pushed to the remote web server. Multiple options must be separated by commas (,).

This resource is available only if /config/push/service is an empty string.

Available options are:

• day: Data will be pushed with day granularity (at most one row of data per day).

• deflate: Use the deflate algorithm to compress the push data. This adds HTTP header Content-Encoding: deflate to the POST request.

• epoch: Report the register values relative to the epoch. Without this option, absolute values are sent which start at zero at the time the meter database was created.

• gzip: Use the gzip algorithm to compress the push data. This adds HTTP header Content-Encoding: gzip to the POST request.

• json: Push data in JSON format instead of XML. The JSON format is the same as the one returned by the /register service, except that the top-level ts section and the idx members in the registers section are omitted since they are not meaningful for push data.

• hour: Data will be pushed with hour granularity (at most one row of data per hour).

• max=n: Pushed at most n rows in a single POST request. This limit must be in the range from 1 to 900.

• msec: Data will be pushed with millisecond granularity (at most one row of data per millisecond).

• old_first: Push the oldest data row first. By default, the youngest data row is pushed first.

• sec: Data will be pushed with second granularity (at most one row of data per second).

• secure: If this option is present, secure connections to the remote web server are allowed only if the server possesses a certificate that the meter can verify as authentic. Without this option, the server's certificate is not verified. This option is ignored if /config/net/http/client/insecure is true.

• skip=n: Push only every (n+1)-th data row. For example, with hour granularity and skip=2, data rows would be spaced apart by (at least) 3 hours. They may be spaced apart more depending on the rows that are available in the database.

• totals: Push not just the physical registers but also the virtual registers.

By default, data is pushed with minute granularity (at most one row of data per minute).

The password to be provided to the remote web server for authentication purposes. The password is submitted to the remote web server as part of a Basic HTTP Authorization header. For this reason, a password should only be specified when using a secure connection (https scheme).

This resource is available only if /config/push/web/service is an empty string.

This resource is write-only.

The name of a push service provider to shared data with.

To set this to a non-empty value please use the service activation command since that ensures the push provider knows to expect data from this meter. The body of the activation request should contain member service set to the string push and provider set to name of the desired push service provider.