periph: Index | Examples | Files | Directories

package periph

import ""

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

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


// You normally want host.Init() instead of periph.Init(), as it registers
// all the periph-provided host drivers automatically.
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.



Package Files


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.


cmd/apa102apa102 writes to a strip of APA102 LED.
cmd/bmxx80bmxx80 reads environmental data from a BMP180/BME280/BMP280.
cmd/gpio-listgpio-list prints out the function of each GPIO pin.
cmd/gpio-readgpio-read reads a GPIO pin.
cmd/gpio-writegpio-write sets a GPIO pin to low or high.
cmd/headers-listheaders-list prints out the headers as found on the computer and print the functionality of each pin.
cmd/i2c-ioi2c-io communicates to an I²C device.
cmd/i2c-listi2c-list lists all I²C buses.
cmd/irir reads from an IR receiver via LIRC.
cmd/ledled reads the state of a LED or change it.
cmd/leptonlepton captures a single image, prints metadata about the camera state or triggers a calibration.
cmd/onewire-listonewire-list lists all onewire buses and devices.
cmd/periph-infoperiph-info prints out information about the loaded periph drivers.
cmd/periph-smoketestperiph-smoketest runs all known smoke tests.
cmd/spi-iospi-io writes to an SPI port data from stdin and outputs to stdout or writes arguments and outputs hex encoded output.
cmd/spi-listspi-list lists all SPI ports.
cmd/ssd1306ssd1306 writes to a display driven by a ssd1306 controler.
cmd/thermalthermal reads the state of thermal sensors exposed via sysfs.
cmd/tm1637tm1637 writes to a digits LED display.
connPackage conn defines core interfaces for protocols and connections.
conn/conntestPackage conntest implements fakes for package conn.
conn/gpioPackage gpio defines digital pins.
conn/gpio/gpioregPackage gpioreg defines a registry for the known digital pins.
conn/gpio/gpiosmoketestPackage gpiosmoketest is leveraged by periph-smoketest to verify that basic GPIO pin functionality work.
conn/gpio/gpiostreamPackage gpiostream defines digital streams.
conn/gpio/gpiostream/gpiostreamtestPackage gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
conn/gpio/gpiotestPackage gpiotest is meant to be used to test drivers using fake Pins.
conn/i2cPackage i2c defines interface to an I²C bus and an I²C device.
conn/i2c/i2cregPackage i2creg defines I²C bus registry to list buses present on the host.
conn/i2c/i2csmoketestPackage i2csmoketest is leveraged by periph-smoketest to verify that an I²C EEPROM device and a DS2483 device can be accessed on an I²C bus.
conn/i2c/i2ctestPackage i2ctest is meant to be used to test drivers over a fake I²C bus.
conn/irPackage ir defines InfraRed codes for use with a IR remote control.
conn/mmrPackage mmr defines helpers to interact with devices exposing Memory Mapped Registers protocol.
conn/onewirePackage onewire defines a Dallas Semiconductor / Maxim Integrated 1-wire bus.
conn/onewire/onewireregPackage onewirereg defines a registry for onewire buses present on the host.
conn/onewire/onewiresmoketestPackage onewiresmoketest is leveraged by periph-smoketest to verify that a 1-wire bus search returns two devices, that a ds18b20 temperature sensor can be read, and that a ds2431 eeprom can be written and read.
conn/onewire/onewiretestPackage onewiretest is meant to be used to test drivers over a fake 1-wire bus.
conn/pinPackage pin declare well known pins.
conn/pin/pinregPackage pinreg is a registry for the physical headers (made up of pins) on a host.
conn/spiPackage spi defines the SPI protocol.
conn/spi/spiregPackage spireg defines the SPI registry for SPI ports discovered on the host.
conn/spi/spismoketestPackage spismoketest is leveraged by periph-smoketest to verify that an EEPROM device can be accessed on a SPI port.
conn/spi/spitestPackage spitest is meant to be used to test drivers over a fake SPI port.
devicesPackage devices contains interfaces for classes of devices.
devices/apa102Package apa102 drives a strip of APA102 LEDs connected on a SPI port.
devices/bmxx80Package bmxx80 controls a Bosch BMP180/BME280/BMP280 device over I²C, or SPI for the BMx280.
devices/bmxx80/bmx280smoketestPackage bmx280smoketest is leveraged by periph-smoketest to verify that two BME280/BMP280, one over I²C, one over SPI, read roughly the same temperature, humidity and pressure.
devices/devicestestPackage devicestest contains non-hardware devices implementations for testing or emulation purpose.
devices/ds18b20Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820 1-wire temperature sensors.
devices/ds248xPackage ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip over I²C.
devices/leptonPackage lepton drivers a FLIR Lepton.
devices/lepton/cciPackage cci declares the Camera Command Interface to interact with a FLIR Lepton over I²C.
devices/lircPackage lirc implements InfraRed receiver support through native linux app lirc.
devices/ssd1306Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306 controller.
devices/ssd1306/image1bitPackage image1bit implements black and white (1 bit per pixel) 2D graphics.
devices/ssd1306/ssd1306smoketestPackage ssd1306smoketest is leveraged by periph-smoketest to verify that two SSD1306, one over I²C, one over SPI, can display the same output.
devices/tm1637Package tm1637 controls a TM1637 device over GPIO pins.
experimental/conn/analogPackage analog defines analog pins, both DAC and ADC.
experimental/conn/uartPackage uart defines the UART protocol.
experimental/conn/uart/uartregPackage uartreg defines the UART registry for UART ports discovered on the host.
experimental/devices/bitbangPackage bitbang implements conn by banging on the bits (GPIO pins).
experimental/devices/cap1188Package cap1188 controls a Microchip cap1188 device over I²C.
experimental/devices/mfrc522Package mfrc522 controls a Mifare RFID card reader.
experimental/devices/nrzledPackage nrzled is a driver for LEDs ws2811/ws2812/ws2812b and compatible devices like sk6812 and ucs1903 that uses a single wire NRZ encoded communication protocol.
experimental/devices/piblasterPackage piblaster implements interfacing code is piblaster.
experimental/driverskeletonPackage driverskeleton is an example that can be copy pasted to help write a new driver, either in devices/ or in host/.
experimental/host/am335xPackage am335x exposes functionality for the Texas Instruments Sitara AM335x processor family.
experimental/host/beaglePackage beagle contains BeagleBoard/BeagleBone board family headers definition.
experimental/host/pruPackage pru exposes the Programmable Real-Time Unit Subsystem and Industrial Communication Subsystem (PRUICSS) functionality found on many Texas Instruments processors.
experimental/host/sysfsPackage sysfs implements experimental sysfs support not yet in mainline.
hostPackage host defines the host itself.
host/allwinnerPackage allwinner exposes the GPIO functionality that is common to all AllWinner processors.
host/allwinner/allwinnersmoketestPackage allwinnersmoketest verifies that allwinner specific functionality work.
host/bcm283xPackage bcm283x exposes the BCM283x GPIO functionality.
host/bcm283x/bcm283xsmoketestPackage bcm283xsmoketest verifies that bcm283x specific functionality work.
host/chipPackage chip contains header definitions for NextThing Co's C.H.I.P.
host/chip/chipsmoketestPackage chipsmoketest is leveraged by periph-smoketest to verify that basic CHIP specific functionality works.
host/cpuPackage cpu implements functions relating to the host CPU itself.
host/distroPackage distro implements common functionality to auto-detect features on the host; generally about linux distributions.
host/fsPackage fs provides access to the file system on the host.
host/odroidc1Package odroidc1 contains header definitions for Hardkernel's ODROID C0, C1, and C1+ boards.
host/odroidc1/odroidc1smoketestPackage odroidc1smoketest is leveraged by periph-smoketest to verify that basic ODROID-C1 specific functionality works.
host/pine64Package pine64 contains Pine64 hardware logic.
host/pmemPackage pmem implements handling of physical memory for user space programs.
host/rpiPackage rpi contains Raspberry Pi hardware logic.
host/sysfsPackage sysfs implements a sane library to interact with sysfs provided hardware access.
host/sysfs/sysfssmoketestPackage sysfssmoketest verifies that sysfs specific functionality work.
host/videocorePackage videocore interacts with the VideoCore GPU found on bcm283x.

Package periph imports 4 packages (graph) and is imported by 25 packages. Updated 2018-03-18. Refresh now. Tools for package owners.