I²C protocol

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

Todo

This section is currently incomplete.

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

Using the I²C protocol functionality

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

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

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

ProtocolI2C reference

class ProtocolI2C

The ProtocolI2C class provides access to the I²C 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.i2c attribute.

reset() → None

Reset the I²C protocol instrument.

Raises:: DwfLibraryError – An error occurred while executing the reset operation.

clear() → bool

Clear the I²C bus.

Detect and try to solve an I²C bus lockup condition.

Todo

The precise behavior of this method needs to be understood and documented.

Returns:: True if the bus is clear after the operation, False otherwise.
Return type:: bool
Raises:: DwfLibraryError – An error occurred while executing the operation.

stretchSet(stretch_enable: int) → None

Set I²C stretch behavior.

Todo

The precise behavior of this method needs to be understood and documented.

Parameters:: stretch_enable (bool) – True to enable stretch, False to disable.
Raises:: DwfLibraryError – An error occurred while executing the operation.

rateSet(data_rate: float) → None

Set the I²C data rate, in Hz.

Parameters:

data_rate (float) –

I²C data rate. Often-encountered rates are 100 kHz and 400 kHz, but many modern I²C devices support higher data rates. Check the datasheet of your device.

The default value is 100 kHz.

Raises:

DwfLibraryError – An error occurred while executing the operation.

timeoutSet(timeout: float) → None

Set the I²C timeout, in seconds.

Parameters:: timeout (float) – I²C timeout. The default value is 1 second.
Raises:: DwfLibraryError – An error occurred while executing the operation.

readNakSet(nak_last_read_byte: int) → None

Set read NAK state.

Todo

The precise behavior of this method needs to be understood and documented.

Parameters:: nak_last_read_byte (int) – (undocumented)
Raises:: DwfLibraryError – An error occurred while executing the operation.

sclSet(channel_index: int) → None

Set the digital channel (pin) where the I²C clock (SCL) signal is transmitted.

Parameters:: channel_index (int) – The digital channel (pin) on which to generate the SCL clock.
Raises:: DwfLibraryError – An error occurred while executing the operation.

sdaSet(channel_index: int) → None

Set the digital channel (pin) where the I²C data (SDA) signal is transmitted/received.

Parameters:: channel_index (int) – The digital channel (pin) on which to send/receive SDA data.
Raises:: DwfLibraryError – An error occurred while executing the operation.

writeRead(address: int, tx: List[int], number_of_rx_bytes: int) → Tuple[int, List[int]]

Perform a combined I²C write/read operation.

Parameters:

address (int) – The I²C address of the target device.
tx (List[int]) – The octets to send.
number_of_rx_bytes (int) – The number of octets to receive.

Returns:

The first element is the NAK indication; the second element is a list of octet values received.

Return type:

Tuple[int, List[int]]

Raises:

DwfLibraryError – An error occurred while executing the operation.

read(address: int, number_of_words: int) → Tuple[int, List[int]]

Perform an I²C read operation.

Parameters:

address (int) – The I²C address of the target device.
number_of_words (int) – The number of octets to receive.

Returns:

The first element is the NAK indication; the second element is a list of octet values received.

Return type:

Tuple[int, List[int]]

Raises:

DwfLibraryError – An error occurred while executing the operation.

write(address: int, tx: List[int]) → int

Perform an I²C write operation.

Parameters:

address (int) – The I²C address of the target device.
tx (List[int]) – The octets to send.

Returns:

The NAK indication.

Return type:

int

Raises:

DwfLibraryError – An error occurred while executing the operation.

writeOne(address: int, tx: int) → int

Perform an I²C write operation of a single octet.

Parameters:

address (int) – The I²C address of the target device.
tx (int) – The single octet to send.

Returns:

The NAK indication.

Return type:

int

Raises:

DwfLibraryError – An error occurred while executing the operation.

spyStart() → None

Start I²C spy.

Raises:: DwfLibraryError – An error occurred while executing the operation.

spyStatus(max_data_size: int) → Tuple[int, int, List[int], int]

Get I²C spy status.

Returns:: A tuple (start, stop, data-values, nak-indicator).
Return type:: Tuple[int, int, List[int], int]
Raises:: DwfLibraryError – An error occurred while executing the 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