@spec backend_info(backend() | nil) :: map()

Return info about the low level GPIO interface

This may be helpful when debugging issues.

@spec close(Circuits.GPIO.Handle.t()) :: :ok

Release the resources associated with a GPIO

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

@spec enumerate(backend() | nil) :: [identifiers()]

Return a list of accessible GPIOs

Each GPIO is described in a identifiers/0 map. Some fields in the map like :location and :label may be passed to open/3 to use the GPIO. The map itself can also be passed to open/3 and the function will figure out how to access the GPIO.

@spec force_close(gpio_spec() | identifiers() | [gpio_spec() | identifiers()]) ::
  :ok | {:error, atom()}

Close GPIO handles by gpio spec or identifier

This is useful when a process has lost its handles or when GPIO hardware is being reconfigured. After this call, any use of the old file handles will raise an exception.

See the :on_busy option in the open_options/0 docs for automatically taking over GPIOs when calling open/3.

@spec gpio_spec?(any()) :: boolean()

Return if a term looks like a gpio_spec

This function only verifies that the term has the right shape to be a gpio_spec/0. Whether or not it refers to a usable GPIO is checked by Circuits.GPIO.open/3.

@spec identifiers(gpio_spec()) :: {:ok, identifiers()} | {:error, atom()}

Return identifying information about a GPIO

See gpio_spec/0 for the ways of referring to GPIOs. If the GPIO is found, this function returns information about the GPIO.

Guard version of gpio_spec?/1

Add require Circuits.GPIO to your source file to use this guard.

@spec open(
  gpio_spec() | identifiers() | [gpio_spec() | identifiers()],
  direction(),
  open_options()
) :: {:ok, Circuits.GPIO.Handle.t()} | {:error, atom()}

Open one or more GPIOs

See gpio_spec/0 for the ways of referring to GPIOs. Set direction to either :input or :output. If opening as an output, then be sure to set the :initial_value option to minimize the time the GPIO is in the default state.

Groups

Passing a list of GPIO specs opens them together as a group. read/1 then returns a single integer and write/2 takes one. The first GPIO in the list is the least significant bit (bit 0), the second is bit 1, and so on:

iex> {:ok, bus} = Circuits.GPIO.open([{"gpiochip0", 2}, {"gpiochip0", 4}], :output)
iex> Circuits.GPIO.write(bus, 0b10)   # GPIO 2 -> 0, GPIO 4 -> 1
:ok
iex> Circuits.GPIO.close(bus)
:ok

All GPIOs in a group must be on the same controller. :initial_value is interpreted as an integer with the same one-bit-per-line layout, and :pull_mode/:drive_mode apply to every line in the group.

Exclusivity

Each GPIO may only have one open handle at a time. This is enforced by the backend, so while one backend may support it, it's not guaranteed. Library authors should assume exclusivity on GPIOs to be cross platform. In practice, this isn't a big deal except when debugging.

Use the :on_busy option to :take_over a GPIO from another open handle when it's busy. This is useful for GenServers when they restart to avoid waiting for the BEAMs GC to clean up the old handle. It's also handy when experimenting at the IEx prompt when you lose a reference. The :on_busy option only works for handles known to the running BEAM instance.

Troubleshooting

The most common issue is figuring out the names or labels on GPIOs. See enumerate/0 for available GPIOs. On Linux, labels are defined in the device tree.

If you suspect a hardware or driver issue, see Circuits.GPIO.Diagnostics.

If you're getting {:error, :already_open}, try passing on_busy: :take_over to try taking over the GPIO from a lost or outdated reference.

Options:

• :initial_value - Set to 0 or 1 (or an integer with one bit per line for a group). Only used for outputs. Defaults to 0.
• :pull_mode - Set to :not_set, :pullup, :pulldown, or :none for an input pin. :not_set is the default.
• :drive_mode - Set to :push_pull, :open_drain, or :open_source. :push_pull is the default. Only used for outputs.
• :on_busy - Set to :take_over or :error. :take_over will try closing other GPIO users to allow this call to succeed. Defaults to :error.

Returns {:ok, handle} on success.

@spec read(Circuits.GPIO.Handle.t()) :: value()

Read a GPIO's value

For a group opened with a list of GPIO specs, this returns an integer with the first GPIO as bit 0, the second as bit 1, and so on. See value/0.

The value returned for GPIO's that are configured as outputs is undefined. Backends may choose not to support this.

