Quite often you will want to control some aspect of your edge-to-cloud flow from an external, third-party cloud entity Octave enables you to do this from any device with an internet connection through its REST API.

This topic builds on Using the REST API in an External System with a tutorial showing how this can be accomplished in combination with other elements of a typical edge-to-cloud flow including GPIO outputs and Edge Actions.

In this tutorial, you will create a low-light detector that:

• turns on an LED when the measured light is below a given threshold using the device's GPIOs and an Edge Action.
• relies on a detection threshold that can be updated from the cloud using the Octave REST API.

By following the steps for this tutorial you will learn how to:

• read a light sensor.
• control an IO with an Edge Action based on incoming light versus a sensor threshold.
• store a threshold in a Virtual Resource.
• change the threshold (Virtual Resource value) from a third-party cloud entity using the Octave REST API.
• use the :command Stream and how to retrieve a device's Stream ID.

📘

For this tutorial you will need the following:

• mangOH Red with IoT Expansion Board installed
• 5V LED
• (Optional) Breadboard and jumper wires to make the connections
• REST API client such as Postman or Insomnia. Alternatively, you can use CURL, your browser (e.g., Firefox in developer mode), or a cloud service such as Microsoft Power Automate (formerly Microsoft Flow) IFTTT.

Configuring Your Device's Resources and Observations

Configure the Resources

Follow the steps below to enable a Resource to control the LED:

1. Add a GPIO Output for IOT0_GPIO1.
2. Add a Sensor Resource for redSensor > light with a period of 10 seconds.
3. Add a Virtual Resource named /virtual/light_threshold, set its type to number, and the value to 1000.

Configuring the Observation

Next, create an Observation that will send events about the light sensor's values to an Edge Action.

Create a new Observation and set the Observed resource to /redSensor/light/value and Send events to to Edge Action (see Sending Events to an Edge Action for more information).

📘

Note:

In order to witness what is happening, you can chose to create Cloud Stream Observations on the light sensor and on the light_threshold Virtual Resource (but this is not mandatory for the setup to work).

Implementing Your Edge action

​
The Edge Action that you create below, will be triggered by the light_ea Observation and will perform the following:

• read the measured light value.
• retrieve the light_threshold value.
• compare the measured light to the threshold.
• set the GPIO status to true or false to control the LED, depending on the comparison result.
  ​

Follow the steps below to add the Edge Action:

1. Create an Edge Action and set the Source Observation to light_ea.
2. Copy and paste the following code into the code section and save the Edge Action. In this example, the code reads both the current light from the sensor and the light threshold value, and if the light is greater than the threshold, sets a flag (led_on) to false. The code then writes the flag to IOT0_GPIO1 via the Data Hub as indicated by dh: in the return statement:

function(event) {
  var light = event.value;
  var light_threshold = Datahub.read('/virtual/light_threshold/value', 0);
  var led_on = true;

  if (light >=light_threshold.value) {led_on = false;}
  
  return{"dh://io/IOT0_GPIO1/value":[!led_on]}
}

Setting up the Hardware

​
In this section you will plug your LED onto the mangOH Red's IoT card.

📘

Note:

As indicated in Octave, IOT0_GPIO1 corresponds to IoT Slot 0 on pin 24. See the IoT Expansion Pin Map for more information.

1. On your IoT connector expansion card, plug in the LED as follows:

• connect the long LED leg to VCC (IoT card pin 28).
• connect the short LED leg to pin 24 (the GPIO output you are controlling).

Follow the steps below to test this setup by manually setting the GPIO state for the Resource:

1. Navigate to Build > Device > Actions and temporarily disable the light_ea Edge Action created above.
2. Navigate to Build > Device > Resources.
3. Locate IO/IOTO_GPIO1.
4. Set the enabled state for the Resource to true.
5. Click Apply. The LED should turn on.
6. Re-enable the light_ea action created above.
   ​
   ​With the Edge Action enabled, your LED will turn on when the light is below the threshold and turn off whenever the light is above.

Controlling the Threshold From the Cloud.

In order to control the threshold from the cloud, a simple API call needs to be invoked to your device's :command stream to set the value of /virtual/light_threshold.
​

In order to do so, first retrieve your device's stream ID:

1. Navigate in the Octave UI to Build > Device > Streams and select the :command stream for your device.

2. Take note of the URL in your browser which will display: https://octave.sierrawireless.io/device/streams/sxxxxxxxxxxxxxxxxxx where "sxxxxxx..." is the Stream ID you are looking for. Alternatively, locate the string of interest in the list of events and click on Edit. The pop-up window will display the Stream ID.

3. Refer to Octave REST API reference on how to create an Event in a stream (see: Creating an Event). The REST call will look similar to the following example that sends the updated threshold value to the device:

POST /v5.0/my_company/event/s5b7310ae6f38613585853e5b HTTP/1.1
Host: octave-api.sierrawireless.io
X-Auth-Token: 1234
X-Auth-User: abc

{
   "elems":{
      "virtual":{
         "light_threshold":{
            "value":200
         }
      }
   }
}

Pushing Sensor Data to the Cloud for Dashboarding

Sensor data can optionally be pushed to the cloud for dashboarding as described in Pushing Data from Octave to IoT Central.