periph

Peripherals I/O in Go

News

2017-12-21 Towards v3: Polishing the APIs
2017-12-15 🚄 Reaching 80MHz: How we cranked up GPIO performance in v2.1.0
2017-12-15 Announcing v2.1.0: 25x speed bump just in time for 🎄 holidays!
2017-08-28 Announcing v2.0.0: v1.0.0, we barely knew ya!
2017-08-27 One Year!: One year already, what a ride.

boardimage

Overview

periph.io/x/periph is a standalone library with no external dependency to interface with low-level board facilities exposed by the OS or leveraged against OS’ will. It can be viewed as a lower level layer than Gobot, and yes we’re discussing to collaborate in the future!

Features

Documentation

  • platform/ for an overview of supported boards (Raspberry Pi, CHIP, etc) and OSes plus tips and tricks.
  • device/ for an overview of included device drivers and examples. GoDoc
  • project/ to read about design goals, using as a libray, using included tools, contribution rules or expand the list of supported hardware.

Tools

periph includes many ready-to-use tools! See project/tools/ for more info about using the included tools.

# Retrieve and install all the commands at once:
go get periph.io/x/periph/cmd/...
# List the host drivers registered and/or initialized:
periph-info
# List the known headers:
headers-list
# List the known GPIO state:
gpio-list

Library

For application developers, using periph as a library provides OS-independent bus interfacing. It really tries hard to get out of the way. Here’s the canonical “toggle a LED” example:

package main

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

func main() {
    host.Init()
    for l := gpio.Low; ; l = !l {
        gpioreg.ByName("11").Out(l)
        time.Sleep(500 * time.Millisecond)
    }
}

The following are synonyms, use the form you prefer:

This example uses basically no CPU: the Out() call doesn’t call into the kernel, unlike other Go hardware libraries. Instead it directly writes to the GPIO memory mapped register.

Examples

See device/ for more examples.

boardimage

Code

Code is located at github.com/google/periph

Supplemental projects are located at github.com/periph. This includes:

  • The website itself, so you can easily submit a PR to improve the documentation.
  • gohci for hardware smoke testing.
  • periph-tester which is a board used to confirm the buses (I²C, SPI, 1-wire) are correctly working.
  • bootstrap tool to automate the deployment of Raspberry Pis.

Contact

Contributions

periph provides an extensible driver registry and common bus interfaces which are explained in more details at project/. 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 for documentation improvements and from device driver developers via GitHub pull requests, as long as the author has signed the Google Contributor License. Please see project/contributing/ 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.
  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 board.
  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 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.