UART protocol

The UART protocol support allows a Digilent Waveforms device to be used as a simple Universal Asynchronous Receiver/Transmitter (UART).

Todo

This section is currently incomplete.

Specifically, the meaning of the parity error indication as returned by the rx() method is unclear. It needs to be investigated and documented.

Using the UART protocol functionality

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

from pydwf import DwfLibrary
from pydwf.utilities import openDwfDevice

dwf = DwfLibrary()

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

The UART protocol as implemented supports a single digital pin to act as a transmitter (TX), and a single digital pin to act as a receiver (RX). Transmission and reception are relative to the viewpoint of the Digilent Waveforms device; so ‘transmission’ means that the Digilent Waveforms device sends outgoing data, and ‘reception’ means that the Digilent Waveforms device receives incoming data.

The UART protocol only supports the two basic serial TX and RX signals. Other signals commonly encountered on serial ports (e.g., hardware handshaking using RTS/CTS) are not supported.

Note that while the UART API provides several methods to configure the serial communication (most notably, the baudrate, number of data-bits, parity, and number of stop-bits), there is no way to read back the currently active communication parameter values.

ProtocolUART reference

class ProtocolUART

The ProtocolUART class provides access to the UART 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.uart attribute.

reset() → None

Reset the UART protocol functionality.

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

rateSet(baudrate: float) → None

Set the UART baudrate.

Parameters:

baudrate (float) –

The baud-rate used by the receiver and transmitter.

Commonly encountered values are 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200, but other values are valid as well.

Raises:

DwfLibraryError – An error occurred while executing the operation.

bitsSet(databits: int) → None

Set the number of UART data bits.

Parameters:

databits (int) –

The number of data-bits used by the receiver and transmitter.

The most common choice is 8, but other values are possible.

Raises:

DwfLibraryError – An error occurred while executing the operation.

paritySet(parity: int) → None

Set the UART character parity.

Parameters:

parity (int) –

The parity used by the receiver and transmitter:

0 — no parity
1 — odd parity
2 — even parity

The most common choice is no parity (i.e., 0).

Raises:

DwfLibraryError – An error occurred while executing the operation.

polaritySet(polarity: int) → None

Set the UART signal polarity.

Parameters:

polarity (int) –

The polarity used by the receiver and transmitter:

0 — normal
1 — inverted

The most common choice and default polarity is normal (i.e., 0).

Raises:

DwfLibraryError – An error occurred while executing the operation.

stopSet(stopbits: float) → None

Set the number of UART stop bits.

Parameters:

stopbits (float) –

The number of stop-bits used by the receiver and transmitter.

The most common choice is 1 stop-bit. Other values that are (rarely) encountered are 1.5 and 2 stop-bits.

Note that the actual number of stop-bits is the number specified here, rounded up to the next highest integer.

The parameter is declared as a float in anticipation of future support for 1.5 stop-bits.

Raises:

DwfLibraryError – An error occurred while executing the operation.

txSet(channel_index: int) → None

Set the digital channel (pin) where the UART’s outgoing (TX) signal will be transmitted.

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

rxSet(channel_index: int) → None

Set the digital channel (pin) where the UART’s incoming (RX) signal is received.

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

tx(tx_data: bytes) → None

Transmit data according to the currently active UART settings.

Parameters:: tx_data (bytes) – The data to be transmitted.
Raises:: DwfLibraryError – An error occurred while executing the operation.

rx(rx_max: int) → Tuple[bytes, int]

Receive UART data or prepare for reception.

Important

This method must be called with value 0 prior to receiving data, to initialize the receiver.

Parameters:

rx_max (int) –

If 0, initialize the receiver.

Otherwise, receive the specified number of characters.

Returns:

Bytes received and parity error indication.

Return type:

Tuple[bytes, int]

Todo

The meaning of the parity error indication is currently unclear. This needs to be investigated.

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