Powered by Redocly

/cmd

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

Activate a service

Activate a service with an external provider (web server).

This request returns a token which can then be used to monitor the status of the operation. See /sys/status/token/result for details.

SecurityApiKey
Request
Request Body schema: application/json
service
required
string

The type of service to activate. This can be alert for the alert reporting service or push for the data-sharing service.

Enum: "alert" "push"
provider
required
string

The name of the service provider with which to activate the service.

Responses
200

Activation response.

401

Unauthorized response.

post/cmd/activate
Request samples
application/json
{
  • "service": "alert",
  • "provider": "Cloudly's Alert Service"
}
Response samples
application/json
{
  • "token": "473c31462e62848b5352314dfc608669",
  • "error": "Error message (present if an error occurred)."
}

Cancel pending operation

Cancel the long-running operation identified by its token.

SecurityApiKey
Request
Request Body schema: application/json
token
string >= 32 characters

The token of the operation to be cancelled. This token is the hexadecimal string (typically 32 characters long) that was returned when the operation was initiated.

Responses
200

Cancel response.

401

Unauthorized response.

post/cmd/cancel
Request samples
application/json
{ }
Response samples
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}

Clear data

Clear data. The string in the request body identifies what data to clear:

  • excess: For register values that are read from a remote device, it is possible that the meter may not be able to reach the remote device at times (e.g., due to a networking problem). If the remote device provides cumulative values, this means that when the remote device becomes accessible again, the cumulative value may have increased significantly, which could then cause a spike in the graphed values for that register. To prevent such spikes, the meter will instead record the jump as an excess and then replay that excess gradually over time so that the meter can catch up to the true value without causing a spike. Executing this command clears to zero the excess of all registers. This will typically cause a spike in the graphed values for any remote registers which had a non-zero excess but, on the positive side, will then ensure that the cumulative values afterwards match those of the remote device(s).

    Note If excess keeps accumulating, it may be better to use the spiky option for remote registers.

  • web_cache: Clears the web server cache of compressed files. Under normal circumstances, it is not necessary to clear this cache explicitly. However, this command can be used in case the cache gets corrupted, e.g., due to a power cycle while the meter is in the middle of writing a cache file.

SecurityApiKey
Request
Request Body schema: application/json
string
Enum: "excess" "web_cache"
Responses
200

Clear response.

401

Unauthorized response.

post/cmd/clear
Request samples
application/json
"excess"
Response samples
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}

Manipulate database

This command supports restoring the database from a backup file, zeroing of all or parts of the database, as well as splitting the positive values of certain registers into separate positive-only registers.

SecurityApiKey
Request
Request Body schema: application/json
action
required
string

The action to perform. The possible values are:

  • restore: Restores data from a backup file to the device database.
  • zero: Zeroes out one or more registers in the device database.
  • split: Split the positive changes of a net register into a separate positive-only register.
Enum: "restore" "zero" "split"
from
string (ForeverStamp)

If specified, this limits the operation to data that is not older than the timestamp specified here.

to
string (ForeverStamp)

If specified, this limits the operation to data that is not younger than the timestamp specified here.

regs
Array of integers

If specified, the operation is limited to the registers whose database ids appear in this list.

data
string

This member is required for action restore. It contains the binary backup data to be restored, encoded in base64. A device may reject a restore request if this member is larger than 2 MiB. It may therefore be necessary to split up a large backup file into multiple smaller chunks that are then restored one after the other.

more_chunks
boolean

This is used only for restore operations. It indicates whether a the backup data has been split up into multiple chunks and the current chunk is to be follow by the next older, adjacent chunk. Setting this flag is not required, but doing so can greatly speed up a restore operation. On the other hand, setting this flag to true without following it up with the next older adjacent chunk can leave the database in a corrupted state, with large spikes at the beginning of the current chunk.

Responses
200

DB response.

401

Unauthorized response.

post/cmd/db
Request samples
application/json
{
  • "action": "restore"
}
Response samples
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}

Restore factory settings

Restore the factory settings and reboot the meter.

Warning All existing data and settings will be lost.

SecurityApiKey
Responses
200

Restore factory settings response.

401

Unauthorized response.

post/cmd/factory-restore
Request samples 
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Manage HomePlug
Manage one or more HomePlug devices.


SecurityApiKey 
Request 
Request Body schema: application/json
action
required
string
The action to perform.  The only action currently
supported is setpwd.  It establishes a new encryption
password on the meter's HomePlug bridge and one or more
remote bridges.


 Value: "setpwd"  
password
required
string  [ 4 .. 24 ] characters 
The password to use for encrypting the HomePlug
traffic.  The password may consist of any characters
except for double-quote or control characters.


 
targets
required
Array of strings  non-empty 
The list of bridges on which to set the new
password.  Each bridge is identified by a string
that specifies its MAC address (in the form
xx:xx:xx:xx:xx:xx where x is a hexadecimal
digit), followed by a slash character (/),
followed by the bridge's device encryption key
(DEK).  The latter can be found printed on the label
of the bridge.


 
Responses 
200
Manage HomePlug response.


401
Unauthorized response.


post/cmd/homeplug
Request samples 
application/json
{
  • "action": "setpwd",
  • "password": "HomePlugAV",
  • "targets": [
    ]
}
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Reboot the meter
Initiate a reboot of the meter. The actual reboot command is
delayed by one second to increase the likelihood that the reply
to this request can be received by the client before the meter
shuts down.


