The Octave Developer Hub

Welcome to the Octave developer hub. You'll find comprehensive guides and documentation to help you start working with Octave as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

GPIO Guides

This topic describes how to configure a GPIO pin in Octave and verify that Octave can control/monitor it. This process is necessary to identify a device's pin in Octave as either input or output and whether it is analog or digital. Once complete, the configured pin is then available in Octave as a Resource through which you can enable it to emit output (voltage) or read input signals.

Identifying and Viewing GPIO Pinouts

Before configuring a GPIO pin in Octave, first identify the pin's number on your chosen device using appropriate the pin map:

You will use this pin number in the steps below to specify the pin designation in Octave when configuring an input or output pin.

GPIO Output

Configuring a GPIO Output

A GPIO output pin on an Octave edge device emits voltage (e.g., to control an asset). Setting up a GPIO output involves configuring a pin on the Octave edge device as an output pin which in turn, creates an Output (Actuator) Resource for the pin that will be available on the Build > Device > Resources screen. You can then enable and set the pin's value using that Resource.

Follow the steps below to configure a device's pin in Octave as a digital output pin:

  1. Navigate to Build > Device > Services, locate the GPIO section, and click Configure.
  2. Locate the Add pin section (1):
  1. Click the Pin drop down (2) and select a GPIO pin (e.g., WP_GPIO_2 for a mangOH Red output pin, EXT_IO3_DO for an FX30 rear port pin, IOT0_GPIO4 for an IoT expansion board pin, etc.). Note the expected voltage indicated for the pin which will be either 1800mV or 3300mV.
  2. (Optional) Change the name in Resource (3) to a more descriptive name.
  3. Set the Direction (4) to Output.
  4. Click Add (5). The configured output pin appears in the list of GPIO Services.
  5. Enable and set the pin's value in the Resource as described here.

📘

Note

When adding a GPIO output, the output will take on the current state of the GPIO pin. If that GPIO output had been previously configured with a value set, then Octave will apply that previously configured value to the GPIO output. This ensures that pin values don't change state unexpectedly when a configuration is applied.

GPIO Input

A GPIO input pin on an Octave edge device receives are signals which are pushed by assets at some arbitrary time and interval. You will create an input in Octave any time you have an asset connected to the Octave edge device that you want to monitor in Octave.

📘

Note

If the asset does not push data signals, then you may be able to monitor it using a Sensor Resource instead of an Input Resource.

Configuring a Digital Input

Setting up a GPIO input involves configuring a pin on the Octave edge device as an input pin which in turn, creates an Input Resource for the pin that will be available on the Build > Device > Resources screen. You can then enable the pin using that Resource.

📘

Note

You can set up a pin for either digital input (as described below) or analog input

Follow the steps below to configure a device's pin in Octave as a digital input pin:

  1. Navigate to Build > Device > Services (1), locate the GPIO section (2), and click Configure (3):
  1. Locate the Add pin section (1):
  1. Click the Pin drop down and select a GPIO pin (e.g., WP_GPIO_1 for a mangOH Red input pin, EXT_IO2_DI for an FX30 rear port pin, IOT0_GPIO1 for an IoT expansion board pin, etc.).
  2. Note the expected voltage indicated for the pin which will be 1800mV.
  3. (Optional) Change the name in Resource (2) to a more descriptive name. By default, the Resource created by the IO service will share the name of the pin that it connects. However, it's usually much more practical to use a short name that describes what you are actually connecting. For example, red_led might make sense for a digital output connected to an LED.
  1. Ensure the Direction is set to Input (I).
  2. Set Pull to Up.
  3. Click Add (3). The configured pin appears in the list of GPIO Services.

Configuring an Analog Input

Follow the steps below to configure a device's pin in Octave as an analog input pin:

  1. Navigate to Build > Device > Services, locate the GPIO section, and click Configure.
  2. Locate the Add pin section.
  3. Click the Pin drop down and select a GPIO pin (e.g., ADC0).
  4. Note the expected voltage range indicated for the pin under the Voltage label.
  5. (Optional) Change the name in Resource to a more descriptive name. By default, the Resource created by the IO service will share the name of the pin that it connects. However, it's usually much more practical to use a short name that describes what you are actually connecting. For example, photoresistor might make sense for an analog input name.
  6. (Optional) Click Enable Scaling (1) to customize the voltage curve and modify the function parameters (2) to adjust the graph. This feature transforms the voltages reported by Octave (shown on the Y-axis (3)) from the actual voltages measured on the pin (shown on the X-axis (4)) over the pin's voltage range:

📘

Note

Due to a bug in Octave, scaling on the ADC may not be taken into account. To rectify this you can multiply the following scaling coefficient to the first addend of the function:

a1 = 1000mv / 1700mV ~= 0.58

For example, in the screenshot above you would multiply 1 * 0.58 to get 0.58. The function would then be:

