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.
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.
Items marked deprecated should not be used going forward as they will be removed in a future firmware release.
Most device attributes are simple name/value pairs with both the name and the value consisting of strings. Two exceptions are the path and interface attributes:
path: The value of this attribute is a list of strings. The list provides a unique path to the device. If present, it must be the first attribute. This is the only attribute which provides a guaranteed unique identifier for the device. The flip-side is that the path is not necessary stable. For example, if a USB device is moved from one port to another, the path would change. Thus, depending on the needs of the application, it may be more appropriate to identify a device through other means, such as the manufacturer, model, and serial-number, which, together, might provide a unique identifier for the device that remains stable regardless of how the device is connected to the meter.
interface: The value of this attribute is also a list of strings. Each entry is the name of an interface that is supported by the device. A description of each interface can be obtained from /ctrl/interface.
The meaning of other attributes is given below:
link: The physical link used by the device. If present, the value must be one of:
Ethernet: The device is connected via Ethernet.
USB: The device is connected via USB.
serial: The device is connected via a serial link such as RS485, RS232, or similar.
mfg: The name of the manufacturer of the device (e.g., eGauge).
model: The model name of the device (e.g., PRM3).
name: If present, a user-selected name of the device.
prot: The communication protocol used by the device. If present, it must be one of:
CoAP: The device uses the Constrained Application Protocol.
CtrlByWeb: The device uses the ControlByWeb XML protocol.
Modbus: The device uses the Modbus protocol.
RTCoA: The device uses the Radio Thermostat Co of America protocol.
SCPI: The device uses the SCPI protocol (pronounced "skippy".
SMANet: The device uses the SMAnet protocol used by older PV inverters manufactured by SMA.
quality: Devices that can potentially be reached through multiple paths may set this attribute to indicate the communication-quality of a particular path. The value of this attribute must be a decimal string. Paths that provide better communication-quality in some sense (e.g., higher speed or smaller loss-rate) should have a higher value. When mapping a set of attributes to a set of paths, the paths will be ordered by decreasing quality value such that higher quality paths will appear before lower quality ones.
sn: The serial "number" of the device. Even though called a number, the value may also contain non-digit characters (e.g., 0Y0035).
eScript is a simple scripting langage which supports basic arithmetic operations (addition, subtraction, multiplication, and division) of double-precision floating point numbers. The operations follow normal precedence rules. Parentheses can be used to force evaluation in a particular order. A C-like ternary operator is also supported for conditional evaluation. Specifically:
c ? e1 : e2
evaluates to e1 if c is non-zero and to e2 otherwise.
The latest instantaneous value of a meter register can be obtained with the $ operator which must be followed by a register name in quotes. For example:
$"Grid"
would evaluate to the instantaneous value of register Grid.
eScript also supports various functions such as sin() to calculate the sine of an angle or THD() to calculate total-harmonic distortion in a signal. A list of functions is available at /sys/func.
An eScript expression which starts with a colon (:) is interpreted as a Lua expression.
Filter-specs can be used to return only certain members of an object or certain elements of an array.
For example, {foo,bar} would limit the output of an object to the members with names foo and bar. Similarly, [0,3:5] would limit the output of an array to the elements with indices 0, 3, 4, and 5.
If a member or array filter is empty, all members/elements of that object/array are returned. This is handy when filtering deeper levels of a response. For example [{addr}] would return only member addr from all the objects in the returned array.
For a more complex example, the filter-spec {reg[7:8{addr}]} would, for each object in the response, only return the reg member and, within each reg array, only elements with indices 7 or 8 would be returned. Within the objects of those elements, only the addr member would be returned.
Note that braces and square brackets normally need to be percent-encoded before using them in a URL (e.g., %7B for {).
The formal syntax of a filter-spec (FSPEC) is given by the EBNF syntax below. No whitespace is allowed between symbols.
FSPEC = [OBJECT_FILTER | ARRAY_FILTER] .
OBJECT_FILTER = "{" MEMBER_FILTER {"," MEMBER_FILTER)} "}" .
ARRAY_FILTER = "["INDEX_FILTER {"," INDEX_FILTER)} "]" .
MEMBER_FILTER = [NAME | "(" NAME {"," NAME} ")"] FSPEC .
INDEX_FILTER = [RANGE | "(" RANGE {"," RANGE} ")"] FSPEC .
RANGE = UINT [ ":" UINT ] .
UINT = DIGIT { DIGIT } .
DIGIT = "0".."9".
NAME = ALPHA | DIGIT | "-" | "." | "_" | "~" | PCT_ENC .
ALPHA = "a".."z" | "A".."Z" .
PCT_ENC = "%" HEX HEX .
HEX = DIGIT | "a".."f" | "A".."F" .
EMPTY = .
In words: a filter-spec can restrict the members returned from an object by listing zero or more member names, separated by commas, in curly braces. Only listed member names will be returned. As a special case, the empty object filter {} returns all members. A member name can be followed by a nested filter-spec to further filter the value the member with that name. A common nested filter-spec can also be applied to several comma-separated member names by enclosing them in parentheses and writing the common filter-spec after the closing parenthesis.
Similarly, a filter-spec can restrict the elements returned from an array by listing zero or more indices, separated by commas, in square brackets. Only listed indices will be returned. As a special case, the empty array filter [] returns all elements in an array. An index can be a single unsigned integer or a range of indices written as a starting index, a colon, and an ending index. For example, range 10:20 would corresponds to indices 10 through 20. An index can be followed by a nested filter-spec to further filter the value of the element with that index. A common nested filter-spec can also be applied to several comma-separated indices by enclosing them in parentheses and writing the common filter-spec after the closing parenthesis.
The link type of a remote device determines the communication protocol that is used to talk to the device and the format of the address string. Supported link-types are:
ailux: This link type can be used to read data from heat pump controllers manufactured by Alpha Innotec. The address must be the hostname or IP address of the heat pump controller. The data is fetched from TCP port 8088 of the controller.
coap: This link type can be used to read data from devices that support the CoAP protocol. The address must be the hostname or IP address of the device. The data is fetched from UDP port 5683.
ctrlbyweb: This link type can be used to read data from devices manufactured by ControlByWeb. The address must be the hostname or IP address of the device. An optional port number may be specified after a colon (:). By default, port 80 is used. The data is fetched from the device with the HTTP protocol.
modbus: This link type can be used to read data from a Modbus/TCP device. The address must have the format map.unit@host:port:
map: The name of the Modbus address map to use for the device (see /sys/modbus/client/map and /config/modbus/client/map). If the Modbus device supports the SunSpec standard, this can be sunspec instead. With SunSpec, the meter can automatically detect the available Modbus registers.
unit: The Modbus unit number of the device (defaults to 255).
host: The hostname or IP address of the device.
port: The port number to use. Defaults to the value of map option default-tcp-port, or port 502 if the option is not present.
An example address is sunspec.1@192.168.1.34 which would refer to a SunSpec-compatible device with unit number 1 and IP address 192.168.1.34.
po: This link type can be used to read data from Aurora solar inverters manufactured by Power One. The inverter's serial port must be connected to an RS485-to-Ethernet adapter such as the Chiyu BF-430. The default RS485 serial parameters used by the inverter are: 19200 baud, 1 stop bit, no parity. The address must have the format devnum@addr:port, where devnum is the inverter's serial address in the range from 2 to 254, addr is the host or IP address of the RS485-to-Ethernet adapter, and port is the port number of the adapter.
rtcoa: This link type can be used to read data from thermostats manufactured by Radio Thermostat Company of America. The address must be the hostname or IP address of the thermostat. An optional port number may be specified after a colon (:). By default, port 80 is used. The data is fetched from the device with the HTTP protocol.
slowd: This link type can be used to read data from various devices connected over a serial port. The address must have the format proto://devaddr, where proto is the name of the communication protocol and devaddr is a device-address in a format that depends on the protocol. The available protocols are:
alphatechnics: Implements a proprietary protocol for reading AlphaTechnics 5000 series precision thermometers. These devices have a USB port which emulates a serial interface, so they can be plugged directly into EG4xxx meters.
The serial port parameters default to 57600 baud, no parity, and one stop bit. devaddr must be a serial-port name and optional serial parameters.
An example address is alphatechnics://USB2 which would connect to the thermometer plugged into the meter's USB2 port.
modbus: Implements the Modbus/RTU protocol which can connect two or more devices over RS485. devaddr must have the format modbus://map.unit@serdev where:
map: The name of the Modbus address map to use for the device (see /sys/modbus/client/map and /config/modbus/client/map). If the Modbus device supports the SunSpec standard, this can be sunspec instead. With SunSpec, the meter can automatically detect the available Modbus registers.
unit: The Modbus unit number of the device. This defaults to the value of map option default-modbus-addr or 0 if the option is not present.
serdev: The serial port and optional serial parameters of the meter which is wired to the RS485 bus. The serial parameters default to the values given by map option default-serial-params or 19200 baud, no parity and 1 stop bit if the option is not present. Alternatively, serdev may also have the format host:port where host is the hostname or IP address of an RS485-to-Ethernet adapter and port is an optional TCP port number.
An example address is modbus://sunspec.1@USB1 which would refer to a SunSpec-compatible device with unit number 1, connected to the meter via serial port USB1.
po: Implements the protocol used by older Power One Aurora inverters. These inverters are no longer being manufactured and Power One has been acquired by ABB.
The inverters are connected via RS485. The serial communication parameters are 19200 baud, 1 stop-bit, and no parity. devaddr must have the format num@addr where num is the inverter's serial address in the range from 2 to 254 and addr is the name of the meter's serial-port that is wired to the RS485 bus. Alternatively, addr may also be the hostname or IP address of an RS485-to-Ethernet adapter that the bus is wired to.
scpi: Implements the SCPI (skippy) protocol. devaddr must be a serial-port name and optional serial parameters or a hostname or IP-address of serial-to-Ethernet adapter to which the SCPI-compatible device is connected.
The registers available to be read are automatically detected based on the result of SCPI command *IDN? (Identify). Currently, only eGauge PRM3 relay modules are recognized.
sma: Implements the SMA Data Communication protocol which is used by older inverters and weather stations manufactured by SMA. These devices are connected via RS485. The serial communication parameters are 1200 baud, 1 stop-bit, and no parity. The protocol automatically detects connected devices and the available registers. However, since the bus operates at only 1200 baud, detection can take several minutes.
devaddr must be the name of the meter's serial-port that is wired to the RS485 bus. It may also be the hostname or IP address of an RS485-to-Ethernet adapter that the bus is wired to.
sony: Implements a proprietary protocol for reading certain Sony battery charge controllers (BMUs) over RS232. Specifically, specification P5-9 027, version 2 is supported. The serial port parameters are fixed to 19200 baud, even parity, and one stop bit. devaddr must have the format sony://num@addr where:
num: Is the number of the battery charge controller to read from. It must be in the range from 0 to 15.
addr: Must be the hostname or IP address of the RS232-to-Ethernet adapter which the charge controller is connected to.
An example address is sony://1@192.168.1.34:10001 which would connect to battery charge controller 1 which is wired to the RS232-to-Ethernet adapter at IP address 192.168.1.34, port 10001.
tcp: This link type can be used to read the data from another eGauge meter over the TCP protocol. The address must be a hostname or IP address which may optionally followed by a vertical bar character (|) and a comma-separated list of options. The available options are:
async: This option must be used if two or more eGauge meters read each other's data. This causes a cyclic dependency which, without this option, would result in timeouts and the inability to read the remote meter's data. To break the cycle, it is sufficient for one of the meters in the cycle to turn on this option. The downside of turning on this option is that remote data will be recorded at the time it is received by the local meter, rather than the time when it was measured by the remote meter, as would normally be the case.
sync: This is enables the default synchronous read mode where remote data is recorded with the time that it was measured at by the remote meter.
spiky: This option affects how data is recorded after the remote meter is unavailable for a period of time. By default, the local meter will smooth out any jumps (spikes) in the data that are due to the remote meter not being reachable. Turning on this option disables the smoothing and instead records jumps as they occur. Normally, smoothing is preferable. However, if a remote meter is frequently unreachable (10% or more of the time), the local meter will fall behind the remote meter data more and more and, in such a case, turning on this option would be advisable.
The remote data is fetched via HTTP protocol (TCP port 80). It is not possible to specify authentication credentials.
An example address is eGauge1234.local|sync,spiky. This would connect to the remote meter with hostname eGauge1234.local using the sync and spiky options.
tempalert: This link type can be used to read data from temperature sensors manufactured by Temperature Alert (no longer in business). The address must be the hostname or IP address of the sensor. The data is fetched from port 80 of the device with the HTTP protocol.
udp: This link type can be used to read the data from another eGauge meter over a proprietary UDP protocol. As such, it provides the same functionality as tcp, but since it runs over UDP, it is a lighter-weight, more efficient protocol. The data is read from UDP port 59046. The address syntax and available options are the same as for link type tcp.
The max-depth parameter can be specified to limit the depth to which a response object or array is output. When the depth-limit is reached, only a list of member names is returned for objects and only the length is returned for arrays.
For example, if the full result object were:
{"obj": {"a": ..., "b": ...}, "arr": [1, 2, 3, 4]}
then this restricted to max-depth=2 would return:
{"obj": ["a", "b"], "arr": 4}
That is, the value of obj was replaced by the list of the object's member names and the value of array arr was replaced by its length.
When a modification request to a resource is not executed transactionally, it means that it may be possible to observe the modification of that resource before or after modifications to the other resources being updated within the same request. It is also possible for the modification to take effect even though the overall request may end up failing with an error.
Passwords are never written directly to this API. Instead, only hashes are written which are derived from the user name, realm, and password. Specifically, the hash is calculated as the MD5 sum over the string obtained when concatenating the user name, the realm, and the password while using colons as field-separators. For example, the hash of user name jane, realm domain, and password secret, would be:
MD5("jane:domain:secret") = 251910de04f5eab86859939167d4fded
Physical register names may not be empty, contain control characters, dots (.), or commas (,). They may also not consist entirely of digits.
Register names of locally calculated registers (registers with dev set to local) attach special meaning to the last character (suffix):
+: Allowed only for power-registers (type code P). Only positive power will be accumulated.
-: Allowed only for power-registers (type code P). Only negative measured power will be accumulated.
|: Allowed only for power-registers (type code P). The absolute value of the measured power will be accumulated.
*: Allowed only and required for apparent-power registers (type code S).
These suffixes are not allowed for registers whose value is calculated by an eScript expression.
If the name of a locally calculated power register does not end with one of the above suffixes, the measured net real power is accumulated. Net real power may be positive or negative, depending on the direction of the power flow.
A serial port may be specified either as a device name or as a USB path. A device name must have the format /dev/ttyUSBn, where n is a non-negative integer. A USB path must have the format USBpath where path is a sequence of one or more non-negative integers, separated by dots (.). Resource /sys/dev/serial returns a list of serial ports detected by the meter.
A serial port string may optionally also specify serial parameters. The parameters must follow the device name and have the format :b/8ps where b is the baud rate (positive integer), 8 is the number of bits per character (must be 8), p is the parity (n for none, e for even, o for odd), and s is the number of stop bits (1 or 2).
WebAPI provides an automatic mechanism to setup communication between a meter and a service provider (web server). The resulting communication path can be used, for example, to send register data ("push data") or alerts to the service provider.
The setup mechanism is called service activation and is initiated by posting a request to end-point /cmd/activate. The command, in turn, executes the follow steps:
Meter sends an activation request to a URL defined by the service provider. This URL is called the control URL.
The service provider may respond with an error, a challenge, or a service URL. If an error is returned, service activation has failed and an error response is returned. If a challenge is returned, execution resumes with step 3 below. If a service URL is returned, execution resumes with step 4.
Given a challenge response, the meter decrypts the challenge using a private key and sends the result to the service provider. The service provider checks if the result is valid and, if so, responds with a service URL. Otherwise, it responds with an error and service activation has failed.
The meter extracts the service URL from the service provider's response and starts sending data to that URL. With this, service activation has completed sucessfully.
Once activated, the meter will send data to the service URL as needed (e.g., periodically for push data or when an alert occurs for the alert service). This stops if a post to the service URL returns HTTP status code 418 (I'm a teapot) or if the meter gets reconfigured to deactivate the service.
The details of the above steps are described below.
The activation request the meter sends to the control URL is a POST request with a JSON-body containing the following members:
name (required): The hostname of the meter.
sn (required): The serial-number of the meter.
opts: If present, this is an array of strings specifying the service options that are understood by the meter for the service being activated. If not present, the service provider must assume that the meter does not understand any service options.
Additional members may be present in the posted object. If so, the service provider must ignore any members whose meaning it does not understand.
A typical activation request body is shown below (formatted for readability):
{ "name": "Test1234", "sn": "G13456789", "opts": ["gzip", "json", "secure"] }
A service provider may choose to return a challenge response to ascertain that the activation request was actually sent by the meter identified in the request. If the service provider does not require authentication, it can skip to directly returning a service URL response (see below).
A challenge response consists of a JSON-object with the following members:
nnc (required): The server nonce. This must be a string consisting entirely of lowercase hexadecimal digits (0-9, or a-f). The server creates this nonce by:
generating a sequence of cryptographically random bytes,
encrypting the sequence with the meter's public key, and, finally,
converting the encrypted sequence to a hexadecimal string.
rid (required): A non-negative integer that uniquely identifies this service activation request.
Additional members may be present in the returned object. If so, the meter will ignore any members whose meaning it does not understand.
Once the meter receives a challenge response, it:
rnd,creates a cryptographically strong random hexadecimal string which we'll call cnnc (client nonce),
calculates the MD5 hash of the string obtained by concatenating rnd, a colon (:), and cnnc.
sends a post request to the control URL whose body is a JSON object with the following members:
cnnc (required): The client nonce.
hash (required): The calculated MD5 hash as a hexadecimal string.
rid (required): A copy of the rid member as received in the challenge response.
When the service provider receives the post request, it can check whether the meter is authentic by calculating the MD5 sum of the concatenation of the server's random hexadecimal string rnd, a colon, and the client nonce and confirming that it matches the value of hash in the posted JSON object. If there is a mismatch, service activation has failed and the provider returns an error response.
A typical challenge response is shown below (formatted for readability and nnc shortened with an ellipsis):
{ "nnc": "76e75...9fbc", "rid": 4102166033 }
In return to this challenge, the meter would then send a post request to the control URL with a body that might look like this:
{ "cnnc": "565ce9541eddec103347b5174704e188", "hash": "ce5e308c27da651964de14f65bd8b059", "rid": 4102166033 }
If the authentication is successful, the service provider responds with a service URL response.
Upon successful service activation, the provider returns a response body containing a JSON object with the following members:
url (required): The service URL to which the service's data should be sent.
options: The service options to use. This must be a string containing a comma-separated list of option names. Certain options may require a value. For those, the option name must be followed immediately by an equal sign (=) and the option value (no whitespace is allowed).
pw: If specified, the password to use when sending the post request to the service URL.
user: If specified, the username to use when sending the post request to the service URL. The username and password are sent using an HTTP basic authentication header. For security reasons, this should only be used over secure (https) connections.
Additional members may be present in the returned object. If so, the meter will ignore any members whose meaning it does not understand.
{ "url": "https://provider.com/alert/post/a08b44098", "options": "json,gzip,min_prio=7" }
If service activation fails, HTTP status 200 must be returned with a response body which contains member error. The value of error must be a string explaining why service activation failed. The string is typically in the locale of the service provider.
The returned JSON object may contain additional members which the meter must ignore.
A time expression defines a single point in time. An absolute time expression is a number, a time-point name, or a function call. A number is interpreted as a Unix timestamp. Time-point names are described here. A function call consists of a name, immediately followed by a time expression in parentheses. The following supported function names and their meaning are as follows:
soy(t): Returns the timestamp of the start of the year in which t falls.
soq(t): Returns the timestamp of the start of the quarter in which t falls.
sob(t): Returns the timestamp of the start of the billing cycle in which t falls. Server-storage variable global.billing.start_day establishes the day of the month a new billing period starts. If that day is greater than the number of days in the current month, the last day of that month is taken as the start of the billing period. The new billing cycle is assumed to start at 12pm on the billing day (meter-local time).
som(t): Returns the timestamp of the start of the month in which time t falls.
sow(t): Returns the timestamp of the start of the week in which t falls. Monday is considered to be the start of the week.
sod(t): Returns the timestamp of the start of the day in which t falls.
soh(t): Returns the timestamp of the start of the hour in which t falls.
soQ(t): Returns the timestamp of the start of the quarter hour in which t falls.
soM(t): Returns the timestamp of the start of the minute in which t falls.
sos(t): Returns the timestamp of the start of the second in which t falls.
An absolute time expression may be followed by one or more offsets that are added to or subtracted from the value of the absolute time expression. Each offset starts with a plus or minus sign, an integer number, and an optional unit. Without a unit, the specified number may contain a fractional part and indicates the number of seconds to be added/subtracted. Otherwise, the unit may be one of:
y: yearsq: quartersb: billing-cyclesm: monthsw: weeksd: daysh: hoursQ: quarter-hoursM: minutesFor an offset with a unit, the specified number of time periods are added to/subtracted from the timestamp. For example, som(now)+1d-1h would return the start of the last hour of the first day of the current month as som(now) returns the start of the current month, +1d would add one day to that, and -1h would subtract 1 hour from the result.
Due to irregularities in the Gregorian calendar, normal rules of addition do not apply and the order in which the offsets are applied is significant. When adding/subtracting months or billing-cycles, the operations ensures that the final date is valid. For example, adding 1m to January 31st would yield the last day of February, which would be either February 28th or 29th, depending on whether or not the year is a leap-year.
The full syntax for a time expression is given in EBNF syntax below:
TIME = ABSOLUTE {("+" | "-")OFFSET} .
ABSOLUTE = UNIX_TS | POINT_NAME | FCALL .
UNIX_TS = ["+"|"-"] SECONDS .
FCALL = FNAME "(" TIME ")" .
FNAME = "soy" | "soq" | "sob" | "som" | "sow" | "sod" | "soh" | "soQ" | "soM" .
POINT_NAME = "now" | "epoch" | FNAME .
OFFSET = (UNSIGNED_INTEGER UNIT) | SECONDS.
UNIT = "y" | "q" | "b" | "m" | "w" | "d" | "h" | "Q" | "M".
SECONDS = UNSIGNED_INTEGER ["." UNSIGNED_INTEGER] .
A time point name that consists of a function name which is not immediately followed by a left parenthesis is interpreted as if the function of the same name had been called on the current time (now). For example, sod is equivalent to sod(now).
Time-point names provide a way to refer to both absolute points in time as well as times relative to the current time. Specifically:
now: The most recent time for which the meter has collected data.
epoch: The time at which the meter started recording data. That is, the oldest time for which the database will return data. This time is user configurable via /config/db/epoch.
soy: Short for soy(now).
soq: Short for soq(now).
sob: Short for sob(now).
som: Short for som(now).
sow: Short for sow(now).
sod: Short for sod(now).
soh: Short for soh(now).
soQ: Short for soQ(now).
soM: Short for soM(now).
A time range is an ordered series of Unix timestamps which are spaced out at a certain interval between two points in time. Time ranges are written as three decimal numbers, separated by colons: start:step:stop, where start is the oldest timestamp, step is the interval between timestamps, and stop is the youngest timestamp. For example, 100:1:103 would correspond to the timestamp series [100, 101, 102, 103]. If step and the subsequent colon are left out, the interval defaults to one second. If step is an empty string, the range consists of only the start and end timestamps. For example, 100::103 would correspond to [100, 103]. If the timerange consists of only a single number, it is interpreted as a singleton consisting of only the specified time.
The timestamps are generated from youngest to oldest. Thus, if the oldest timestamp is not an integer-multiple of step apart from youngest, then the oldest timestamp will not be in the series of generated timestamps.
In general, start and stop can be not just Unix timestamps but arbitrary time expressions.
Similarly, the time step may also be expressed as an integer count followed by a unit character. The available units are the same as for offsets in time expressions. For example, 1d would step through the time range one day at a time, taking daylight savings into account (assuming the correct timezone is set on the meter).
As a complete example, the time range som:1d:sod would generate the timestamps that correspond to midnight each day of the current month to date. sod is the start (midnight) of today and from there, the timestamps step back one day at a time until som, the start of the month is reached.
When a time range is used to select rows from the database, the resulting timestamps may not align with the timestamps of the rows stored in the database. When this happens, the meter will, by default, round down the specified timestamp to that of the nearest older row. However, if the starting or ending timestamp starts with a plus sign (+), the meter will instead round the timestamp up to that of the nearest younger row.
The full syntax for a time range is given in EBNF syntax below:
TIME_RANGE = [FROM ":" [[STEP] ":"]]TO .
FROM = TIME_WITH_ROUNDING .
TO = TIME_WITH_ROUNDING .
STEP = OFFSET .
TIME_WITH_ROUNDING = ["+"]TIME .
See section Time Expressions for definitions of OFFSET and TIME.
Each register records values in a physical unit indicated by a type code. Apart from the physical unit, the type code also defines the quantum with which a value is recorded in the database.
To understand the role of the quantum, you need to know that the database stores all values as signed 64-bit integer numbers. For all type codes except d (discrete numbers), the meter accumulates values before storing them in the database. Let us see how this is done for a sensor that measures a voltage. If we look up type code V in the table below, we see that the quantum q for a voltage is 0.001. Now, suppose the voltage v of a sensor was measured to be 120V on average over a measurement interval dt of one second and that the previous accumulated value of that sensor was c0. The meter would then calculate the new accumulated value c1 as:
c1 = c0 + round(v / quantum)·dt
or
c1 = c0 + round(120V / 0.001)·1s = c0 + 120000 V·s
This new accumulated value is then stored in the database. In other words, for every second where the average voltage is 120V, the value stored in the database would increase by 120000. This also shows that the accumulated values stored in the database have a unit that is the rate unit multiplied by seconds. For volts, that turns into volt-seconds. Similarly, power in watts would be recorded as watt-seconds (or joules), and speed in meters-per-second would be recorded as meters.
Note that an accumulated value may eventually overflow if the measured rate has predominantly the same sign for a very long period of time. If that were to happen, the value would wrap around from a large positive value to a large negative value or vice versa. The quanta have been selected such that under normal circumstances, wrap-arounds will not occur within the lifetime of a meter. Nevertheless, when calculating how much an accumulated value changed between two points in time, we recommend calculating that difference modulo 263 since that will give the correct result provided at most one wrap-around occurred between the two points in time.
Discrete numbers (type code d) are unit-less and are used to record discrete states (such as error states or bitsets). Such quantities cannot be averaged and hence they are not accumulated. Instead, they are stored directly as signed 64-bit integers in the database.
| Type code | Physical quantity | Rate unit | Quantum |
|---|---|---|---|
# | Whole number | 1 | |
#3 | Number with 3 decimal places | 0.001 | |
% | Percentage | % | 0.001 |
$ | Monetary accrual rate | ${currency}/s | 2-29 |
a | Angle | ° | 0.001 |
aq | Air quality index (0=good, 500=bad) | s | 0.001 |
d | Discrete number | 1 | |
Ee | Irradiance | W/m2 | 1 |
F | Frequency | Hz | 0.001 |
h | Relative humidity | % | 0.001 |
I | Electrical current | A | 0.001 |
m | Mass | g | 0.001 |
P | Power | W | 1 |
Pa | Pressure | Pa | 1 |
ppm | Parts per million | ppm | 0.001 |
var | Reactive power | var | 1 |
Q | Mass flow | g/s | 1 |
Qe | Electric charge | Ah | 0.001 |
Qv | Volumetric flow | m3/s | 10-9 |
R | Electric resistance | Ω | 1 |
S | Apparent power | VA | 1 |
T | Temperature | °C | 0.001 |
THD | Total harmonic distortion | % | 0.001 |
V | Voltage | V | 0.001 |
v | Speed | m/s | 0.001 |
Note For the monetary unit, ${currency} should be replaced by the the currency symbol applicable to the region the meter is installed in. The builtin user interface of the meter uses the value of server-storage variable global.default.currency_symbol for this purpose or, if undefined, a dollar sign ($).
A Unix timestamp is a number that counts the seconds since the start of January 1, 1970 UTC.
Users may have the one or more of the following privileges:
unlimited_save: The user may change (save) the meter configuration.
local_save: The user may change (save) the meter configuration but only when connected over a local network connection. LAN-connections are considered local if the user's browser is on the same subnet as the meter. Bluetooth connections are always considered local. All other connections (e.g., via proxy server) are considered not local.
view_settings: The user may view the meter configuration. Without this privilege, the user only has access to configuration settings that are directly related to the user.
ctrl: The user may issue control operations such as putting a device in a particular operational state (e.g., opening or closing a relay or setting the temperature on a thermostat).
restricted_view: The user only has restricted access to the meter data. Specifically, the user may only view registers in the view that matches the user name.
While access to the device is generally governed by these privileges, there are two exceptions:
Users without view_settings privilege may still read their own user configuration (but not that of any other user).
Users without save privilege (unlimited_save or local_save) may still change their own password.
Views are used to group related registers. For example, if a single meter measures multiple apartments, a separate view could be defined for each apartment. A user-interface can then offer to display all measurements for a particular apartment by selecting the desired apartment's view name. Similarly, users can be setup so that they may access only a particular view. That way, views can be used to ensure, for example, that each apartment tenant can only view their own data.
In this API, view names are defined as part of a register name. Specifically, the view name is written as prefix of the register name, followed by a dot. For example, the string apt1.cooktop defines register cooktop as being part of view apt1.
The values of virtual registers are calculated based on the values of physical registers. The formulas for these calculations are limited to addition and subtraction. When expressed as a JSON string, virtual register formulas are written as a sequence of register names which are prefixed either by a plus sign (+) to indicate addition or by a minus sign (-) to indicate subtraction. The register names are enclosed in double-quotes. Within a register name, a double-quote character can be included by prefixing it with a backslash character: \". Likewise, to include a literal backslash character in the name, it must be doubled up and written as \\.
As an example, the formula:
+"Panel \"A\""+"Solar+"-"EV"
would calculate the virtual register value by adding the values of registers Panel "A" and Solar+ and then subtracting the value of register EV.
Note
Old meters may still use deprecated operators in virtual register formulas. The syntax for these operators is op(reg,n) where op is either MIN or MAX (case-sensitive), reg is a register name, and n is an integer constant (usually 0). These operators are deprecated because they only work correctly when the formula is applied to rates, not when applied to accumulated register values. When applied to rates, these operators should work as follows:
MAX(reg,n): Returns the value of register reg if it is greater than n or n otherwise.
MIN(reg,n): Returns the value of register reg if it is less than n or n otherwise.