Using GPIO Tools

A Rockface GPIO tool provides read and write access to a collection of digital signals connected to your hardware. These signals can act as inputs or outputs. The tool can also play simple timed sequences on its outputs.

---

In the rockface python library, power supply tools are represented using the rockface.tools.gpio.GPIOTool type:

from rockface import Rig
from rockface.tools.gpio import (GPIOTool, SignalState, SignalMode)

rig = Rig.find_by_name("my-rig")
gpio = rig.tools["my-gpio"]

assert isinstance(gpio, GPIOTool)

Examples continue from the above

For brevity, the rest of the examples on this page will continue on from the above example, with the gpio variable set to a GPIOTool instance.

Also note that we have imported SignalState and SignalMode — these will be used in examples further down this page.

Signals

A GPIO tool has a collection of physical inputs and outputs, each of which is represented by an entry in its signals property. This property can be indexed with the name of the signal:

# Get the object representing the 'button' signal
button = gpio.signals["button"]

# Get the object representing the 'led' signal
led = gpio.signals["led"]

# The signals property is a dict, so the signals can be iterated through
# just like any dict:
print("Signals available on this tool:",
      ", ".join(gpio.signals.keys()))

Signal names

The names of the signals will have been assigned at the time of your rig being installed. If you need them to be changed, contact us.

Configuring a Signal

Signals have three possible modes:

1. Input: Reads a digital signal.
2. Push-pull output: Drives a signal high or low.
3. Open-drain output: Drives a signal low, or is inactive.

The mode that a signal operates in is set using its config property. This property takes SignalConfig instances.

To configure a signal as an input, the mode field of the config needs to be set to SignalMode.INPUT:

led = gpio.signals["led"]

# Configure the led signal as a digital input
led.config = SignalConfig(mode=SignalMode.INPUT)

When configuring a signal as an output, the desired initial state of the signal must also be provided:

button = gpio.signals["button"]
control = gpio.signals["control"]

# Configure the button signal as an open-drain output, which is initially inactive
button.config = SignalConfig(mode=SignalMode.OUTPUT_OD,
                             initial_state=SignalState.INACTIVE)

# Configure the control signal as an initially active push-pull output
control.config = SignalConfig(mode=SignalMode.OUTPUT_PP,
                             initial_state=SignalState.ACTIVE)

The config property can also be read to retrieve the signal's configuration.

Signal State

Once the signal is configured as an input or output, its state property can be used to discover and control its state. As we will see in this section, the meaning of this property depends on how the signal is configured.

Input State

When a signal is configured as an input, then the value of its state property reflects the state of its associated physical GPIO tool input. Reading the property triggers the tool to sample the signal state:

led = gpio.signals["led"]
led.config = SignalConfig(mode=SignalMode.INPUT)

if led.state == SignalState.ACTIVE:
    print("The LED is on")
else:
    print("The LED is off")

Output State

When the signal is configured as an output, setting the state property causes the associated physical GPIO tool output to change state:

import time

button = gpio.signals["button"]
button.config = SignalConfig(mode=SignalMode.OUTPUT_OD,
                             initial_state=SignalState.INACTIVE)

# Press the button
button.state = SignalState.ACTIVE

time.sleep(0.1)

# Release the button
button.state = SignalState.INACTIVE

What is an active open-drain signal?

When an open-drain signal is in the 'active' state, it is actively pulling the line low. When it is 'inactive', it is in a high-impedance state.

The current state of the output can also be read using the state property:

assert button.state == SignalState.INACTIVE

Playlists

Sometimes it is necessary to control the timing with which GPIO outputs are set with more precision. For example, you may want to briefly press a button for 5 ms and check that your hardware registers the press correctly. This can be done using GPIO tool playlists: a timed sequence of output signal states.

To create a playlist, construct a Playlist object, and then register the sequence of operations you wish to perform with it:

from rockface.tools.gpio import Playlist
from datetime import timedelta

playlist = Playlist()
playlist.set_active(button)
playlist.delay(timedelta(milliseconds=5))
playlist.set_inactive(button)

Once you have constructed your playlist, command the GPIO tool to play it using the tool's play method:

gpio.play(playlist)

You can request the state of the playlist playback using the playlist_running property, and you can stop its execution using the stop_playlist method:

if gpio.playlist_running:
    print("Playlist is running")

# Stop the playlist
gpio.stop_playlist()

What are the limits of playlist timing and length?

By default, playlists have:

• Millisecond resolution
• Maximum delays of 2³² milliseconds
• A maximum of 12 entries

If you have requirements outside of these constraints, contact us.

Reset

A GPIO tool can be reset using its reset method:

gpio.reset()

When the tool is reset, all of its signals will configured as inputs.

The GPIO tool supply will always be reset at the end of a session (when the rig lock is dropped).