package periph

import "periph.io/x/periph"

Package periph is a peripheral I/O library.

It contains host and device drivers, and test packages to emulate the hardware.

You will find API documentation in godoc, to learn more about the goals and design, visit https://periph.io/

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.

It is less concerned about implementing all possible device drivers that may be attached to the host's I²C, SPI, or other buses and pio pins.

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

The user must call periph.Init() on startup to initialize all the registered drivers in the correct order all at once.

→ cmd/ contains executables to communicate directly with the devices or the buses using raw protocols.

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

→ devices/ contains devices drivers that are connected to a bus (i.e I²C, SPI, GPIO) that can be controlled by the host, i.e. ssd1306 (display controller), bm280 (environmental sensor), etc. 'devices' contains the interfaces and subpackages contain contain concrete types.

→ 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.

→ 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' contains the interfaces and subpackages contain contain concrete types.

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 ¶

• Init

Package Files ¶

periph.go

func MustRegister ¶ Uses

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 ¶ Uses

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.

type Driver ¶ Uses

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
    // 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 ¶ Uses

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 ¶ Uses

func (d DriverFailure) String() string

type State ¶ Uses

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 ¶ Uses

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.

// You probably want host.Init() instead as it registers all the
// periph-provided host drivers automatically.
state, err := Init()
if err != nil {
    log.Fatalf("failed to initialize periph: %v", err)
}
fmt.Printf("Using drivers:\n")
for _, driver := range state.Loaded {
    fmt.Printf("- %s\n", driver)
}
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.

Directories ¶