gpio

package
v3.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2025 License: Apache-2.0 Imports: 7 Imported by: 300

Documentation

Overview

Package gpio defines digital pins.

All GPIO implementations are expected to implement PinIO but the device driver may accept a more specific one like PinIn or PinOut.

Example 
package main

import (
	"fmt"
	"log"

	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/gpio/gpioreg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Use gpioreg GPIO pin registry to find a GPIO pin by name.
	p := gpioreg.ByName("GPIO6")
	if p == nil {
		log.Fatal("Failed to find GPIO6")
	}

	// A pin can be read, independent of its state; it doesn't matter if it is
	// set as input or output.
	fmt.Printf("%s is %s\n", p, p.Read())
}

Output:

Index

Examples

Constants

View Source 
const (
	// Inputs
	IN      pin.Func = "IN"      // Input
	IN_HIGH pin.Func = "In/High" // Read high
	IN_LOW  pin.Func = "In/Low"  // Read low

	// Outputs
	OUT      pin.Func = "OUT"      // Output, drive
	OUT_OC   pin.Func = "OUT_OPEN" // Output, open collector/drain
	OUT_HIGH pin.Func = "Out/High" // Drive high
	OUT_LOW  pin.Func = "Out/Low"  // Drive low; open collector low

	FLOAT pin.Func = "FLOAT" // Input float or Output open collector high

	CLK pin.Func = "CLK" // Clock is a subset of a PWM, with a 50% duty cycle
	PWM pin.Func = "PWM" // Pulse Width Modulation, which is a clock with variable duty cycle
)

Well known pin functionality.

Variables

View Source 
var ErrGroupFeatureNotImplemented = errors.New("gpio group feature not implemented")

Implementations that don't implement specific interface methods should return ErrGroupFeatureNotImplemented as the error to allow clients to generically check for the condition.

Functions

This section is empty.

Types

type Duty 

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 = 1 << 24
	// DutyHalf is a 50% duty PWM, which boils down to a normal clock.
	DutyHalf Duty = DutyMax / 2
)

func ParseDuty 

func ParseDuty(s string) (Duty, error)

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

Example 
package main

import (
	"fmt"
	"log"

	"periph.io/x/conn/v3/gpio"
)

func main() {
	d, err := gpio.ParseDuty("33%")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(d)
}

Output:

33%

func (Duty) String 

func (d Duty) String() string

func (Duty) Valid 

func (d Duty) Valid() bool

Valid returns true if the Duty cycle value is valid.

type Edge 

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 

func (i Edge) String() string

type GPIOValue added in v3.7.2 

type GPIOValue uint64

type Group added in v3.7.2 

type Group interface {
	// The set of GPIO pins that make up this group. Implementations will
	// typically Use gpio.PinIO, gpio.PinIn, or gpio.PinOut as the actual return
	// value type.
	Pins() []pin.Pin
	// Given a specific pin offset within the group, return that pin.
	// For example, a pin group may be GPIO pins 3,5,7,9 in that order.
	// ByOffset(1) returns GPIO pin 5.
	ByOffset(offset int) pin.Pin
	// Given the unique name of a GPIO pin, return that pin.
	ByName(name string) pin.Pin
	// Given the specific GPIO pin number, return the corresponding
	// pin from the group.
	ByNumber(number int) pin.Pin
	// Out writes the specified bitwise value to the pins. Bit 0 corresponds to
	// the first pin in the set, bit 1 the second, etc. Only pins within the
	// group that have mask bit set are modified. For example, if you have 8
	// pins within the group and you want to write the value 0x0a to the lower
	// 4 pins, you would use a mask of 0x0f.
	//
	// If the device doesn't support write operations, implementations should
	// return gpio.ErrGroupFeatureNotImplemented.
	Out(value, mask GPIOValue) error
	// Read reads the pins within the group, and returns the  value, ANDed with
	// mask. If the device doesn't support read operations, implementations
	// should return gpio.ErrGroupFeatureNotImplemented.
	Read(mask GPIOValue) (GPIOValue, error)
	// WaitForEdge blocks for a GPIO line change event to happen. If the does
	// not implement gpio.PinIn, or doesn't support this capability,
	// implementations should return gpio.ErrGroupFeatureNotImplemented.
	//
	// Number is the GPIO pin number within the group that had an edge change.
	WaitForEdge(timeout time.Duration) (number int, edge Edge, err error)
	// conn.Resource brings in resource.Halt(), and fmt.Stringer
	conn.Resource
}

Group is an interface that an IO device can implement to manipulate multiple IO Pins at one time. Performing GPIO Operations in this manner can dramatically simplify code and reduce IO Operation latency.

Device specific code can also provide methods that return a Group that operates on a subset of the pins the device supports.

type Level 

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 

func (l Level) String() string

type PinIO 

