View Source Circuits.SPI (circuits_spi v2.0.4)

This module enables Elixir programs to interact with hardware that's connected via a SPI bus.

Summary

Types

backend()

Backends specify an implementation of a Circuits.SPI.Backend behaviour

spi_option()

SPI bus options

spi_option_map()

SPI bus options as returned by config/1.

Return a list of available SPI bus names. If nothing is returned, it's possible that the kernel driver for that SPI bus is not enabled or the kernel's device tree is not configured. On Raspbian, run raspi-config and look in the advanced options.

close(spi_bus)

Release any resources associated with the given file descriptor

config(spi_bus)

Return the configuration for this SPI bus

info(backend \\ nil)

Return info about the low level SPI interface

max_transfer_size(bus \\ nil)

Return the maximum transfer size in bytes

open(bus_name, options \\ [])

Open a SPI bus device

transfer(spi_bus, data)

Transfer data

transfer!(spi_bus, data)

Transfer data and raise on error

Types

backend()

@type backend() :: {module(), keyword()}

Backends specify an implementation of a Circuits.SPI.Backend behaviour

The second parameter of the Backend 2-tuple is a list of options. These are passed to the behaviour function call implementations.

spi_option()

@type spi_option() ::
  {:mode, 0..3}
  | {:bits_per_word, 8..16}
  | {:speed_hz, pos_integer()}
  | {:delay_us, non_neg_integer()}
  | {:lsb_first, boolean()}

SPI bus options

Options:

mode - Set the clock polarity and phase to use:
- Mode 0 (CPOL=0, CPHA=0) - Clock idle low/sample leading edge (default)
- Mode 1 (CPOL=0, CPHA=1) - Clock idle low/sample trailing edge
- Mode 2 (CPOL=1, CPHA=0) - Clock idle high/sample leading edge
- Mode 3 (CPOL=1, CPHA=1) - Clock idle high/sample trailing edge
bits_per_word - Set the bits per word on the bus. Defaults to 8 bit words.
speed_hz - Set the bus speed. Supported speeds are device-specific. The default speed is 1 Mbps (1000000).
delay_us - Set the delay between transactions (10)
lsb_first - Set to true to send the least significant bit first rather than the most significant one. (false) The error message unsupported mode bits 8 might be printed due to hardware that doesn't support the LSB-first mode, which can be ignored since Circuits.SPI handles it automatically.

spi_option_map()

@type spi_option_map() :: %{
  mode: 0..3,
  bits_per_word: 8..16,
  speed_hz: pos_integer(),
  delay_us: non_neg_integer(),
  lsb_first: boolean(),
  sw_lsb_first: boolean()
}

SPI bus options as returned by config/1.

These mirror the options that can be passed to open/2. :sw_lsb_first is set if :lsb_first is true, but Circuits.SPI is doing this in software.

Functions

bus_names()

@spec bus_names() :: [binary()]

iex> Circuits.SPI.bus_names
["spidev0.0", "spidev0.1"]

close(spi_bus)

@spec close(Circuits.SPI.Bus.t()) :: :ok

Release any resources associated with the given file descriptor

config(spi_bus)

@spec config(Circuits.SPI.Bus.t()) :: {:ok, spi_option_map()} | {:error, term()}

Return the configuration for this SPI bus

The configuration could be different that what was given to open/2 if the device had to change it for it to work.

info(backend \\ nil)

@spec info(backend() | nil) :: map()

Return info about the low level SPI interface

This may be helpful when debugging SPI issues.

max_transfer_size(bus \\ nil)

@spec max_transfer_size(Circuits.SPI.Bus.t() | nil) :: non_neg_integer()

Return the maximum transfer size in bytes

The number of bytes that can be sent and received at a time may be capped by the low level SPI interface. For example, the Linux spidev driver allocates its transfer buffer at initialization based on the bufsiz parameter and rejects requests that won't fit.

If you're sending large amounts of data over SPI, use this function to determine how to split up large messages.

open(bus_name, options \\ [])

@spec open(binary(), [spi_option()]) :: {:ok, Circuits.SPI.Bus.t()} | {:error, term()}

Open a SPI bus device

On success, open/2 returns a reference that may be passed to with transfer/2. The device will be closed automatically when the reference goes out of scope.

SPI is not a standardized interface so appropriate options will different from device-to-device. The defaults use here work on many devices.

Parameters:

bus_name is the name of the bus (e.g., "spidev0.0"). See bus_names/0
opts is a keyword list to configure the bus

transfer(spi_bus, data)

@spec transfer(Circuits.SPI.Bus.t(), iodata()) :: {:ok, binary()} | {:error, term()}

Transfer data

Since each SPI transfer sends and receives simultaneously, the return value will be a binary of the same length as data.

transfer!(spi_bus, data)

@spec transfer!(Circuits.SPI.Bus.t(), iodata()) :: binary()

Transfer data and raise on error