1.. _module-pw_hdlc-guide: 2 3==================== 4Get started & guides 5==================== 6.. pigweed-module-subpage:: 7 :name: pw_hdlc 8 9.. include:: design.rst 10 :start-after: .. pw_hdlc-overview-start 11 :end-before: .. pw_hdlc-overview-end 12 13.. _module-pw_hdlc-getstarted: 14 15------------------------ 16Get started with pw_hdlc 17------------------------ 18Depend on the library: 19 20.. tab-set:: 21 22 .. tab-item:: Bazel 23 :sync: bazel 24 25 Add ``@pigweed//pw_hdlc`` to the ``deps`` list in your Bazel target: 26 27 .. code-block:: 28 29 cc_library("...") { 30 # ... 31 deps = [ 32 # ... 33 "@pigweed//pw_hdlc", 34 # ... 35 ] 36 } 37 38 This assumes that your Bazel ``WORKSPACE`` has a `repository 39 <https://bazel.build/concepts/build-ref#repositories>`_ named ``@pigweed`` 40 that points to the upstream Pigweed repository. 41 42 .. tab-item:: GN 43 :sync: gn 44 45 Add ``$dir_pw_hdlc`` to the ``deps`` list in your ``pw_executable()`` 46 build target: 47 48 .. code-block:: 49 50 pw_executable("...") { 51 # ... 52 deps = [ 53 # ... 54 "$dir_pw_hdlc", 55 # ... 56 ] 57 } 58 59 60 .. tab-item:: CMake 61 :sync: cmake 62 63 Add ``pw_hdlc`` to your ``pw_add_library`` or similar CMake target: 64 65 .. code-block:: 66 67 pw_add_library(my_library STATIC 68 HEADERS 69 # ... 70 PRIVATE_DEPS 71 # ... 72 pw_hdlc 73 # ... 74 ) 75 76 .. tab-item:: Zephyr 77 :sync: zephyr 78 79 There are two ways to use ``pw_hdlc`` from a Zephyr project: 80 81 * (Recommended) Depend on ``pw_hdlc`` in your CMake target. See the CMake 82 tab. The Pigweed team recommends this approach because it enables 83 precise CMake dependency analysis. 84 85 * Add ``CONFIG_PIGWEED_HDLC=y`` to your Zephyr project's configuration. 86 Also add ``CONFIG_PIGWEED_HDLC_RPC=y`` if using RPC. Although this is 87 the typical Zephyr solution, the Pigweed team doesn't recommend this 88 approach because it makes ``pw_hdlc`` a global dependency and exposes 89 its includes to all targets. 90 91And then :ref:`encode <module-pw_hdlc-guide-encode>` and 92:ref:`decode <module-pw_hdlc-guide-decode>` some data! 93 94Set up RPC over HDLC 95==================== 96See :ref:`module-pw_hdlc-rpc-example`. 97 98.. _module-pw_hdlc-guide-encode: 99 100-------- 101Encoding 102-------- 103.. include:: docs.rst 104 :start-after: .. pw_hdlc-encoding-example-start 105 :end-before: .. pw_hdlc-encoding-example-end 106 107Allocating buffers when encoding 108================================ 109.. tab-set:: 110 111 .. tab-item:: C++ 112 :sync: cpp 113 114 HDLC encoding overhead changes depending on the payload size and the 115 nature of the data being encoded. ``pw_hdlc`` provides helper functions 116 for determining the size of buffers. The helper functions provide 117 worst-case sizes of frames given a certain payload size and vice-versa. 118 119 .. code-block:: cpp 120 121 #include "pw_assert/check.h" 122 #include "pw_bytes/span.h" 123 #include "pw_hdlc/encoder" 124 #include "pw_hdlc/encoded_size.h" 125 #include "pw_status/status.h" 126 127 // The max on-the-wire size in bytes of a single HDLC frame after encoding. 128 constexpr size_t kMtu = 512; 129 constexpr size_t kRpcEncodeBufferSize = pw::hdlc::MaxSafePayloadSize(kMtu); 130 std::array<std::byte, kRpcEncodeBufferSize> rpc_encode_buffer; 131 132 // Any data encoded to this buffer is guaranteed to fit in the MTU after 133 // HDLC encoding. 134 pw::ConstByteSpan GetRpcEncodeBuffer() { 135 return rpc_encode_buffer; 136 } 137 138.. _module-pw_hdlc-guide-decode: 139 140-------- 141Decoding 142-------- 143.. include:: docs.rst 144 :start-after: .. pw_hdlc-decoding-example-start 145 :end-before: .. pw_hdlc-decoding-example-end 146 147 148Allocating buffers when decoding 149================================ 150.. tab-set:: 151 152 .. tab-item:: C++ 153 :sync: cpp 154 155 ``pw::hdlc::Decoder`` is a helper for allocating a buffer. It has slightly 156 lower overhead because it doesn't need to decode the entire escaped 157 frame in-memory. 158 159 .. code-block:: cpp 160 161 #include "pw_hdlc/decoder.h" 162 163 // The max on-the-wire size in bytes of a single HDLC frame after encoding. 164 constexpr size_t kMtu = 512; 165 166 // Create a decoder given the MTU constraint. 167 constexpr size_t kDecoderBufferSize = 168 pw::hdlc::Decoder::RequiredBufferSizeForFrameSize(kMtu); 169 pw::hdlc::DecoderBuffer<kDecoderBufferSize> decoder; 170 171----------------- 172More pw_hdlc docs 173----------------- 174.. include:: docs.rst 175 :start-after: .. pw_hdlc-nav-start 176 :end-before: .. pw_hdlc-nav-end 177