SPI protocol

The SPI protocol support allows a Digilent Waveforms device to be used as a simple SPI bus master.

Todo

This section is currently incomplete.

It does not properly explain the meaning of some of the settings that influence the behavior of the SPI functionality, and the difference between the several write/read methods.

Using the SPI protocol functionality

To use the SPI protocol functionality you first need to initialize a DwfLibrary instance. Next, you open a specific device. The device’s SPI protocol functionality can now be accessed via its protocol.spi attribute, which is an instance of the ProtocolSPI class:

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

with openDwfDevice(dwf) as device:
    spi = device.protocol.spi
    spi.reset()

ProtocolSPI reference

class ProtocolSPI

The ProtocolSPI class provides access to the SPI protocol functionality of a DwfDevice.

Attention

Users of pydwf should not create instances of this class directly.

It is instantiated during initialization of a DwfDevice and subsequently accessible via its protocol.spi attribute.

reset() → None

Reset the SPI protocol support.

Raises:

DwfLibraryError – An error occurred while executing the reset operation.

frequencySet(frequency: float) → None

Set the SPI frequency, in Hz.

Parameters:

frequency (float) – SPI frequency, in Hz.

Raises:

DwfLibraryError – An error occurred while executing the operation.

clockSet(channel_index: int) → None

Set the digital channel (pin) for the SPI clock signal.

Parameters:

channel_index (int) – The digital channel (pin) where the SPI clock signal will be generated.

Raises:

DwfLibraryError – An error occurred while executing the operation.

dataSet(spi_data_bit: int, channel_index: int) → None

Set the digital channel (pin) for an SPI data bit.

Parameters:

• spi_data_bit (int) –

  The data bit to configure:

  • 0 — DQ0 / MOSI / SISO

  • 1 — DQ1 / MISO

  • 2 — DQ2

  • 3 — DQ3

• channel_index (int) – The digital channel (pin) for this data bit.

Raises:

DwfLibraryError – An error occurred while executing the operation.

idleSet(spi_data_bit: int, idle_mode: DwfDigitalOutIdle) → None

Set the idle behavior for an SPI data bit.

Parameters:

• spi_data_bit (int) –

  The data bit to configure:

  • 0 — DQ0 / MOSI / SISO

  • 1 — DQ1 / MISO

  • 2 — DQ2

  • 3 — DQ3

• idle_mode (DwfDigitalOutIdle) – The idle behavior of this bit.

Raises:

DwfLibraryError – An error occurred while executing the operation.

modeSet(spi_mode: int) → None

Set the SPI mode.

Parameters:

spi_mode (int) –

The values for CPOL (polarity) and CPHA (phase) to use with the attached slave device:

• 0 — CPOL = 0, CPHA = 0

• 1 — CPOL = 0, CPHA = 1

• 2 — CPOL = 1, CPHA = 0

• 3 — CPOL = 1, CPHA = 1

Refer to the slave device’s datasheet to select the correct value.

Raises:

DwfLibraryError – An error occurred while executing the operation.

orderSet(bit_order: int) → None

Set the SPI data bit order.

Parameters:

bit_order (int) –

Select the bit order of each word sent out:

• 1 — MSB first, LSB last

• 0 — LSB first, MSB last

Raises:

DwfLibraryError – An error occurred while executing the operation.

delaySet(start: int, cmd: int, word: int, stop: int) → None

Set the SPI delays.

Raises:

DwfLibraryError – An error occurred while executing the operation.

selectSet(channel: int, level: int) → None

Set SPI device select channel and level.

Raises:

DwfLibraryError – An error occurred while executing the operation.

select(channel_index: int, level: int) → None

Set the chip select (CS) status.

Parameters:

• channel_index (int) – The digital channel (pin) for the Chip Select signal.

• level (int) –

  The Chip Select level to configure.

  • 0 — low

  • 1 — high

  • -1 — Z (high impedance)

  The CS (chip select) is an active-low signal, from the SPI bus master to a specific SPI slave device. Before starting a bus request, the master should set CS to 0 for the chip it wants to talk to.

  Each slave on an SPI bus has its own CS line. At most one of them should be selected at any time.

Raises:

DwfLibraryError – An error occurred while executing the operation.

writeRead(transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Write and read multiple SPI data-words, with up to 8 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…8).

• tx (List[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

writeRead16(transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Write and read multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• tx (list[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

writeRead32(transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Write and read multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

read(transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Read multiple SPI data-words, with up to 8 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…8).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

readOne(transfer_type: int, bits_per_word: int) → int

Read a single SPI data-word, with up to 32 bits.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits of the data-word (1…32).

Returns:

The data-word received.

Return type:

int

Raises:

DwfLibraryError – An error occurred while executing the read operation.

read16(transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Read multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

read32(transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Read multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

write(transfer_type: int, bits_per_word: int, tx: List[int]) → None

Write multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

writeOne(transfer_type: int, bits_per_word: int, tx: int) → None

Write a single SPI data-word, with up to 32 bits.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits of the data-word (1…32).

• tx (int) – The data-word to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

write16(transfer_type: int, bits_per_word: int, tx: List[int]) → None

Write multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

write32(transfer_type: int, bits_per_word: int, tx: List[int]) → None

Write multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

cmdWriteRead(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Send command and write and read multiple SPI data-words, with up to 8 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…8).

• tx (List[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

cmdWriteRead16(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Send command and write and read multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• tx (list[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

cmdWriteRead32(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → List[int]

Send command and write and read multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the write/read operation.

cmdRead(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Send command and read multiple SPI data-words, with up to 8 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…8).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

cmReadOne(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int) → int

Send command and read a single SPI data-word, with up to 32 bits.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits of the data-word (1…32).

Returns:

The data-word received.

Return type:

int

Raises:

DwfLibraryError – An error occurred while executing the read operation.

cmdRead16(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Send command and read multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

cmdRead32(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, number_of_words: int) → List[int]

Send command and read multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• number_of_words (int) – The number of data-words to read.

Returns:

The data-words received.

Return type:

List[int]

Raises:

DwfLibraryError – An error occurred while executing the read operation.

cmdWrite(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → None

Send command and write multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

cmdWriteOne(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: int) → None

Send command and write a single SPI data-word, with up to 32 bits.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits of the data-word (1…32).

• tx (int) – The data-word to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

cmdWrite16(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → None

Send command and write multiple SPI data-words, with up to 16 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…16).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

cmdWrite32(command_bits: int, command_value: int, dummy_bits: int, transfer_type: int, bits_per_word: int, tx: List[int]) → None

Send command and write multiple SPI data-words, with up to 32 bits per data-word.

Parameters:

• command_bits (int) – The number of command bits.

• command_value (int) – The command value.

• dummy_bits (int) – The number of dummy bits before the data transfer.

• transfer_type (int) –

  • 0 — SISO

  • 1 — MOSI/MISO

  • 2 — dual

  • 4 — quad

• bits_per_word (int) – The number of bits per data-word (1…32).

• tx (List[int]) – The data-words to write.

Raises:

DwfLibraryError – An error occurred while executing the write operation.

property device

Return the DwfDevice instance of which we are an attribute.

This is useful if we have a variable that contains a reference to a DwfDevice attribute, but we need the DwfDevice itself.

Returns:

The DwfDevice instance that this attribute belongs to.

Return type:

DwfDevice