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:

Field	Description
`id`	Unique BSON ID. Assigned by Edge when the command is created.
`name`	A friendly name for the command.
`device_id`	The 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_type`	The type of sender to be used to send the command (e.g., tcp, http, rest forwarder, bacnet, opcua. modbus, plugin).
`sender`	The actual sender configuration (e.g., host, port, etc.).
`translator_id`	The BSON ID of the translator used to translate from
`long_description`	Formatted text (markdown). This can be used to provide instructions to users for executing the command (e.g., which additional parameters must be supplied).
`options`	A JSON object. Intended to contain metadata useful to process or send the command.
`payload`	A JSON object. This is the data structure containing all data to be translated (if applicable) and sent to the device.
`save_command_output`	Boolean 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.

Field	Description	Example
`host`	The hostname or IP address of the recipient device	`192.168.10.5`
`port`	The socket listening port of the recipient device	9876
`timeout`	Timeout (in seconds) before returning with an error	5

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.

Field	Description	Example
`url`	The full uri/url of the endpoint	`https://www.example.com:9999/an/endpoint`
`method`	The HTTP method (only `POST` or `PUT` are supported)	`POST`
`headers`	HTTP request headers	`{ "Content-Type": "application/json", "Accept": "application/json" }`
`timeout`	Optional. Timeout (in seconds) before returning with an error. Default value is 30 sec.	5
`unix-socket`	Optional. 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:

Dev guide: Commands developer guide
Example: REST Command Forwarder example

Modbus Sender

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

Field	Description	Example
`host`	The hostname or IP address of the recipient device	`192.168.10.5`
`port`	The socket listening port of the recipient device (modbus default is 502)	502
`slave_id`	The modbus slave device ID (1-247)	42
`timeout`	Timeout (in seconds) before returning with an error	5

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:

Field	Description	Example
`request_type`	TODO	TODO
`address`	TODO	TODO
`quantity`	TODO	TODO
`values`	TODO	TODO
`value`	TODO	TODO
`and_mask`	TODO	TODO
`or_mask`	TODO	TODO

BACnet Sender

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

Field	Description	Example
`host`	The hostname or IP address of the recipient device	`192.168.10.5`
`port`	The socket listening port of the recipient device (modbus default is 502)	502
`timeout`	Timeout (in seconds) before returning with an error	5

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:

Field	Description	Example
`request_type`	TODO	TODO
`object_type`	TODO	TODO
`object_instance`	TODO	TODO
`property_id`	TODO	TODO
`value`	TODO	TODO

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.

Field	Description	Example
`host`	The hostname or IP address of the recipient device	`192.168.10.5`
`port`	The socket listening port of the recipient device (modbus default is 502)	502
`timeout`	Timeout (in seconds) before returning with an error	5

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:

Field	Description	Example
`request_type`	TODO	TODO
`node_id`	TODO	TODO
`value`	TODO	TODO

Shell Sender

The Shell Sender executes a command on the target device.

The sender object can contain the following fields:

Field	Description	Example
`command`	The command to be executed.	`echo $PAYLOAD > /etc/deviceconfig`
`environment`	Environment 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" }`
`timeout`	Timeout (in seconds) before returning with an error	5

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.