periph: Index | Examples | Files | Directories

package gpio

import ""

Package gpio defines digital pins.

While all GPIO implementations are expected to implement PinIO, they may expose more specific functionality like PinPWM, PinDefaultPull, etc.



Package Files


type Duty Uses

type Duty int32

Duty is the duty cycle for a PWM.

Valid values are between 0 and DutyMax.

const (
    // DutyMax is a duty cycle of 100%.
    DutyMax Duty = 65535
    // DutyHalf is a 50% duty PWM, which boils down to a normal clock.
    DutyHalf Duty = DutyMax / 2

func ParseDuty Uses

func ParseDuty(s string) (Duty, error)

ParseDuty parses a string and converts it to a Duty value.

func (Duty) String Uses

func (d Duty) String() string

func (Duty) Valid Uses

func (d Duty) Valid() bool

Valid returns true if the Duty cycle value is valid.

type Edge Uses

type Edge int

Edge specifies if an input pin should have edge detection enabled.

Only enable it when needed, since this causes system interrupts.

const (
    NoEdge      Edge = 0
    RisingEdge  Edge = 1
    FallingEdge Edge = 2
    BothEdges   Edge = 3

Acceptable edge detection values.

func (Edge) String Uses

func (i Edge) String() string

type Level Uses

type Level bool

Level is the level of the pin: Low or High.

const (
    // Low represents 0v.
    Low Level = false
    // High represents Vin, generally 3.3v or 5v.
    High Level = true

func (Level) String Uses

func (l Level) String() string

type PinDefaultPull Uses

type PinDefaultPull interface {
    // DefaultPull returns the pull that is initialized on CPU reset.
    DefaultPull() Pull

PinDefaultPull is optionally implemented to return the default pull at boot time. This is useful to determine if the pin is acceptable for operation with certain devices.

type PinIO Uses

type PinIO interface {
    // PinIn
    In(pull Pull, edge Edge) error
    Read() Level
    WaitForEdge(timeout time.Duration) bool
    Pull() Pull
    // PinOut
    Out(l Level) error

PinIO is a GPIO pin that supports both input and output. It matches both interfaces PinIn and PinOut.

A GPIO pin implementing PinIO may fail at either input or output or both.

The GPIO pin may optionally support more interfaces, like PinPWM, PinDefaultPull.


INVALID implements PinIO and fails on all access.

type PinIn Uses

type PinIn interface {
    // In setups a pin as an input.
    // If WaitForEdge() is planned to be called, make sure to use one of the Edge
    // value. Otherwise, use None to not generated unneeded hardware interrupts.
    // Calling In() will try to empty the accumulated edges but it cannot be 100%
    // reliable due to the OS (linux) and its driver. It is possible that on a
    // gpio that is as input, doing a quick Out(), In() may return an edge that
    // occurred before the Out() call.
    In(pull Pull, edge Edge) error
    // Read return the current pin level.
    // Behavior is undefined if In() wasn't used before.
    // In some rare case, it is possible that Read() fails silently. This happens
    // if another process on the host messes up with the pin after In() was
    // called. In this case, call In() again.
    Read() Level
    // WaitForEdge() waits for the next edge or immediately return if an edge
    // occurred since the last call.
    // Only waits for the kind of edge as specified in a previous In() call.
    // Behavior is undefined if In() with a value other than None wasn't called
    // before.
    // Returns true if an edge was detected during or before this call. Return
    // false if the timeout occurred or In() was called while waiting, causing the
    // function to exit.
    // Multiple edges may or may not accumulate between two calls to
    // WaitForEdge(). The behavior in this case is undefined and is OS driver
    // specific.
    // It is not required to call Read() to reset the edge detection.
    // Specify -1 to effectively disable timeout.
    WaitForEdge(timeout time.Duration) bool
    // Pull returns the internal pull resistor if the pin is set as input pin.
    // Returns PullNoChange if the value cannot be read.
    Pull() Pull

PinIn is an input GPIO pin.

It may optionally support internal pull resistor and edge based triggering.


//p := gpioreg.ByName("GPIO6")
var p PinIn
if err := p.In(PullDown, RisingEdge); err != nil {
fmt.Printf("%s is %s\n", p, p.Read())
for p.WaitForEdge(-1) {
    fmt.Printf("%s went %s\n", p, High)

type PinOut Uses

type PinOut interface {
    // Out sets a pin as output if it wasn't already and sets the initial value.
    // After the initial call to ensure that the pin has been set as output, it
    // is generally safe to ignore the error returned.
    // Out() tries to empty the accumulated edges detected if the gpio was
    // previously set as input but this is not 100% guaranteed due to the OS.
    Out(l Level) error

PinOut is an output GPIO pin.


//p := gpioreg.ByName("GPIO6")
var p PinOut
if err := p.Out(High); err != nil {

type PinPWM Uses

type PinPWM interface {
    // PWM sets the PWM output on supported pins.
    // To use as a general purpose clock, set duty to DutyHalf. Some pins may
    // only support DutyHalf and no other value.
    // Using 0 as period will use the optimal value as supported/preferred by the
    // pin.
    PWM(duty Duty, period time.Duration) error

PinPWM exposes hardware PWM.

The driver may uses DMA controller underneath for zero CPU implementation.

type Pull Uses

type Pull uint8

Pull specifies the internal pull-up or pull-down for a pin set as input.

const (
    Float        Pull = 0 // Let the input float
    PullDown     Pull = 1 // Apply pull-down
    PullUp       Pull = 2 // Apply pull-up
    PullNoChange Pull = 3 // Do not change the previous pull resistor setting or an unknown value

Acceptable pull values.

func (Pull) String Uses

func (i Pull) String() string

type RealPin Uses

type RealPin interface {
    Real() PinIO // Real returns the real pin behind an Alias

RealPin is implemented by aliased pin and allows the retrieval of the real pin underlying an alias.

The purpose of the RealPin is to be able to cleanly test whether an arbitrary gpio.PinIO returned by ByName is really an alias for another pin.


gpioregPackage gpioreg defines a registry for the known digital pins.
gpiosmoketestPackage gpiosmoketest is leveraged by periph-smoketest to verify that basic GPIO pin functionality work.
gpiostreamPackage gpiostream defines digital streams.
gpiostream/gpiostreamtestPackage gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
gpiotestPackage gpiotest is meant to be used to test drivers using fake Pins.

Package gpio imports 6 packages (graph) and is imported by 60 packages. Updated 2018-01-03. Refresh now. Tools for package owners.