gpio

README

gpio

Golang implementation of linux GPIO interface.

Features

• Pure go. No C code. Easy to cross compile(Write code on PC or Mac and deploy the binary on Raspberry Pi etc.).

• Go style API. Receiving GPIO edge events through go channels. Write go code, NOT write c doe with go syntax.

• Full implementation of linux GPIO character device interface. Chip info, line info, reading/setting values, active low, open drain, open source, edge events...

• Tested (on my really old Raspberry Pi Model B Rev 2).

• Linux GPIO tools(tools/gpio), aka. lsgpio, gpio-event-mon and gpio-hammer, implemented in go. Serve both as code examples and diagnostic tools. See samples directory.

• Legacy GPIO sysfs interface(aka. /sys/class/gpio) supporting. See gpiosysfs package.

Requirements

• Go1.13+

• Linux 4.8+ with GPIO interface to deploy and test.

Troubleshooting

• build .: cannot find module for path . , undefined: gpio.OpenChip or something like that:

  If you get this error message from go build when building the samples or your own project, you probably need to use GOOS=linux GOARCH=arm GOARM=6 go build or something like that.

• bash: ./lsgpio: cannot execute binary file:

  If your shell complains, please run the binary(lsgpio in this example) on linux.

• failed to set direction of GPIO pin #N: open /sys/class/gpio/gpioN/direction: permission denied:

  The legacy GPIO sysfs interface may need root privilege to operate. Try sudo.

Documentation

Overview

Package gpio implements linux GPIO character device interface.

Ref: https://www.kernel.org/doc/Documentation/gpio/gpio.txt

Index

• Constants
• func ChipDevices() (chips []string)
• type Chip
  • func OpenChip(device string) (chip *Chip, err error)
  • func (c *Chip) Close() (err error)
  • func (c *Chip) Info() (info ChipInfo, err error)
  • func (c *Chip) LineInfo(offset uint32) (info LineInfo, err error)
  • func (c *Chip) OpenLine(offset uint32, defaultValue byte, flags LineFlag, consumer string) (line *Line, err error)
  • func (c *Chip) OpenLineWithEvents(offset uint32, flags LineFlag, eventFlags EventFlag, consumer string) (line *LineWithEvent, err error)
  • func (c *Chip) OpenLines(offsets []uint32, defaultValues []byte, flags LineFlag, consumer string) (*Lines, error)
• type ChipInfo
• type Event
• type EventFlag
• type Line
  • func (l *Line) Close() (err error)
  • func (l *Line) SetValue(value byte) (err error)
  • func (l *Line) Value() (value byte, err error)
• type LineFlag
• type LineInfo
  • func (info *LineInfo) ActiveLow() bool
  • func (info *LineInfo) Kernel() bool
  • func (info *LineInfo) OpenDrain() bool
  • func (info *LineInfo) OpenSource() bool
  • func (info *LineInfo) Output() bool
• type LineWithEvent
  • func (l *LineWithEvent) Close() (err error)
  • func (l *LineWithEvent) Events() <-chan *Event
  • func (l *LineWithEvent) Value() (value byte, err error)
• type Lines
  • func (l *Lines) Close() (err error)
  • func (l *Lines) SetValues(values []byte) (err error)
  • func (l *Lines) Values() (values []byte, err error)

Constants

const (
	// Direction input.
	Input = LineFlag(sys.GPIOHANDLE_REQUEST_INPUT)
	// Direction output.
	Output = LineFlag(sys.GPIOHANDLE_REQUEST_OUTPUT)
	// ActiveLow inverts the value for writing.
	ActiveLow LineFlag = LineFlag(sys.GPIOHANDLE_REQUEST_ACTIVE_LOW)
	// OpenDrain
	//
	// https://embeddedartistry.com/blog/2018/6/4/demystifying-microcontroller-gpio-settings#open-drain-output=
	// "Unlike push-pull, an open-drain output can only sink current. The output has two states: low and high-impedance.
	// In order to achieve a logical high output on the line, a pull-up resistor is used to connect the open-drain output
	// to the desired output voltage level.
	// You can think of an open-drain GPIO as behaving like a switch which is either connected to ground or disconnected."
	OpenDrain  = LineFlag(sys.GPIOHANDLE_REQUEST_OPEN_DRAIN)
	OpenSource = LineFlag(sys.GPIOHANDLE_REQUEST_OPEN_SOURCE)
)

const (
	RisingEdge  EventFlag = EventFlag(sys.GPIOEVENT_REQUEST_RISING_EDGE)
	FallingEdge           = EventFlag(sys.GPIOEVENT_EVENT_FALLING_EDGE)
	BothEdges             = RisingEdge | FallingEdge
)

Functions

func ChipDevices

func ChipDevices() (chips []string)

ChipDevices returns all available GPIO chip devices. The returned paths can be used to call OpenChip.

Types

type Chip

type Chip struct {
	// contains filtered or unexported fields
}

Chip is certain GPIO chip.

func OpenChip

func OpenChip(device string) (chip *Chip, err error)

OpenChip opens a certain GPIO chip device.

func (*Chip) Close

func (c *Chip) Close() (err error)

