1.. _module-pw_uart: 2 3======= 4pw_uart 5======= 6.. pigweed-module:: 7 :name: pw_uart 8 9Pigweed's ``pw_uart`` module provides a set of interfaces for communicating via 10UART. 11 12-------- 13Overview 14-------- 15``pw_uart`` defines core methods for UART communication. This serves 16as a blueprint for concrete UART implementations. You will need to write the 17backend code tailored to your specific hardware device to interact with the 18UART peripheral. 19 20The interface consists of these main classes: 21 22- `UartBase`_ - Base class which provides basic enable/disable and 23 configuration control, but no communication. 24- `Uart`_ - Extends ``pw::uart::UartBase`` to provide blocking Read and Write 25 APIs. 26- `UartNonBlocking`_ - Extends ``pw::uart::UartBase`` to provide non-blocking 27 (callback-based) Read and Write APIs. 28- `UartBlockingAdapter`_ - Provides the blocking `Uart`_ interface on top of a 29 `UartNonBlocking`_ device. 30- `UartStream`_ - Provides the ``pw::stream::NonSeekableReaderWriter`` 31 (:ref:`module-pw_stream`) interface on top of a `Uart`_ device. 32 33.. mermaid:: 34 35 classDiagram 36 namespace uart { 37 class UartBase 38 class Uart 39 class UartNonBlocking 40 class UartBlockingAdapter 41 class UartStream 42 } 43 44 namespace stream { 45 class NonSeekableReaderWriter 46 } 47 48 UartBase <|-- Uart : extends 49 UartBase <|-- UartNonBlocking : extends 50 51 Uart <|-- UartBlockingAdapter : implements 52 UartNonBlocking --> UartBlockingAdapter 53 54 NonSeekableReaderWriter <|-- UartStream : implements 55 Uart --> UartStream 56 57----------- 58Get started 59----------- 60.. repository: https://bazel.build/concepts/build-ref#repositories 61 62.. tab-set:: 63 64 .. tab-item:: Bazel 65 66 Add ``@pigweed//pw_uart`` to the ``deps`` list in your Bazel target: 67 68 .. code-block:: 69 70 cc_library("...") { 71 # ... 72 deps = [ 73 # ... 74 "@pigweed//pw_uart", 75 # ... 76 ] 77 } 78 79 This assumes that your Bazel ``WORKSPACE`` has a `repository 80 <https://bazel.build/concepts/build-ref#repositories>`_ named ``@pigweed`` 81 that points to the upstream Pigweed repository. 82 83 .. tab-item:: GN 84 85 Add ``$dir_pw_uart`` to the ``deps`` list in your ``pw_executable()`` 86 build target: 87 88 .. code-block:: 89 90 pw_executable("...") { 91 # ... 92 deps = [ 93 # ... 94 "$dir_pw_uart", 95 # ... 96 ] 97 } 98 99 .. tab-item:: CMake 100 101 Add ``pw_uart`` to your ``pw_add_library`` or similar CMake target: 102 103 .. code-block:: 104 105 pw_add_library(my_library STATIC 106 HEADERS 107 ... 108 PRIVATE_DEPS 109 # ... 110 pw_uart 111 # ... 112 ) 113 114.. _module-pw_uart-reference: 115 116------------- 117API reference 118------------- 119 120.. warning:: 121 122 Drivers should not implement both ``Uart`` and ``UartNonBlocking`` 123 interfaces. 124 125 Drivers which support non-blocking (callback) behavior should implement 126 ``UartNonBlocking``. Applications that require the blocking ``Uart`` 127 interface can use the ``UartBlockingAdapter``. 128 129UartBase 130======== 131.. doxygenclass:: pw::uart::UartBase 132 :members: 133 134Uart 135==== 136.. doxygenclass:: pw::uart::Uart 137 :members: 138 139UartNonBlocking 140=============== 141.. doxygenclass:: pw::uart::UartNonBlocking 142 :members: 143 144UartBlockingAdapter 145=================== 146.. doxygenclass:: pw::uart::UartBlockingAdapter 147 :members: 148 149UartStream 150========== 151.. doxygenclass:: pw::uart::UartStream 152 :members: 153 154 155.. toctree:: 156 :hidden: 157 :maxdepth: 1 158 159 Backends <backends> 160