Device: Command Trigger Node

The Device: Command Trigger fires a workflow whenever the Edge Compute or Embedded Device executing the workflow receives a command.

Node Properties

The Device: Command Trigger has no configuration. When a workflow with this trigger is deployed to a device, the workflow will fire on receipt of any command sent to the device.

Payload

The payload for the Device: Command Trigger differs slightly between Edge Workflows and Embedded Workflows. For both workflow types, the payload’s data object contains the following properties:

• name: The name of the command that was sent to the device. Since the trigger fires for all commands, most users follow up the trigger with a Switch Node or a Conditional Node to take different actions based on this value.
• payload: An optional value sent in the command. This can take a number of shapes: a JSON object, an array, a string, a number, or a boolean. This often includes additional information needed to execute the command. For example, if a command with a name of “setTemp” is sent, the payload may include the numerical value of what the temperature should be set to.
• time: The time at which the command was sent. For Edge Workflows, this is in the form of a Date object; for Embedded Workflows, the value is a number representing the time (in milliseconds) in Unix time.

Edge Workflow Payload

In the general case, a Device: Command payload in an Edge Workflow looks like the following:

{
  "agentEnvironment": {
    "EXAMPLE": "Environment Variable"
  },
  "agentVersion": "1.31.0",
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "name": "myCommandName",
    "payload": {
      "temp": 69
    },
    "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST)
  },
  "device": {
    "applicationId": "555555555555eeeeeeeeeeee",
    "attributes": {
      "exampleNumber": {
        "attributeTags": {
          "attrTagKey": "tagValue1"
        },
        "dataType": "number",
        "name": "exampleNumber"
      },
      "exampleString": {
        "attributeTags": {
          "attrTagKey": "tagValue2"
        },
        "dataType": "string",
        "name": "exampleString"
      }
    },
    "creationDate": "2018-03-16T18:19:03.376Z",
    "deviceClass": "edgeCompute",
    "deviceId": "222222222222bbbbbbbbbbbb",
    "id": "222222222222bbbbbbbbbbbb",
    "name": "My Great Device",
    "tags": {
      "aTagKey": [
        "exampleTagValue"
      ],
      "tagWithMultipleValues": [
        "tagValue",
        "anotherTagValue"
      ]
    }
  },
  "deviceId": "222222222222bbbbbbbbbbbb",
  "deviceName": "My Great Device",
  "deviceTags": {
    "aTagKey": [
      "exampleTagValue"
    ],
    "tagWithMultipleValues": [
      "tagValue",
      "anotherTagValue"
    ]
  },
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "isConnectedToLosant": true,
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "deviceCommand",
  "triggerType": "deviceCommand"
}

Embedded Workflow Payload

In the general case, a Device: Command payload in an Embedded Workflow looks like the following:

{
  "data": {
    "name": "myCommandName",
    "payload": {
      "temp": 69
    },
    "time": 1455902760000
  },
  "deploymentId": "666666666666ffffffffffff",
  "deviceId": "222222222222bbbbbbbbbbbb",
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "isConnectedToLosant": true,
  "time": 1455902760000,
  "triggerId": "deviceCommand",
  "triggerType": "deviceCommand"
}

Notes

The Losant platform does not queue device commands in our MQTT broker or require acknowledgment that a command was received by the device. This means that, if the device is not connected to the broker at the time the command is sent, the device will never receive the command.

As a result, many users build their own command acknowledgment system by publishing a message on a custom MQTT topic (using an MQTT Node). Then, in an Application Workflow, an MQTT Trigger listening on that topic can process that message and know that the command was received.

Another option is to utilize the Losant API’s Device: Get Command endpoint to fetch the command history of the device on boot, which can be done using a Device: Startup Trigger and a Losant API Node. This list could then be checked for any commands sent during a period when the device was disconnected, and the commands could then be executed if desired.

Related Nodes

• Device: Command Node