@spec read_one(gpio_spec(), open_options()) :: value() | {:error, atom()}

One line GPIO read

This is a convenience function that opens, reads, and closes a GPIO. It's intended to simplify one-off reads in code and for IEx prompt use.

Prefer using handles in other situations.

@spec set_direction(Circuits.GPIO.Handle.t(), direction()) :: :ok | {:error, atom()}

Change the direction of the pin

@spec set_drive_mode(Circuits.GPIO.Handle.t(), drive_mode()) :: :ok | {:error, atom()}

Set the drive mode (push-pull, open-drain, or open-source)

@spec set_interrupts(Circuits.GPIO.Handle.t(), trigger(), interrupt_options()) ::
  :ok | {:error, atom()}

Enable or disable GPIO value change notifications

New code should prefer subscribe/2, which delivers a map (with the value and previous value), works with GPIO groups, and returns a reference for matching messages. set_interrupts/3 remains for backwards compatibility and sends the tuple described below. It cannot be used with a group handle.

Notifications are sent based on the trigger:

• :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 - Not supported in Circuits.GPIO v2
• :receiver - Process which should receive the notifications. Defaults to the calling process (self())

Notification messages look like:

{:circuits_gpio, gpio_spec, timestamp, value}

Where gpio_spec is the gpio_spec/0 passed to open/3, timestamp is an OS monotonic timestamp in nanoseconds, and value is the new value.

Timestamps are not necessarily the same as from System.monotonic_time/0. For example, with the cdev backend, they come the Linux kernel. It's also possible for them to come from a monotonic hardware timer. Both may be different from Erlang's monotonic time. The takeaway is that these timestamps can be compared with each other, but be careful when comparing them to anything else.

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.

@spec set_pull_mode(Circuits.GPIO.Handle.t(), pull_mode()) :: :ok | {:error, atom()}

Enable or disable an internal pull-up or pull-down resistor

@spec status(gpio_spec() | Circuits.GPIO.Handle.t()) ::
  {:ok, status()} | {:error, atom()}

Return dynamic configuration and status information about a GPIO or handle

Pass a gpio_spec/0 to query a GPIO without opening it, or a t:Handle.t/0 to query an open GPIO. If the GPIO is found, this function returns information about the GPIO. Status for GPIO groups is not supported.

@spec subscribe(Circuits.GPIO.Handle.t(), subscribe_options()) ::
  {:ok, term()} | {:error, atom()}

Subscribe to GPIO value change notifications

This is the preferred way to receive change notifications and the only way to receive them for a group (a handle opened with a list of GPIO specs). It returns {:ok, ref} where ref is a reference echoed in every notification so you can match messages to this subscription.

Available options:

• :receiver - process that should receive notifications. Defaults to the calling process (self()).
• :tag - a term echoed in the :ref field instead of the auto-generated reference.
• :trigger - send notifications on the :rising, :falling, or :both edges. Defaults to :both.

Notification messages are maps:

{:circuits_gpio, %{ref: ref, timestamp: timestamp, value: value, previous_value: previous_value}}

Where ref is the reference returned by this function (or your :tag), timestamp is an OS monotonic timestamp in nanoseconds, value is the new value (an integer with one bit per line for a group), and previous_value is the previously reported value. Bitwise.bxor(value, previous_value) has the changed bits. It's possible to receive reports with no changes due to transients.

Timestamps are not necessarily the same as from System.monotonic_time/0. For example, with the cdev backend, they're applied by the Linux kernel or can be come from a hardware timer. Erlang's monotonic time is adjusted so it's not the same as OS monotonic time. The result is that these timestamps can be compared with each other, but not with anything else.

NOTE: You will need to keep the handle from open/3 (for example, in your GenServer's state) so that it isn't garbage collected. Notifications stop when it is collected.

@spec unsubscribe(Circuits.GPIO.Handle.t()) :: :ok | {:error, atom()}

Stop GPIO value change notifications started with subscribe/2

@spec write(Circuits.GPIO.Handle.t(), value()) :: :ok

Set the value of a GPIO

The GPIO must be configured as an output.

For a group opened with a list of GPIO specs, pass an integer with the first GPIO as bit 0, the second as bit 1, and so on. See value/0.

@spec write_one(gpio_spec(), value(), open_options()) :: :ok | {:error, atom()}

One line GPIO write

This is a convenience function that opens, writes, and closes a GPIO. It's intended to simplify one-off writes in code and for IEx prompt use.

Prefer using handles in other situations.