SPI

The serbus.SPIDev class provides an API for interfacing with standard GNU/Linux spidev devices. It is instantiated with a bus number corresponding to the spidev device file it will use - to communicate with devices on the SPI bus connected to /dev/spidev0.X you could create the instance bus = serbus.SPIDev(0). The read/write methods then take a chip select as their first argument, so to read a byte from a device on chip select 1 of spidev0 (/dev/spidev0.1) you would call bus.read(1, 1).

Note

For more info on SPI (Serial Peripheral Interface) see https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus

API

class serbus.SPIDev(bus[, mode_3wire=False])
Parameters:
  • bus (int) – The bus number to use, e.g. 0 for /dev/spidev0.X
  • mode_3wire (bool, optional) – True to enable 3-wire mode (half-duplex), False for standard 4-wire mode (default).
close()

Close the SPI interface.

disableCS(cs)
Parameters:cs (int) – The chip select the setting will apply to

Disables the given chip select for the SPI interface.

Raises:IOError if unable to disable loopback mode.
disableLoopback(cs)
Parameters:cs (int) – The chip select the setting will apply to

Disables loopback mode on the SPI interface for the given chip select.

Raises:IOError if unable to disable loopback mode.
enableCS(cs)
Parameters:cs (int) – The chip select the setting will apply to

Enables the given chip select for the SPI interface.

Raises:IOError if unable to disable loopback mode.
enableLoopback(cs)
Parameters:cs (int) – The chip select the setting will apply to

Sets the SPI interface to loopback mode for the given chip select.

Raises:IOError if unable to enable loopback mode.
open()

Initialize the SPI interface - must be called before any other methods.

read(cs, n_words)
Parameters:
  • cs (int) – The chip select to use for reading
  • n_words (int) – The number of words to read
Returns:

A list of the words read as integers, in the order they were read.

Reads n_words words from the SPI device using the given chip select.

setBitsPerWord(cs, bits_per_word)
Parameters:
  • cs (int) – The chip select the setting will apply to
  • bits_per_word – The number of bits per word, must be in the range [1,255]

Sets the SPI bits per word for the given chip select to the given value.

Raises:IOError if unable to set the bits per word.
setCSActiveHigh(cs) → None
Parameters:cs (int) – The chip select the setting will apply to

Sets the SPI interface to use a high level when activating the given chip select (inverted).

Raises:IOError if unable to disable loopback mode.
setCSActiveLow(cs)
Parameters:cs (int) – The chip select the setting will apply to

Sets the SPI interface to use a low level when activating the given chip select (default).

Raises:IOError if unable to disable loopback mode.
setClockMode(cs, clock_mode)
Parameters:
  • cs (int) – The chip select the setting will apply to
  • clock_mode (int) – The desired SPI clock mode

Sets the clock mode for the given chip select of the SPI interface.

See:https://graycat.io/docs/serbus/python/SPI.html#clock-modes
Raises:IOError if unable to disable loopback mode.
setLSBFirst(cs)
Parameters:cs (int) – The chip select the setting will apply to

Sets the SPI bit order for the given chip select to be least significant bit first.

Raises:IOError if unable to set the bit order.
setMSBFirst(cs)
Parameters:cs (int) – The chip select the setting will apply to

Sets the SPI bit order for the given chip select to be most significant bit first.

Raises:IOError if unable to set the bit order.
setMaxFrequency(cs, frequency)
Parameters:
  • cs (int) – The chip select the setting will apply to
  • frequency – The clock frequency in Hz

Sets the maximum SPI clock frequency for the given chip select

Raises:IOError if unable to set the frequency.
transaction(cs, tx_words, n_rx_words)
Parameters:
  • cs (int) – The chip select to use
  • tx_words (list) – The words to be written
  • n_rx_words (int) – The number of words to read
Returns:

A list of the words read as integers, in the order they were read.

Writes the given list of words to the SPI interface using the given chip select, then reads words from the SPI interface using the given chip select. CS remains unchanged.

Note:Will only write/read up to a maximum of 4096 bytes.
transfer(cs, words)
Parameters:
  • cs (int) – The chip select to use
  • words (list) – The words to be written
Returns:

The words read as a list of ints, the same length as words.

Writes the given list of words to the SPI interface using the given chip select while simultaneously reading bytes.

Note:Will only write/read up to a maximum of 4096 bytes.
write(cs, words)
Parameters:
  • cs (int) – The chip select to use for writing
  • words (list) – The words to be written
Returns:

The number of bytes written, or -1 if unable to write interface.

Writes the given list of words to the SPI interface using the given chip select.

Note:Will only write up to a maximum of 4096 bytes.

Clock Modes

The clock_mode parameter passed to setClockMode() tells the SPI kernel driver how to drive the clock signal. The SPI spec allows four possible clock configurations, and the required mode for a particular device will be given in its datasheet (sometimes explicitly, but often just shown visually in an SPI timing diagram). The possible modes are:

clock_mode clock idle state clock edge data is captured on
0 low rising edge
1 low falling edge
2 high falling edge
3 high rising edge

Examples

These are a few examples of using the SPIDev object. They will only work if you have the proper hardware connected to the system running them and your SPI kernel driver loaded. Depending on the system there may be additional required setup as well, such as configuring pin multiplexers on embedded GNU/Linux systems like the BeagleBone Black.

Reading data

This example shows how to read a single word from an SPI device. It is not specific to any particular device.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import serbus

# The chip select connected to the slave device:
cs = 0

# Create a SPIDev instance for interfacing to /dev/spidev0.x devices:
bus = serbus.SPIDev(0)
bus.open()

# Set bus configuration:
bus.setMaxFrequency(cs, 1000000)
bus.setBitsPerWord(cs, 8)
bus.setClockMode(cs, 0)
bus.setCSActiveLow(cs)
bus.setMSBFirst(cs)

# Read a single 8-bit word from the device:
data = bus.read(cs, 1)
print "word received: {:x}".format(data[0])

bus.close()

AD7390 digital-to-analog converter

This example shows how to control an AD7390 12-bit SPI DAC (digital-to-analog converter).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import serbus, time

# The SPI bus and chip select the AD7390 is connected to:
spi_bus = 1
cs      = 0
# /dev/spidev1.0

bus = serbus.SPIDev(spi_bus)
bus.open()

# Set bus configuration, as described in the AD7390 datasheet:
bus.setMaxFrequency(cs, 1000000)
bus.setBitsPerWord(cs, 16)
bus.setClockMode(cs, 3)
bus.setCSActiveHigh(cs)
bus.setMSBFirst(cs)

try:
  while True:
    # Ramp up from 0V to full-scale:
    for i in range(0, 2**12, 100):
      bus.write(cs, [i])
      time.sleep(0.01)

    # Ramp down from full-scale to 0V:
    for i in range(2**12-1, 0, -100):
      bus.write(cs, [i])
      time.sleep(0.01)

except KeyboardInterrupt:
  bus.close()

The AD7390 requires an active high chip slelct signal on its LD pin, and because it uses 12-bit values its word size in larger than the default 8-bits of many SPI modules - both of these are easy set with the included methods.