Struct stm32f3xx_hal::serial::Serial

pub struct Serial<Usart, Pins> { /* fields omitted */ }

Serial abstraction

This is an abstraction of the UART peripheral intended to be used for standard duplex serial communication.

Implementations

impl<Usart, Tx, Rx> Serial<Usart, (Tx, Rx)> where
    Usart: Instance, 

pub fn new<Config>(
    usart: Usart,
    pins: (Tx, Rx),
    config: Config,
    clocks: Clocks,
    apb: &mut <Usart as Instance>::APB
) -> Self where
    Usart: Instance,
    Tx: TxPin<Usart>,
    Rx: RxPin<Usart>,
    Config: Into<Config>, 

Configures a USART peripheral to provide serial communication

pub unsafe fn peripheral(&mut self) -> &mut Usart

Get access to the underlying register block.

Safety

This function is not memory unsafe per se, but does not guarantee anything about assumptions of invariants made in this implementation.

Changing specific options can lead to un-expected behavior and nothing is guaranteed.

pub fn free(self) -> (Usart, (Tx, Rx))

Releases the USART peripheral and associated pins

pub fn join(tx: Tx<Usart, Tx>, rx: Rx<Usart, Rx>) -> Self where
    Tx: TxPin<Usart>,
    Rx: RxPin<Usart>, 

Joins previously Serial::split() serial.

This is often needed to access methods only implemented for Serial but not for Tx nor Rx.

Example

let dp = pac::Peripherals::take().unwrap();

(tx, rx) = Serial::new(dp.USART1, ...).split();

// Do something with tx and rx

serial = Serial::join(tx, rx);

impl<Usart, Pins> Serial<Usart, Pins> where
    Usart: Instance, 

pub fn raw_read(&self) -> Option<u8>

Serial read out of the read register

No error handling and no additional side-effects, besides the implied side-effects when reading out the RDR register. Handling errors has to be done manually. This can be done, by checking the triggered events via Serial::triggered_events.

Returns None if the hardware is busy.

pub fn is_busy(&mut self) -> bool

Check if the USART peripheral is busy.

This can be useful to block on to synchronize between peripheral and CPU because of the asynchronous nature of the peripheral.

pub fn interrupt(&self) -> <Usart as InterruptNumber>::Interrupt

Obtain the associated interrupt number for the serial peripheral.

Used to unmask / enable the interrupt with cortex_m::peripheral::NVIC::unmask(). This is useful for all cortex_m::peripheral::INTERRUPT functions.

Note

This is the easier alternative to obatain the interrupt for:

use cortex_m::peripheral::INTERRUPT;
use stm32f3xx_hal::pac::USART1;
use stm32f3xx_hal::interrupt::InterruptNumber;

const INTERRUPT: Interrupt = <USART1 as InterruptNumber>::INTERRUPT;

though this function can not be used in a const context.

pub fn enable_interrupt(&mut self, event: Event)

Enable the interrupt for the specified Event.

pub fn disable_interrupt(&mut self, event: Event)

Disable the interrupt for the specified Event.

pub fn configure_interrupt(&mut self, event: Event, enable: impl Into<Toggle>)

Enable or disable the interrupt for the specified Event.

pub fn configure_interrupts(&mut self, events: EnumSet<Event>)

Enable or disable interrupt for the specified Events.

Like Serial::configure_interrupt, but instead using an enumset. The corresponding interrupt for every Event in the set will be enabled, every other interrupt will be disabled.

pub fn is_event_triggered(&self, event: Event) -> bool

Check if an interrupt event happend.

pub fn triggered_events(&self) -> EnumSet<Event>

Get an EnumSet of all fired interrupt events.

Examples

This allows disabling all fired event at once, via the enum set abstraction, like so

for event in serial.events() {
    serial.listen(event, false);
}

pub fn clear_event(&mut self, event: Event)

Clear the given interrupt event flag.

pub fn clear_events(&mut self)

Clear all interrupt events.

pub fn detect_overrun(&mut self, enable: bool)

Enable or disable overrun detection

When overrun detection is disabled and new data is received while the Event::ReceiveDataRegisterNotEmpty flag is still set, the Event::OverrunError flag is not set and the new received data overwrites the previous content of the RDR register.

pub fn set_match_character(&mut self, char: u8)

Configuring the UART to match each received character, with the configured one.

If the character is matched Event::CharacterMatch is generated, which can fire an interrupt, if enabled via Serial::configure_interrupt()

pub fn match_character(&self) -> u8

Read out the configured match character.

impl<Usart, Tx, Rx> Serial<Usart, (Tx, Rx)> where
    Usart: Instance + ReceiverTimeoutExt, 

pub fn set_receiver_timeout(&mut self, value: Option<u32>)

Set the receiver timeout value.

The RTOF flag (Event::ReceiverTimeout) is set if, after the last received character, no new start bit is detected for more than the receiver timeout value, where the value is being a counter, which is decreased by the configured baud rate.

A simple calculation might be time_per_counter_value = 1 / configured_baud_rate

Note

• If the value is None, the receiver timeout feature is disabled.
• This value must only be programmed once per received character.
• Can be written on the fly. If the new value is lower than or equal to the counter, the RTOF flag is set.
• Values higher than 24 bits are truncated to 24 bit max (16_777_216).

pub fn receiver_timeout(&self) -> Option<u32>

