1.. _docs-quickstart-zephyr: 2 3================= 4Zephyr quickstart 5================= 6.. _Zephyr: https://zephyrproject.org/ 7.. _native_sim: https://docs.zephyrproject.org/latest/boards/native/native_sim/doc/index.html 8.. _GPIO Driver API: https://docs.zephyrproject.org/latest/doxygen/html/group__devicetree-gpio.html 9 10This tutorial shows you how to set up a new C++-based `Zephyr`_ project that's 11ready to use Pigweed. You'll learn how to build and run the project's app on 12`native_sim`_ as well as a physical Raspberry Pi Pico. The app uses 13:ref:`module-pw_log` and :ref:`module-pw_string` to log messages and 14Zephyr's `GPIO Driver API`_ to blink an LED. 15 16.. figure:: https://storage.googleapis.com/pigweed-media/zephyr-quickstart-pw_ide.png 17 :alt: Editing the Zephyr quickstart project in VS Code 18 19 The project's :ref:`module-pw_ide` integration provides code intelligence 20 and easy target swapping in VS Code 21 22.. _docs-quickstart-zephyr-prereqs: 23 24------------- 25Prerequisites 26------------- 27* **Disk space**: After setting everything up, the project takes ~19GB of space. 28 The project clones the Zephyr and Pigweed repos as well as their dependencies. 29 It also downloads toolchains and sets up a hermetic development environment. 30* **Operating systems**: This tutorial has only been validated on Debian-based 31 Linux and macOS. Windows support is a work in progress. 32 33.. _docs-quickstart-zephyr-setup: 34 35----- 36Setup 37----- 38#. Complete Pigweed's :ref:`First-time setup <docs-first-time-setup-guide>` 39 process. 40 41#. Clone the starter repo. 42 43 .. tab-set:: 44 45 .. tab-item:: Linux 46 :sync: lin 47 48 .. code-block:: console 49 50 git clone --recursive \ 51 https://pigweed.googlesource.com/pigweed/quickstart/zephyr \ 52 zephyr-quickstart 53 54 .. tab-item:: macOS 55 :sync: mac 56 57 .. code-block:: console 58 59 git clone --recursive \ 60 https://pigweed.googlesource.com/pigweed/quickstart/zephyr \ 61 zephyr-quickstart 62 63 .. _main Pigweed: https://pigweed.googlesource.com/pigweed/pigweed/ 64 .. _main Zephyr: https://github.com/zephyrproject-rtos/zephyr 65 66 This command downloads the `main Pigweed`_ and `main Zephyr`_ repos 67 as Git submodules. 68 69#. Change your working directory to the quickstart repo. 70 71 .. tab-set:: 72 73 .. tab-item:: Linux 74 :sync: lin 75 76 .. code-block:: console 77 78 cd zephyr-quickstart 79 80 .. tab-item:: macOS 81 :sync: mac 82 83 .. code-block:: console 84 85 cd zephyr-quickstart 86 87#. Bootstrap the repo. 88 89 .. tab-set:: 90 91 .. tab-item:: Linux 92 :sync: lin 93 94 .. code-block:: console 95 96 source bootstrap.sh 97 98 .. tab-item:: macOS 99 :sync: mac 100 101 .. code-block:: console 102 103 source bootstrap.sh 104 105 Pigweed's bootstrap workflow creates a hermetic development environment 106 for you, including toolchain setup! 107 108 .. tip:: 109 110 For subsequent development sessions, activate your development environment 111 with the following command: 112 113 .. tab-set:: 114 115 .. tab-item:: Linux 116 :sync: lin 117 118 .. code-block:: console 119 120 source activate.sh 121 122 .. tab-item:: macOS 123 :sync: mac 124 125 .. code-block:: console 126 127 source activate.sh 128 129 The activate script is faster than the bootstrap script. You only need to 130 run the bootstrap script after updating your Zephyr or Pigweed submodules. 131 132 .. _West: https://docs.zephyrproject.org/latest/develop/west/index.html 133 134#. Initialize your `West`_ workspace using the manifest that came with the 135 starter repo. 136 137 .. code-block:: console 138 139 west init -l manifest 140 141#. Update your West workspace. 142 143 .. code-block:: console 144 145 west update 146 147#. (Optional) Initialize :ref:`module-pw_ide` if you plan on working in 148 VS Code. ``pw_ide`` provides code intelligence features and makes it 149 easy to swap targets. 150 151 .. code-block:: console 152 153 pw ide sync 154 155.. _docs-quickstart-zephyr-build: 156 157--------------------- 158Build and run the app 159--------------------- 160 161.. _docs-quickstart-zephyr-build-native_sim: 162 163Native simulator 164================ 165#. Build the quickstart app for `native_sim`_ and run it: 166 167 .. code-block:: console 168 169 export ZEPHYR_TOOLCHAIN_VARIANT=llvm && 170 west build -p -b native_sim app -t run 171 172 You should see the app successfully build and then log messages to 173 ``stdout``: 174 175 .. code-block:: none 176 177 [00:00:00.000,000] <inf> pigweed: Hello, world! 178 [00:00:00.000,000] <inf> pigweed: LED state: OFF 179 [00:00:01.010,000] <inf> pigweed: LED state: ON 180 [00:00:02.020,000] <inf> pigweed: LED state: OFF 181 [00:00:03.030,000] <inf> pigweed: LED state: ON 182 [00:00:04.040,000] <inf> pigweed: LED state: OFF 183 184 .. important:: 185 186 When building for ``native_sim`` make sure that 187 ``ZEPHYR_TOOLCHAIN_VARIANT`` is set to ``llvm``. 188 See :ref:`docs-quickstart-zephyr-troubleshooting-envvar`. 189 190#. (Optional) Build and run an upstream Zephyr sample app: 191 192 .. code-block:: console 193 194 west build -p -b native_sim third_party/zephyr/samples/basic/blinky -t run 195 196.. _docs-quickstart-zephyr-build-pico: 197 198Raspberry Pi Pico 199================= 200.. _Raspberry Pi Pico: https://docs.zephyrproject.org/latest/boards/raspberrypi/rpi_pico/doc/index.html 201.. _Pico SDK: https://github.com/raspberrypi/pico-sdk 202.. _picotool: https://github.com/raspberrypi/picotool 203 204#. Build the quickstart app for `Raspberry Pi Pico`_: 205 206 .. code-block:: console 207 208 export ZEPHYR_TOOLCHAIN_VARIANT=zephyr && 209 west build -p -b rpi_pico app 210 211 .. important:: 212 213 When building for physical boards make sure that 214 ``ZEPHYR_TOOLCHAIN_VARIANT`` is set to ``zephyr``. 215 See :ref:`docs-quickstart-zephyr-troubleshooting-envvar`. 216 217#. Install the `Pico SDK`_ and `picotool`_ so that you can easily 218 flash the quickstart app onto your Pico over USB without needing to 219 manually put your Pico board into ``BOOTSEL`` mode: 220 221 .. code-block:: console 222 223 pw package install pico_sdk 224 pw package install picotool 225 226#. Add the following rules to ``/etc/udev/rules.d/49-pico.rules`` or 227 ``/usr/lib/udev/rules.d/49-pico.rules``. Create the file if it doesn't exist. 228 229 .. literalinclude:: /targets/rp2040/49-pico.rules 230 :language: linuxconfig 231 :start-at: # Raspberry 232 233#. Apply the rules: 234 235 .. code-block:: console 236 237 sudo udevadm control --reload-rules 238 sudo udevadm trigger 239 240#. Flash the app onto your board: 241 242 .. code-block:: console 243 244 picotool reboot -f -u && 245 sleep 3 && 246 picotool load -x ./build/zephyr/zephyr.elf 247 248.. _docs-quickstart-zephyr-troubleshooting: 249 250--------------- 251Troubleshooting 252--------------- 253 254.. _docs-quickstart-zephyr-troubleshooting-envvar: 255 256``fatal error: bits/c++config.h: No such file or directory`` 257============================================================ 258If you see a compilation error about not being able to find 259``<bits/c++config.h>``, make sure that your ``ZEPHYR_TOOLCHAIN_VARIANT`` 260environment variable is correctly set: 261 262* Set it to ``llvm`` when building for ``native_sim``. 263* Set it to ``zephyr`` when building for physical boards. 264 265Here's an example of the error: 266 267.. code-block:: console 268 269 ... 270 [2/109] Generating include/generated/version.h 271 -- Zephyr version: 3.6.99 (~/zephyr-quickstart/third_party/zephyr), build: v3.6.0-1976-g8a88cd4805b0 272 [10/109] Building CXX object modules/pigweed/pw_string/CMakeFiles/pw_string.to_string.dir/type_to_string.cc.obj 273 FAILED: modules/pigweed/pw_string/CMakeFiles/pw_string.to_string.dir/type_to_string.cc.obj 274 ccache /usr/bin/g++ 275 ... 276 -c ~/zephyr-quickstart/third_party/pigweed/pw_string/type_to_string.cc 277 In file included from ~/zephyr-quickstart/third_party/pigweed/pw_string/public/pw_string/type_to_string.h:20, 278 from ~/zephyr-quickstart/third_party/pigweed/pw_string/type_to_string.cc:15: 279 /usr/include/c++/13/cstdint:38:10: fatal error: bits/c++config.h: No such file or directory 280 38 | #include <bits/c++config.h> 281 | ^~~~~~~~~~~~~~~~~~ 282 compilation terminated. 283 ... 284 [12/109] Building CXX object modules/pigweed/pw_string/CMakeFiles/pw_string.builder.dir/string_builder.cc.obj 285 FAILED: modules/pigweed/pw_string/CMakeFiles/pw_string.builder.dir/string_builder.cc.obj 286 ccache /usr/bin/g++ 287 ... 288 -c ~/zephyr-quickstart/third_party/pigweed/pw_string/string_builder.cc 289 In file included from /usr/include/c++/13/algorithm:60, 290 from ~/zephyr-quickstart/third_party/pigweed/pw_string/public/pw_string/string_builder.h:21, 291 from ~/zephyr-quickstart/third_party/pigweed/pw_string/string_builder.cc:15: 292 /usr/include/c++/13/bits/stl_algobase.h:59:10: fatal error: bits/c++config.h: No such file or directory 293 59 | #include <bits/c++config.h> 294 | ^~~~~~~~~~~~~~~~~~ 295 compilation terminated. 296 [15/109] Building C object zephyr/CMakeFiles/offsets.dir/arch/posix/core/offsets/offsets.c.obj 297 ninja: build stopped: subcommand failed. 298 FATAL ERROR: command exited with status 1: ~/zephyr-quickstart/environment/cipd/packages/cmake/bin/cmake 299 --build ~/zephyr-quickstart/build --target run 300
