zara
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
50526 Commits
82 Branches
204 Tags
1.7 GiB
 
 
 
 
 
 
Tree: 52b03a2350
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '52b03a2350'
${ noResults }
zephyr/doc/getting_started/index.rst

424 lines
12 KiB
Raw Blame History

.. _getting_started:
Getting Started Guide
#####################
Follow this guide to:
- Set up a command-line Zephyr development environment on Ubuntu, macOS, or
Windows (instructions for other Linux distributions are discussed in
:ref:`installation_linux`)
- Get the source code
- Build, flash, and run a sample application
.. _host_setup:
.. rst-class:: numbered-step
Select and Update OS
********************
Click the operating system you are using.
.. tabs::
.. group-tab:: Ubuntu
This guide covers Ubuntu version 18.04 LTS and later.
.. code-block:: bash
sudo apt update
sudo apt upgrade
.. group-tab:: macOS
On macOS Mojave or later, select *System Preferences* >
*Software Update*. Click *Update Now* if necessary.
On other versions, see `this Apple support topic
<https://support.apple.com/en-us/HT201541>`_.
.. group-tab:: Windows
Select *Start* > *Settings* > *Update & Security* > *Windows Update*.
Click *Check for updates* and install any that are available.
.. _install-required-tools:
.. rst-class:: numbered-step
Install dependencies
********************
Next, you'll install some host dependencies using your package manager.
.. tabs::
.. group-tab:: Ubuntu
#. Use ``apt`` to install dependencies:
.. code-block:: bash
sudo apt install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-dev 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:
.. 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 apt repository for your OS release. For Ubuntu
18.04 LTS:
.. code-block:: bash
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
c) Then install the updated cmake with ``apt``:
.. code-block:: bash
sudo apt update
sudo apt install cmake
.. group-tab:: macOS
#. Install `Homebrew <https://brew.sh/>`_:
.. code-block:: bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
#. Use ``brew`` to install dependencies:
.. code-block:: bash
brew install cmake ninja gperf python3 ccache qemu dtc
.. group-tab:: Windows
.. note::
Due to issues finding executables, the Zephyr Project doesn't
currently support application flashing using the `Windows Subsystem
for Linux (WSL)
<https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`_
(WSL).
Therefore, we don't recommend using WSL when getting started.
These instructions must be run in a ``cmd.exe`` command prompt. The
required commands differ on PowerShell.
These instructions rely on `Chocolatey`_. If Chocolatey isn't an option,
you can install dependencies from their respective websites and ensure
the command line tools are on your :envvar:`PATH` :ref:`environment
variable <env_vars>`.
|p|
#. `Install chocolatey`_
#. Open an **Administrator** ``cmd.exe`` window: press the Windows key,
type "cmd.exe", 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
#. Use ``choco`` to install dependencies:
.. code-block:: console
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git
#. Open a new ``cmd.exe`` window **as a regular user** to continue.
.. _Chocolatey: https://chocolatey.org/
.. _Install chocolatey: https://chocolatey.org/install
.. _get_the_code:
.. _clone-zephyr:
.. _install_py_requirements:
.. _gs_python_deps:
.. rst-class:: numbered-step
Get Zephyr and install Python dependencies
******************************************
Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west
<west>` workspace named :file:`zephyrproject`. You'll also install Zephyr's
additional Python dependencies.
.. tabs::
.. group-tab:: Ubuntu
#. Install west, and make sure :file:`~/.local/bin` is on your
:envvar:`PATH` :ref:`environment variable <env_vars>`:
.. code-block:: bash
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
#. Get the Zephyr source code:
.. code-block:: bash
west init ~/zephyrproject
cd ~/zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: console
west zephyr-export
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.
.. code-block:: bash
pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: macOS
#. Install west:
.. code-block:: bash
pip3 install west
#. Get the Zephyr source code:
.. code-block:: bash
west init ~/zephyrproject
cd ~/zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: console
west zephyr-export
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.
.. code-block:: bash
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: Windows
#. Install west:
.. code-block:: bash
pip3 install west
#. Get the Zephyr source code:
.. code-block:: bat
cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: console
west zephyr-export
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.
.. code-block:: bat
pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
.. rst-class:: numbered-step
Install a Toolchain
*******************
A toolchain provides a compiler, assembler, linker, and other programs required
to build Zephyr applications.
.. tabs::
.. group-tab:: Ubuntu
The Zephyr Software Development Kit (SDK) contains toolchains for each of
Zephyr's supported architectures. It also includes additional host tools,
such as custom QEMU binaries and a host compiler.
|p|
#. Download the `latest SDK installer
<https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
.. code-block:: bash
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.12.4/zephyr-sdk-0.12.4-x86_64-linux-setup.run
#. Run the installer, installing the SDK in :file:`~/zephyr-sdk-0.12.4`:
.. code-block:: bash
chmod +x zephyr-sdk-0.12.4-x86_64-linux-setup.run
./zephyr-sdk-0.12.4-x86_64-linux-setup.run -- -d ~/zephyr-sdk-0.12.4
.. note::
It is recommended to install the Zephyr SDK at one of the following locations:
* ``$HOME/zephyr-sdk[-x.y.z]``
* ``$HOME/.local/zephyr-sdk[-x.y.z]``
* ``$HOME/.local/opt/zephyr-sdk[-x.y.z]``
* ``$HOME/bin/zephyr-sdk[-x.y.z]``
* ``/opt/zephyr-sdk[-x.y.z]``
* ``/usr/zephyr-sdk[-x.y.z]``
* ``/usr/local/zephyr-sdk[-x.y.z]``
where ``[-x.y.z]`` is optional text, and can be any text, for example ``-0.12.4``.
If installing the Zephyr SDK outside any of those locations, please read: :ref:`zephyr_sdk`
You cannot move the SDK directory after you have installed it.
#. Install `udev <https://en.wikipedia.org/wiki/Udev>`_ rules, which
allow you to flash most Zephyr boards as a regular user:
.. code-block:: bash
sudo cp ~/zephyr-sdk-0.12.4/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload
.. group-tab:: macOS
Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
is not available on macOS.
Do not forget to set the required :ref:`environment variables <env_vars>`
(:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
.. group-tab:: Windows
Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
is not available on Windows.
Do not forget to set the required :ref:`environment variables <env_vars>`
(:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
.. _getting_started_run_sample:
.. rst-class:: numbered-step
Build the Blinky Sample
***********************
.. note::
Blinky is compatible with most, but not all, :ref:`boards`. If your board
does not meet Blinky's :ref:`blinky-sample-requirements`, then
:ref:`hello_world` is a good alternative.
Build the :ref:`blinky-sample` with :ref:`west build <west-building>`, changing
``<your-board-name>`` appropriately for your board:
.. tabs::
.. group-tab:: Ubuntu
.. code-block:: bash
cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
.. group-tab:: macOS
.. code-block:: bash
cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
.. group-tab:: Windows
.. code-block:: bat
cd %HOMEPATH%\zephyrproject\zephyr
west build -p auto -b <your-board-name> samples\basic\blinky
The ``-p auto`` option automatically cleans byproducts from a previous build
if necessary, which is useful if you try building another sample.
.. rst-class:: numbered-step
Flash the Sample
****************
Connect your board, usually via USB, and turn it on if there's a power switch.
If in doubt about what to do, check your board's page in :ref:`boards`.
Then flash the sample using :ref:`west flash <west-flashing>`:
.. code-block:: console
west flash
You may need to install additional :ref:`host tools <flash-debug-host-tools>`
required by your board. The ``west flash`` command will print an error if any
required dependencies are missing.
If you're using blinky, the LED will start to blink as shown in this figure:
.. figure:: img/ReelBoard-Blinky.gif
:width: 400px
:name: reelboard-blinky
Phytec :ref:`reel_board <reel_board>` running blinky
Next Steps
**********
Here are some next steps for exploring Zephyr:
* Try other :ref:`samples-and-demos`
* Learn about :ref:`application` and the :ref:`west <west>` tool
* Find out about west's :ref:`flashing and debugging <west-build-flash-debug>`
features, or more about :ref:`flashing_and_debugging` in general
* Check out :ref:`beyond-GSG` for additional setup alternatives and ideas
* Discover :ref:`project-resources` for getting help from the Zephyr
community