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 log configuration.

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.

The URI of the web server to share data with. This resource is available only if /config/push/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 as part of a Basic HTTP Authorization header.

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

The register configuration of the meter.

The physical register configuration of the meter.

A register is a named measurement whose values are recorded in a database at discrete points in time (the database rows). There is an upper limit on the number of physical registers that can be supported by the meter. Depending on meter model and database configuration, typically, 16 to 64 phycial registers are available. The actual limit is available at /sys/db/max-registers.

The configuration of the named physical register.

The name of the device that is the source of the register values. The name local indicates that the meter itself measures or calculates the value. Any other value is a reference to the remote device of the same name defined at /config/remote.

The column number in which the database stores the register value. Each physical register has a unique column number. If a register is renamed, this number remains the same. On the other hand, if a register is deleted and then another one is added back, the new one may get assigned the column number of the old, deleted register.

Each physical register must have a unique value. Invalid values automatically get remapped to an unused index.

The type code of the register.

Defines the how the register value is obtained or calculated. For register where dev is local, this is one of:

• A local sensor name: L1-L3, Ldc, or S1-S30.

• A power formula written as a sum of products of sensors. For example, S1*L1+S2*L2 would indicate that the register value is calculated as the real power measured by current sensor S1 and line-voltage L1 plus the real power measured by current sensor S2 and line-voltage L2. Note that even though the real power calculation is indicated by an asterisk, it is actually calculated by averaging the product of the instantaneous current and voltage samples, not by multiplying the RMS voltages of S1 and L1. The first factor of each real power calculation may also be negated. For example, -S1*L2 would yield the negative of the real power calculated by S1*L2.

• An equal sign (=) followed by an eScript expression. The register value is obtained by evaluating the eScript expression once per update interval. Non-finite numbers (e.g., not-a-number, or infinities) are silently converted to 0 before recording the register value.

For registers where dev is not local, so-called remote registers, the value is interpreted in a way that is specific to the particular remote device in use. Commonly, the value is some sort of register name or identifier. For example, for Modbus remote devices, the value is a register name defined by the Modbus map of the remote device.

The virtual register configuration of the meter.

Virtual registers are calculated from physical register values and do not take up space in the database. As such there is no a priori limit on the number of virtual registers that can be configured on a meter.

The virtual register configuration.

Several virtual register names are well-known and provide special semantics:

• use: Intended to represent total power consumption at a site. It is generally presented with the name Usage in English and the equivalent translation in other languages (subject to availablility).

• gen: Intended to represent total power generation at a site, e.g., from local solar or wind power generation facilities. It is generally presented with the name Generation in English and the equivalent translation in other languages (subject to availability).

• bat: Intended to represent total power coming from on-site batteries (if positive) or power going to on-site batteries for charging (if negative). It is generally presented with the name Battery in English and the equivalent translation in other languages (subject to availability).

• bat_el: Intended to represent the amount of energy left in on-site batteries. The value of this register should be equal to the sum of each battery's state of charge times the battery's capacity (in joules). It is generally presented with the name Battery left in English and the equivalent translation in other languages (subject to availability).

The formula to calculate the value of this virtual register. It consists of a list of physical register names whose values are to be added or subtracted.

An additive term of the virtual register formula.

The operation that calculates the value of this addend.

Possible values are:

• +: The physical register value is to be added.

• -: The physical register value is to be subtracted.

• +max0, -max0, +min0, -min0: Deprecated. These operators do not work correctly and remain only to preserve compatibility with existing, old, device configurations. Attempting to write these operators with a PUT or POST request will result in an error. They can only be returned as a result of a GET request. The intent of these operators was to add (+max0, +min0) or subtract (-max0, -min0) the maximum of the physical register value and 0 (+max0, -max0) or the minimum of the register value and 0 (+min0, -min0).

The name of the physical register to use in calculating the value of this addend.

The remote device configurations.

The configuration of a remote device.

The address of the remote device. The meaning of this value depends on the link-type.

The link-type of the remote device.

Time related configurations.

The timezone the meter is located in. The string is interpreted as a Unix TZ string.

The user accounts.

Each user account has a name, a set of privileges, and the credentials (password) required to log into the account.

A user configuration (account).

The list of privileges the user possesses.

A privilege the user possesses.

The hash of the user's password. Writing an empty hash string disables the account.

This resource is write-only.

Meter variables provide a means to store arbitrary name/value pairs on the meter itself. These variables can be employed by a WebAPI user to customize behavior. For example, the preferred currency symbol is stored in a meter variable so that all WebAPI users can consistenty display monetary values.

Any authenticated user can read meter variables but only users who have the privilege to save settings can create or update them.