type PinIO interface {
	pin.Pin
	// PinIn
	In(pull Pull, edge Edge) error
	Read() Level
	WaitForEdge(timeout time.Duration) bool
	Pull() Pull
	DefaultPull() Pull
	// PinOut
	Out(l Level) error
	PWM(duty Duty, f physic.Frequency) 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. 

var INVALID PinIO

INVALID implements PinIO and fails on all access.

type PinIn 

type PinIn interface {
	pin.Pin
	// 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 NoEdge 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 NoEdge 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
	// DefaultPull returns the pull that is initialized on CPU/device reset. This
	// is useful to determine if the pin is acceptable for operation with
	// certain devices.
	DefaultPull() Pull
}

PinIn is an input GPIO pin.

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

A button is semantically a PinIn. So if you are looking to read from a button, PinIn is the interface you are looking for.

Example 
package main

import (
	"fmt"
	"log"

	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/gpio"
	"periph.io/x/conn/v3/gpio/gpioreg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Use gpioreg GPIO pin registry to find a GPIO pin by name.
	p := gpioreg.ByName("GPIO6")
	if p == nil {
		log.Fatal("Failed to find GPIO6")
	}

	// Set it as input, with a pull down (defaults to Low when unconnected) and
	// enable rising edge triggering.
	if err := p.In(gpio.PullDown, gpio.RisingEdge); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s is %s\n", p, p.Read())

	// Wait for rising edges (Low -> High) and print when one occur.
	for p.WaitForEdge(-1) {
		fmt.Printf("%s went %s\n", p, gpio.High)
	}
}

Output:

type PinOut 

type PinOut interface {
	pin.Pin
	// 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
	// PWM sets the PWM output on supported pins, if the pin has hardware PWM
	// support.
	//
	// To use as a general purpose clock, set duty to DutyHalf. Some pins may
	// only support DutyHalf and no other value.
	//
	// Using 0 as frequency will use the optimal value as supported/preferred by
	// the pin.
	//
	// To use as a servo, see https://en.wikipedia.org/wiki/Servo_control as an
	// explanation how to calculate duty.
	PWM(duty Duty, f physic.Frequency) error
}

PinOut is an output GPIO pin.

A LED, a buzzer, a servo, are semantically a PinOut. So if you are looking to control these, PinOut is the interface you are looking for.

Example 
package main

import (
	"log"

	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/gpio"
	"periph.io/x/conn/v3/gpio/gpioreg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Use gpioreg GPIO pin registry to find a GPIO pin by name.
	p := gpioreg.ByName("GPIO6")
	if p == nil {
		log.Fatal("Failed to find GPIO6")
	}

	// Set the pin as output High.
	if err := p.Out(gpio.High); err != nil {
		log.Fatal(err)
	}
}

Output:
Example (PWM) 
package main

import (
	"log"

	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/gpio"
	"periph.io/x/conn/v3/gpio/gpioreg"
	"periph.io/x/conn/v3/physic"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Use gpioreg GPIO pin registry to find a GPIO pin by name.
	p := gpioreg.ByName("GPIO6")
	if p == nil {
		log.Fatal("Failed to find GPIO6")
	}

	// Generate a 33% duty cycle 10KHz signal.
	if err := p.PWM(gpio.DutyMax/3, 10*physic.KiloHertz); err != nil {
		log.Fatal(err)
	}
}

Output:

type Pull 

type Pull uint8

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

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

Acceptable pull values.

func (Pull) String 

func (i Pull) String() string

type RealPin 

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.

Aliases are created by RegisterAlias. Aliases permits presenting a user friendly GPIO pin name while representing the underlying real pin.

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

Example 
package main

import (
	"fmt"
	"log"

	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/gpio"
	"periph.io/x/conn/v3/gpio/gpioreg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Use gpioreg GPIO pin registry to find a GPIO pin by name.
	p := gpioreg.ByName("P1_3")
	if p == nil {
		log.Fatal("Failed to find P1_3")
	}
	fmt.Printf("P1_3: %s", p)

	// Resolve the real underlying pin.
	if r, ok := p.(gpio.RealPin); ok {
		// On Raspberry Pis, pin #3 on header P1 is an alias for GPIO2.
		fmt.Printf("%s is in fact %s", p, r.Real())
	} else {
		log.Printf("%s is not an alias", p)
	}
}

Output:

Source Files

View all Source files

Directories

Path Synopsis
Package gpioreg defines a registry for the known digital pins.
 Package gpioreg defines a registry for the known digital pins.
Package gpiostream defines digital streams.
 Package gpiostream defines digital streams.
gpiostreamtest
Package gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
 Package gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
Package gpiotest is meant to be used to test drivers using fake Pins.
 Package gpiotest is meant to be used to test drivers using fake Pins.
Package gpioutil includes utilities to filter or augment GPIOs.
 Package gpioutil includes utilities to filter or augment GPIOs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.