doc/getting_started/index.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _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

       This guide covers Ubuntu version 18.04 LTS and later. See
       :ref:`installation_linux` for information about other Linux
       distributions and older versions of Ubuntu.

       Use these commands to bring your Ubuntu system up to date:

       .. 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 g++-multilib libsdl2-dev

       #. 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 the Ubuntu 18.04 LTS release:

             .. code-block:: bash

                sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic 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 SDK Downloads: https://github.com/zephyrproject-rtos/sdk-ng/releases

 .. 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.11.1/zephyr-sdk-0.11.1-setup.run

       #. Run the installation binary, installing the SDK in your home
          folder :file:`~/zephyr-sdk-0.11.1`:

          .. code-block:: bash

             chmod +x zephyr-sdk-0.11.1-setup.run
             ./zephyr-sdk-0.11.1-setup.run -- -d ~/zephyr-sdk-0.11.1

       #. 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.11.1

       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.
	.. _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

	This guide covers Ubuntu version 18.04 LTS and later. See
	:ref:`installation_linux` for information about other Linux
	distributions and older versions of Ubuntu.

	Use these commands to bring your Ubuntu system up to date:

	.. 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 g++-multilib libsdl2-dev

	#. 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 the Ubuntu 18.04 LTS release:

	.. code-block:: bash

	sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic 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 SDK Downloads: https://github.com/zephyrproject-rtos/sdk-ng/releases

	.. 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.11.1/zephyr-sdk-0.11.1-setup.run

	#. Run the installation binary, installing the SDK in your home
	folder :file:`~/zephyr-sdk-0.11.1`:

	.. code-block:: bash

	chmod +x zephyr-sdk-0.11.1-setup.run
	./zephyr-sdk-0.11.1-setup.run -- -d ~/zephyr-sdk-0.11.1

	#. 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.11.1

	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.