gpiod

A native Go library for Linux GPIO.

gpiod is a library for accessing GPIO pins/lines on Linux platforms using the GPIO character device.

The goal of this library is to provide the Go equivalent of the C libgpiod library. The intent is not to mirror the libgpiod API but to provide the equivalent functionality.

Roadmap

On the road to v1.0 the intent is to rename this library to gpiocdev to more clearly distinguish it from libgpiod, and to highlight that it operates on the GPIO character device. Additionally, the tools and testing will be more closely aligned to libgpiod v2, rather than libgpiod v1.

The plan is to work on the renaming in a gpiocdev branch and, once that is complete, to release a final 0.8.x version which deprecates the gpiod name, and to merge the gpiocdev branch into master and release v0.9.0 which will be the first release as gpiocdev. Coincident with this, the github repo will be renamed from gpiod to go-gpiocdev.

So, in summary, the planned changes are:

v0.8.x

Deprecate github.com/warthog618/gpiod in favour of github.com/warthog618/go-gpiocdev

v0.9.0

First release as gpiocdev (released simultaneously with the final 0.8.x)
Rename gpiodctl to gpiocdev and upgrade tools to match libgpiod v2 tools

Features

Supports the following functionality per line and for collections of lines:

direction (input/output)¹
write (active/inactive)
read (active/inactive)
active high/low (defaults to high)
output mode (push-pull/open-drain/open-source)
pull up/down²
watches and edge detection (rising/falling/both)
chip and line labels
debouncing input lines³
different configurations for lines within a collection³

¹ Dynamically changing line direction without releasing the line requires Linux 5.5 or later.

² Requires Linux 5.5 or later.

³ Requires Linux 5.10 or later.

All library functions are safe to call from different goroutines.

Quick Start

A simple piece of wire example that reads the value of an input line (pin 2) and writes its value to an output line (pin 3):

import "github.com/warthog618/gpiod"

...

in, _ := gpiod.RequestLine("gpiochip0", 2, gpiod.AsInput)
val, _ := in.Value()
out, _ := gpiod.RequestLine("gpiochip0", 3, gpiod.AsOutput(val))

...

Error handling and releasing of resources omitted for brevity.

Usage

import "github.com/warthog618/gpiod"

Error handling is omitted from the following examples for brevity.

Line Requests

To read or alter the value of a line it must first be requested using gpiod.RequestLine:

l, _ := gpiod.RequestLine("gpiochip0", 4)   // in its existing state

or from the Chip object using Chip.RequestLine:

l, _ := c.RequestLine(4)                    // from a Chip object

The offset parameter identifies the line on the chip, and is specific to the GPIO chip. To improve readability, convenience mappings can be provided for specific devices, such as the Raspberry Pi:

l, _ := c.RequestLine(rpi.J8p7)             // using Raspberry Pi J8 mapping

The initial configuration of the line can be set by providing line configuration options, as shown in this AsOutput example:

l, _ := gpiod.RequestLine("gpiochip0", 4, gpiod.AsOutput(1))  // as an output line

Multiple lines from the same chip may be requested as a collection of lines using gpiod.RequestLines

ll, _ := gpiod.RequestLines("gpiochip0", []int{0, 1, 2, 3}, gpiod.AsOutput(0, 0, 1, 1))

or from a Chip object using Chip.RequestLines:

ll, _ := c.RequestLines([]int{0, 1, 2, 3}, gpiod.AsOutput(0, 0, 1, 1))

When no longer required, the line(s) should be closed to release resources:

l.Close()
ll.Close()

Line Values

Lines must be requsted using RequestLine before their values can be accessed.

Read Input

The current line value can be read with the Value method:

r, _ := l.Value()  // Read state from line (active / inactive)

For collections of lines, the level of all lines is read simultaneously using the Values method:

rr := []int{0, 0, 0, 0} // buffer to read into...
ll.Values(rr)           // Read the state of a collection of lines

Write Output

The current line value can be set with the SetValue method:

l.SetValue(1)     // Set line active
l.SetValue(0)     // Set line inactive

Also refer to the blinker example.

For collections of lines, all lines are set simultaneously using the SetValues method:

ll.SetValues([]int{0, 1, 0, 1}) // Set a collection of lines

Edge Watches

The value of an input line can be watched and trigger calls to handler functions.

The watch can be on rising or falling edges, or both.

