circuits_gpio v0.4.5 Circuits.GPIO View Source

Control GPIOs from Elixir

If you're coming from Elixir/ALE, check out our porting guide.

Circuits.GPIO works great with LEDs, buttons, many kinds of sensors, and simple control of motors. In general, if a device requires high speed transactions or has hard real-time constraints in its interactions, this is not the right library. For those devices, see if there's a Linux kernel driver.

Link to this section Summary

Types

Options for open/3

The GPIO direction (input or output)

A GPIO pin number. See your device's documentation for how these connect to wires

Pull mode for platforms that support controllable pullups and pulldowns

Trigger edge for pin change notifications

GPIO logic value (low = 0 or high = 1)

Functions

Release the resources associated with the GPIO.

Return info about the low level GPIO interface

Get the GPIO pin number

Read the current value on a pin.

Change the direction of the pin.

Enable or disable pin value change notifications. The notifications are sent based on the trigger parameter

Enable or disable internal pull-up or pull-down resistor to GPIO pin

Set the value of a pin. The pin should be configured to an output for this to work.

Link to this section Types

Link to this type

open_option()

View Source
open_option() ::
  {:initial_value, value() | :not_set} | {:pull_mode, pull_mode()}

Options for open/3

Link to this type

pin_direction()

View Source
pin_direction() :: :input | :output

The GPIO direction (input or output)

A GPIO pin number. See your device's documentation for how these connect to wires

Link to this type

pull_mode()

View Source
pull_mode() :: :not_set | :none | :pullup | :pulldown

Pull mode for platforms that support controllable pullups and pulldowns

Link to this type

trigger()

View Source
trigger() :: :rising | :falling | :both | :none

Trigger edge for pin change notifications

Link to this type

value()

View Source
value() :: 0 | 1

GPIO logic value (low = 0 or high = 1)

Link to this section Functions

Release the resources associated with the GPIO.

This is optional. The garbage collector will free GPIO resources that aren't in use, but this will free them sooner.

Return info about the low level GPIO interface

This may be helpful when debugging issues.

Link to this function

open(pin_number, pin_direction, options \\ [])

View Source
open(pin_number(), pin_direction(), [open_option()]) ::
  {:ok, reference()} | {:error, atom()}

Open a GPIO for use.

pin should be a valid GPIO pin number on the system and pin_direction should be :input or :output. If opening as an output, then be sure to set the :initial_value option if you need the set to be glitch free.

Options:

  • :initial_value - Set to :not_set, 0 or 1 if this is an output. :not_set is the default.
  • :pull_mode - Set to :not_set, :pullup, :pulldown, or :none for an input pin. :not_set is the default.

Get the GPIO pin number

Read the current value on a pin.

Link to this function

set_direction(gpio, pin_direction)

View Source
set_direction(reference(), pin_direction()) :: :ok | {:error, atom()}

Change the direction of the pin.

Link to this function

set_interrupts(gpio, trigger, opts \\ [])

View Source
set_interrupts(reference(), trigger(), list()) :: :ok | {:error, atom()}

Enable or disable pin value change notifications. The notifications are sent based on the trigger parameter:

  • :none - No notifications are sent
  • :rising - Send a notification when the pin changes from 0 to 1
  • :falling - Send a notification when the pin changes from 1 to 0
  • :both - Send a notification on all changes

Available Options:

  • suppress_glitches - It is possible that the pin transitions to a value and back by the time that Circuits GPIO gets to process it. This controls whether a notification is sent. Set this to false to receive notifications.
  • receiver - Process which should receive the notifications. Defaults to the calling process (self())

Notifications look like:

{:circuits_gpio, pin_number, timestamp, value}

Where pin_number is the pin that changed values, timestamp is roughly when the transition occurred in nanoseconds since host system boot time, and value is the new value.

NOTE: You will need to store the Circuits.GPIO reference somewhere (like your GenServer's state) so that it doesn't get garbage collected. Event messages stop when it gets collected. If you only get one message and you are expecting more, this is likely the case.

Link to this function

set_pull_mode(gpio, pull_mode)

View Source
set_pull_mode(reference(), pull_mode()) :: :ok | {:error, atom()}

Enable or disable internal pull-up or pull-down resistor to GPIO pin

Link to this function

write(gpio, value)

View Source
write(reference(), value()) :: :ok

Set the value of a pin. The pin should be configured to an output for this to work.