1.. _getting_started: 2 3Getting Started Guide 4##################### 5 6Follow this guide to: 7 8- Set up a command-line Zephyr development environment on Ubuntu, macOS, or 9 Windows (instructions for other Linux distributions are discussed in 10 :ref:`installation_linux`) 11- Get the source code 12- Build, flash, and run a sample application 13 14.. _host_setup: 15 16Select and Update OS 17******************** 18 19Click the operating system you are using. 20 21.. tabs:: 22 23 .. group-tab:: Ubuntu 24 25 This guide covers Ubuntu version 20.04 LTS and later. 26 If you are using a different Linux distribution see :ref:`installation_linux`. 27 28 .. code-block:: bash 29 30 sudo apt update 31 sudo apt upgrade 32 33 .. group-tab:: macOS 34 35 On macOS Mojave or later, select *System Preferences* > 36 *Software Update*. Click *Update Now* if necessary. 37 38 On other versions, see `this Apple support topic 39 <https://support.apple.com/en-us/HT201541>`_. 40 41 .. group-tab:: Windows 42 43 Select *Start* > *Settings* > *Update & Security* > *Windows Update*. 44 Click *Check for updates* and install any that are available. 45 46.. _install-required-tools: 47 48Install dependencies 49******************** 50 51Next, you'll install some host dependencies using your package manager. 52 53The current minimum required version for the main dependencies are: 54 55.. list-table:: 56 :header-rows: 1 57 58 * - Tool 59 - Min. Version 60 61 * - `CMake <https://cmake.org/>`_ 62 - 3.20.5 63 64 * - `Python <https://www.python.org/>`_ 65 - 3.10 66 67 * - `Devicetree compiler <https://www.devicetree.org/>`_ 68 - 1.4.6 69 70.. tabs:: 71 72 .. group-tab:: Ubuntu 73 74 .. _install_dependencies_ubuntu: 75 76 #. If using an Ubuntu version older than 22.04, it is necessary to add extra 77 repositories to meet the minimum required versions for the main 78 dependencies listed above. In that case, download, inspect and execute 79 the Kitware archive script to add the Kitware APT repository to your 80 sources list. 81 A detailed explanation of ``kitware-archive.sh`` can be found here 82 `kitware third-party apt repository <https://apt.kitware.com/>`_: 83 84 .. code-block:: bash 85 86 wget https://apt.kitware.com/kitware-archive.sh 87 sudo bash kitware-archive.sh 88 89 #. Use ``apt`` to install the required dependencies: 90 91 .. code-block:: bash 92 93 sudo apt install --no-install-recommends git cmake ninja-build gperf \ 94 ccache dfu-util device-tree-compiler wget \ 95 python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ 96 make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 97 98 .. note:: 99 100 Due to the unavailability of ``gcc-multilib`` and ``g++-multilib`` on AArch64 101 (ARM64) systems, you may need to remove them from the list of packages to install. 102 103 #. Verify the versions of the main dependencies installed on your system by entering: 104 105 .. code-block:: bash 106 107 cmake --version 108 python3 --version 109 dtc --version 110 111 Check those against the versions in the table in the beginning of this section. 112 Refer to the :ref:`installation_linux` page for additional information on updating 113 the dependencies manually. 114 115 .. group-tab:: macOS 116 117 .. _install_dependencies_macos: 118 119 #. Install `Homebrew <https://brew.sh/>`_: 120 121 .. code-block:: bash 122 123 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 124 125 #. After the Homebrew installation script completes, follow the on-screen 126 instructions to add the Homebrew installation to the path. 127 128 * On macOS running on Apple Silicon, this is achieved with: 129 130 .. code-block:: bash 131 132 (echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile 133 source ~/.zprofile 134 135 * On macOS running on Intel, use the command for Apple Silicon, but replace ``/opt/homebrew/`` with ``/usr/local/``. 136 137 #. Use ``brew`` to install the required dependencies: 138 139 .. code-block:: bash 140 141 brew install cmake ninja gperf python3 python-tk ccache qemu dtc libmagic wget openocd 142 143 #. Add the Homebrew Python folder to the path, in order to be able to 144 execute ``python`` and ``pip`` as well ``python3`` and ``pip3``. 145 146 .. code-block:: bash 147 148 (echo; echo 'export PATH="'$(brew --prefix)'/opt/python/libexec/bin:$PATH"') >> ~/.zprofile 149 source ~/.zprofile 150 151 .. group-tab:: Windows 152 153 .. note:: 154 155 Due to issues finding executables, the Zephyr Project doesn't 156 currently support application flashing using the `Windows Subsystem 157 for Linux (WSL) 158 <https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`_ 159 (WSL). 160 161 Therefore, we don't recommend using WSL when getting started. 162 163 In modern version of Windows (10 and later) it is recommended to install the Windows Terminal 164 application from the Microsoft Store. Instructions are provided for a ``cmd.exe`` or 165 PowerShell command prompts. 166 167 These instructions rely on `Chocolatey`_. If Chocolatey isn't an option, 168 you can install dependencies from their respective websites and ensure 169 the command line tools are on your :envvar:`PATH` :ref:`environment 170 variable <env_vars>`. 171 172 |p| 173 174 .. _install_dependencies_windows: 175 176 #. `Install chocolatey`_. 177 178 #. Open a ``cmd.exe`` or PowerShell terminal window as **Administrator**. 179 To do so, press the Windows key, type ``cmd.exe`` or PowerShell, right-click the 180 :guilabel:`Command Prompt` or :guilabel:`PowerShell` search result, and choose 181 :guilabel:`Run as Administrator`. 182 183 #. Disable global confirmation to avoid having to confirm the 184 installation of individual programs: 185 186 .. code-block:: bat 187 188 choco feature enable -n allowGlobalConfirmation 189 190 #. Use ``choco`` to install the required dependencies: 191 192 .. code-block:: bat 193 194 choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' 195 choco install ninja gperf python311 git dtc-msys2 wget 7zip strawberryperl 196 197 .. warning:: 198 199 As of November 2024, Python 3.13 is not recommended for Zephyr development on Windows, 200 as some required Python dependencies may be difficult to install. 201 202 #. Close the terminal window. 203 204.. _Chocolatey: https://chocolatey.org/ 205.. _Install chocolatey: https://chocolatey.org/install 206 207.. _get_the_code: 208.. _clone-zephyr: 209.. _install_py_requirements: 210.. _gs_python_deps: 211 212Get Zephyr and install Python dependencies 213****************************************** 214 215Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west 216<west>` workspace. In the following instructions the name :file:`zephyrproject` 217is used for the workspace, however in practice its name and location can be freely 218chosen. You'll also install Zephyr's additional Python dependencies in a 219`Python virtual environment`_. 220 221.. _Python virtual environment: https://docs.python.org/3/library/venv.html 222 223.. tabs:: 224 225 .. group-tab:: Ubuntu 226 227 #. Use ``apt`` to install Python ``venv`` package: 228 229 .. code-block:: bash 230 231 sudo apt install python3-venv 232 233 #. Create a new virtual environment: 234 235 .. code-block:: bash 236 237 python3 -m venv ~/zephyrproject/.venv 238 239 #. Activate the virtual environment: 240 241 .. code-block:: bash 242 243 source ~/zephyrproject/.venv/bin/activate 244 245 Once activated your shell will be prefixed with ``(.venv)``. The 246 virtual environment can be deactivated at any time by running 247 ``deactivate``. 248 249 .. note:: 250 251 Remember to activate the virtual environment every time you 252 start working. 253 254 #. Install west: 255 256 .. code-block:: bash 257 258 pip install west 259 260 #. Get the Zephyr source code: 261 262 .. code-block:: bash 263 264 west init ~/zephyrproject 265 cd ~/zephyrproject 266 west update 267 268 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 269 automatically load boilerplate code required for building Zephyr 270 applications. 271 272 .. code-block:: bash 273 274 west zephyr-export 275 276 #. The Zephyr west extension command, ``west packages`` can be used to install Python 277 dependencies. 278 279 .. code-block:: bash 280 281 west packages pip --install 282 283 .. group-tab:: macOS 284 285 #. Create a new virtual environment: 286 287 .. code-block:: bash 288 289 python3 -m venv ~/zephyrproject/.venv 290 291 #. Activate the virtual environment: 292 293 .. code-block:: bash 294 295 source ~/zephyrproject/.venv/bin/activate 296 297 Once activated your shell will be prefixed with ``(.venv)``. The 298 virtual environment can be deactivated at any time by running 299 ``deactivate``. 300 301 .. note:: 302 303 Remember to activate the virtual environment every time you 304 start working. 305 306 #. Install west: 307 308 .. code-block:: bash 309 310 pip install west 311 312 #. Get the Zephyr source code: 313 314 .. code-block:: bash 315 316 west init ~/zephyrproject 317 cd ~/zephyrproject 318 west update 319 320 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 321 automatically load boilerplate code required for building Zephyr 322 applications. 323 324 .. code-block:: bash 325 326 west zephyr-export 327 328 #. The Zephyr west extension command, ``west packages`` can be used to install Python 329 dependencies. 330 331 .. code-block:: bash 332 333 west packages pip --install 334 335 .. group-tab:: Windows 336 337 #. Open a ``cmd.exe`` or PowerShell terminal window **as a regular user** 338 339 #. Create a new virtual environment: 340 341 .. tabs:: 342 343 .. code-tab:: bat 344 345 cd %HOMEPATH% 346 python -m venv zephyrproject\.venv 347 348 .. code-tab:: powershell 349 350 cd $Env:HOMEPATH 351 python -m venv zephyrproject\.venv 352 353 #. Activate the virtual environment: 354 355 .. tabs:: 356 357 .. code-tab:: bat 358 359 zephyrproject\.venv\Scripts\activate.bat 360 361 .. code-tab:: powershell 362 363 zephyrproject\.venv\Scripts\Activate.ps1 364 365 Once activated your shell will be prefixed with ``(.venv)``. The 366 virtual environment can be deactivated at any time by running 367 ``deactivate``. 368 369 .. note:: 370 371 Remember to activate the virtual environment every time you 372 start working. 373 374 #. Install west: 375 376 .. code-block:: bat 377 378 pip install west 379 380 #. Get the Zephyr source code: 381 382 .. code-block:: bat 383 384 west init zephyrproject 385 cd zephyrproject 386 west update 387 388 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 389 automatically load boilerplate code required for building Zephyr 390 applications. 391 392 .. code-block:: bat 393 394 west zephyr-export 395 396 #. The Zephyr west extension command, ``west packages`` can be used to install Python 397 dependencies. 398 399 .. code-block:: bat 400 401 west packages pip --install 402 403Install the Zephyr SDK 404********************** 405 406The :ref:`Zephyr Software Development Kit (SDK) <toolchain_zephyr_sdk>` 407contains toolchains for each of Zephyr's supported architectures, which 408include a compiler, assembler, linker and other programs required to build 409Zephyr applications. 410 411For Linux, it also contains additional host tools, such as custom QEMU and OpenOCD builds 412that are used to emulate, flash and debug Zephyr applications. 413 414 415.. tabs:: 416 417 .. group-tab:: Ubuntu 418 419 Install the Zephyr SDK using the ``west sdk install``. 420 421 .. code-block:: bash 422 423 cd ~/zephyrproject/zephyr 424 west sdk install 425 426 .. tip:: 427 428 Using the command options, you can specify the SDK installation destination 429 and which architecture of toolchains to install. 430 See ``west sdk install --help`` for details. 431 432 .. group-tab:: macOS 433 434 Install the Zephyr SDK using the ``west sdk install``. 435 436 .. code-block:: bash 437 438 cd ~/zephyrproject/zephyr 439 west sdk install 440 441 .. tip:: 442 443 Using the command options, you can specify the SDK installation destination 444 and which architecture of toolchains to install. 445 See ``west sdk install --help`` for details. 446 447 .. group-tab:: Windows 448 449 Install the Zephyr SDK using the ``west sdk install``. 450 451 .. tabs:: 452 453 .. code-tab:: bat 454 455 cd %HOMEPATH%\zephyrproject\zephyr 456 west sdk install 457 458 .. code-tab:: powershell 459 460 cd $Env:HOMEPATH\zephyrproject\zephyr 461 west sdk install 462 463 .. tip:: 464 465 Using the command options, you can specify the SDK installation destination 466 and which architecture of toolchains to install. 467 See ``west sdk install --help`` for details. 468 469.. note:: 470 471 If you want to install Zephyr SDK without using the ``west sdk`` command, 472 please see :ref:`toolchain_zephyr_sdk_install`. 473 474.. _getting_started_run_sample: 475 476Build the Blinky Sample 477*********************** 478 479.. note:: 480 481 :zephyr:code-sample:`blinky` is compatible with most, but not all, :ref:`boards`. If your board 482 does not meet Blinky's :ref:`blinky-sample-requirements`, then 483 :zephyr:code-sample:`hello_world` is a good alternative. 484 485 If you are unsure what name west uses for your board, ``west boards`` 486 can be used to obtain a list of all boards Zephyr supports. 487 488Build the :zephyr:code-sample:`blinky` with :ref:`west build <west-building>`, changing 489``<your-board-name>`` appropriately for your board: 490 491.. tabs:: 492 493 .. group-tab:: Ubuntu 494 495 .. code-block:: bash 496 497 cd ~/zephyrproject/zephyr 498 west build -p always -b <your-board-name> samples/basic/blinky 499 500 .. group-tab:: macOS 501 502 .. code-block:: bash 503 504 cd ~/zephyrproject/zephyr 505 west build -p always -b <your-board-name> samples/basic/blinky 506 507 .. group-tab:: Windows 508 509 .. tabs:: 510 511 .. code-tab:: bat 512 513 cd %HOMEPATH%\zephyrproject\zephyr 514 west build -p always -b <your-board-name> samples\basic\blinky 515 516 .. code-tab:: powershell 517 518 cd $Env:HOMEPATH\zephyrproject\zephyr 519 west build -p always -b <your-board-name> samples\basic\blinky 520 521The ``-p always`` option forces a pristine build, and is recommended for new 522users. Users may also use the ``-p auto`` option, which will use 523heuristics to determine if a pristine build is required, such as when building 524another sample. 525 526.. note:: 527 528 A board may contain one or multiple SoCs, Also, each SoC may contain one or 529 more CPU clusters. 530 When building for such boards it is necessary to specify the SoC or CPU 531 cluster for which the sample must be built. 532 For example to build :zephyr:code-sample:`blinky` for the ``cpuapp`` core on 533 the :ref:`nRF5340DK <nrf5340dk_nrf5340>` the board must be provided as: 534 ``nrf5340dk/nrf5340/cpuapp``. See also :ref:`board_terminology` for more 535 details. 536 537Flash the Sample 538**************** 539 540Connect your board, usually via USB, and turn it on if there's a power switch. 541If in doubt about what to do, check your board's page in :ref:`boards`. 542 543Then flash the sample using :ref:`west flash <west-flashing>`: 544 545.. code-block:: shell 546 547 west flash 548 549.. note:: 550 551 You may need to install additional :ref:`host tools <flash-debug-host-tools>` 552 required by your board. The ``west flash`` command will print an error if any 553 required dependencies are missing. 554 555.. note:: 556 557 When using Linux, you may need to configure udev rules the first time 558 of using a debug probe. 559 Please also see :ref:`setting-udev-rules`. 560 561If you're using blinky, the LED will start to blink as shown in this figure: 562 563.. figure:: img/ReelBoard-Blinky.png 564 :width: 400px 565 :name: reelboard-blinky 566 567 Phytec :ref:`reel_board <reel_board>` running blinky 568 569Next Steps 570********** 571 572Here are some next steps for exploring Zephyr: 573 574* Try other :zephyr:code-sample-category:`samples` 575* Learn about :ref:`application` and the :ref:`west <west>` tool 576* Find out about west's :ref:`flashing and debugging <west-build-flash-debug>` 577 features, or more about :ref:`flashing_and_debugging` in general 578* Check out :ref:`beyond-GSG` for additional setup alternatives and ideas 579* Discover :ref:`project-resources` for getting help from the Zephyr 580 community 581 582.. _troubleshooting_installation: 583 584Troubleshooting Installation 585**************************** 586 587Here are some tips for fixing some issues related to the installation process. 588 589.. _toolchain_zephyr_sdk_update: 590 591Double Check the Zephyr SDK Variables When Updating 592=================================================== 593 594When updating Zephyr SDK, check whether the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` 595or :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variables are already set. 596See :ref:`gs_toolchain_update` for more information. 597 598For more information about these environment variables in Zephyr, see :ref:`env_vars_important`. 599 600.. _help: 601 602Asking for Help 603*************** 604 605You can ask for help on a mailing list or on Discord. Please send bug reports and 606feature requests to GitHub. 607 608* **Mailing Lists**: users@lists.zephyrproject.org is usually the right list to 609 ask for help. `Search archives and sign up here`_. 610* **Discord**: You can join with this `Discord invite`_. 611* **GitHub**: Use `GitHub issues`_ for bugs and feature requests. 612 613How to Ask 614========== 615 616.. important:: 617 618 Please search this documentation and the mailing list archives first. Your 619 question may have an answer there. 620 621Don't just say "this isn't working" or ask "is this working?". Include as much 622detail as you can about: 623 624#. What you want to do 625#. What you tried (commands you typed, etc.) 626#. What happened (output of each command, etc.) 627 628Use Copy/Paste 629============== 630 631Please **copy/paste text** instead of taking a picture or a screenshot of it. 632Text includes source code, terminal commands, and their output. 633 634Doing this makes it easier for people to help you, and also helps other users 635search the archives. Unnecessary screenshots exclude vision impaired 636developers; some are major Zephyr contributors. `Accessibility`_ has been 637recognized as a basic human right by the United Nations. 638 639When copy/pasting more than 5 lines of computer text into Discord or Github, 640create a snippet using three backticks to delimit the snippet. 641 642.. _Search archives and sign up here: https://lists.zephyrproject.org/g/users 643.. _Discord invite: https://chat.zephyrproject.org 644.. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues 645.. _Accessibility: https://www.w3.org/standards/webdesign/accessibility 646