The events are passed to a handler function provided using the WithEventHandler(eh) option. The handler function is passed a LineEvent, which contains details of the edge event including the offset of the triggering line, the time the edge was detected and the type of edge detected:

func handler(evt gpiod.LineEvent) {
  // handle edge event
}

l, _ = c.RequestLine(rpi.J8p7, gpiod.WithEventHandler(handler), gpiod.WithBothEdges)

To maintain event ordering, the event handler is called serially from a goroutine that reads the events from the kernel. The event handler is expected to be short lived, and so should hand off any potentially blocking operations to a separate goroutine.

An edge watch can be removed by closing the line:

l.Close()

or by reconfiguring the requested lines to disable edge detection:

l.Reconfigure(gpiod.WithoutEdges)

Note that the Close waits for the event handler to return and so must not be called from the event handler context - it should be called from a separate goroutine.

Also see the watcher example.

Line Configuration

Line configuration is set via options to Chip.RequestLine(s) and Line.Reconfigure. These override any default which may be set in NewChip.

Note that configuration options applied to a collection of lines apply to all lines in the collection, unless they are applied to a subset of the requested lines using the WithLines option.

Reconfiguration

Requested lines may be reconfigured using the Reconfigure method:

l.Reconfigure(gpiod.AsInput)            // set direction to Input
ll.Reconfigure(gpiod.AsOutput(1, 0))    // set direction to Output (and values to active and inactive)

The Line.Reconfigure method accepts differential changes to the configuration for the lines, so option categories not specified or overridden by the specified changes will remain unchanged.

The Line.Reconfigure method requires Linux 5.5 or later.

Complex Configurations

It is sometimes necessary for the configuration of lines within a request to have slightly different configurations. Line options may be applied to a subset of requested lines using the WithLines(offsets, options) option.

The following example requests a set of output lines and sets some of the lines in the request to active low:

ll, _ = c.RequestLines([]int{0, 1, 2, 3}, gpiod.AsOutput(0, 0, 1, 1),
    gpiod.WithLines([]int{0, 3}, gpiod.AsActiveLow),
    gpiod.AsOpenDrain)

The configuration of the subset of lines inherits the configuration of the request at the point the WithLines is invoked. Subsequent changes to the request configuration do not alter the configuration of the subset - in the example above, lines 0 and 3 will not be configured as open-drain.

Once a line's configuration has branched from the request configuration it can only be altered with WithLines options:

ll.Reconfigure(gpiod.WithLines([]int{0}, gpiod.AsActiveHigh))

or reset to the request configuration using the Defaulted option:

ll.Reconfigure(gpiod.WithLines([]int{3}, gpiod.Defaulted))

Complex configurations require Linux 5.10 or later.

Chip Initialization

The Chip object is used to discover details about avaialble lines and can be used to request lines from a GPIO chip.

A Chip object is constructed using the NewChip function.

c, _ := gpiod.NewChip("gpiochip0")

The parameter is the chip name, which corresponds to the name of the device in the /dev directory, so in this example /dev/gpiochip0.

The list of currently available GPIO chips is returned by the Chips function:

cc := gpiod.Chips()

Default attributes for Lines requested from the Chip can be set via configuration options to NewChip.

c, _ := gpiod.NewChip("gpiochip0", gpiod.WithConsumer("myapp"))

In this example the consumer label is defaulted to "myapp".

When no longer required, the chip should be closed to release resources:

c.Close()

Closing a chip does not close or otherwise alter the state of any lines requested from the chip.

Line Info

Info about a line can be read at any time from the chip using the LineInfo method:

inf, _ := c.LineInfo(4)
inf, _ := c.LineInfo(rpi.J8p7) // Using Raspberry Pi J8 mapping

Note that the line info does not include the value. The line must be requested from the chip to access the value.

Once requested, the line info can also be read from the line:

inf, _ := l.Info()
infs, _ := ll.Info()

Info Watches

Changes to the line info can be monitored by adding an info watch for the line:

func infoChangeHandler( evt gpiod.LineInfoChangeEvent) {
    // handle change in line info
}

inf, _ := c.WatchLineInfo(4, infoChangeHandler)

Note that the info watch does not monitor the line value (active or inactive) only its configuration. Refer to Edge Watches for monitoring line value.

An info watch can be cancelled by unwatching:

c.UnwatchLineInfo(4)

or by closing the chip.

