pw_uart#

The Uart interface defines the core methods for UART communication. This serves as a blueprint for concrete UART implementations. You will need to write the backend code tailored to your specific hardware device to interact with the UART peripheral.

Get started#

Bazel

Add @pigweed//pw_uart to the deps list in your Bazel target:

cc_library("...") {
  # ...
  deps = [
    # ...
    "@pigweed//pw_uart",
    # ...
  ]
}

This assumes that your Bazel WORKSPACE has a repository named @pigweed that points to the upstream Pigweed repository.

Add $dir_pw_uart to the deps list in your pw_executable() build target:

pw_executable("...") {
  # ...
  deps = [
    # ...
    "$dir_pw_uart",
    # ...
  ]
}

CMake

Add pw_uart to your pw_add_library or similar CMake target:

pw_add_library(my_library STATIC
  HEADERS
    ...
  PRIVATE_DEPS
    # ...
    pw_uart
    # ...
)

API reference#

class Uart#

Public Functions

inline Status Enable()#

Initializes the UART module on the microcontroller, sets it into the default state as determined by the concrete UART implementation. This function should be a no-op if the UART module is in an enabled state.

This may change the power state of the UART module, configure the interface parameters, enable the associated pins, setup the internal TX and RX buffers, etc…

Returns:

Code	Description
`OK`	The UART module has been succesfully initialized.
`INTERNAL`	Internal errors within the hardware abstraction layer.

inline Status Disable()#

Disables the UART module on the microcontroller. Disabling the UART shuts down communication and prevents the microcontroller from sending or receiving data through the UART port.

This is usually done to save power. Interrupt handlers should also be disabled.

Returns:

Code	Description
`OK`	The UART module has been succesfully initialized.
`INTERNAL`	Internal errors within the hardware abstraction layer.

inline Status SetBaudRate(uint32_t baud_rate)#

Configures the UART communication baud rate.

This function sets the communication speed (baud rate) for the UART. Whether the baud rate can be changed while the UART is enabled depends on the specific implementation.

Returns:

Code	Description
`OK`	The UART has been succesfully initialized.
`FAILED_PRECONDITION`	The device is enabled and does not support changing settings on the fly.
`INTERNAL`	Internal errors within the hardware abstraction layer.

inline Status Read(ByteSpan rx_buffer)#

Reads data from the UART into a provided buffer.

This function blocks until the entirety of rx_buffer is filled with data.

Parameters:

rx_buffer – The buffer to read data into.

Returns:

Code	Description
`OK`	The operation was successful.

May return other implementation-specific status codes.

inline StatusWithSize TryReadFor(ByteSpan rx_buffer, chrono::SystemClock::duration timeout)#

Reads data from the UART into a provided buffer.

This function blocks until either the entire buffer has been filled with data or the specified timeout has elapsed, whichever occurs first.

Parameters:

rx_buffer – The buffer to read data into.
timeout – The maximum time to wait for data to be read. If zero, the function will immediately return with at least one hardware read operation attempt.

Returns:

Code	Description
`OK`	The operation was successful and the entire buffer has been filled with data.
`DEADLINE_EXCEEDED`	The operation timed out before the entire buffer could be filled.

May return other implementation-specific status codes.

inline Status Write(ConstByteSpan tx_buffer)#

Writes data from the provided buffer to the UART. The function blocks until the entire buffer has been written.

Parameters:

tx_buffer – - The buffer to write data from.

Returns:

Code	Description
`OK`	The operation was successful.

May return other implementation-specific status codes.

inline StatusWithSize TryWriteFor(ConstByteSpan tx_buffer, chrono::SystemClock::duration timeout)#

Writes data from the provided buffer to the UART. The function blocks until either the entire buffer has been written or the specified timeout has elapsed, whichever occurs first.

Parameters:

tx_buffer – The buffer to write data from.
timeout – The maximum time to wait for data to be written. If zero, the function will immediately return with at least one hardware write operation attempt.

Returns:

Code	Description
`OK`	The operation was successful and the entire buffer has been written.
`DEADLINE_EXCEEDED`	The operation timed out before the entire buffer could be written.

May return other implementation-specific status codes.

inline size_t ConservativeReadAvailable()#

Returns the number of bytes currently available for reading.

This function checks the receive buffer to determine how many bytes of data are ready to be read.

Returns:: The number of bytes available for reading. When no data is available or in case of an error this function returns 0.

inline Status FlushOutput()#

Blocks until all queued data in the UART has been transmitted and the FIFO is empty.

This function ensures that all data enqueued before calling this function has been transmitted. Any data enqueued after calling this function will be transmitted immediately.

Returns:

Code	Description
`OK`	The operation was successful.

May return other implementation-specific status codes.

inline Status ClearPendingReceiveBytes()#

Empties the UART’s receive buffer and discards any unread data.

This function removes all data from the receive buffer, resetting the buffer to an empty state. This is useful for situations where you want to disregard any previously received data and resynchronize.

Returns:

Code	Description
`OK`	The operation was successful.

May return other implementation-specific status codes.