Read out the currently set timeout value

The relationship between the unit value and time is described in Serial::receiver_timeout.

• If the value is None, the receiver timeout feature is disabled.

impl<Usart, Pins> Serial<Usart, Pins> where
    Usart: Instance + Dma, 

pub fn read_exact<B, C>(self, buffer: B, channel: C) -> Transfer<B, C, Self> where
    Self: OnChannel<C>,
    B: WriteBuffer<Word = u8> + 'static,
    C: Channel, 

Fill the buffer with received data using DMA.

pub fn write_all<B, C>(self, buffer: B, channel: C) -> Transfer<B, C, Self> where
    Self: OnChannel<C>,
    B: ReadBuffer<Word = u8> + 'static,
    C: Channel, 

Transmit all data in the buffer using DMA.

impl<Tx, Rx> Serial<USART1, (Tx, Rx)> where
    Tx: TxPin<USART1>,
    Rx: RxPin<USART1>, 

pub fn split(self) -> (Tx<USART1, Tx>, Rx<USART1, Rx>)

Splits the Serial abstraction into a transmitter and a receiver half.

This allows using Tx and Rx related actions to be handled independently and even use these safely in different contexts (like interrupt routines) without needing to do synchronization work between them.

impl<Tx, Rx> Serial<USART2, (Tx, Rx)> where
    Tx: TxPin<USART2>,
    Rx: RxPin<USART2>, 

pub fn split(self) -> (Tx<USART2, Tx>, Rx<USART2, Rx>)

Splits the Serial abstraction into a transmitter and a receiver half.

This allows using Tx and Rx related actions to be handled independently and even use these safely in different contexts (like interrupt routines) without needing to do synchronization work between them.

impl<Tx, Rx> Serial<USART3, (Tx, Rx)> where
    Tx: TxPin<USART3>,
    Rx: RxPin<USART3>, 

pub fn split(self) -> (Tx<USART3, Tx>, Rx<USART3, Rx>)

Splits the Serial abstraction into a transmitter and a receiver half.

This allows using Tx and Rx related actions to be handled independently and even use these safely in different contexts (like interrupt routines) without needing to do synchronization work between them.

impl<Tx, Rx> Serial<UART4, (Tx, Rx)> where
    Tx: TxPin<UART4>,
    Rx: RxPin<UART4>, 

pub fn split(self) -> (Tx<UART4, Tx>, Rx<UART4, Rx>)

Splits the Serial abstraction into a transmitter and a receiver half.

This allows using Tx and Rx related actions to be handled independently and even use these safely in different contexts (like interrupt routines) without needing to do synchronization work between them.

impl<Tx, Rx> Serial<UART5, (Tx, Rx)> where
    Tx: TxPin<UART5>,
    Rx: RxPin<UART5>, 

pub fn split(self) -> (Tx<UART5, Tx>, Rx<UART5, Rx>)

Splits the Serial abstraction into a transmitter and a receiver half.

This allows using Tx and Rx related actions to be handled independently and even use these safely in different contexts (like interrupt routines) without needing to do synchronization work between them.

Trait Implementations

impl<Pins> Debug for Serial<USART1, Pins>

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

Formats the value using the given formatter.

impl<Pins> Debug for Serial<USART2, Pins>

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

Formats the value using the given formatter.

impl<Pins> Debug for Serial<USART3, Pins>

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

Formats the value using the given formatter.

impl<Pins> Debug for Serial<UART4, Pins>

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

Formats the value using the given formatter.

impl<Pins> Debug for Serial<UART5, Pins>

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

Formats the value using the given formatter.

impl<Usart, Tx, Rx> Read<u8> for Serial<Usart, (Tx, Rx)> where
    Usart: Instance, 

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

Getting back an error means that the error is defined as “handled”:

This implementation has the side effect for error handling, that the Event flag of the returned Error is cleared.

This might be a problem, because if an interrupt is enabled for this particular flag, the interrupt handler might not have the chance to find out from which flag the interrupt originated.

So this function is only intended to be used for direct error handling and not leaving it up to the interrupt handler.

To read out the content of the read register without internal error handling, use Serial::raw_read(). …

type Error = Error

Read error

impl<Usart, Pins> Target for Serial<Usart, Pins> where
    Usart: Instance + Dma, 

fn enable_dma(&mut self)

Enable DMA on the target

fn disable_dma(&mut self)

Disable DMA on the target

impl<Usart, Pins> Write for Serial<Usart, Pins> where
    Serial<Usart, Pins>: Write<u8>, 

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl<Usart, Pins> Write<u8> for Serial<Usart, Pins> where
    Usart: Instance, 

type Error = Infallible

Write error

fn flush(&mut self) -> Result<(), Infallible>

Ensures that none of the previously written words are still buffered

fn write(&mut self, byte: u8) -> Result<(), Infallible>

Writes a single word to the serial interface

impl<USART, TX, RX> Default<u8> for Serial<USART, (TX, RX)> where
    USART: Instance, 

impl<Tx, Rx> OnChannel<C2> for Serial<USART3, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C3> for Serial<USART3, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C3> for Serial<UART4, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C4> for Serial<USART1, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C5> for Serial<USART1, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C5> for Serial<UART4, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C6> for Serial<USART2, (Tx, Rx)>

impl<Tx, Rx> OnChannel<C7> for Serial<USART2, (Tx, Rx)>