| .. _getting_started: |
| |
| Getting Started Guide |
| ##################### |
| |
| Follow this guide to get a quick start with Zephyr development where |
| you'll: |
| |
| - **Set up a command-line development environment** for Linux* (Ubuntu), |
| macOS, or Windows, with required package manager, compiler, and |
| build-system tools, |
| - **Get the sources**, |
| - **Build, flash, and run** a sample application on your target board. |
| |
| \*Instructions for other Linux distributions are discussed in the |
| :ref:`advanced Linux setup document <installation_linux>`. |
| |
| .. _host_setup: |
| |
| .. rst-class:: numbered-step |
| |
| Select and Update OS |
| ******************** |
| |
| Zephyr development depends on an up-to-date host system and common build system |
| tools. First, make sure your development system OS is updated: |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| Use these commands to bring your Linux (Ubuntu) system up to date. |
| If you're using a different Linux distribution, use the appropriate |
| package manager for your OS. (See :ref:`installation_linux` for |
| more information about other Linux distributions.) |
| |
| .. code-block:: bash |
| |
| sudo apt update |
| sudo apt upgrade |
| |
| .. group-tab:: macOS |
| |
| On macOS Mojave, you can manually check for updates by choosing |
| System Preferences from the Apple menu, then clicking Software Update (and |
| click Update Now if there are). For other macOS versions, see the |
| `Update macOS topic in Apple support |
| <https://support.apple.com/en-us/HT201541>`_. |
| |
| .. group-tab:: Windows |
| |
| On Windows, you can manually check for updates by selecting Start > Settings > |
| Update & Security > Windows Update, and then select Check for updates. |
| If updates are available, install them. |
| |
| .. _install-required-tools: |
| |
| .. rst-class:: numbered-step |
| |
| Install dependencies |
| ******************** |
| |
| Next, use a package manager to install required support tools. Python 3 |
| and its package manager, pip, are used extensively by Zephyr for |
| installing and running scripts used to compile, build, and run Zephyr |
| applications. |
| |
| We'll also install Zephyr's multi-purpose west tool. |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| #. Use the ``apt`` package manager to install these tools: |
| |
| .. code-block:: bash |
| |
| sudo apt install --no-install-recommends git cmake ninja-build gperf \ |
| ccache dfu-util device-tree-compiler wget \ |
| python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ |
| make gcc gcc-multilib |
| |
| #. Verify the version of cmake installed on your system using:: |
| |
| cmake --version |
| |
| If it's not version 3.13.1 or higher, follow these steps to |
| add the `kitware third-party apt repository <https://apt.kitware.com/>`__ |
| to get an updated version of cmake. |
| |
| a) Add the kitware signing key to apt: |
| |
| .. code-block:: bash |
| |
| wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add - |
| |
| b) Add the kitware repo corresponding to your Ubuntu LTS release (use |
| ``cat /etc/os-release`` to check): |
| |
| For Ubuntu Bionic Beaver (18.04) use:: |
| |
| sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main' |
| |
| For Ubuntu Xenial Xerus (16.04) use:: |
| |
| sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ xenial main' |
| |
| c) Then install the updated cmake using the usual apt commands: |
| |
| .. code-block:: bash |
| |
| sudo apt update |
| sudo apt install cmake |
| |
| #. Install west: |
| |
| .. code-block:: bash |
| |
| pip3 install --user -U west |
| echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc |
| source ~/.bashrc |
| |
| The pip3 ``--user`` option puts installed Python packages into your |
| ``~/.local/bin folder`` so we'll need to add this to the PATH |
| so these packages will be found. Adding the PATH specification to your |
| ``.bashrc`` file ensures this setting is permanent. |
| |
| .. group-tab:: macOS |
| |
| #. On macOS, install :program:`Homebrew` by following instructions on the `Homebrew |
| site`_, and as shown here. Homebrew is a free and open-source package management system that |
| simplifies installing software on macOS. While installing Homebrew, |
| you may be prompted to install additional missing dependencies; please follow |
| any such instructions as well. |
| |
| .. code-block:: bash |
| |
| /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| |
| #. Then, install these host dependencies with the ``brew`` command: |
| |
| .. code-block:: bash |
| |
| brew install cmake ninja gperf ccache dfu-util qemu dtc python3 |
| |
| #. Install west: |
| |
| .. code-block:: bash |
| |
| pip3 install west |
| |
| .. _Homebrew site: https://brew.sh/ |
| |
| .. group-tab:: Windows |
| |
| .. note:: Currently, the built-in `Windows Subsystem for Linux (WSL) |
| <https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`__ |
| doesn't support flashing your application to the board. As such, |
| we don't recommend using WSL yet. |
| |
| These instructions assume you are using the Windows ``cmd.exe`` |
| command prompt. Some of the details, such as setting environment |
| variables, may differ if you are using PowerShell. |
| |
| An easy way to install native Windows dependencies is to first install |
| `Chocolatey`_, a package manager for Windows. If you prefer to install |
| dependencies manually, you can also download the required programs from their |
| respective websites and verify they can be found on your PATH. |
| |
| |p| |
| |
| #. Install :program:`Chocolatey` by following the instructions on the |
| `Chocolatey install`_ page. |
| |
| #. Open a command prompt (``cmd.exe``) as an **Administrator** (press the |
| Windows key, type "cmd.exe" in the prompt, then right-click the result and |
| choose "Run as Administrator"). |
| |
| #. Disable global confirmation to avoid having to confirm |
| installation of individual programs: |
| |
| .. code-block:: console |
| |
| choco feature enable -n allowGlobalConfirmation |
| |
| #. Install CMake: |
| |
| .. code-block:: console |
| |
| choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' |
| |
| #. Install the rest of the tools: |
| |
| .. code-block:: console |
| |
| choco install git python ninja dtc-msys2 gperf |
| |
| #. Close the Administrator command prompt window and open a |
| regular command prompt window to continue.. |
| |
| #. Install west: |
| |
| .. code-block:: bash |
| |
| pip3 install west |
| |
| |
| .. _Chocolatey: https://chocolatey.org/ |
| .. _Chocolatey install: https://chocolatey.org/install |
| |
| .. _get_the_code: |
| .. _clone-zephyr: |
| |
| .. rst-class:: numbered-step |
| |
| Get the source code |
| ******************* |
| |
| Zephyr's multi-purpose west tool simplifies getting the Zephyr |
| project git repositories and external modules used by Zephyr. |
| Clone all of Zephyr's git repositories in a new :file:`zephyrproject` |
| directory using west: |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| .. code-block:: bash |
| |
| cd ~ |
| west init zephyrproject |
| cd zephyrproject |
| west update |
| |
| .. group-tab:: macOS |
| |
| .. code-block:: bash |
| |
| cd ~ |
| west init zephyrproject |
| cd zephyrproject |
| west update |
| |
| .. group-tab:: Windows |
| |
| .. code-block:: bat |
| |
| cd %HOMEPATH% |
| west init zephyrproject |
| cd zephyrproject |
| west update |
| |
| .. rst-class:: numbered-step |
| |
| Install needed Python packages |
| ****************************** |
| |
| The Zephyr source folders we downloaded contain a ``requirements.txt`` file |
| that we'll use to install additional Python tools used by the Zephyr |
| project: |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| .. code-block:: bash |
| |
| pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt |
| |
| .. group-tab:: macOS |
| |
| .. code-block:: bash |
| |
| pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt |
| |
| .. group-tab:: Windows |
| |
| .. code-block:: bat |
| |
| pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt |
| |
| .. _gs_python_deps: |
| |
| .. rst-class:: numbered-step |
| |
| Install Software Development Toolchain |
| ************************************** |
| |
| A toolchain includes necessary tools used to build Zephyr applications |
| including: compiler, assembler, linker, and their dependencies. |
| |
| |
| .. _Zephyr Downloads: https://www.zephyrproject.org/developers/#downloads |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| Zephyr's Software Development Kit (SDK) contains necessary Linux |
| development tools to build Zephyr on all supported architectures. |
| Additionally, it includes host tools such as custom QEMU binaries and a |
| host compiler. |
| |
| |p| |
| |
| #. Download the latest SDK as a self-extracting installation binary: |
| |
| .. code-block:: bash |
| |
| cd ~ |
| wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.10.3/zephyr-sdk-0.10.3-setup.run |
| |
| #. Run the installation binary, installing the SDK in your home |
| folder :file:`~/zephyr-sdk-0.10.3`: |
| |
| .. code-block:: bash |
| |
| chmod +x zephyr-sdk-0.10.3-setup.run |
| ./zephyr-sdk-0.10.3-setup.run -- -d ~/zephyr-sdk-0.10.3 |
| |
| #. Set environment variables to let the build system know where to |
| find the toolchain programs: |
| |
| .. code-block:: bash |
| |
| export ZEPHYR_TOOLCHAIN_VARIANT=zephyr |
| export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.10.3 |
| |
| The SDK contains a udev rules file that provides information |
| needed to identify boards and grant hardware access permission to flash |
| tools. Install these udev rules with these commands: |
| |
| .. code-block:: bash |
| |
| sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d |
| sudo udevadm control --reload |
| |
| .. group-tab:: macOS |
| |
| #. The Zephyr SDK is not supported on macOS. See instructions for |
| :ref:`installing 3rd-party toolchains<gs_toolchain>`. |
| |
| #. Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones) |
| to let the build system know where to find the toolchain programs. |
| |
| .. group-tab:: Windows |
| |
| #. The Zephyr SDK is not supported on Windows. See instructions for |
| :ref:`installing 3rd-party toolchains<gs_toolchain>`. |
| |
| #. Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones) |
| to let the build system know where to find the toolchain programs. |
| |
| |
| .. _getting_started_run_sample: |
| |
| .. rst-class:: numbered-step |
| |
| Build the Blinky Application |
| **************************** |
| |
| The sample :ref:`blinky-sample` blinks an LED on the target board. By |
| building and running it, we can verify that the environment and tools |
| are properly set up for Zephyr development. |
| |
| #. Set build environment variables: |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| .. code-block:: bash |
| |
| cd ~/zephyrproject/zephyr |
| source zephyr-env.sh |
| |
| .. group-tab:: macOS |
| |
| .. code-block:: bash |
| |
| cd ~/zephyrproject/zephyr |
| source zephyr-env.sh |
| |
| .. group-tab:: Windows |
| |
| .. code-block:: bat |
| |
| cd %HOMEPATH%/zephyrproject/zephyr |
| zephyr-env.cmd |
| |
| #. Build the blinky sample. Specify **your board name** |
| (see :ref:`boards`) in the command below: |
| |
| .. code-block:: bash |
| |
| west build -p auto -b <your-board-name> samples/basic/blinky |
| |
| This west command uses the ``-p auto`` parameter to automatically |
| clean out any byproducts from a previous build if needed, useful if |
| you try building another sample. |
| |
| .. rst-class:: numbered-step |
| |
| Flash and Run the Application |
| ***************************** |
| |
| #. Connect a USB cable between the board and your development computer. |
| (Refer to the specific :ref:`boards` documentation if you're not sure |
| which connector to use on the board.) |
| #. If there's a switch, turn the board on. |
| #. Flash the blinky application you just built using the command: |
| |
| .. tabs:: |
| |
| .. group-tab:: Ubuntu |
| |
| .. code-block:: bash |
| |
| west flash |
| |
| If the flash command fails, and you've checked your |
| board is powered on and connected to the right on-board USB connector, |
| verify you've granted needed access permission by |
| :ref:`setting-udev-rules`. |
| |
| .. group-tab:: macOS |
| |
| .. code-block:: bash |
| |
| west flash |
| |
| .. group-tab:: Windows |
| |
| .. code-block:: bat |
| |
| west flash |
| |
| |
| The application will start running and you'll see blinky in action. The |
| actual blinking LED location is board specific. |
| |
| .. figure:: img/ReelBoard-Blinky.gif |
| :width: 400px |
| :name: reelboard-blinky |
| |
| Phytec reel_board running blinky |
| |
| |
| Next Steps |
| ********** |
| |
| Now that you've got the blinky sample running, here are some next steps |
| for exploring Zephyr: |
| |
| * Try some other :ref:`samples-and-demos` that demonstrate Zephyr |
| capabilities. |
| * Learn about :ref:`application` and more details about :ref:`west`. |
| * Check out :ref:`beyond-GSG` for information about advanced setup |
| alternatives and issues. |
| * Discover :ref:`project-resources` for getting help from the Zephyr |
| community. |