periph

README

periph - Peripherals I/O in Go

Documentation is at https://periph.io

Join us for a chat on gophers.slack.com/messages/periph, get an invite here.

Example

Blink a LED:

package main

import (
    "time"
    "periph.io/x/periph/conn/gpio"
    "periph.io/x/periph/host"
    "periph.io/x/periph/host/rpi"
)

func main() {
    host.Init()
    for l := gpio.Low; ; l = !l {
        rpi.P1_33.Out(l)
        time.Sleep(500 * time.Millisecond)
    }
}

Curious? Look at supported devices for more examples!

Authors

periph was initiated with ❤️️ and passion by Marc-Antoine Ruel. The full list of contributors is in AUTHORS and CONTRIBUTORS.

Disclaimer

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.

This project is not affiliated with the Go project.

Documentation

Overview

Package periph is a peripheral I/O library.

Package periph acts as a registry of drivers. It is focused on providing high quality host drivers that provide high-speed access to the hardware on the host computer itself.

To learn more about the goals and design, visit https://periph.io/

Every device driver should register itself in its package init() function by calling periph.MustRegister().

User shall call either host.Init() or hostextra.Init() on startup to initialize all the registered drivers.

Cmd

cmd/ contains executable tools to communicate directly with the devices or the buses.

cmd/ is allowed to import from conn/, devices/ and host/.

Conn

conn/ contains interfaces and registries for all the supported protocols and connections (I²C, SPI, GPIO, etc).

conn/ is not allowed to import from any other package.

Devices

devices/ contains devices drivers that are connected to bus, port or connection (i.e I²C, SPI, 1-wire, GPIO) that can be controlled by the host, i.e. ssd1306 (display controller), bm280 (environmental sensor), etc.

devices/ is allowed to import from conn/ and host/.

Experimental

experimental/ contains the drivers that are in the experimental area, not yet considered stable. See https://periph.io/project/#driver-lifetime-management for the process to move drivers out of this area.

experimental/ is allowed to import from conn/, devices/ and host/.

Host

host/ contains all the implementations relating to the host itself, the CPU and buses that are exposed by the host onto which devices can be connected, i.e. I²C, SPI, GPIO, etc.

host/ is allowed to import from conn/ only.

Example

package main

import (
	"fmt"
	"log"

	"periph.io/x/periph/host"
)

func main() {
	// host.Init() registers all the periph-provided host driver automatically,
	// so it is preferable to use than periph.Init().
	//
	// You can also use periph.io/x/extra/hostextra.Init() for additional drivers
	// that depends on cgo and/or third party packages.
	state, err := host.Init()
	if err != nil {
		log.Fatalf("failed to initialize periph: %v", err)
	}

	// Prints the loaded driver.
	fmt.Printf("Using drivers:\n")
	for _, driver := range state.Loaded {
		fmt.Printf("- %s\n", driver)
	}

	// Prints the driver that were skipped as irrelevant on the platform.
	fmt.Printf("Drivers skipped:\n")
	for _, failure := range state.Skipped {
		fmt.Printf("- %s: %s\n", failure.D, failure.Err)
	}

	// Having drivers failing to load may not require process termination. It
	// is possible to continue to run in partial failure mode.
	fmt.Printf("Drivers failed to load:\n")
	for _, failure := range state.Failed {
		fmt.Printf("- %s: %v\n", failure.D, failure.Err)
	}

	// Use pins, buses, devices, etc.
}

Index

• func MustRegister(d Driver)
• func Register(d Driver) error
• type Driver
• type DriverFailure
  • func (d DriverFailure) String() string
• type State
  • func Init() (*State, error)

Examples

• Package

Functions

func MustRegister

func MustRegister(d Driver)

MustRegister calls Register() and panics if registration fails.

This is the function to call in a driver's package init() function.

func Register

func Register(d Driver) error

Register registers a driver to be initialized automatically on Init().

The d.String() value must be unique across all registered drivers.

It is an error to call Register() after Init() was called.

Types

type Driver

type Driver interface {
	// String returns the name of the driver, as to be presented to the user.
	//
	// It must be unique in the list of registered drivers.
	String() string
	// Prerequisites returns a list of drivers that must be successfully loaded
	// first before attempting to load this driver.
	//
	// A driver listing a prerequisite not registered is a fatal failure at
	// initialization time.
	Prerequisites() []string
	// After returns a list of drivers that must be loaded first before
	// attempting to load this driver.
	//
	// Unlike Prerequisites(), this driver will still be attempted even if the
	// listed driver is missing or failed to load.
	//
	// This permits serialization without hard requirement.
	After() []string
	// Init initializes the driver.
	//
	// A driver may enter one of the three following state: loaded successfully,
	// was skipped as irrelevant on this host, failed to load.
	//
	// On success, it must return true, nil.
	//
	// When irrelevant (skipped), it must return false, errors.New(<reason>).
	//
	// On failure, it must return true, errors.New(<reason>). The failure must
	// state why it failed, for example an expected OS provided driver couldn't
	// be opened, e.g. /dev/gpiomem on Raspbian.
	Init() (bool, error)
}

Driver is an implementation for a protocol.

type DriverFailure

type DriverFailure struct {
	D   Driver
	Err error
}

DriverFailure is a driver that wasn't loaded, either because it was skipped or because it failed to load.

func (DriverFailure) String

func (d DriverFailure) String() string

type State

type State struct {
	Loaded  []Driver
	Skipped []DriverFailure
	Failed  []DriverFailure
}

State is the state of loaded device drivers.

Each list is sorted by the driver name.

func Init

func Init() (*State, error)

Init initialises all the relevant drivers.

Drivers are started concurrently.

It is safe to call this function multiple times, the previous state is returned on later calls.

Users will want to use host.Init(), which guarantees a baseline of included host drivers.