Controlling GPIO as an Output and Controlling Values From the Cloud

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 it's ID.

📘

For this tutorial you will need the following:

• mangOH Red with IoT expansion card 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. Navigate to Device > Services menu in Octave.
2. Click GPIO.
3. Add IOT0_GPIO1 as a digital output.
4. Navigate to Device > Resources.
5. Locate redSensor > light.
6. Set its enabled property to true and its period to 10 seconds.
7. Click Add virtual resource at the top of the Resources screen.
8. Enter a name for the Virtual Resource (e.g., /virtual/light_threshold), set its type to number and the value to 1000.
9. Click Add to close the Virtual Resource popup.
10. Click Apply on the Resources screen.

Configuring the Observations:

1. Navigate to Device > Observations.
2. Click Add Observation.
3. Set Observed resource to /redSensor/light/value.
4. Enter the name light_ea into Observation name.
5. Set Send events to to Edge Action.
6. Click Save.

📘

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. Navigate to Device > Edge Actions.
2. Click Add edge action.
3. Set Source observation to light_ea.
4. Copy and paste the following code into the code section:

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]}
}

5. Click Save to save the Edge Action.

Setting up the Hardware

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

📘

As indicated in Octave, IOT0_GPIO1 corresponds to IoT Slot 0 on pin 24.

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 Device > Edge actions and temporarily disable the light_ea Edge Action created above.
2. Navigate to 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 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 Dash Boarding

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