README

periph - Peripherals I/O in Go

mascot

Documentation is at https://periph.io

PkgGoDev CoverageStatus

Join us for a chat on gophers.slack.com/messages/periph, get an invite here.

Example

Blink a LED:

package main

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

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

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 conn defines core interfaces for protocols and connections.

This package and its subpackages describe the base interfaces to connect the software with the real world. It doesn't contain any implementation but includes registries to enable the application to discover the available hardware.

Concepts

periph uses 3 layered concepts for interfacing:

Bus → Port → Conn

Not every subpackage expose all 3 concepts. In fact, most packages don't. For example, SPI doesn't expose Bus as the OSes generally only expose the Port, that is, a Chip Select (CS) line must be selected right upfront to get an handle. For I²C, there's no Port to configure, so selecting a "slave" address is sufficient to jump directly from a Bus to a Conn.

periph doesn't have yet a concept of star-like communication network, like an IP network.

Bus

A Bus is a multi-point communication channel where one "master" and multiple "slaves" communicate together. In the case of periph, the Bus handle is assumed to be the "master". The "master" generally initiates communications and selects the "slave" to talk to.

As the "master" selects a "slave" over a bus, a virtual Port is automatically created.

Examples include SPI, I²C and 1-wire. In each case, selecting a communication line (Chip Select (CS) line for SPI, address for I²C or 1-wire) converts the Bus into a Port.

Port

A port is a point-to-point communication channel that is yet to be initialized. It cannot be used for communication until it is connected and transformed into a Conn. Configuring a Port converts it into a Conn. Not all Port need configuration.

Conn

A Conn is a fully configured half or full duplex communication channel that is point-to-point, only between two devices. It is ready to use like any readable and/or writable pipe.

Subpackages

Most connection-type specific subpackages include subpackages:

→ XXXreg: registry as that is populated by the host drivers and that can be leveraged by applications.

→ XXXtest: fake implementation that can be leveraged when writing device driver unit test.

Example
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Conn

type Conn interface {
	String() string
	// Tx does a single transaction.
	//
	// For full duplex protocols (generally SPI, UART), the two buffers must have
	// the same length as both reading and writing happen simultaneously.
	//
	// For half duplex protocols (I²C), there is no restriction as reading
	// happens after writing, and r can be nil.
	//
	// Query Limits.MaxTxSize() to know if there is a limit on the buffer size
	// per Tx() call.
	Tx(w, r []byte) error
	// Duplex returns the current duplex setting for this point-to-point
	// connection.
	//
	// It is expected to be either Half or Full unless the connection itself is
	// in an unknown state.
	Duplex() Duplex
}

    Conn defines the interface for a connection on a point-to-point communication channel.

    The connection can either be unidirectional (read-only, write-only) or bidirectional (read-write). It can either be half-duplex or full duplex.

    This is the lowest common denominator for all point-to-point communication channels.

    Implementation are expected but not required to also implement the following interfaces:

    - fmt.Stringer which returns something meaningful to the user like "SPI0.1", "I2C1.76", "COM6", etc.

    - io.Reader and io.Writer as a way to use io.Copy() for half duplex operation.

    - io.Closer for the owner of the communication channel.

    type Duplex

    type Duplex int

      Duplex declares whether communication can happen simultaneously both ways.

      Some protocol can be either depending on configuration settings, like UART.

      const (
      	// DuplexUnknown is used when the duplex of a connection is yet to be known.
      	//
      	// Some protocol can be configured either as half-duplex or full-duplex and
      	// the connection is not yet is a determinate state.
      	DuplexUnknown Duplex = 0
      	// Half means that communication can only occurs one way at a time.
      	//
      	// Examples include 1-wire and I²C.
      	Half Duplex = 1
      	// Full means that communication occurs simultaneously both ways in a
      	// synchronized manner.
      	//
      	// Examples include SPI (except 3-wire variant).
      	Full Duplex = 2
      )

      func (Duplex) String

      func (i Duplex) String() string

      type Limits

      type Limits interface {
      	// MaxTxSize returns the maximum allowed data size to be sent as a single
      	// I/O.
      	//
      	// Returns 0 if undefined.
      	MaxTxSize() int
      }

        Limits returns information about the connection's limits.

        type Resource

        type Resource interface {
        	// String returns a human readable identifier representing this resource in a
        	// descriptive way for the user. It is the same signature as fmt.Stringer.
        	String() string
        	// Halt stops the resource.
        	//
        	// Unlike a Conn, a Resource may not be closable, On the other hand, a
        	// resource can be halted. What halting entails depends on the resource
        	// device but it should stop motion, sensing loop, light emission or PWM
        	// output and go back into an inert state.
        	Halt() error
        }

          Resource is a basic resource (like a gpio pin) or a device.

          Source Files

          Directories

          Path Synopsis
          Package analog defines analog pins, both digital to analog converter (DAC) and analog to digital converter (ADC).
          Package analog defines analog pins, both digital to analog converter (DAC) and analog to digital converter (ADC).
          Package conntest implements fakes for package conn.
          Package conntest implements fakes for package conn.
          Package display implements interfaces for visual output devices.
          Package display implements interfaces for visual output devices.
          displaytest
          Package displaytest contains non-hardware devices implementations for testing or emulation purpose.
          Package displaytest contains non-hardware devices implementations for testing or emulation purpose.
          Package driver devices a host peripheral driver to register when initializing.
          Package driver devices a host peripheral driver to register when initializing.
          driverreg
          Package driverreg is a registry for all host driver implementation that can be automatically discovered.
          Package driverreg is a registry for all host driver implementation that can be automatically discovered.
          Package gpio defines digital pins.
          Package gpio defines digital pins.
          gpioreg
          Package gpioreg defines a registry for the known digital pins.
          Package gpioreg defines a registry for the known digital pins.
          gpiostream
          Package gpiostream defines digital streams.
          Package gpiostream defines digital streams.
          gpiostream/gpiostreamtest
          Package gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
          Package gpiostreamtest enables testing device driver using gpiostream.PinIn or PinOut.
          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.
          gpioutil
          Package gpioutil includes utilities to filter or augment GPIOs.
          Package gpioutil includes utilities to filter or augment GPIOs.
          i2c
          Package i2c defines the API to communicate with devices over the I²C protocol.
          Package i2c defines the API to communicate with devices over the I²C protocol.
          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.
          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.
          Package i2s will eventually define the API to communicate with devices over the I²S protocol.
          Package i2s will eventually define the API to communicate with devices over the I²S protocol.
          Package ir defines InfraRed codes for use with a IR remote control.
          Package ir defines InfraRed codes for use with a IR remote control.
          Package jtag will eventually define the API to communicate with devices over the JTAG protocol.
          Package jtag will eventually define the API to communicate with devices over the JTAG protocol.
          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.
          Package onewire defines the API to communicate with devices over the Dallas Semiconductor / Maxim Integrated 1-wire protocol.
          Package onewire defines the API to communicate with devices over the Dallas Semiconductor / Maxim Integrated 1-wire protocol.
          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.
          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.
          Package physic declares types for physical input, outputs and measurement units.
          Package physic declares types for physical input, outputs and measurement units.
          pin
          Package pin declare well known pins.
          Package pin declare well known pins.
          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 API to communicate with devices over the SPI protocol.
          Package spi defines the API to communicate with devices over the SPI protocol.
          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.
          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 uart defines the UART protocol.
          Package uart defines the UART protocol.
          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.