Share Octave applications - GPIOs & Cloud API

Hi everyone,
I’m sharing here a very simple code sample for Octave to use GPIOs and cloud APIs. Feel free to post comments or ask questions below! Also, here’s the related video: https://www.youtube.com/watch?v=VYH4J37MxLQ

Introduction

Prerequisites

  • mangOH Red open source platform (could run on mangOH Yellow too)
  • Octave account
  • breadboard IoT expansion card (provided with all mangOH boards)
  • a 5V LED
  • a REST API client such as Postman or Insomnia, etc…

Octave concepts used

  • I/O service
  • Observations
  • Virtual resources
  • Edge actions
  • Octave REST API

Use Case - Control GPIO as an output and controlling values from the cloud

In this tutorial, we are going to create a low-light detector, which:

  • turns on an LED when the measured light is below a given threshold, thanks to the devices GPIOs and to an Edge Action
  • relies on a detection threshold that can be updated from the cloud (thanks to Octave API)

Implementation

Step 1: Configure your devices resources & Observations

Configure the resources:

  • Enabling the output to control the LED: in the Services menu on Octave, configure GPIOs in order to enable “IOT0_GPIO1” as a digital output.
  • Enabling the RedSensor light sensor: in the Resources menu in Octave, set the light sensor to Enable with a reporting period of 10 seconds.
  • Create a numerical Virtual Resource called “light_threshold” where we will store the value used to compare with (and give it a default value of 1000 for instance).

Configure the Observations:

  • Create an Observation called “light_ea” which takes “/redSensor/light/value” and sends it to Edge Action
  • 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 resources (but this is not mandatory for the setup to work)

Step 2: Code your Edge action

The edge action will be triggered by the “light_ea” observation.
It will :

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

    Here’s the code to use in your Edge Action:
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]
   }
}

Step 3: Plug the LED on the mangOH IoT card:

As indicated in the Services/GPIO menu in Octave, “IOT0_GPIO1” corresponds to “IoT Slot 0 on pin 24”
On your IoT connector expansion card, plud the LED such as:

  • the long LED leg is connected to VCC (IoT card pin 28)
  • the short LED leg is connected to pin 24 (the GPIO output we are controlling)

To test this setup, you can control the GPIO state manually from the Octave UI (Resources/io/IOT0_GPIO1/value) to turn the LED On or Off (in order to do so you might want to disable your Edge Action first).
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.

Step 4: Control the threshold form the cloud.

In order to control the threshold, a simple API call needs to be made to your device’s :command stream to set the value of /virtual/light_threshold
In order to do so, first retrieve your devices stream ID: in the Octave UI go to streams and select the :command stream for your device.
The url in your browser will display : https://octave.sierrawireless.io/device/streams/sxxxxxx
with sxxxxxx being the stream Id you are looking for.

Altrenatively, in the Octave Stream menu (Device or Cloud), select the string of interest and click on Edit. The pop-up window will display the Stream IdThen refer to Octave API references: indicating how to create an Event in a stream https://rest.octave.dev/#creating-an-event

As indicated, having set the X-Auth User and Token in the request Header, make an API POST to :
https://octave-api.sierrawireless.io/v5.0/companyName /event/sxxxxxx
with {"elems":{"virtual": {"light_threshold": {"value":200}}}} as the request Body

This will send the updated threshold value to the device.
You may perform this API call in different fashions:

  • from a CURL command
  • from an API client such as Postman or Insomnia
  • from your browser (Firefox in developer mode)
  • from a cloud service such as Microsoft Power Automate (formerly Microsoft Flow) IFTTT
1 Like

Hi,
On mangOh Yellow, with the frimware 2.1.0 the ressources RedSensor doesn’t appear.
Is it possible to downgrade the firmware or what is the method to access to this ressources ?
Thank you

Hello,

on the MangOh Yellow, the light sensor is directly accessible as “light” in the Resource tree (with enable, period & value as children)

A.