Variable names must be at least one character long and may consist of lower- and upper-case ASCII letters, digits, dashes (-), underscores (_), and percent signs (%). Note that when using a variable name as part of a URL path, any percent sign must be encoded as %25 (25 is the hexadecimal value of the ASCII code of %).

For backwards-compatibility, a variable name may also contain a single dot (.) if it does not appear as the first or last character in the name. When a dot is present, the string before the dot is called the paragraph name.

Variable values may contain any UTF-8 points except ASCII control characters.

The meter variables in the named section.

The value of the named meter variable. Complex values can be stored, e.g., by JSON-encoding them.

This service provides access to the CTid® facility built into the EG4xxx series meters. Specifically, it enables:

1. retrieving the CTid® information from a sensor,

2. flashing the (optional) locator LED on the sensor, and

3. deleting the stored CTid® information associated with a sensor port.

Note that while scanning or flashing a sensor, normal measurement of local sensors is suspended. It is therefore recommended to use this service primarily during device setup.

All methods other than GET required a user with the save right.

This resource is used to issue control calls and to check on the status of a previously issued calls.

Provides information about devices that can accept control calls. Each device is described by a set of name/value pairs called device attributes.

The names and descriptions of control interfaces detected by the meter.

Description of the interface.

The array of methods provided by this interface. The methods are listed in no particular order.

The description of this method.

The name of the method. The name starts with a letter and consists entirely of letters, digits, or underscores.

The DBus type signature of the input arguments to the method. An empty string indicates that the method accepts no input arguments.

The names of the input arguments passed to the method. Each argument name is meant to indicate the purpose of the respective argument but, other than that, it is arbitrary. The documentation string given by member doc may also refer to these names. The doc member documentation for details.

The name of this input argument.

The DBus type signature of the return value of the method. An empty string indicates that the method returns no value.

Description of the purpose and operation of the method. Within this string, references to input argument names are enclosed within <arg> and </arg> tags to facilitate highlighting of argument names.

This service provides access to the values directly measured or derived from the sensors attached to the meter. Values obtained from other, remote, devices are not accessible through this service. Similarly, only the most recent (current) values are available. Use the /register service for accessing values stored in the database of the meter.

Derived values are called energy and apparent energy and are calculated from a pair of sensors. Specifically, energy values are calculated by numerically integrating over time the product of two sensor values. Similarly, apparent energy is calculated as the product of the normal (RMS) values of a pair of sensors. For example, if one sensor value measures an electrical current and the other a voltage, these calculate the real electric energy and apparent electric energy of the measured current/voltage pair, respectively.

This service guarantees to return an atomic snapshot of the measurements as of the time indicated by the timestamp in the response. Various query parameters can be used to select the exact data that is to be returned.

In particular, query parameters values, energy, apparent, or stats can be used to select which sections to include in the response. If none of these are specified, only the values section is returned by default.

Query parameters rate, cumul, or type can be used to select the metrics to return for each sensor. If none of these are specified, the rate and type metrics are returned by default.

Within the rate and cumulative metrics, query parameters normal, mean, or freq select what measurements to return. If none of these are specified, all measurements are returned by default.

Finally, the env, l, and s query parameters can be used to select which sensors to include in the response. If none of these are specified, all sensors are included in the response by default.

Provides access to various logs. Since logs may contain sensitive information, this service is available only to users with the save privilege (see /auth/rights).

This service provides access to Lua-script related information.

The persistent Lua variables. Such variables are non-volatile. That is, their value is preserved across script restarts and reboots (power-cycles). Persistent variables can be created and manipulated with the built-in Lua module persistent.

A persistent Lua variable.

A brief, user-friendly description of the purpose of this persistent variable. This description is set when the persistent variable is created and is in the language chosen by the author of the Lua script that is created the variable. The string is, therefore, not localized to the user's environment.

The current value of this persistent variable as a JSON-encoded string.

While it is possible to write this value via the WebAPI, Lua scripts generally will also be updating the value as part of their execution, so any change in value may be temporary and whether or not a WebAPI write is detected by the scripts depends on the scripts themselves.

This service provides information about various third-party providers such as alert service providers, push data service providers, tariff information providers, and so on. Since the information depends on third-party sites, a working Internet connection is generally required in order for this service to work properly.

This service provides access to both current and past register values of the meter. A register can be thought of as a named column in a database that tracks the value of a measurement over time.

The database consists of rows of register values. Each row has a timestamp indicating the time at which the measurements were taken. The maximum numbers of the rows in the database is fixed and the rows are managed in a round-robin style. Typically, meters can hold up to the most recent 60 years of rows in the database. Older data is automatically dropped.

Older data is stored with a coarser granularity than younger data. A typical database might store the most recent one year of data with 1 minute between rows, the next 9 years with 15 minutes between rows, and the next 50 years with 24-hours between rows. The actual database configuration of a meter can be found in /sys/db.