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).
The endpoints generally support HTTP methods GET, PUT, POST, and DELETE, though some of the endpoints may have restrictions. For example, security-sensitive values such as certificates or passwords are usually write-only.
GET returns the current value of the endpoint and has no side-effect.
The exact semantics of the other methods depend on the JSON type of the value that the endpoint represents:
PUT replaces the value of the object with the one in the request body. POST updates the object based on the members in the request body. That is, the POST may add new members or updates the values of existing members. DELETE removes the object where that makes sense and otherwise resets the object to its default value.
PUT replaces the value of the array with the array contained in the request body. POST appends the array in the request body to the existing array. DELETE removes the array where that makes sense and otherwise resets it to its default value (usually the empty array).
PUT and POST replace the value. DELETE removes the value if that is possible and otherwise resets it to the default value.
GET responses are guaranteed to return a consistent view of the meter configuration. That is, if there are simultaneous modification requests, it is guaranteed that the modifications take place either before or after the GET response is created, not partway through it.
Modification requests (POST, PUT, and DELETE) are executed transactionally, meaning either all of a modification is applied or none of it. Multiple modifications are applied in a sequentially consistent fashion. That is, there must exist a sequential order in which the modifications can be applied that yields the final result.
HTTP headers ETag and If-Match can be used to ensure a modification request is applied only if the configuration has not been changed since the GET request that returned the ETag.
curl -i -X GET \ 'https://webapi.egauge.net/_mock/webapi/4.6/openapi/config?filter=string&max-depth=1' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
{ "result": { "bacnet": { … }, "db": { … }, "display": { … }, "language_code": "en_GB", "local": { … }, "location": { … }, "log": { … }, "lua": { … }, "modbus": { … }, "net": { … }, "push": { … }, "remote": { … }, "register": { … }, "time": { … }, "user": { … }, "var": { … }, "alert": { … } }, "error": "Error message (present if an error occurred)." }
A PUT request is equivalent to a DELETE followed by a POST with the same request body. Because of that, care must be taken to ensure the desired configuration is written. Specifically:
The classic interface uses CGI-BIN programs. It is therefore recommended to include member "net":{"http":{"cgi-bin":"user-required"}} in the request body as otherwise CGI-BIN support is disabled.
Member alert may contain references to register names (as part of custom alert conditions). This member should therefore appear after member register.
Member remote must appear in the request body before member register as otherwise the remote registers in this member will be deleted when member remote is processed.
The BACnet configuration.
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.
Modbus-related configurations.
The network configuration.
The current state of the network is available at /sys/net.
The push service configuration. This service is used to share the meter data with a remote web server. The data is sent via an HTTP POST request.
curl -i -X PUT \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/config \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "bacnet": { "server": { "bip": { "port": 47808 }, "enable": [ "ethernet" ], "epoch-relative": true, "id": 4194303, "mstp": 1 } }, "db": { "epoch": "1675276020" }, "display": { "backlight": { "brightness": 255, "duration": 60 }, "contrast": 65, "fontset": "normal", "screen": { "use": "ic", "gen": "ic", "Grid": "ic", "Solar": "ic", "temp": "i", ".default": "" }, "orientation": 90 }, "language_code": "en_GB", "local": { "sensor": { "L1": { "channel": { "bias": 0, "mode": "normal", "scale": -74.013999939 }, "error": 0, "model": "1:1", "phase": "" }, "S1": { "channel": { "bias": 0, "mode": "normal", "scale": -206.659896851 }, "error": 0, "model": "ML-SCT-019-0100", "phase": "2.96@1.5:2.59@3:2.34@6:2.06@15:1.82@50:1.89@100" }, "S2": { "channel": { "bias": 0, "mode": "normal", "scale": -206.659896851 }, "error": 0, "model": "ML-SCT-019-0100", "phase": "2.96@1.5:2.59@3:2.34@6:2.06@15:1.82@50:1.89@100" } }, "gain": "normal", "update-interval": 500 }, "location": { "latitude": 36.035, "longitude": -115.46639 }, "log": { "system": { "size": 131072 } }, "lua": { "script": { "alertd": "print(\"this is the alert script\");", "tariff": "print(\"this is the tariff script\");", "teamd": "print(\"this is the formulas script\");" }, "ctrld": { "test": "print(\"this is control script test\");" } }, "modbus": { "client": { "map": { "user_dev": { "option": { "default-modbus-addr": "2", "default-serial-params": "9600/8n1" }, "reg": [ { "name": "irradiance", "addr": 0, "type": "u32", "kind": "analog", "unit": "W", "offset": 0, "scale": 0.1, "access": "ro" }, { "name": "temp", "addr": 1, "type": "s32", "kind": "analog", "unit": "degC", "offset": 0, "scale": 0.01, "access": "ro" } ] } } }, "server": { "enable": [ "rtu" ], "id": 1, "rtu": { "port": "USB2:9600/8o2" }, "tcp": { "port": 502 } } }, "net": { "ethernet": { "watchdog": true }, "goproxy": { "enable": true, "server": "proxy.egauge.io" }, "homeplug": { "region": "CE" }, "hostname": "eGauge42", "http": { "cgi-bin": "user-required", "client": { "insecure": "false" } }, "ipv4": { "dhcp": true, "address": "192.168.1.42", "broadcast": "192.168.1.255", "netmask": "255.255.255.0", "network": "192.168.1.0", "gateway": "192.168.1.1" }, "nameserver": { "server": [ "1.1.1.1", "8.8.8.8", "2606:4700:4700::1111" ] }, "ntp": { "server": [ "192.168.1.1", "north-america.pool.ntp.org", "2610:20:6f15:15::27" ] }, "option": { "secure_only": false }, "proxy": { "enable": true, "server": "d.egauge.net" }, "ptp": { "client_only": true, "interface": { "eth0": { "transport": "UDPv4", "udp_ttl": 1 } } } }, "push": { "interval": 60, "options": "json,gzip,epoch,sec,skip=59", "service": "", "uri": "https://push-service.com/data", "user": "jsmith" }, "remote": { "PRM3": { "address": "modbus://sunspec.1@USB2", "link_type": "slowd" }, "panel2": { "address": "panel2.local", "link_type": "udp" } }, "register": { "physical": { "grid": { "dev": "local", "did": 0, "type": "P", "value": "S16*L1+S17*L2" }, "grid*": { "dev": "local", "did": 8, "type": "S", "value": "grid" }, "solar": { "dev": "local", "did": 1, "type": "P", "value": "S3*L1+-S3*L2" }, "temp": { "dev": "SMANet", "did": 12, "type": "T", "value": "13590.TmpAmb_C" } }, "virtual": { "use": { "value": [ { "op": "+", "register": "grid" }, { "op": "+", "register": "solar" } ] }, "gen": { "value": [ { "op": "+", "register": "solar" } ] } } }, "time": { "zone": "LST7LDT6,M3.2.0/02:00,M11.1.0/02:00" }, "user": { "jsmith": { "priv": [ "unlimited_save", "view_settings" ] }, "guest": { "priv": [ "view_settings" ] } }, "var": { "global": { "billing.start_day": "6", "billing.interval": "15" }, "health": { "last_check": "1682200804" } }, "alert": { "custom": [ { "name": "temperature alert", "detail": "It is hot in here: %l C!", "frequency": "sec", "priority": 7, "cond": { "lhs": "temp_internal()", "op": "<", "rhs": "30" } } ], "reporter": { "web": { "min-priority": 7, "service": "", "uri": "https://alerts.com/report", "options": "gzip,secure", "user": "jsmith", "password": "secret!" }, "mail": { "server": "smtp.mail.com", "user": "egaugealert@mail.com", "password": "string", "from-address": "eGauge1345", "to": [ { "format": "string", "min-priority": 3, "address": "user@site.com" } ] } }, "sys-prio": [ 0, 0, 7, 0, 7, 4, 0, 0, 1, 6, 0, 0, 0, 5, 0, 0, 0, 0, 0, 0 ] } }'
{ "status": "OK", "error": "Error message (present if an error occurred)." }
The BACnet configuration.
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.
Modbus-related configurations.
The network configuration.
The current state of the network is available at /sys/net.
The push service configuration. This service is used to share the meter data with a remote web server. The data is sent via an HTTP POST request.