spi

Documentation

Overview

Package spi defines the API to communicate with devices over the SPI protocol.

As described in https://periph.io/x/periph/conn#hdr-Concepts, periph.io uses the concepts of Bus, Port and Conn.

In the package spi, 'Bus' is not exposed, as it would be SPI bus number without a CS line, for example on linux asking for "/dev/spi0" without the ".0" suffix.

The OS doesn't allow that so it is counter productive to express this at the API layer, so 'Port' is exposed directly instead.

Use Port.Connect() converts the uninitialized Port into a Conn.

See https://en.wikipedia.org/wiki/Serial_Peripheral_Interface for more information.

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)
	}

	// Use spireg SPI port registry to find the first available SPI bus.
	p, err := spireg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer p.Close()

	// Convert the spi.Port into a spi.Conn so it can be used for communication.
	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

• Constants
• type Conn
• type Mode
  • func (m Mode) String() string
• type Packet
• type Pins
• type Port
• type PortCloser

Examples

• Package
• Pins

Constants

const (
	CLK  pin.Func = "SPI_CLK"  // Clock
	CS   pin.Func = "SPI_CS"   // Chip select
	MISO pin.Func = "SPI_MISO" // Master in
	MOSI pin.Func = "SPI_MOSI" // Master out
)

Types

type Conn

type Conn interface {
	conn.Conn
	// TxPackets does multiple operations over the SPI connection.
	//
	// The maximum number of bytes can be limited depending on the driver. Query
	// conn.Limits.MaxTxSize() can be used to determine the limit.
	//
	// If the last packet has KeepCS:true, the behavior is undefined. The CS line
	// will likely not stay asserted. This is a driver limitation.
	TxPackets(p []Packet) error
}

Conn defines the interface a concrete SPI driver must implement.

Implementers can optionally implement io.Writer and io.Reader for unidirectional operation.

type Mode

type Mode int

Mode determines how communication is done.

The bits can be OR'ed to change the parameters used for communication.

const (
	Mode0 Mode = 0x0 // CPOL=0, CPHA=0
	Mode1 Mode = 0x1 // CPOL=0, CPHA=1
	Mode2 Mode = 0x2 // CPOL=1, CPHA=0
	Mode3 Mode = 0x3 // CPOL=1, CPHA=1

	// HalfDuplex specifies that MOSI and MISO use the same wire, and that only
	// one duplex is used at a time.
	HalfDuplex Mode = 0x4
	// NoCS request the driver to not use the CS line.
	NoCS Mode = 0x8
	// LSBFirst requests the words to be encoded in little endian instead of the
	// default big endian.
	LSBFirst = 0x10
)

Mode determines the SPI communication parameters.

CPOL means the clock polarity. Idle is High when set.

CPHA is the clock phase, sample on trailing edge when set.

func (Mode) String

func (m Mode) String() string

type Packet

type Packet struct {
	// W and R are the output and input data. When HalfDuplex is specified to
	// Connect, only one of the two can be set.
	W, R []byte
	// BitsPerWord overrides the default bits per word value set in Connect.
	BitsPerWord uint8
	// KeepCS tells the driver to keep CS asserted after this packet is
	// completed. This can be leveraged to create long transaction as multiple
	// packets like to use 9 bits commands then 8 bits data.
	//
	// Casual observation on a Rasberry Pi 3 is that two packets with
	// KeepCS:false, there is a few µs with CS asserted after the clock stops,
	// then 11.2µs with CS not asserted, then CS is asserted for (roughly) one
	// clock cycle before the clock starts again for the next packet. This seems
	// to be independent of the port clock speed but this wasn't fully verified.
	//
	// It cannot be expected that the driver will correctly keep CS asserted even
	// if KeepCS:true on the last packet.
	//
	// KeepCS is ignored when NoCS was specified to Connect.
	KeepCS bool
}

Packet represents one packet when sending multiple packets as a transaction.

type Pins

type Pins interface {
	// CLK returns the SCK (clock) pin.
	CLK() gpio.PinOut
	// MOSI returns the SDO (master out, slave in) pin.
	MOSI() gpio.PinOut
	// MISO returns the SDI (master in, slave out) pin.
	MISO() gpio.PinIn
	// CS returns the CSN (chip select) pin.
	CS() gpio.PinOut
}

Pins defines the pins that a SPI port interconnect is using on the host.

It is expected that a implementer of ConnCloser or Conn also implement Pins but this is not a requirement.

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)
	}

	// Use spireg SPI port registry to find the first available SPI bus.
	p, err := spireg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer p.Close()

	// Convert the spi.Port into a spi.Conn so it can be used for communication.
	c, err := p.Connect(physic.MegaHertz, spi.Mode3, 8)
	if err != nil {
		log.Fatal(err)
	}

	// Prints out the gpio pin used.
	if p, ok := c.(spi.Pins); ok {
		fmt.Printf("  CLK : %s", p.CLK())
		fmt.Printf("  MOSI: %s", p.MOSI())
		fmt.Printf("  MISO: %s", p.MISO())
		fmt.Printf("  CS  : %s", p.CS())
	}
}

type Port

type Port interface {
	String() string
	// Connect sets the communication parameters of the connection for use by a
	// device.
	//
	// The device driver must call this function exactly once.
	//
	// f must specify the maximum rated speed by the device's spec. The lowest
	// speed between the port speed and the device speed is selected. Use 0 for f
	// if there is no known maximum value for this device.
	//
	// mode specifies the clock and signal polarities, if the port is using half
	// duplex (shared MISO and MOSI) or if CS is not needed.
	//
	// bits is the number of bits per word. Generally you should use 8.
	Connect(f physic.Frequency, mode Mode, bits int) (Conn, error)
}

Port is the interface to be provided to device drivers.

The device driver, that is the driver for the peripheral connected over this port, calls Connect() to retrieve a configured connection as Conn.

type PortCloser

type PortCloser interface {
	io.Closer
	Port
	// LimitSpeed sets the maximum port speed.
	//
	// It lets an application use a device at a lower speed than the maximum
	// speed as rated by the device driver. This is useful for example when the
	// wires are long or the connection is of poor quality.
	//
	// This function can be called multiple times and resets the previous value.
	// 0 is not a valid value for f. The lowest speed between the port speed and
	// the device speed is selected.
	LimitSpeed(f physic.Frequency) error
}

PortCloser is a SPI port that can be closed.

This interface is meant to be handled by the application.