func (*Chip) Info

func (c *Chip) Info() (info ChipInfo, err error)

Info returns the information of this GPIO chip.

func (*Chip) LineInfo

func (c *Chip) LineInfo(offset uint32) (info LineInfo, err error)

LineInfo returns the information about a certain GPIO line. Offset is the local line offset on this GPIO chip.

func (*Chip) OpenLine

func (c *Chip) OpenLine(offset uint32, defaultValue byte, flags LineFlag, consumer string) (line *Line, err error)

OpenLine opens a single GPIO line on this chip. It is equivalent to call OpenLines with a single offset and devault value if Output is set.

func (*Chip) OpenLineWithEvents

func (c *Chip) OpenLineWithEvents(offset uint32, flags LineFlag, eventFlags EventFlag, consumer string) (line *LineWithEvent, err error)

OpenLineWithEvents opens a single GPIO line on this chip for input and GPIO events.

func (*Chip) OpenLines

func (c *Chip) OpenLines(offsets []uint32, defaultValues []byte, flags LineFlag, consumer string) (*Lines, error)

OpenLines opens up to 64 lines on this GPIO chip at once. Parameter offsets are the local line offsets on this chip. Parameter defaultValues specifies the default output values, if Output is set in flags. Value should be 0 (low) or 1 (high), anything else than 0 be interpreted as 1 (high). DefaultValues is ignored if Output is not set in flags. If there are more default values than requested output lines, the extra values will be discarded, and if there are less values, the missing values will be 0s. Parameter flags is or'ed LineFlag values that will be applied to all quested lines. Parameter consumer is a desired consumer label for the selected GPIO line(s) such as "my-bitbanged-relay".

type ChipInfo

type ChipInfo struct {
	// The Linux kernel name of this GPIO chip.
	Name string
	// A functional name for this GPIO chip, such as a product number, may be empty.
	Label string
	// Number of GPIO lines on this chip.
	NumLines uint32
}

ChipInfo is the information about a certain GPIO chip.

type Event

type Event = fdevents.Event

type EventFlag

type EventFlag uint32

type Line

type Line Lines

Line is an opened GPIO line.

func (*Line) Close

func (l *Line) Close() (err error)

func (*Line) SetValue

func (l *Line) SetValue(value byte) (err error)

SetValue sets the value of the GPIO line. Value should be 0 (low) or 1 (high), anything else than 0 will be interpreted as 1 (high).

func (*Line) Value

func (l *Line) Value() (value byte, err error)

Value returns the current value of the GPIO line. 1 (high) or 0 (low).

type LineFlag

type LineFlag uint32

type LineInfo

type LineInfo struct {
	// The offset of this line on the chip.
	Offset uint32
	// The name of this GPIO line, such as the output pin of the line on the
	// chip, a rail or a pin header name on a board, as specified by the gpio
	// chip, may be empty.
	Name string
	// A functional name for the consumer of this GPIO line as set by
	// whatever is using it, will be empty if there is no current user but may
	// also be empty if the consumer doesn't set this up.
	Consumer string
	// contains filtered or unexported fields
}

LineInfo represents the information about a certain GPIO line

func (*LineInfo) ActiveLow

func (info *LineInfo) ActiveLow() bool

ActiveLow returns whether the GPIO line is configured as active low.

func (*LineInfo) Kernel

func (info *LineInfo) Kernel() bool

Kernel returns whether the GPIO line is used by the kernel.

func (*LineInfo) OpenDrain

func (info *LineInfo) OpenDrain() bool

ActiveLow returns whether the GPIO line is configured as open-drain.

func (*LineInfo) OpenSource

func (info *LineInfo) OpenSource() bool

ActiveLow returns whether the GPIO line is configured as open-source.

func (*LineInfo) Output

func (info *LineInfo) Output() bool

Output returns whether the GPIO line is output.

type LineWithEvent

type LineWithEvent struct {
	// contains filtered or unexported fields
}

LineWithEvent is an opened GPIO line whose events can be subscribed.

func (*LineWithEvent) Close

func (l *LineWithEvent) Close() (err error)

func (*LineWithEvent) Events

func (l *LineWithEvent) Events() <-chan *Event

Events returns a channel from which the occurrence time of GPIO events can be read. The GPIO events of this line will be sent to the returned channel, and the channel is closed when l is closed.

Package gpio will not block sending to the channel: it only keeps the lastest value in the channel.

func (*LineWithEvent) Value

func (l *LineWithEvent) Value() (value byte, err error)

Value returns the current value of the GPIO line. 1 (high) or 0 (low).

type Lines

type Lines struct {
	// contains filtered or unexported fields
}

Lines is a batch of opened GPIO lines.

func (*Lines) Close

func (l *Lines) Close() (err error)

func (*Lines) SetValues

func (l *Lines) SetValues(values []byte) (err error)

SetValue sets the value of the GPIO line. Value should be 0 (low) or 1 (high), anything else than 0 will be interpreted as 1 (high).

func (*Lines) Values

func (l *Lines) Values() (values []byte, err error)

Values returns the current values of the GPIO lines. 1 (high) or 0 (low).