periph

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2017 License: Apache-2.0 Imports: 4 Imported by: 0

README

periph - Peripherals I/O in Go

mascot

Documentation is at https://periph.io

GoDoc Go Report Card Coverage Status Build Status Gitter chat

Example

package main

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

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

Curious? Look at supported devices for more examples!

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.

Documentation

Overview

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 doc/drivers/DESIGN.md 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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func MustRegister

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

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.

Types

type Driver

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

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

func (d DriverFailure) String() string

type State

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

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.

Example
// 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.
Output:

Directories

Path Synopsis
cmd
apa102
apa102 writes to a strip of APA102 LED.
apa102 writes to a strip of APA102 LED.
bme280
bme280 reads environmental data from a BME280.
bme280 reads environmental data from a BME280.
gpio-list
gpio-list prints out the function of each GPIO pin.
gpio-list prints out the function of each GPIO pin.
gpio-read
gpio-read reads a GPIO pin.
gpio-read reads a GPIO pin.
gpio-write
gpio-write sets a GPIO pin to low or high.
gpio-write sets a GPIO pin to low or high.
headers-list
headers-list prints out the headers as found on the computer and print the functionality of each pin.
headers-list prints out the headers as found on the computer and print the functionality of each pin.
i2c-io
i2c-io communicates to an I²C device.
i2c-io communicates to an I²C device.
i2c-list
i2c-list lists all I²C buses.
i2c-list lists all I²C buses.
ir
ir reads from an IR receiver via LIRC.
ir reads from an IR receiver via LIRC.
led
led reads the state of a LED or change it.
led reads the state of a LED or change it.
lepton
lepton captures a single image, prints metadata about the camera state or triggers a calibration.
lepton captures a single image, prints metadata about the camera state or triggers a calibration.
periph-info
periph-info prints out information about the loaded periph drivers.
periph-info prints out information about the loaded periph drivers.
periph-smoketest
periph-smoketest runs all known smoke tests.
periph-smoketest runs all known smoke tests.
spi-io
spi-io writes to an SPI port data from stdin and outputs to stdout or writes arguments and outputs hex encoded output.
spi-io writes to an SPI port data from stdin and outputs to stdout or writes arguments and outputs hex encoded output.
spi-list
spi-list lists all SPI ports.
spi-list lists all SPI ports.
ssd1306
ssd1306 writes to a display driven by a ssd1306 controler.
ssd1306 writes to a display driven by a ssd1306 controler.
thermal
thermal reads the state of thermal sensors exposed via sysfs.
thermal reads the state of thermal sensors exposed via sysfs.
tm1637
tm1637 writes to a digits LED display.
tm1637 writes to a digits LED display.
Package conn defines core interfaces for protocols and connections.
Package conn defines core interfaces for protocols and connections.
conntest
Package conntest implements fakes for package conn.
Package conntest implements fakes for package conn.
gpio
Package gpio defines digital pins.
Package gpio defines digital pins.
gpio/gpioreg
Package gpioreg defines a registry for the known digital pins.
Package gpioreg defines a registry for the known digital pins.
gpio/gpiosmoketest
Package gpiosmoketest is leveraged by periph-smoketest to verify that basic GPIO pin functionality work.
Package gpiosmoketest is leveraged by periph-smoketest to verify that basic GPIO pin functionality work.
gpio/gpiostream
Package gpiostream defines digital streams.
Package gpiostream defines digital streams.
gpio/gpiotest
Package gpiotest is meant to be used to test drivers using fake Pins.
Package gpiotest is meant to be used to test drivers using fake Pins.
i2c
Package i2c defines interface to an I²C bus and an I²C device.
Package i2c defines interface to an I²C bus and an I²C device.
i2c/i2creg
Package i2creg defines I²C bus registry to list buses present on the host.
Package i2creg defines I²C bus registry to list buses present on the host.
i2c/i2csmoketest
Package 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.
Package 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.
i2c/i2ctest
Package i2ctest is meant to be used to test drivers over a fake I²C bus.
Package i2ctest is meant to be used to test drivers over a fake I²C bus.
ir
Package ir defines InfraRed codes for use with a IR remote control.
Package ir defines InfraRed codes for use with a IR remote control.
mmr
Package mmr defines helpers to interact with devices exposing Memory Mapped Registers protocol.
Package mmr defines helpers to interact with devices exposing Memory Mapped Registers protocol.
onewire
Package onewire defines a Dallas Semiconductor / Maxim Integrated 1-wire bus.
Package onewire defines a Dallas Semiconductor / Maxim Integrated 1-wire bus.
onewire/onewirereg
Package onewirereg defines a registry for onewire buses present on the host.
Package onewirereg defines a registry for onewire buses present on the host.
onewire/onewiresmoketest
Package 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.
Package 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.
onewire/onewiretest
Package onewiretest is meant to be used to test drivers over a fake 1-wire bus.
Package onewiretest is meant to be used to test drivers over a fake 1-wire bus.
pin
Package pin declare well known pins.
Package pin declare well known pins.
pin/pinreg
Package pinreg is a registry for the physical headers (made up of pins) on a host.
Package pinreg is a registry for the physical headers (made up of pins) on a host.
spi
Package spi defines the SPI protocol.
Package spi defines the SPI protocol.
spi/spireg
Package spireg defines the SPI registry for SPI ports discovered on the host.
Package spireg defines the SPI registry for SPI ports discovered on the host.
spi/spismoketest
Package spismoketest is leveraged by periph-smoketest to verify that an EEPROM device can be accessed on a SPI port.
Package spismoketest is leveraged by periph-smoketest to verify that an EEPROM device can be accessed on a SPI port.
spi/spitest
Package spitest is meant to be used to test drivers over a fake SPI port.
Package spitest is meant to be used to test drivers over a fake SPI port.
Package devices contains interfaces for classes of devices.
Package devices contains interfaces for classes of devices.
apa102
Package apa102 drives a strip of APA102 LEDs connected on a SPI port.
Package apa102 drives a strip of APA102 LEDs connected on a SPI port.
bme280
Package bme280 controls a Bosch BME280 device over I²C. Datasheet https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf
Package bme280 controls a Bosch BME280 device over I²C. Datasheet https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf
bme280/bme280smoketest
Package bme280smoketest is leveraged by periph-smoketest to verify that two BME280, one over I²C, one over SPI, read roughly the same temperature, humidity and pressure.
Package bme280smoketest is leveraged by periph-smoketest to verify that two BME280, one over I²C, one over SPI, read roughly the same temperature, humidity and pressure.
devicestest
Package devicestest contains non-hardware devices implementations for testing or emulation purpose.
Package devicestest contains non-hardware devices implementations for testing or emulation purpose.
ds18b20
Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820 1-wire temperature sensors.
Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820 1-wire temperature sensors.
ds248x
Package ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip over I²C. Datasheets https://www.maximintegrated.com/en/products/digital/one-wire/DS2483.html https://www.maximintegrated.com/en/products/interface/controllers-expanders/DS2482-100.html
Package ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip over I²C. Datasheets https://www.maximintegrated.com/en/products/digital/one-wire/DS2483.html https://www.maximintegrated.com/en/products/interface/controllers-expanders/DS2482-100.html
lepton
Package lepton drivers a FLIR Lepton.
Package lepton drivers a FLIR Lepton.
lepton/cci
Package cci declares the Camera Command Interface to interact with a FLIR Lepton over I²C. This protocol controls and queries the camera but is not used to read the images.
Package cci declares the Camera Command Interface to interact with a FLIR Lepton over I²C. This protocol controls and queries the camera but is not used to read the images.
lirc
Package lirc implements InfraRed receiver support through native linux app lirc.
Package lirc implements InfraRed receiver support through native linux app lirc.
ssd1306
Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306 controller.
Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306 controller.
ssd1306/image1bit
Package image1bit implements black and white (1 bit per pixel) 2D graphics.
Package image1bit implements black and white (1 bit per pixel) 2D graphics.
ssd1306/ssd1306smoketest
Package ssd1306smoketest is leveraged by periph-smoketest to verify that two SSD1306, one over I²C, one over SPI, can display the same output.
Package ssd1306smoketest is leveraged by periph-smoketest to verify that two SSD1306, one over I²C, one over SPI, can display the same output.
tm1637
Package tm1637 controls a TM1637 device over GPIO pins.
Package tm1637 controls a TM1637 device over GPIO pins.
experimental
cmd/bmp180
bmp180 reads the current temperature and pressure from a BMP180.
bmp180 reads the current temperature and pressure from a BMP180.
conn/analog
Package analog defines analog pins, both DAC and ADC.
Package analog defines analog pins, both DAC and ADC.
conn/uart
Package uart defines the UART protocol.
Package uart defines the UART protocol.
conn/uart/uartreg
Package uartreg defines the UART registry for UART ports discovered on the host.
Package uartreg defines the UART registry for UART ports discovered on the host.
conn/usb
Package usb implements an USB device registry.
Package usb implements an USB device registry.
devices/bitbang
Package bitbang implements conn by banging on the bits (GPIO pins).
Package bitbang implements conn by banging on the bits (GPIO pins).
devices/bmp180
Package bmp180 controls a Bosch BMP180 device over I²C. Datasheet The official data sheet can be found here: https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-121.pdf The font the official datasheet on page 15 is unreadable, a copy with readable text can be found here: https://cdn-shop.adafruit.com/datasheets/BST-BMP180-DS000-09.pdf Notes on the datasheet The results of the calculations in the algorithm on page 15 are partly wrong.
Package bmp180 controls a Bosch BMP180 device over I²C. Datasheet The official data sheet can be found here: https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-121.pdf The font the official datasheet on page 15 is unreadable, a copy with readable text can be found here: https://cdn-shop.adafruit.com/datasheets/BST-BMP180-DS000-09.pdf Notes on the datasheet The results of the calculations in the algorithm on page 15 are partly wrong.
devices/piblaster
Package piblaster implements interfacing code is piblaster.
Package piblaster implements interfacing code is piblaster.
driverskeleton
Package driverskeleton is an example that can be copy pasted to help write a new driver, either in devices/ or in host/.
Package driverskeleton is an example that can be copy pasted to help write a new driver, either in devices/ or in host/.
host/sysfs
Package sysfs implements experimental sysfs support not yet in mainline.
Package sysfs implements experimental sysfs support not yet in mainline.
host/usbbus
Package usbbus implements OS specific functions for conn/usb.
Package usbbus implements OS specific functions for conn/usb.
Package host defines the host itself.
Package host defines the host itself.
allwinner
Package allwinner exposes the GPIO functionality that is common to all AllWinner processors.
Package allwinner exposes the GPIO functionality that is common to all AllWinner processors.
bcm283x
Package bcm283x exposes the BCM283x GPIO functionality.
Package bcm283x exposes the BCM283x GPIO functionality.
chip
Package chip contains header definitions for NextThing Co's C.H.I.P. board.
Package chip contains header definitions for NextThing Co's C.H.I.P. board.
chip/chipsmoketest
Package chipsmoketest is leveraged by periph-smoketest to verify that basic CHIP specific functionality works.
Package chipsmoketest is leveraged by periph-smoketest to verify that basic CHIP specific functionality works.
cpu
Package cpu implements functions relating to the host CPU itself.
Package cpu implements functions relating to the host CPU itself.
distro
Package distro implements common functionality to auto-detect features on the host; generally about linux distributions.
Package distro implements common functionality to auto-detect features on the host; generally about linux distributions.
fs
Package fs provides access to the file system on the host.
Package fs provides access to the file system on the host.
odroidc1
Package odroidc1 contains header definitions for Hardkernel's ODROID C0, C1, and C1+ boards.
Package odroidc1 contains header definitions for Hardkernel's ODROID C0, C1, and C1+ boards.
odroidc1/odroidc1smoketest
Package odroidc1smoketest is leveraged by periph-smoketest to verify that basic ODROID-C1 specific functionality works.
Package odroidc1smoketest is leveraged by periph-smoketest to verify that basic ODROID-C1 specific functionality works.
pine64
Package pine64 contains Pine64 hardware logic.
Package pine64 contains Pine64 hardware logic.
pmem
Package pmem implements handling of physical memory for user space programs.
Package pmem implements handling of physical memory for user space programs.
rpi
Package rpi contains Raspberry Pi hardware logic.
Package rpi contains Raspberry Pi hardware logic.
sysfs
Package sysfs implements a sane library to interact with sysfs provided hardware access.
Package sysfs implements a sane library to interact with sysfs provided hardware access.
videocore
Package videocore interacts with the VideoCore GPU found on bcm283x.
Package videocore interacts with the VideoCore GPU found on bcm283x.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL