Commands

A command defines how we assemble and send outbound command data to a device. Commands are sent via HTTP POST as JSON, and are then translated (either within Edge or an external command processor) to the data structure supported by the recipient device, and finally sent to the device.

The structure of a JSON command consists of the following:

FieldDescription
idUnique BSON ID. Assigned by Edge when the command is created.
nameA friendly name for the command.
device_idThe BSON ID of the device to which the command will be sent. This can be populated at creation for a command that always goes to a specific device, or populated dynamically during command execution.
sender_typeThe type of sender to be used to send the command (e.g., tcp, http, rest forwarder, bacnet, opcua. modbus, plugin).
senderThe actual sender configuration (e.g., host, port, etc.).
translator_idThe BSON ID of the translator used to translate from
long_descriptionFormatted text (markdown). This can be used to provide instructions to users for executing the command (e.g., which additional parameters must be supplied).
optionsA JSON object. Intended to contain metadata useful to process or send the command.
payloadA JSON object. This is the data structure containing all data to be translated (if applicable) and sent to the device.
save_command_outputBoolean flag: Return and store the output of a command. Not applicable to all command sender types.

Sender

A sender type is specified for the command which determines how the command will be transmitted to the device. The supported sender types are documented in sub-headings below.

TCP Sender

A TCP sender ("sender_type": "tcp_sender") sends the command to the device over a TCP socket. Currently, the response (if any) from the device is ignored, but a communication error will be propagated back to the caller of the execute endpoint.

FieldDescriptionExample
hostThe hostname or IP address of the recipient device192.168.10.5
portThe socket listening port of the recipient device9876
timeoutTimeout (in seconds) before returning with an error5

Also see this example.

HTTP Sender

An HTTP sender ("sender_type": "http_sender") sends the command to the device via an HTTP (or HTTPS) request. Currently, the success response body (if any) from the device is ignored, but a response code greater than or equal to 400 will propagate an error back to the caller of the execute endpoint.

FieldDescriptionExample
urlThe full uri/url of the endpointhttps://www.example.com:9999/an/endpoint
methodThe HTTP method (only POST or PUT are supported)POST
headersHTTP request headers{ "Content-Type": "application/json", "Accept": "application/json" }
timeoutOptional. Timeout (in seconds) before returning with an error. Default value is 30 sec.5
unix-socketOptional. Path to the unix socket file which is used as transport of http client./run/snapd.socket

REST Forwarder Sender

A REST Forwarder Sender ("sender_type": "rest_fwd_sender") is similar to an HTTP sender, but whereas the HTTP Sender translates the command and sends the translated payload, the REST Forwarder simply forwards the merged command to the specified endpoint. This endpoint assumes responsibility for translating or formatting the command, then delivering to the recipient device. The fields specified are exactly the same as the HTTP Sender directly above.

See these additional resources for more details:

Modbus Sender

A Modbus Sender ("sender_type": "modbus_sender") writes a value to a Modbus object via a TCP socket.

FieldDescriptionExample
hostThe hostname or IP address of the recipient device192.168.10.5
portThe socket listening port of the recipient device (modbus default is 502)502
slave_idThe modbus slave device ID (1-247)42
timeoutTimeout (in seconds) before returning with an error5

When using a modbus sender, the modbus params struct must be provided as the options object of the Command. This object contains the following fields:

FieldDescriptionExample
request_typeTODOTODO
addressTODOTODO
quantityTODOTODO
valuesTODOTODO
valueTODOTODO
and_maskTODOTODO
or_maskTODOTODO

BACnet Sender

A BACnet Sender ("sender_type": "bacnet_sender") writes a value to a BACnet object via a TCP socket.

FieldDescriptionExample
hostThe hostname or IP address of the recipient device192.168.10.5
portThe socket listening port of the recipient device (modbus default is 502)502
timeoutTimeout (in seconds) before returning with an error5

When using a BACnet sender, the BACnet params struct must be provided as the options object of the Command. This object contains the following fields:

FieldDescriptionExample
request_typeTODOTODO
object_typeTODOTODO
object_instanceTODOTODO
property_idTODOTODO
valueTODOTODO

OPC-UA Sender

An OPC-UA (OPC Unified Architecture) Sender ("sender_type": "opcua_sender") writes a value to an
OPCUA address via a TCP socket.

FieldDescriptionExample
hostThe hostname or IP address of the recipient device192.168.10.5
portThe socket listening port of the recipient device (modbus default is 502)502
timeoutTimeout (in seconds) before returning with an error5

When using a OPC-UA sender, the OPC-UA params struct must be provided as the options object of the Command. This object contains the following fields:

FieldDescriptionExample
request_typeTODOTODO
node_idTODOTODO
valueTODOTODO

Shell Sender

The Shell Sender executes a command on the target device.

The sender object can contain the following fields:

FieldDescriptionExample
commandThe command to be executed.echo $PAYLOAD > /etc/deviceconfig
environmentEnvironment variables as key-value pairs. Any value set in the payload field of the command will be available as the PAYLOAD environment variable (unless it has been explicitly set here).{ "version": "2.0", "location": "Boston" }
timeoutTimeout (in seconds) before returning with an error5

If save_command_output is enabled on the command, the result of the shell command will be uploaded and stored as part of the command execution status.