Whereas messages being pushed to Edge from attached devices are called "reports", messages pushed from Edge to attached devices are called "commands". These messages are meant to affect some change to the attached device configuration, status, or behavior.

Commands make up the instructions that are sent to a device to take action. Example commands may be to turn on a fan, put a device into service mode, or instruct a device to send a report. Disparate devices accept disparate commands. That said, there is often a set of commands that may result in the same action being performed by different types of devices. The only difference is the low level structure of the message the device takes as a command.

For example, a tracking device can be created by both Manufacturer A and Manufacturer B. Both devices support a command to report the device’s current location but Manufacturer A’s device accepts base64 encoded binary over SMS while Manufacturer B’s device only accepts XML over HTTP. In both cases, the commands have a JSON representation within Edge, which is then translated to the low level device protocol for delivery to the device.

Thus, Edge provides human readable command definitions that can apply to a number of disparate devices.

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.

Saved Commands

In order to use a command in Edge, the command must be created and persisted within Edge. See the Commands API for more details. No fields are required to create a command, but an empty command will be assigned an id. This may seem surprising, but Edge commands work by merging fields provided at the time of command execution into the structure of the saved command, then executing the command from the merged result. It's therefore up to the developer to determine which fields to pre-populate and save when the command is created, and which to specify when the command is later executed.

Merged Command fields

When a command is executed, additional data fields can be passed to the commands endpoint. This must include the command id, but all other fields are optional. Whatever additional fields are provided will be merged into the saved command. Note that fields merged in this way at execution time will override field values (if they exist) in the saved command.

Fields can be merged into command at any level of nesting. The fields to be merged can be provided within a JSON POST body, as query params within a GET, or as form params within a POST.

See this example of creating and executing a simple command.

External Command processing

Commands can also be processed outside of Edge. For example, a device protocol might have already been implemented in another programming language, and processing the command outside of Edge allows a customer to reuse this code. There are two ways to process commands externally:

Via a REST Command forwarder
Via a plugin

REST Command forwarder

There may be cases where the easiest path to a working solution is to process and send commands via some process external to Edge. For example, if a complex binary message protocol has been implemented and tested in python, it could be easier to use that than to add translators in Edge to implement some or all of the protocol. For a use case such as this, Edge supports forwarding commands to a REST endpoint.

There are some key differences between a "normal" command (as described above) and a REST Command forwarder.

Translation -- executing a normal command invokes a translator to translate the command to the protocol expected by the device. The endpoint invoked by a REST Command forwarder is responsible for doing its own translation.
Delivery -- executing a normal command delivers the command to the device. The endpoint invoked by a REST Command forwarder is responsible for delivering the command directly to the device.

See this example of creating and using a REST Command forwarder.

Wrap up

Creating and configuring commands is an advanced feature of Edge that is not currently supported in the EdgeIQ portal. However, a command dry run endpoint (also see
command dry run example is available with the ability to test command execution against existing or simulated devices.