Struct rppal::uart::Uart

pub struct Uart { /* fields omitted */ }

Provides access to the Raspberry Pi's UART peripherals and any USB to serial adapters.

The embedded-hal serial::Read, serial::Write and blocking::serial::Write trait implementations for Uart can be enabled by specifying the optional hal feature in the dependency declaration for the rppal crate.

Methods

impl Uart

pub fn new(
    baud_rate: u32,
    parity: Parity,
    data_bits: u8,
    stop_bits: u8
) -> Result<Uart>

Constructs a new Uart.

new attempts to identify the UART peripheral tied to BCM GPIO 14 and 15, and then calls with_path with the appropriate device path.

pub fn with_path<P: AsRef<Path>>(
    path: P,
    baud_rate: u32,
    parity: Parity,
    data_bits: u8,
    stop_bits: u8
) -> Result<Uart>

Constructs a new Uart connected to the serial character device specified by path.

with_path can be used to connect to either a UART peripheral or a USB to serial adapter.

When a new Uart is constructed, the specified device is configured for non-canonical mode which processes input per character, ignores any special terminal input or output characters and disables local echo. DCD is ignored, all flow control is disabled, and the input and output queues are flushed.

pub fn baud_rate(&self) -> u32

Returns the line speed in baud (Bd).

pub fn set_baud_rate(&mut self, baud_rate: u32) -> Result<()>

Sets the line speed in baud (Bd).

On the Raspberry Pi, baud rate is equivalent to bit rate in bits per second (bit/s).

Accepted values: 0, 50, 75, 110, 134, 150, 200, 300, 600, 1_200, 1_800, 2_400, 4_800, 9_600, 19_200, 38_400, 57_600, 115_200, 230_400, 460_800, 500_000, 576_000, 921_600, 1_000_000, 1_152_000, 1_500_000, 2_000_000, 2_500_000, 3_000_000, 3_500_000, 4_000_000.

Support for some values may be device-dependent.

pub fn parity(&self) -> Parity

Returns the parity bit mode.

pub fn set_parity(&mut self, parity: Parity) -> Result<()>

Sets the parity bit mode.

The parity bit mode determines how the parity bit is calculated.

Support for some modes may be device-dependent.

pub fn parity_check(&self) -> ParityCheck

Returns the parity check mode for incoming data.

pub fn set_parity_check(&mut self, parity_check: ParityCheck) -> Result<()>

Configures parity checking for incoming data.

The parity check mode determines how parity errors are handled.

By default, parity_check is set to None.

Support for some modes may be device-dependent.

pub fn data_bits(&self) -> u8

Returns the number of data bits.

pub fn set_data_bits(&mut self, data_bits: u8) -> Result<()>

Sets the number of data bits.

Accepted values: 5, 6, 7, 8.

Support for some values may be device-dependent.

pub fn stop_bits(&self) -> u8

Returns the number of stop bits.

pub fn set_stop_bits(&mut self, stop_bits: u8) -> Result<()>

Sets the number of stop bits.

Accepted values: 1, 2.

Support for some values may be device-dependent.

pub fn status(&self) -> Result<Status>

Returns the status of the control signals.

pub fn set_dtr(&mut self, dtr: bool) -> Result<()>

Sets DTR to active (true) or inactive (false).

DTR is not supported by the Raspberry Pi's UART peripherals, but may be available on some USB to serial adapters.

pub fn set_rts(&mut self, rts: bool) -> Result<()>

Sets RTS to active (true) or inactive (false).

pub fn software_flow_control(&self) -> bool

Returns true if XON/XOFF software flow control is enabled.

pub fn set_software_flow_control(
    &mut self,
    software_flow_control: bool
) -> Result<()>

Enables or disables XON/XOFF software flow control.

When software flow control is enabled, incoming XON (decimal 17) and XOFF (decimal 19) control characters are filtered from the input queue. When XOFF is received, the transmission of data in the output queue is paused until the external device sends XON. XOFF is automatically sent to the external device to prevent the input queue from overflowing. XON is sent when the input queue is ready for more data. You can also manually send these control characters by calling send_stop and send_start.

By default, software flow control is disabled.

Support for XON/XOFF software flow control is device-dependent. You can manually implement XON/XOFF by disabling software flow control, parsing incoming XON/XOFF control characters received with read, and sending XON/XOFF when needed using write.

pub fn hardware_flow_control(&self) -> bool

Returns true if RTS/CTS hardware flow control is enabled.

