Installing on Linux

To manually install the nRF Connect SDK, you must ensure that all required tools are installed and clone the nRF Connect SDK repositories. See the following sections for detailed instructions.

The first two steps, Installing the required tools and Installing the toolchain, are identical to the installation in Zephyr. If you already have your system set up to work with the Zephyr OS, you can skip these steps.

Installing the required tools

To install the required tools, follow the Install Requirements and Dependencies section of Zephyr’s Getting Started Guide.

In addition, make sure that you have dtc v1.4.6 or later installed. Depending on the Linux distribution that you use, you might need to install it manually because the current official package version might be older than v1.4.6. If you use Ubuntu, install v1.4.7 from Cosmic by entering the following commands:

wget http://mirrors.kernel.org/ubuntu/pool/main/d/device-tree-compiler/device-tree-compiler_1.4.7-1_amd64.deb
sudo dpkg -i device-tree-compiler_1.4.7-1_amd64.deb

Note

You do not need to install the Zephyr SDK. We recommend to install the compiler toolchain separately, as detailed in Installing the toolchain.

Installing the toolchain

To be able to cross-compile your applications for Arm targets, you must install version 7-2018-q2-update of the GNU Arm Embedded Toolchain.

Important

Make sure to install the version that is mentioned above. Other versions might not work with the nRF Connect SDK.

To set up the toolchain, complete the following steps:

  1. Download the GNU Arm Embedded Toolchain for your operating system.

  2. Extract the toolchain into a folder of your choice. Make sure that the folder name does not contain any spaces or special characters. We recommend to use the folder ~/gnuarmemb.

  3. If you want to build and program applications from the command line, define the environment variables for the GNU Arm Embedded toolchain. To do so, open a terminal window and enter the following commands (assuming that you have installed the toolchain to ~/gnuarmemb; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):

     export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
     export GNUARMEMB_TOOLCHAIN_PATH="~/gnuarmemb"
    
  4. Instead of setting the environment variables every time you open a terminal window, define them in the ~/.zephyrrc file as described in Setting up the build environment.

Getting the nRF Connect SDK code

The nRF Connect SDK consists of the following repositories:

Every nRF Connect SDK release consists of a combination of these repositories at different revisions.

Note

The latest state of development is on the master branch of the fw-nrfconnect-nrf repository. To ensure a usable state, the fw-nrfconnect-nrf repository defines the compatible states of the other repositories. However, this state is not necessarily tested. For a higher degree of quality assurance, check out a tagged release.

Therefore, unless you are familiar with the development process, you should always work with a specific release of the nRF Connect SDK.

To manage the combination of repositories and versions, the nRF Connect SDK uses West (Zephyr’s meta-tool). The main repository, fw-nrfconnect-nrf, contains a west manifest file that defines the versions of all other repositories. This means that fw-nrfconnect-nrf acts as the manifest repository (see Repository structure), while the other repositories are project repositories. The revision (in Git terms) of the fw-nrfconnect-nrf repository determines the contents of the manifest file. This file in turn defines what versions of the project repositories are checked out. This means that the full revision set of all repositories can be uniquely identified by a particular Git revision of the fw-nrfconnect-nrf repository.

In this way, you can decide to work with a specific nRF Connect SDK release either by initializing a new west installation at a particular tag or by checking out the corresponding tag for a release in an existing installation and then updating your project repositories to the corresponding state with west. Alternatively, you can work with the latest state of development by using the master branch of the fw-nrfconnect-nrf repository, updating it with Git regularly and then using west to update the project repositories after that.

See the west documentation for detailed information about the tool.

Installing west

Install the bootstrapper for west by entering the following command:

pip3 install --user west

You only need to do this once. Like any other Python package, the west bootstrapper is updated regularly. Therefore, remember to regularly check for updates:

pip3 install --user -U west

Cloning the repositories

Tip

If you already cloned the nRF Connect SDK repositories in Git and want to continue using these clones instead of creating new ones, see Updating your existing clones to use west.

To clone the repositories, complete the following steps:

  1. Create a folder named ncs. This folder will hold all nRF Connect SDK repositories.

  2. Open a terminal window in the ncs folder.

  3. Initialize west with the revision of the nRF Connect SDK that you want to check out:

    • To check out a specific release, go to the nRF Connect SDK Release Notes of that release and find the corresponding tag. Then enter the following command, replacing NCS_version with the tag:

      west init -m https://github.com/NordicPlayground/fw-nrfconnect-nrf --mr NCS_version
      

      Note

      • West was introduced after nRF Connect SDK v0.3.0. Therefore, you cannot use it to check out v0.1.0 or v0.3.0.
      • Initializing west with a specific revision of the manifest file does not lock your repositories to this version. Checking out a different branch or tag in the repositories changes the version of the nRF Connect SDK that you work with.
    • To check out the latest state of development, enter the following command:

      west init -m https://github.com/NordicPlayground/fw-nrfconnect-nrf
      

    This will clone the manifest repository (nrf).

  4. Enter the following command to clone the project repositories:

    west update
    

Your directory structure now looks like this:

ncs
 |___ .west
 |___ mcuboot
 |___ nrf
 |___ nrfxlib
 |___ zephyr

Updating the repositories

If you work with a specific release of the nRF Connect SDK, you do not need to update your repositories, because the release will not change. However, you might want to switch to a newer release or check out the latest state of development.

To manage the nrf repository (the manifest repository), use Git. Checking out a branch or tag in the nrf repository gives you a different version of the manifest file. Running west update will then update the project repositories to the state specified in this manifest file.

For example, to switch to release v0.4.0 of the nRF Connect SDK, enter the following commands in the ncs/nrf directory:

git checkout v0.4.0
west update

To switch to the latest state of development, enter the following commands:

git checkout master
west update

Note

Run west update every time you change or modify the current working branch (for example, when you pull, rebase, or check out a different branch). This will bring the project repositories to the matching revision defined by the manifest file.

Updating your existing clones to use west

If you already cloned the nRF Connect SDK repositories in Git and want to continue using these clones instead of creating new ones, you can initialize west to use your clones. All branches, remotes, and other configuration in your repositories will be maintained.

To update your repositories to be managed by west, make sure that they are structured and named in the following way:

ncs
 |___ mcuboot
 |___ nrf
 |___ nrfxlib
 |___ zephyr

Then complete the following steps:

  1. Open a terminal window in the ncs\nrf folder.

  2. Do a git pull or rebase your branch so that you are on the latest fw-nrfconnect-nrf master.

  3. Navigate one folder level up to the ncs folder:

    cd ..
    
  4. Initialize west with the manifest folder from the current branch of your nrf repository:

    west init -l nrf
    

    This will create the required .west folder that is linked to the manifest repository (nrf).

  5. Enter the following command to clone or update the project repositories:

    west update
    

Installing additional Python dependencies

Both Zephyr and the nRF Connect SDK require additional Python packages to be installed.

To install those, open a terminal window in the ncs folder and enter the following commands:

pip3 install --user -r zephyr/scripts/requirements.txt
pip3 install --user -r nrf/scripts/requirements.txt
pip3 install --user -r mcuboot/scripts/requirements.txt

Setting up the build environment

If you want to build and program your applications from the command line, you must set up your build environment by defining the required environment variables every time you open a new terminal window. If you plan to build with SEGGER Embedded Studio, you can skip this step.

To define the environment variables, navigate to the ncs folder and enter the following command: source zephyr/zephyr-env.sh

If you need to define additional environment variables, create the file ~/.zephyrrc and add the variables there. This file is loaded automatically when you run the above command.