import "periph.io/x/periph"
Package periph is a peripheral I/O library.
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.
To learn more about the goals and design, visit https://periph.io/
Every device driver should register itself in its package init() function by calling periph.MustRegister().
User shall call either host.Init() or hostextra.Init() on startup to initialize all the registered drivers.
cmd/ contains executable tools to communicate directly with the devices or the buses.
cmd/ is allowed to import from conn/, devices/ and host/.
conn/ contains interfaces and registries for all the supported protocols and connections (I²C, SPI, GPIO, etc).
conn/ is not allowed to import from any other package.
devices/ contains devices drivers that are connected to bus, port or connection (i.e I²C, SPI, 1-wire, GPIO) that can be controlled by the host, i.e. ssd1306 (display controller), bm280 (environmental sensor), etc.
devices/ is allowed to import from conn/ and host/.
experimental/ contains the drivers that are in the experimental area, not yet considered stable. See https://periph.io/project/#driver-lifetime-management for the process to move drivers out of this area.
experimental/ is allowed to import from conn/, devices/ and host/.
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/ is allowed to import from conn/ only.
Code:
// host.Init() registers all the periph-provided host driver automatically, // so it is preferable to use than periph.Init(). // // You can also use periph.io/x/extra/hostextra.Init() for additional drivers // that depends on cgo and/or third party packages. 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.
MustRegister calls Register() and panics if registration fails.
This is the function to call in a driver's package init() function.
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 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 // After returns a list of drivers that must be loaded first before // attempting to load this driver. // // Unlike Prerequisites(), this driver will still be attempted even if the // listed driver is missing or failed to load. // // This permits serialization without hard requirement. After() []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.
DriverFailure is a driver that wasn't loaded, either because it was skipped or because it failed to load.
func (d DriverFailure) String() string
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.
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.
Path | Synopsis |
---|---|
cmd | Package cmd contains tools. |
cmd/apa102 | apa102 writes to a strip of APA102 LED. |
cmd/bmxx80 | bmxx80 reads environmental data from a BMP180/BME280/BMP280. |
cmd/cap1xxx | cap1xxx sense touches. |
cmd/gpio-list | gpio-list prints out the function of each GPIO pin. |
cmd/gpio-read | gpio-read reads a GPIO pin. |
cmd/gpio-write | gpio-write sets a GPIO pin to low or high. |
cmd/headers-list | headers-list prints out the headers as found on the computer and print the functionality of each pin. |
cmd/i2c-io | i2c-io communicates to an I²C device. |
cmd/i2c-list | i2c-list lists all I²C buses. |
cmd/ir | ir reads from an IR receiver via LIRC. |
cmd/led | led reads the state of a LED or change it. |
cmd/lepton | lepton captures a single image, prints metadata about the camera state or triggers a calibration. |
cmd/onewire-list | onewire-list lists all onewire buses and devices. |
cmd/periph-info | periph-info prints out information about the loaded periph drivers. |
cmd/periph-smoketest | periph-smoketest runs all known smoke tests. |
cmd/periph-smoketest/gpiosmoketest | Package gpiosmoketest is leveraged by periph-smoketest to verify that basic GPIO pin functionality work. |
cmd/periph-smoketest/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. |
cmd/periph-smoketest/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. |
cmd/periph-smoketest/spismoketest | Package spismoketest is leveraged by periph-smoketest to verify that an EEPROM device can be accessed on a SPI port. |
cmd/spi-io | spi-io writes to an SPI port data from stdin and outputs to stdout or writes arguments and outputs hex encoded output. |
cmd/spi-list | spi-list lists all SPI ports. |
cmd/ssd1306 | ssd1306 writes to a display driven by a ssd1306 controler. |
cmd/thermal | thermal reads the state of thermal sensors exposed via sysfs. |
cmd/tm1637 | tm1637 writes to a digits LED display. |
conn | Package conn defines core interfaces for protocols and connections. |
conn/conntest | Package conntest implements fakes for package conn. |
conn/display | Package display implements interfaces for visual output devices. |
conn/display/displaytest | Package displaytest contains non-hardware devices implementations for testing or emulation purpose. |
conn/gpio | Package gpio defines digital pins. |
conn/gpio/gpioreg | Package gpioreg defines a registry for the known digital pins. |
conn/gpio/gpiostream | Package gpiostream defines digital streams. |
conn/gpio/gpiostream/gpiostreamtest | Package gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut. |
conn/gpio/gpiotest | Package gpiotest is meant to be used to test drivers using fake Pins. |
conn/i2c | Package i2c defines the API to communicate with devices over the I²C protocol. |
conn/i2c/i2creg | Package i2creg defines I²C bus registry to list buses present on the host. |
conn/i2c/i2ctest | Package i2ctest is meant to be used to test drivers over a fake I²C bus. |
conn/i2s | Package i2s will eventually define the API to communicate with devices over the I²S protocol. |
conn/ir | Package ir defines InfraRed codes for use with a IR remote control. |
conn/jtag | Package jtag will eventually define the API to communicate with devices over the JTAG protocol. |
conn/mmr | Package mmr defines helpers to interact with devices exposing Memory Mapped Registers protocol. |
conn/onewire | Package onewire defines the API to communicate with devices over the Dallas Semiconductor / Maxim Integrated 1-wire protocol. |
conn/onewire/onewirereg | Package onewirereg defines a registry for onewire buses present on the host. |
conn/onewire/onewiretest | Package onewiretest is meant to be used to test drivers over a fake 1-wire bus. |
conn/physic | Package physic declares types for physical input, outputs and measurement units. |
conn/pin | Package pin declare well known pins. |
conn/pin/pinreg | Package pinreg is a registry for the physical headers (made up of pins) on a host. |
conn/spi | Package spi defines the API to communicate with devices over the SPI protocol. |
conn/spi/spireg | Package spireg defines the SPI registry for SPI ports discovered on the host. |
conn/spi/spitest | Package spitest is meant to be used to test drivers over a fake SPI port. |
conn/uart | Package uart will eventually define the API to communicate with devices over the UART protocol. |
devices | Package devices is a container for device drivers. |
devices/apa102 | Package apa102 drives a strip of APA102 LEDs connected on a SPI port. |
devices/bmxx80 | Package bmxx80 controls a Bosch BMP180/BME280/BMP280 device over I²C, or SPI for the BMx280. |
devices/bmxx80/bmx280smoketest | Package 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/cap1xxx | Package cap1xxx controls a Microchip cap1105/cap1106/cap1114/cap1133/cap1126/cap1128/cap1166/cap1188 device over I²C. |
devices/ds18b20 | Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820 1-wire temperature sensors. |
devices/ds248x | Package ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip over I²C. |
devices/lepton | Package lepton drives a FLIR Lepton Infra Red (IR) camera. |
devices/lepton/cci | Package cci declares the Camera Command Interface to interact with a FLIR Lepton over I²C. |
devices/lepton/image14bit | Package image14bit implements 14-bit per pixel images. |
devices/lepton/internal | Package internal contains code shared between cci and lepton. |
devices/lirc | Package lirc implements InfraRed receiver support through native linux app lirc. |
devices/ssd1306 | Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306 controller. |
devices/ssd1306/image1bit | Package image1bit implements black and white (1 bit per pixel) 2D graphics. |
devices/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. |
devices/tm1637 | Package tm1637 controls a TM1637 device over GPIO pins. |
experimental/cmd/ads1015 | |
experimental/cmd/as7262 | as7262 communicates with an as7262 continually reading the spectrum. |
experimental/cmd/ccs811 | |
experimental/cmd/hd44780 | hd44780 writes to a text LCD screen. |
experimental/cmd/hx711 | |
experimental/cmd/ina219 | ina219 communicates with an ina219 sensor reading voltage, current and power. |
experimental/cmd/inky | |
experimental/cmd/mcp9808 | mcp9808 communicates with an mcp9808 sensor reading ambient temperature. |
experimental/cmd/mfrc522 | mfrc522 reads RFID tags. |
experimental/cmd/mpu9250 | mpu9250 calibrates and performs the self-test, then measures the acceleration continuously. |
experimental/cmd/nrzled | nrzled writes to a strip of LEDs using the NRZ protocol. |
experimental/cmd/pca9548 | pca9548 scans the 8 ports of a pca9548 i2c multiplexer for other i2c devices. |
experimental/cmd/periph-web | periph-web runs a web server exposing periph's state. |
experimental/cmd/sn3218 | |
experimental/cmd/st7567 | |
experimental/cmd/tlv493d | tlv493d measures the magnetic flux sensed by a tlv493d component. |
experimental/conn/analog | Package analog defines analog pins, both digital to analog converter (DAC) and analog to digital converter (ADC). |
experimental/conn/gpio/gpioutil | Package gpioutil includes utilities to filter or augment GPIOs. |
experimental/conn/uart | Package uart defines the UART protocol. |
experimental/conn/uart/uartreg | Package uartreg defines the UART registry for UART ports discovered on the host. |
experimental/devices/ads1x15 | Package ads1x15 controls ADS1015/ADS1115 Analog-Digital Converters (ADC) via I²C interface. |
experimental/devices/as7262 | Package as7262 controls an AMS 6 channel visible spectral sensor via an i2c interface. |
experimental/devices/bh1750 | Package bh1750 controls a ROHM BH1750 ambient light sensor, over an i2c bus. |
experimental/devices/bitbang | Package bitbang implements conn by banging on the bits (GPIO pins). |
experimental/devices/ccs811 | Package ccs811 controls CCS811 Volatile Organic Compounds sensor via I²C interface. |
experimental/devices/epd | Package epd controls Waveshare e-paper series displays. |
experimental/devices/epd/image2bit | Package image2bit implements two bit gray scale (white, light gray, dark gray, black) 2D graphics. |
experimental/devices/hd44780 | Package hd44780 controls the Hitachi LCD display chipset HD-44780 |
experimental/devices/ht16k33 | Package ht16k33 implements interfacing code to Holtek HT16K33 Alphanumeric 16x8 LED driver. |
experimental/devices/hx711 | Package hx711 implements an interface to the 24-bits HX711 analog to digital converter. |
experimental/devices/ina219 | Package ina219 controls a Texas Instruments ina219 high side current, voltage and power monitor IC over an i2c bus. |
experimental/devices/ina219/ina219smoketest | Package ina219smoketest tests the ina219 device. |
experimental/devices/inky | Package inky drives an Inky pHAT or wHAT E ink display. |
experimental/devices/mcp23xxx | Package mcp23xxx provides driver for the MCP23 family of IO extenders |
experimental/devices/mcp9808 | Package mcp9808 controls a Microchip MCP9808 digital I²C temperature sensor. |
experimental/devices/mcp9808/mcp9808smoketest | Package mcp9808smoketest implements a smoke test for the mcp9808. |
experimental/devices/mfrc522 | Package mfrc522 controls a Mifare RFID card reader. |
experimental/devices/mfrc522/commands | Package commands contains the command that a MFRC522 supports. |
experimental/devices/mpu9250 | Package mpu9250 MPU-9250 is a 9-axis MotionTracking device that combines a 3-axis gyroscope, 3-axis accelerometer, 3-axis magnetometer and a Digital Motion Processor™ (DMP) |
experimental/devices/mpu9250/accelerometer | Package accelerometer contains constants for the MPU9250. |
experimental/devices/mpu9250/reg | Package reg defines constants for the MPU9250. |
experimental/devices/nrzled | Package 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/pca9548 | Package pca9548 is a driver for an 8 port I²C multiplexer that is available from multiple vendors. |
experimental/devices/pca9685 | Package pca9685 includes utilities to controls pca9685 module and servo motors. |
experimental/devices/piblaster | Package piblaster implements interfacing code is piblaster. |
experimental/devices/rainbowhat | Package rainbowhat implements interfacing code to Pimoroni's Rainbow hat. |
experimental/devices/sn3218 | Package sn3218 controls a SN3218 LED driver with 18 LEDs over an i2c bus. |
experimental/devices/st7567 | Package st7567 implements an interface to the single-chip dot matrix LCD |
experimental/devices/tlv493d | Package tlv493d implements interfacing code to the Infineon TLV493D haff effect sensor. |
experimental/devices/unicornhd | Package unicornhd implements interfacing code to Pimoroni's Unicorn HD hat. |
experimental/driverskeleton | Package driverskeleton is an example that can be copy pasted to help write a new driver, either in devices/ or in host/. |
experimental/host/mt7688 | Package mt7688 interfaces with the MediaTek MT7688 MIPS CPU used on low cost board. |
experimental/host/netlink | Package netlink implements host drivers based on the Linux netlink connector interface. |
experimental/host/pru | Package pru exposes the Programmable Real-Time Unit Subsystem and Industrial Communication Subsystem (PRU-ICSS) functionality found on many Texas Instruments processors. |
experimental/host/serial | Package serial implements cross platform UART support exposed by the operating system. |
host | Package host defines the host itself. |
host/allwinner | Package allwinner exposes the GPIO functionality that is common to all AllWinner processors. |
host/allwinner/allwinnersmoketest | Package allwinnersmoketest verifies that allwinner specific functionality work. |
host/am335x | Package am335x exposes functionality for the Texas Instruments Sitara AM335x processor family. |
host/bcm283x | Package bcm283x exposes the BCM283x GPIO functionality. |
host/bcm283x/bcm283xsmoketest | Package bcm283xsmoketest verifies that bcm283x specific functionality work. |
host/beagle | Package beagle regroups subpackages containing BeagleBoard/BeagleBone board family headers definition. |
host/beagle/black | Package black implements headers for the BeagleBone Black and BeagleBone Black Wireless micro-computers. |
host/beagle/bone | Package bone implements headers J1, P8 and P9 found on many (but not all) BeagleBone micro-computer. |
host/beagle/green | Package green implements headers for the BeagleBone Green and BeagleBone Green Wireless micro-computers. |
host/chip | Package chip contains header definitions for NextThing Co's C.H.I.P. |
host/chip/chipsmoketest | Package chipsmoketest is leveraged by periph-smoketest to verify that basic CHIP specific functionality works. |
host/cpu | Package cpu implements functions relating to the host CPU itself. |
host/distro | Package distro implements common functionality to auto-detect features on the host; generally about linux distributions. |
host/fs | Package fs provides access to the file system on the host. |
host/odroidc1 | Package odroidc1 contains header definitions for Hardkernel's ODROID C0, C1, and C1+ boards. |
host/odroidc1/odroidc1smoketest | Package odroidc1smoketest is leveraged by periph-smoketest to verify that basic ODROID-C1 specific functionality works. |
host/pine64 | Package pine64 contains Pine64 hardware logic. |
host/pmem | Package pmem implements handling of physical memory for user space programs. |
host/rpi | Package rpi contains Raspberry Pi hardware logic. |
host/sysfs | Package sysfs implements a sane library to interact with sysfs provided hardware access. |
host/sysfs/sysfssmoketest | Package sysfssmoketest verifies that sysfs specific functionality work. |
host/videocore | Package videocore interacts with the VideoCore GPU found on bcm283x. |
Package periph imports 4 packages (graph) and is imported by 68 packages. Updated 2021-01-01. Refresh now. Tools for package owners.