Kernel Version	Clock source
pre-5.7	CLOCK_REALTIME
5.7 - 5.10	CLOCK_MONOTONIC
5.11 and later	configurable (defaults to CLOCK_MONOTONIC)

Configuration Options

The available configuration options are:

Option	Category	Description
WithConsumer¹	Info	Set the consumer label for the lines
AsActiveLow	Level	Treat a low physical line value as active
AsActiveHigh	Level	Treat a high physical line value as active (default)
AsInput	Direction	Request lines as input
AsIs²	Direction	Request lines in their current input/output state (default)
AsOutput(<values>...)³	Direction	Request lines as output with the provided values
AsPushPull	Drive	Request output lines drive both high and low (default)
AsOpenDrain	Drive	Request lines as open drain outputs
AsOpenSource	Drive	Request lines as open source outputs
WithEventHandler(eh)¹		Send edge events detected on requested lines to the provided handler
WithEventBufferSize(num)^1,5		Suggest the minimum number of events that can be stored in the kernel event buffer for the requested lines
WithFallingEdge	Edge Detection³	Request lines with falling edge detection
WithRisingEdge	Edge Detection³	Request lines with rising edge detection
WithBothEdges	Edge Detection³	Request lines with rising and falling edge detection
WithoutEdges⁵	Edge Detection³	Request lines with edge detection disabled (default)
WithBiasAsIs	Bias⁴	Request the lines have their bias setting left unaltered (default)
WithBiasDisabled	Bias⁴	Request the lines have internal bias disabled
WithPullDown	Bias⁴	Request the lines have internal pull-down enabled
WithPullUp	Bias⁴	Request the lines have internal pull-up enabled
WithDebounce(period)⁵	Debounce	Request the lines be debounced with the provided period
WithMonotonicEventClock	Event Clock	Request the timestamp in edge events use the monotonic clock (default)
WithRealtimeEventClock⁶	Event Clock	Request the timestamp in edge events use the realtime clock
WithLines(offsets, options...)^3,5		Specify configuration options for a subset of lines in a request
Defaulted⁵		Reset the configuration for a request to the default configuration, or the configuration of a particular line in a request to the default for that request

The options described as default are generally not required, except to override other options earlier in a chain of configuration options.

¹ Can be applied to either NewChip or Chip.RequestLine, but cannot be used with Line.Reconfigure.

² Can be applied to Chip.RequestLine, but cannot be used with NewChip or Line.Reconfigure.

³ Can be applied to either Chip.RequestLine or Line.Reconfigure, but cannot be used with NewChip.

⁴ Requires Linux 5.5 or later.

⁵ Requires Linux 5.10 or later.

⁶ Requires Linux 5.11 or later.

Installation

On Linux:

go get github.com/warthog618/gpiod

For other platforms, where you intend to cross-compile for Linux, don't attempt to compile the package when it is installed:

go get -d github.com/warthog618/gpiod

Tools

A command line utility, gpiodctl, can be found in the cmd directory and is provided to allow manual or scripted manipulation of GPIO lines. This utility combines the Go equivalent of all the libgpiod command line tools into a single tool.

gpiodctl is a utility to control GPIO lines on Linux GPIO character devices

Usage:
  gpiodctl [flags]
  gpiodctl [command]

Available Commands:
  detect      Detect available GPIO chips
  find        Find a GPIO line by name
  get         Get the state of a line or lines
  help        Help about any command
  info        Info about chip lines
  mon         Monitor the state of a line or lines
  set         Set the state of a line or lines
  version     Display the version
  watch       Watch lines for changes to the line info

Flags:
  -h, --help   help for gpiodctl

Use "gpiodctl [command] --help" for more information about a command.

Tests

The library is fully tested, other than some error cases and sanity checks that are difficult to trigger.

The tests require a kernel release 5.19 or later to run, built with CONFIG_GPIO_SIM set or as a module.

The tests must be run as root, to allow contruction of gpio-sims. They can still be built as an unprivileged user, e.g.

$ go test -c

but must be run as root.

The tests can also be cross-compiled for other platforms. e.g. build tests for a Raspberry Pi using:

$ GOOS=linux GOARCH=arm GOARM=6 go test -c

Later Pis can also use ARM7 (GOARM=7).

Benchmarks

The tests include benchmarks on reads, writes, bulk reads and writes, and interrupt latency.

These are the results from a Raspberry Pi Zero W running Linux 6.4 and built with go1.20.6:

$ ./gpiod.test -test.bench=.*
goos: linux
goarch: arm
pkg: github.com/warthog618/gpiod
BenchmarkChipNewClose     	     248	   4381075 ns/op
BenchmarkLineInfo         	   24651	     47278 ns/op
BenchmarkLineReconfigure  	   20312	     55273 ns/op
BenchmarkLineValue        	   71774	     14933 ns/op
BenchmarkLinesValues      	   54920	     24659 ns/op
BenchmarkLineSetValue     	   73359	     16501 ns/op
BenchmarkLinesSetValues   	   53557	     21056 ns/op
BenchmarkInterruptLatency 	     105	  10407929 ns/op
PASS

The latency benchmark is no longer representative as the measurement now depends on how quickly gpio-sim can toggle lines, and that is considerably slower than how quickly gpiod responds. For comparison, the same test using looped Raspberry Pi lines produced a result of ~640μsec on the same platform.

And on a Raspberry Pi 4 running Linux 6.4 (32bit kernel) and built with go1.20.6:

$ ./gpiod.test -test.bench=.*
goos: linux
goarch: arm
pkg: github.com/warthog618/gpiod
BenchmarkChipNewClose-4       	    9727	    118291 ns/op
BenchmarkLineInfo-4           	  185316	      6104 ns/op
BenchmarkLineReconfigure-4    	  364795	      3205 ns/op
BenchmarkLineValue-4          	 1072785	      1061 ns/op
BenchmarkLinesValues-4        	  816200	      1428 ns/op
BenchmarkLineSetValue-4       	 1015972	      1150 ns/op
BenchmarkLinesSetValues-4     	  715154	      1717 ns/op
BenchmarkInterruptLatency-4   	   18439	     61145 ns/op
PASS

Prerequisites

The library targets Linux with support for the GPIO character device API. That generally means that /dev/gpiochip0 exists.

The caller must have access to the character device - typically /dev/gpiochip0. That is generally root unless you have changed the permissions of that device.

The Bias line options and the Line.Reconfigure method both require Linux 5.5 or later.

Debounce and other uAPI v2 features require Linux 5.10 or later.

The requirements for each configuration option are noted in that section.

Release Notes

v0.8.2

Switch tests from gpio-mockup to gpio-sim.

Drop test dependency on pilebones/go-udev.

Drop example dependency on warthog618/config.

v0.8.1

Add bananapi pin mappings.

Fix config check in gpioset.

v0.8.0

Add top level RequestLine and RequestLines functions to simplify common use cases.

blinker and watcher examples interwork with each other on a Raspberry Pi with a jumper across J8-15 and J8-16.

Fix deadlock in gpiodctl set no-wait.

v0.7.0

LineEvent exposes sequence numbers for uAPI v2 events.

Info tools (gpiodctl info and gpioinfo) report debounce-period.

gpiodctl mon and watcher example report event sequence numbers.

gpiodctl mon supports setting debounce period.

gpiodctl detect reports kernel uAPI version in use.

Watchers use Eventfd instead of pipes to reduce open file descriptors.

Start migrating to Go 1.17 go:build style build tags.

Make licensing REUSE compliant.

v0.6.0

gpiod now supports both the old GPIO uAPI (v1) and the newer (v2) introduced in Linux 5.10. The library automatically detects the available uAPI versions and makes use of the latest.

Applications written for uAPI v1 will continue to work with uAPI v2.

Applications that make use of v2 specific features will return errors when run on Linux kernels prior to 5.10.

Breaking API changes:

The event handler parameter has been moved from edge options into the WithEventHandler(eh) option to allow for reconfiguration of edge detection which is supported in Linux 5.10.

Old edge options should be replaced with the WithEventHandler option and the now parameterless edge option, e.g.:
```
s/gpiod\.WithBothEdges(/gpiod.WithBothEdges, gpiod.WithEventHandler(/g
```
WithBiasDisable is renamed WithBiasDisabled. This option is probably rarely used and the renaming is trivial, so no backward compatibility is provided.
FindLine has been dropped as line names are not guaranteed to be unique. Iterating over the available chips and lines to search for line by name can be easily done - the Chips function provides the list of available chips as a starting point.

Refer to the find command in gpiodctl for example code.

warthog618/gpiod