Once initiated, the meter will be unavailable for a while
(typically, 20 to 60 seconds). If the network configuration of
the meter was changed, the reboot may cause the meter to not
become available again at the old network address. Thus, the
client should check for such changes before initiating the
reboot and take appropriate action if the network configuration
did change.


SecurityApiKey 
Responses 
200
Set time response.


401
Unauthorized response.


post/cmd/reboot
Request samples 
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Set date and time
Optionally set the date/time of the meter and restart the NTP
and/or the PTP services, if configured.


SecurityApiKey 
Request 
Request Body schema: application/json
One of:
A Unix timestamp expressed as a
decimal string that may contain a fractional value for sub-second
resolution.  A string is used here since most JSON libraries store
numbers as IEEE-754 double-precision numbers and the 54-bit
mantissa of that format may not be sufficient to accurately
represent the timestamp.


string (ForeverStamp) 
 
Responses 
200
Set time response.


401
Unauthorized response.


post/cmd/set-time
Request samples 
application/json
"1677523091.000900435"
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Test sending email
Test sending an email using the mail configuration specified
in the body of this request.


This request returns a token which can then be used to monitor
the status of the operation.  See
/sys/status/token/result
for details.


SecurityApiKey 
Request 
Request Body schema: application/json
address
required
string
The email address to send the test email to.


 
smarthost
string
The hostname of the smart host (mail relay) through
which to send the email.  If this is left
unspecified, the meter will attempt to send the
email directly to the destination address.


 
mailuser
string
If a smarthost is defined, this specifies the user
name which is used to log into the smart host.  If
left unspecified, the meter will attempt to send the
email without authentication.


 
mailpass
string
If a smarthost is defined, this specifies the password
which is used to log into the smart host.  If
left unspecified, the meter will attempt to send the
email without authentication.


 
fromaddr
string
The email address to use as the sender of the email
("From:" address).


 
Responses 
200
Test email response.


401
Unauthorized response.


post/cmd/test-email
Request samples 
application/json
{
  • "address": "user@domain.com"
}
Response samples 
application/json
{
  • "token": "473c31462e62848b5352314dfc608669",
  • "error": "Error message (present if an error occurred)."
}
Test remote device
Try connecting to a remote device and, if successful, return
the set of registers available on the device.


This request returns a token which can then be used to monitor
the status of the operation.  See
/sys/status/token/result
for details.


SecurityApiKey 
Request 
Request Body schema: application/json
address
required
string
The address of the remote device.  The format of
this string depends on the value of linktype.


 
linktype
required
string
The link type to use to
connect to the remote device.


 
Responses 
200
Test remote device response.


401
Unauthorized response.


post/cmd/test-remote
Request samples 
application/json
{
  • "address": "modbus://sunspec.1@USB2",
  • "linktype": "slowd"
}
Response samples 
application/json
{
  • "token": "473c31462e62848b5352314dfc608669",
  • "error": "Error message (present if an error occurred)."
}
Update the meter
Update the meter firmware or kernel.


SecurityApiKey 
Request 
Request Body schema: application/json
action
required
string
The action to perform. The value list requests
that the latest available version should be returned
as a version object response.


The value install requests that the kernel or
firmware should be updated.  In this case, a token
is returned.  With that, the progress of the
installation can be monitor at
/sys/status/token.


 Enum: "list" "install"  
target
required
string
The target of the action. A value of fw indicates
that the meter firmware is the target of the action,
a value of kernel indicates that the kernel is the
target.


 Enum: "fw" "kernel"  
branch
string
The release branch to install from or to list the
available version for. If left unspecified, this
defaults to the branch the currently running
firmware was installed from.  An empty string refers
to the default release branch.


 
force
boolean
If true, the firmware/kernel is installed even if
the version to be installed does not appear to be
newer than the currently installed version.


 
version
string
The version to install.


Note Downgrading to an older firmware or kernel
may have unpredictable effects and may damage the
meter.


 
Responses 
200
Update response.


401
Unauthorized response.


post/cmd/update
Request samples 
application/json
{
  • "action": "list",
  • "target": "fw"
}
Response samples 
application/json
{
  • "version": 4.4,
  • "minimum": "4.1.2",
  • "error": "Error message (present if an error occurred)."
}
Manage WLAN (WiFi) connection
Manage WLAN (Wi-Fi) connection.  See
/sys/net/wlan to get the currently
detected and configured WLAN networks.


SecurityApiKey 
Request 
Request Body schema: application/json
action
required
string
The action to perform.  It must be one of:


    

  • add: Add a WLAN network by specifying its SSID,
whether or not it is a hidden network, and,
optionally, its passphrase or passkey.  If adding
the network succeeds, it is also selected as the
currently active one.
    • 

  • select: Select a network as the currently active one.
    • 

  • forget: Forget the information associated with
a network.
    • 



 Enum: "add" "select" "forget"  
hex
boolean
Must be set to true if member key is a
hexadecimal key rather than a passphrase.


 
hidden
boolean
Must be set to true if the network to be added is
hidden (i.e., its SSID is not being broadcast).


 
id
integer  >= 0 
The id of the network that should be selected or
forgotten.


 
key
string
The passphrase or hex key to use for the network
being added. If omitted, the newly added network has
key management disabled.


 
ssid
string
The name (SSID) of the network to be added.  The
characters in this string may be any Unicode
 character except for ASCII newline or ASCII NUL.


 
Responses 
200
WLAN response.


401
Unauthorized response.


post/cmd/wlan
Request samples 
application/json
{
  • "action": "add"
}
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
➔ Next to /config