Device Commands

Device commands instruct your device to take an action. Commands include a name and an optional payload. Then the device’s firmware takes the appropriate action based on the command and payload.

Sending Commands

Commands are generally invoked from Losant workflows. Another common way to invoke commands is using the Losant API from a custom interface like a mobile app. For example, a thermostat may have a companion mobile app that allows the user to remotely set the temperature. The developer sends a command over the Losant REST API to set the temperature. The device receives the command and takes the appropriate action, which is likely to turn on or off the furnace or air conditioner.

Losant workflows provide a way to send commands to devices based on any number of triggers. The example below sends a command to a thermostat to disable “away” mode when a person is detected by a separate smoke detector device that has a motion sensor.

In the above example, the smoke detector is reporting state whenever motion is detected or not. The condition node checks that motion is detected. The condition might look something like {{ data.motion }} == true. If motion is detected, it then sends a command to the thermostat to disable its “away” mode. The command name is set-away and the payload is { "away" : false }.

Command names and payloads can be anything. It’s entirely up the device and its firmware for what commands will be supported.

You may view a history of sent commands in the Command History Log found inside the device detail page.

Handling Commands

Commands can be received over an MQTT connection to Losant, via the REST API or through the workflow engine’s Device Command Node. The Losant MQTT clients allow for connecting and receiving commands. All commands contain a name and an optional payload, sent as a JSON string that takes the following form:

{
  "name": "the-command-name",
  "payload": {
    "key": "value",
    "another-key": "another-value"
  }
}

The following example uses the Losant Arduino MQTT client to handle a command and turn on an LED:

// Called whenever the device receives a command from the Losant Platform.
void handleCommand(LosantCommand *command) {
  Serial.print("Command received: ");
  Serial.println(command->name);
  if(strcmp(command->name, "turn-on-led") == 0) {
    digitalWrite(LED_PIN, 1);
  }
}

LosantDevice device("my-device-id");
device.connectSecure(wifiClient, "my-access-key", "my-access-secret");

// Subscribe to commands.
device.onCommand(&handleCommand);

If you wish to send a payload with your commands, that value can be accessed and passed on to your handlers as well:

void handleCommand(LosantCommand *command) {
  JsonObject& payload = *command->payload;
  payload.printTo(Serial); // print the entire payload
  Serial.println(payload['key']); // print the 'key' property of the payload object
}

Note: If you are sending payloads of even moderate size, and your commands are failing to reach your microcontroller, it may be necessary to adjust the MQTT’s maximum packet size. Add the following line in your sketch:

#define MQTT_MAX_PACKET_SIZE 256

Handling Commands on Edge Compute Devices

You can also send commands to Edge Compute Devices running the Gateway Edge Agent. In these cases, you can respond and act on commands through the Device: Command Trigger. That trigger fires whenever the device receives a command, and the command name and payload is available on the workflow payload.

Handling Commands on Embedded Devices

Similar to handling commands on Edge Compute Devices, the Device: Command Trigger will also fire within Embedded Workflows running within the Embedded Edge Agent. However, this requires setting up your MQTT integration and invoking eea_message_received whenever a message is received on the device’s command topic.