Setting a Value From an Edge Action

This topic describes how to create and set a value from an edge action.

Overview

When writing the logic for an Edge Actions, you will typically begin by reading the Event data and then set a value (e.g., active an Output (Actuator), display a status, etc.). This topic describes how to set that value in your Action Script's logic.

Basic Steps to Create an Edge Action

  1. Create an Observation for a Resource (e.g., the mangOH Red's /redSensor/light/value Sensor Resource) and configure the Observation to send events to an Edge Action.

  2. Create an Edge Action, enter your code in the code editor, and set the Observation (or add it as a source, depending on the device's firmware version). The following subsections provide example code for sending data to different targets:

  3. Click Save. The logic has now been sent to the Octave Edge device and will execute when an Event from an Observation is received by the Edge Action.

Sending Data to the Datahub

The following example illustrates an Edge Action that monitors the light sensor included on the mangOH Red, computes the luminosity, and sends the result to the third line of the device's LCD screen:

function (event) {
  var lightReading = event.value;
  var lightDescription;

  if (lightReading > 1500) {
    lightDescription = "bright"
  } else if (lightReading > 300) {
    lightDescription = "a bit dim"
  } else {
    lightDescription = "dark"
  }

  var s = "It's " + lightDescription + " in here.";

  return {
    "dh://lcd/txt3": [s]
  }
}

The code reads the light value, concatenates it with some text describing the brightness, and then writes the string to the /lcd/txt3 Resource (third line of LCD screen).

Writing text to the LCD screen is accomplished by returning the string to the Data Hub which is indicated with dh:. For additional information see the Edge Action Runner Reference, and more specifically, that topic's Output section.

πŸ“˜

Return syntax

The returned object can include several paths, so several Resources can be updated from a single edge action.

Also, the Action Runner expects an array of objects for each path. As a consequence, even your script provides only one value, you must use the syntax "dh://resource_path": [ resource_value ].
Of course, the value you provide can itself be an array.

Sending Data to the Cloud Immediately

You can send data to the cloud immediately by returning data to cl://. The following example reads a light value and compares it against a threshold stored in a Virtual Resource (/virtual/lightThreshold/value). If the value exceeds the threshold, it sends an alert to the cloud immediately via the return statement:

function(event) {
    var light_reading = event.value;
    var light_threshold = Datahub.read("/virtual/lightThreshold/value",0).value;

    if(light_reading >= light_threshold) {
        //send alert and store state
        return {
            "cl://": [{"alert": "tooMuchLight", "lightReading": light_reading, "lightThreshold": light_threshold}]            
        }
    }
}

πŸ‘

Best Practices

The following should be taken into account when writing Edge Actions which send data to the cloud immediately:

  • Check the /cloudinterface/connected/value Resource to determine if the edge is connected to the cloud before sending data. Note that this is not necessary when using Store and Forward.
  • Due to Octave's security functionality (key rotation), establishing a connection to the cloud can range from several seconds to 1minute 30 seconds. This difference of time needs to be taken into account if a feature like ULPM is used to shutdown the edge, especially if the Edge Action does not check the connected Resource before sending data and performing the shutdown.
  • Wait for the connected Resource to update to true before sending data to the cloud. This indicates that the edge is connected to the cloud and that data can be sent. Otherwise the data may not be sent.

Sending Data via Store and Forward

You can optionally use Store and Forward to have your readings stored and then forwarded on a periodic basis rather than sending them immediately to the Datahub.

function(event) {
  var light_reading = Resource.readValue('/redSensor/light/value');
    
  return {
  'st://': [light_reading]
  }
}

Store and forward buffers the value, and then sends it to the cloud when it as has been configured to do so.

See Sending Data in an Edge Action Using Store and Forward for more information.

Sending Data to a Virtual Resource

The following example reads a light value from a sensor, followed by a light threshold stored in a Virtual Resource (/virtual/lightThreshold/value), as well as the previous state of the light that is also stored in a Virtual Resource (/virtual/tooMuchLight/value). If the previous state was false and the current light exceeds the threshold, then the Edge Action sets the Virtual Resource (tooMuchLight) to true:

function(event) {
    var light_reading = event.value;
    var light_threshold = Datahub.read("/virtual/lightThreshold/value",0).value;
    var previous_state = Datahub.read("/virtual/tooMuchLight/value",0).value;

    if(previous_state===false) {
        if(light_reading >= light_threshold) {
            //send alert and store state
            return {
                "vr://tooMuchLight": [true]
            }
        }
    }
}

See Write in a Virtual Resource for more information.