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 WEGnology workflows. Another common way to invoke commands is using the WEGnology 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 WEGnology 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.

WEGnology 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.

Handling Commands

Commands can be received over an MQTT connection to WEGnology, via the REST API or through the workflow engine’s Device Command Node. The WEGnology 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 WEGnology Arduino MQTT client to handle a command and turn on an LED:

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

WEGnologyDevice 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(WEGnologyCommand *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.