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.
The IPv4 port number used by the server when bip is enabled in /config/bacnet/server/enable. The default value is 0xBAC0 (47808).
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 BACnet over MS/TP configuration. This is used only if the mstp protocol is enabled.
The serial-port to use for the MS/TP protocol.
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 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.
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 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 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 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.
Modbus-related configurations.
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.
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 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 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 serial-port to use for the RTU protocol.
The network configuration.
The current state of the network is available at /sys/net.
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.
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.
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.
The name server (DNS) configuration.
The Network Time Protocol (NTP) configuration.
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 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:
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 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 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.
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 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 address of the remote device. The meaning of this value depends on the link-type.
The link-type of the remote device.
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.
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.
This service provides access to the CTid® facility built into the EG4xxx series meters. Specifically, it enables:
retrieving the CTid® information from a sensor,
flashing the (optional) locator LED on the sensor, and
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.
Provides information about devices that can accept control calls. Each device is described by a set of name/value pairs called device attributes.
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 DBus type signature of the return value of the method. An empty string indicates that the method returns no value.
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).
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 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.
Note This service is deprecated and will be removed in the future. Please use /config/var instead.
This service provides the ability to store arbitrary name/value pairs on the meter. This is called server-side storage.
The service implements a hierarchical name-space, with hierarchy levels separated by slash characters (/). The top-level is called a section, intermediate levels are called paragraphs, and leaves are called variables. For example, the path global/default/currency_code refers to variable currency_code in section global, paragraph default.
Variables may also be stored at the section level. The last character of a URL determines whether the URL refers to a section-level variable or a paragraph. If the URL ends with a slash character (/), it refers to a paragraph, otherwise, it refers to a section-level variable.
Names may contain lower- and upper-case ASCII letters, digits, dashes (-), underscores (_), and percent signs (%).
Variable values may contain any UTF-8 codes except ASCII control codes (codes less than 0x20). Some variables may be defined as storing JSON-encoded values. For those, the value is limited to characters permissible by the JSON grammar.
System information. Everything here is read-only.
Accessing this service requires the view_settings privilege.
The reason for the most recent CPU reset. The strings vary depending on the hardware platform. For EG4xxx model devices, the possible values are:
general reset: CPU was powered on when the backup battery was depleted.
wakeup: CPU was powered on when backup battery still had sufficient charge left.
watchdog reset: The CPU's watchdog timer triggered the reset.
software reset: Firmware requested a reboot.
user reset: Not applicable.
unknown reset: Not applicable.
The time of the last user-initiated reboot. It is a decimal Unix timestamp string or null if unavailable. Unanticipated reboots, e.g., due to power failure or watchdog-timeouts do not update this resource.
The Unix timestamp of the most recent data row stored at this level of the database. If null, no row is currently available at this database level.
Documents the eScript functions built into the meter.
Documents the basic eScript functions. Basic functions are available any place eScript expressions may appear.
The formal name of the argument. The name starts with a letter and consist entirely of alpha-numeric characters or underscores (_). The name usually suggests the purpose of the argument. It may also be referenced within the help string (member help). Other than that, the name has no significance.
A type code indicating the type of the argument. The special value string indicates that the value must be a string.
The help string (documentation) for this function. In this string, references to argument names are enclosed in arg tags using an XML-like syntax. For example, a reference to an argument with name count would appear as <arg>count</arg> in this string. This can be used to highlight argument names in the document string, for example.
Documents the alert eScript functions. These functions are available only for eScript expressions evaluated as part of alert conditions.
The formal name of the argument. The name starts with a letter and consist entirely of alpha-numeric characters or underscores (_). The name usually suggests the purpose of the argument. It may also be referenced within the help string (member help). Other than that, the name has no significance.
A type code indicating the type of the argument. The special value string indicates that the value must be a string.
The help string (documentation) for this function. In this string, references to argument names are enclosed in arg tags using an XML-like syntax. For example, a reference to an argument with name count would appear as <arg>count</arg> in this string. This can be used to highlight argument names in the document string, for example.
System-defined (built-in) Modbus address maps. The user-defined maps are available at /config/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 the same name.
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 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 network settings that are in use by the meter. This may or may not be the same as the configuration established in /config/net.
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.
Network Time Protocol (NTP) status.
Status of each configured NTP server.
The meter's view of the current state of this NTP server. It may have one of the following values:
INVAL: The server is invalid, e.g., because the hostname could not be resolved to a network address or because the remote server is not responding.
TRACK: The server is being tracked and, if everything continues to work fine, it will enter the PEER state shortly.
PEER: The server is a peer and could be used as a time source.
SYNC: The server is a peer and the meter's time is synchronized with this server.
A set of flags enclosed in square brackets. Each flag gives some information about the capabilities of this access point.
The following flags are currently defined:
DMG: Indicates the access-point supports 802.11ad directional multi-gigabit (DMG).
EBSS: The access-point supports extended wireless networks.
FILS: The access-point supports 802.11ai fast initial link setup.
FST: The access-point supports fast session transfers.
HS20: The access-point supports Hot Spot 2.0 (Wi-Fi Certified Passpoint).
IBSS: The access-point supports independent basic service set (ad-hoc) wireless networks.
MESH: The access-point uses a mesh network.
OSEN: The access-point supports Server-only authenticated layer 2 Encryption Network.
OWE-TRANS: See Opportunistic Wireless Extension.
OWE-TRANS-OPEN: See Opportunistic Wireless Extension.
P2P: The access-point supports point-to-point (WiFi Direct) wireless networks.
PBSS: Indicates the access-point supports personal basic service set wireless networks.
RSN: Indicates the access-point supports Robust Security Network (RSN).
UTF-8: The SSID is UTF-8 encoded.
WEP: The access-point supports Wired Equivalent Privacy (WEP).
WPA: The access-point supports Wi-Fi Protected Access (WPA).
WPA2: The access-point supports Wi-Fi Protected Access (WPA) version 2.
WPS: The access-point supports Wi-Fi Protected Setup (WPS).
Encryption-related flags may be followed by various sub-flags that are separated by a + character. For example, WPA2-PSK-CCMP+TKIP indicates that WPA2-PSK-CCMP is supported with the TKIP protocol.
A set of flags which are enclosed in square brackets. The following flags are currently defined:
CURRENT: Indicates that this network is currently being used.
DISABLED: The network is disabled from being used.
TEMP-DISABLED: The network is temporarily disabled from being used.
P2P-PERSISTENT: Indicates a point-to-point (WiFi Direct) connection. This is not used by the meter.
The status of the push (data sharing) service. See /config/push.
The next time the meter will send push data to the server. The time is expressed as a decimal Unix timestamp string. If unavailable, this is an empty string.
The last time the meter sent (or attempted to send) push data to the server. The time is expressed as a decimal Unix timestamp string. If unavailable, this is an empty string.
The most recent time push data was successfully sent to the server. The time is expressed as a decimal Unix timestamp string. If unavailable, this is an empty string.
The time of the last register data row sent to the server. The time is expressed as a decimal Unix timestamp string. If unavailable, this is an empty string.
This is true if the meter needs to be rebooted, e.g., due to a configuration change. If so, a reboot command should be issued at the next opportune moment.
If set, indicates that an error occurred. The meaning of this value depends on the operation being performed. Generally, it is a short tag. For example, OOM to indicate "out of memory". Before presenting the tag to a user, it must be translated to a human-readable string. The strings in member args provide additional info about why the error occurred.
If set, indicates the action the long-running operation is currently performing. The meaning of this value depends on the operation being performed. Generally, the string is a short tag. For example, RESTORE to indicate that data is being restored to the database. Before presenting the tag to a user, it must be translated to a human-readable string. The strings in member args provide additional info about the action being performed.
The time when this status was created. It is a decimal Unix timestamp string.
The Unix timestamp of when the FFT calculations were updated most recently. If null, it indicates that no FFT calculations are being performed. If not null, the timestamp typically lags behind the current time by a couple of seconds because FFTs cannot be calculated in real time.
The pending amount of excess for this register. For locally measured registers and discrete registers, this is always zero. For remote registers, this becomes non-zero if the rate of change to be recorded is outside of the actual rate plus/minus 10%. This is being done to prevent recording big spikes when a remote device is offline for some time and then comes back online. Instead of recording a big jump, an excess is recorded which will then be played back over time by inflating (or deflating) the recorded rate by up to +/-10% of the actual rate until the excess has been drained. The excess of all registes can be reset to zero with the clear command.
The decimal Unix timestamp of when this register was last updated.
The current value of the register as signed 64-bit integer converted to a decimal string. Except for discrete registers, this is an accumulated value (see Section Type Codes for details).
The current meter time as a decimal Unix timestamp string.