pub fn set_hardware_flow_control(
    &mut self,
    hardware_flow_control: bool
) -> Result<()>

Enables or disables RTS/CTS hardware flow control.

When hardware flow control is enabled, the RTS line (active low) is automatically driven high to prevent the input queue from overflowing, and driven low when the input queue is ready for more data. When the CTS line (active low) is driven high by the external device, all data in the output queue is held until CTS is driven low. You can also manually change the active state of RTS by calling send_stop and send_start.

When Uart is controlling a UART peripheral, enabling hardware flow control will also configure the RTS and CTS pins.

More information on hardware flow control can be found here.

By default, hardware flow control is disabled.

Support for RTS/CTS hardware flow control is device-dependent. You can manually implement RTS/CTS using cts, send_stop and send_start, or by disabling hardware flow control and configuring an OutputPin for RTS and an InputPin for CTS.

pub fn send_stop(&self) -> Result<()>

Requests the external device to pause its transmission using flow control.

If software flow control is enabled, send_stop sends the XOFF control character.

If hardware flow control is enabled, send_stop sets RTS to its inactive state.

pub fn send_start(&self) -> Result<()>

Requests the external device to resume its transmission using flow control.

If software flow control is enabled, send_start sends the XON control character.

If hardware flow control is enabled, send_start sets RTS to its active state.

pub fn is_read_blocking(&self) -> bool

Returns true if read is configured to block when needed.

pub fn is_write_blocking(&self) -> bool

Returns true if write is configured to block when needed.

pub fn set_read_mode(&mut self, min_length: u8, timeout: Duration) -> Result<()>

Sets the blocking mode for subsequent calls to read.

min_length indicates the minimum number of requested bytes. This value may differ from the actual buffer length. Maximum value: 255 bytes.

timeout indicates how long read blocks while waiting for incoming data. timeout uses a 0.1 second resolution. Maximum value: 25.5 seconds.

read operates in one of four modes, depending on the specified min_length and timeout values:

• Non-blocking read (min_length = 0, timeout = 0). read retrieves any available data and returns immediately.
• Blocking read (min_length > 0, timeout = 0). read blocks until at least min_length bytes are available, or the provided buffer is full.
• Read with timeout (min_length = 0, timeout > 0). read blocks until at least one byte is available, or the timeout duration elapses.
• Read with inter-byte timeout (min_length > 0, timeout > 0). read blocks until at least min_length bytes are available, the provided buffer is full, or the timeout duration elapses after receiving one or more bytes. The timer is started after an initial byte becomes available, and is restarted after each additional byte. That means read will block indefinitely until at least one byte has been received.

By default, read is configured as non-blocking.

pub fn set_write_mode(&mut self, blocking: bool) -> Result<()>

Sets the blocking mode for subsequent calls to write.

write operates in one of two modes, depending on the specified blocking value:

• Non-blocking write. write returns immediately after copying as much of the contents of the provided buffer to the output queue as it's able to fit.
• Blocking write. write blocks until the entire contents of the provided buffer can be copied to the output queue. If flow control is enabled and the external device has sent a stop request, the transmission of any waiting data in the output queue is paused until a start request has been received.

By default, write is configured as non-blocking.

pub fn input_len(&self) -> Result<usize>

Returns the number of bytes waiting in the input queue.

pub fn output_len(&self) -> Result<usize>

Returns the number of bytes waiting in the output queue.

pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize>

Receives incoming data from the external device and stores it in buffer.

read operates in one of four (non)blocking modes, depending on the settings configured by set_read_mode. By default, read is configured as non-blocking.

Returns how many bytes were read.

pub fn write(&mut self, buffer: &[u8]) -> Result<usize>

Sends the contents of buffer to the external device.

write operates in either blocking or non-blocking mode, depending on the settings configured by set_write_mode. By default, write is configured as non-blocking.

Returns how many bytes were written.

pub fn drain(&self) -> Result<()>

Blocks until all data in the output queue has been transmitted.

pub fn flush(&self, queue_type: Queue) -> Result<()>

Discards all data in the input and/or output queue.

Trait Implementations

impl Debug for Uart

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default<u8> for Uart

impl Read<u8> for Uart

type Error = Error

Read error

fn read(&mut self) -> Result<u8, Self::Error>

Reads a single word from the serial interface

impl Write<u8> for Uart

type Error = Error

Write error

fn write(&mut self, word: u8) -> Result<(), Self::Error>

Writes a single word to the serial interface

fn flush(&mut self) -> Result<(), Self::Error>

Ensures that none of the previously written words are still buffered