Setting a Value From a Cloud Action

There are many use cases where you would like to make a change to the edge as a result of a Cloud Action. It is possible, the Cloud action script simply needs to write an event to the stream :command of the device targeted. An event can be used to change several resources and virtual resources at the edge.

The following steps use the example of setting the LCD value on the LCD screen included with the mangOH Red. We propose to update the line 1 of the LCD with a message in case the light is above an arbitrary thresold of 1500.

1. Navigate to Device > Resources
2. Locate the light sensor, make sure the resource is enabled and a period is set to few seconds let's say 5 seconds. Apply if needed.
3. Create an observation sending the light readings to a cloud stream. As a result once the configuration is applied on the device, you shall see the stream updated every 5 seconds with a new reading from the light sensor. In this example the stream is named light_direct.
4. To create the Cloud action, Navigate to Cloud > Actions
5. Click Add Cloud Action.
6. Set Source Type to Stream.
7. Enter a Name for your cloud action
8. Select the stream //devices//.
9. Select checkbox Send a device command
10. Click on Continue
11. Paste the following code:

function(event) {
  var output = {};
  var deviceId = event.path.split("/")[3];
  var companyId = event.path.split("/")[1];
  var command_path = "/" + companyId.toLowerCase() + "/devices/" + deviceId.toLowerCase() + "/:command";

  var light_reading = event.elems.redSensor.light;


  if (light_reading > 1500) {
    output[command_path] = [{
      "elems": {
        "lcd": {
          "txt1": "too Much Light!"
        }
      }
    }];
  }
  return output;
}

11. Click Create Cloud Action.

If you enlight the light sensor of the mangOH red, you shall see the message too Much Light showing on the screen.

12. You will see the event added to the stream :command of your device.

Like in previous example, you can know if the command has been processed on the device and if there was some error, looking for COMMAND_START / COMMAND_COMPLETE or COMMAND_FAULT in the stream :inbox of your device, they also appear in the Recent changes widget of the Device details screen.

📘

Resource Path

Most of the time you will need to change the sub resource value of a resource, in this case you add value to the resource path: /app/NAME/value.
Example of event to send in order to update a virtual resource named lightThreshold :
{
"elems": {
"virtual/lightThreshold/value": 1200
}
}

It is possible to add a timeout or ttl: time to live parameter to the event you are sending to the stream :command of a device. When this parameter is set, Octave will attempt to deliver the command to the device until it succeeds, or the timeout is exceeded. Timeout and TTL are defined as optional attributes of the event metadata field, parameter is milliseconds.

In the example below the command will timeout after 1 minute:

{  
  "elems": {
    "lcd/txt1": "too Much Light !"
  },
  "metadata": { 
    "ttl": 60000
  }
}