Skip to main content

Command Definition

Support
  • Updated

Commands can be used to execute on the remote product a task, operation, or routine.

For instance, here are some commands:

  • Cleanup: trigger the cleanup procedure on the product.
  • Power ON/OFF: turn ON/OFF the remote product.
  • Start/Stop: start/stop the execution of a recipe.

A command is very similar to a parameter, the difference is the way it is triggered from the UI, a button is used instead of an input field. Moreover, a command payload can include multiple parameters whose value can be static or dynamic depending on a condition or retrieved from a property or metric.

Remote products must subscribe to a specific topic in order to receive command execution requests. Command messages are issued to a specific path according to the IoT Connector, product/command mapping. 

For instance, by using the Servitly Thing Connector (STC), this is an MQTT sample message:

// TOPIC
<username>/<asset-id>(/<thing-path>)?/<command-path>

// PAYLOAD
{
  "data":{
    "foo": "xyz", 
    "bar": 123.456, 
    "baz": true
  }
}

For more details, refer to the Let your product receive parameters through MQTT article.

Creating a Command

To add a new Command to a Thing Definition, you should:

  1. Enter the Remote Control / Commands page.
  2. Select the Thing Definition to edit.
  3. Press the Add Command button.
  4. Provide the required information.
  5. Press the Save button and edit the additional information, if needed.

Editing a Command

The command editing is composed by several sections.

General

Here you can define the name of the command, which is used to reference the command in the UI, in the Automations, and which is included in the JSON payloads sent to the remote products.

Parameters

A command when sent to the remote product can be enriched with parameters, here by clicking on the Add button you can define new parameters, by specifying:

  • Name: the field used into the payload of the command
  • Value: the value of the parameter, it can be a static value, but you can also use placeholders (see the section below).

  • Type: the type of the value, this affects the way the value is encoded in the payload.

  • Send When: the policy defining when the parameter must be included in the command payload, Always included, or depending on the On Condition status.

Enabled Condition

A metric-based condition enabling/disabling the button in the UI. 

ON Condition

A metric-based condition driving the UI status of the button in case of commands with status (e.g. On/Off the light). This can be used to use different colors, icons, and text according to the ON status.

Running Condition

Used for long-running commands to highlight in the UI the command is still running.
For instance, you can display a spinning icon when the Run Condition is true.  

Mapping

Here is the place to define how the command is sent to the remote product.

  • Path: this is the publishing path, for instance, the last part for an MQTT topic.
  • Max parameter count per message: if you have a lot of parameters to send but you have limited bandwidth or device capabilities, you can reduce the number of parameters to include in the payload. If it is exceeded, more payloads will be sent until all the parameters have been sent.

Options

Additional command options:

  • Bulk Update: allows users to perform the same command on multiple things.
  • Secure: enriches the command payload with signatures which can be used by the remote device to verify the incoming command validity.

Placeholders

In the parameter value definition, you can use placeholders to send dynamic values, for instance:

ABC-${thing.serialNumber}-123

Here is the list of placeholders you can use:

thing.<PROPERTY>

Any property of the thing, including also custom properties.

${thing.serialNumber}

${thing.properties.<PROPERTY_NAME>}  
location.<PROPERTY>

Any property of the location, including also custom properties.

${location.name}

${location.properties.<PROPERTY_NAME>}
customer.<PROPERTY>

Any property of the customer, including also custom properties.

${customer.name}

${customer.properties.<PROPERTY_NAME>}
partner.<PROPERTY>

Any property of the partner associated with the location or parent customer, including also custom properties.

${partner.name}

${partner.properties.<PROPERTY_NAME>}
metrics.<METRIC_NAME>.value

Includes the last value of the metric referenced by name.

${metrics.temperature.value}
request.<PARAM_NAME>

Any query string parameter passed to the execution command API.

 

Sending Commands

Within the pages, you can use the Commands widget to let the users execute commands on the remote product.

Commands

When the button is pressed, a message containing the information of the command to execute is sent to the remote product.

A feedback mechanism informs the user whether the operation has succeeded or not.

Bulk Update

According to the permissions, users can perform bulk execution for commands, for instance, it is possible to select multiple products (e.g. by tracing an area on the map) and trigger on them the execution of a specific command.

Servitly automatically schedules an operation that pushes to the remote products the command execution request through the chosen IoT connector. If the remote products are offline, the bulk execution is automatically retried periodically (1 per hour for a maximum of 12 hours) until all the connected products will be updated.

Related articles

Comments

0 comments

Please sign in to leave a comment.