conn

Documentation

Overview

Package conn defines core interfaces for protocols and connections.

Is it now superseded by https://periph.io/x/conn/v3 (or later).

See https://periph.io/news/2020/a_new_start/ for more details.

Example

package main

import (
	"fmt"
	"log"

	"periph.io/x/periph/conn/physic"
	"periph.io/x/periph/conn/spi"
	"periph.io/x/periph/conn/spi/spireg"
	"periph.io/x/periph/host"
)

func main() {
	// Make sure periph is initialized.
	if _, err := host.Init(); err != nil {
		log.Fatal(err)
	}

	// Using SPI as an example. See package ./spi/spireg for more details.
	p, err := spireg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer p.Close()
	c, err := p.Connect(physic.MegaHertz, spi.Mode3, 8)
	if err != nil {
		log.Fatal(err)
	}

	// Write 0x10 to the device, and read a byte right after.
	write := []byte{0x10, 0x00}
	read := make([]byte, len(write))
	if err := c.Tx(write, read); err != nil {
		log.Fatal(err)
	}
	// Use read.
	fmt.Printf("%v\n", read[1:])
}

Index

• type Conn
• type Duplex
  • func (i Duplex) String() string
• type Limits
• type Resource

Examples

• Package

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.