periph - Peripherals I/O in Go

• doc/users/ for ready-to-use tools.
• doc/apps/ to use periph as a library. The complete API documentation, including examples, is at .
• doc/drivers/ to expand the list of supported hardware.

Users

periph includes many ready-to-use tools! See doc/users/ for more info on configuring the host and using the included tools.

go get github.com/google/periph/cmd/...
periph-info
headers-list

Application developers

For application developers, periph provides OS-independent bus interfacing. The following gets the current temperature, barometric pressure and relative humidity using a bme280:

package main

import (
    "fmt"
    "log"

    "github.com/google/periph/devices"
    "github.com/google/periph/devices/bme280"
    "github.com/google/periph/host"
)

func main() {
    // Load all the drivers:
    if _, err := host.Init(); err != nil {
        log.Fatal(err)
    }

    // Open a handle to the first available I²C bus. It could be via a FT232H
    // over USB or an I²C bus exposed on the host's headers, it doesn't matter.
    bus, err := i2c.New(-1)
    if err != nil {
        log.Fatal(err)
    }
    defer bus.Close()

    // Open a handle to a bme280 connected on the I²C bus using default settings:
    dev, err := bme280.NewI2C(bus, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer dev.Close()

    // Read temperature from the sensor:
    var env devices.Environment
    if err = dev.Sense(&env); err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%8s %10s %9s\n", env.Temperature, env.Pressure, env.Humidity)
}

Samples

See doc/apps/SAMPLES.md for more examples.

Contributions

periph provides an extensible driver registry and common bus interfaces which are explained in more details at doc/drivers/. periph is designed to work well with drivers living in external repositories so you are not required to fork the periph repository to load out-of-tree drivers for your platform.

Every commit is tested on real hardware via gohci workers.

We gladly accept contributions from device driver developers via GitHub pull requests, as long as the author has signed the Google Contributor License. Please see doc/drivers/CONTRIBUTING.md for more details.

Philosophy

1. Optimize for simplicity, correctness and usability in that order.
   • e.g. everything, interfaces and structs, uses strict typing, there's no interface{} in sight.
2. OS agnostic. Clear separation of interfaces in conn/, enablers in host/ and device drivers in devices/.
   • e.g. no devfs or sysfs path in sight.
   • e.g. conditional compilation enables only the relevant drivers to be loaded on each platform.
3. ... yet doesn't get in the way of platform specific code.
   • e.g. A user can use statically typed global variables rpi.P1_3, bcm283x.GPIO2 to refer to the exact same pin on a Raspberry Pi.
4. The user can chose to optimize for performance instead of usability.
   • e.g. apa102.Dev exposes both high level draw.Image to draw an image and low level io.Writer to write raw RGB 24 bits pixels. The user chooses.
5. Use a divide and conquer approach. Each component has exactly one responsibility.
   • e.g. instead of having a driver per "platform", there's a driver per "component": one for the CPU, one for the board headers, one for each bus and sensor, etc.
6. Extensible via a driver registry.
   • e.g. a user can inject a custom driver to expose more pins, headers, etc. A USB device (like an FT232H) can expose headers in addition to the headers found on the host.
7. The drivers must use the fastest possible implementation.
   • e.g. both allwinner and bcm283x leverage sysfs gpio to expose interrupt driven edge detection, yet use memory mapped GPIO registers to perform single-cycle reads and writes.

Authors

Periph was initiated 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.