f(x) = 0.58 + 2.1 + 2.4

Note that you may need to tweak the value for your specific hardware.

  1. Click Add. The configured pin appears in the list of GPIO Services.
  2. Enable and verify the pin Resource as described here Input Resources.

GPIO Input Tutorials

The following tutorials show how to work GPIO inputs using an IoT Expansion Breadboard.

For these tutorials you'll need to:

  1. Take a look at the IoT Expansion Board pin map and locate the ADC pin (Pin 20).
  2. Wire up the ADC pin.
  3. Configure an output pin via the GPIO service.

Tutorial 1: Driving the Value by Jumping the PIN to Ground

In this tutorial, you will use a jumper wire to bridge the ADC pin (Pin 20) on the IoT Expansion Board to a ground pin, and then view the change in value of the ADC pin using Octave.

📘

Note

For this tutorial you will need a jumper wire.

Preparing the Pin in Octave

Follow the steps below to set up and configure an ADC pin on the device via Octave:

  1. Add an analog input pin for GPIO pin for ADC0.
  2. Add an Observation for the pin's resource (/io/ADC0/value ).
  3. Enable the pin's Resource and set its period to a short time period (e.g., 5 seconds).

Viewing the Change in Value of the ADC Pin.

Follow the steps below to view and modify the value of the ADC pin:

  1. Navigate to Build > Device > Streams.
  2. Locate your device in the Stream list and ensure it is expanded.
  3. Locate the adc_0 stream and click on it.
  4. Note the pin's maximum value, which should be appearing in the list of events at the interval specified via the period property that you configured in the previous section.
  5. Review the IoT Expansion Board pin map and identify the location of the ADC pin (Pin 20) and a ground pin (e.g., Pin 21).
  6. Bridge the ADC pin (Pin 20) to a ground pin (e.g., Pin 21) using a jumper wire.
  7. Wait for the configured interval to elapse. The next event in the stream should indicate a value below the pin's expected range (i.e., a value below 100mV such as 17mV).

Tutorial 2: Detecting Changes from a Photocell

In this tutorial, you will wire up a photocell to the ADC pin (Pin 20) on the IoT Expansion Board and then view the variations in voltage that occur as the amount of light detected changes.

📘

Note

For this tutorial you will need the following electronic components:

  • mangOH Red with the IoT Expansion Board installed
  • photocell
  • 1 kilo Ohm resistor
  • three jumper wires
  • (optional) a breadboard to make the connections on

Wiring the Circuit

  1. Wire up the following circuit:

Image of mangOH RedImage of mangOH Red

  1. Power on the mangOH Red.

Preparing the Pin in Octave

  1. Add an analog input pin for GPIO pin for ADC0.
  2. Add an Observation for the pin's resource (/io/ADC0/value).
  3. Enable the pin's Resource and set its period to a short time period (e.g., 5 seconds).

Viewing the Change in Value of the ADC Pin

Follow the steps below to view and modify the incoming value on the ADC pin:

  1. Navigate to Build > Device > Streams.
  2. Locate your device in the Stream list and ensure it is expanded.
  3. Locate the adc_0 stream and click on it.
  4. Note the pin's current value, which should be appearing in the list of events at the interval specified via the period property that you configured in the previous section.
  5. Place your finger over the photocell to reduce the light level.
  6. Wait for the configured interval to elapse. The next event in the Stream should indicate a significantly lower value corresponding to the change in light.

Setting the FX30 LED Colors via GPIO

You can set the color of the FX30/FX30S's power and user LEDs by assigning different combinations of values to the LED_PWR_... and LED_USR_... GPIO pins.

Setting the Color of the Power LED

Follow the steps below to set the color of the FX30/FX30S's power LED:

  1. Open the Octave Dashboard.
  2. Add GPIO outputs for LED_PWR_GRN_FCN, LED_PWR_GRN, and LED_PWR_RED.
  3. Navigate to the Resources screen and expand the io node.
  4. Set the values for the three GPIO outputs created in Step 2 according to the following table and click Apply. The power LED should change color accordingly.

Color

LED_PWR_GRN_FCN

LED_PWR_GRN

LED_PWR_RED

None (off)

true

true

false

Red

true

true

true

Amber

true

false

true

Green

true

false

false

Setting the Color of the User LED

Follow the steps below to set the color of the FX30/FX30S's user LED:

  1. Open the Octave Dashboard.
  2. Add GPIO outputs for LED_USR_GRN and LED_USR_RED.
  3. Navigate to the Resources screen and expand the io node.
  4. Set the values for the two GPIO outputs created in Step 2 according to the following table and click Apply. The power LED should change color accordingly.

Color

LED_USR_GRN

LED_USR_RED

None (off)

true

true

Red

true

false

Amber

false

false

Green

false

true

Updated about a month ago

GPIO Guides


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.