devices/README.md

periph - Peripherals I/O in Go

Features

• Continuously tested on Raspberry Pi, C.H.I.P. and Windows 10 via gohci.
• Interfaces: I²C, SPI, gpio (both low latency memory mapped registers and zero-CPU edge detection), 1-wire and more.
• Devices: apa102, bme280, ds18b20, ssd1306, tm1637, and more coming.

Quick links

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

# 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

Application developers

For application developers, periph provides OS-independent bus interfacing. It really tries hard to get out of the way. Here's the canonical "toggle a LED" sample:

package main

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

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

The following are synonyms, use the form you prefer:

• Runtime discovery:
  • gpio.ByNumber(13) or gpio.ByName("13")
  • gpio.ByName("GPIO13")
• Using global variables:
  • rpi.P1_33 to select the pin via its position on the board
  • bcm283x.GPIO13

This example uses basically no CPU: the Out() call doesn't call into the kernel. Instead it directly changes the GPIO memory mapped register.

Samples

See doc/apps/samples/ 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 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 doc/drivers/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.
   • 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.