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
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.
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:
Download the GNU Arm Embedded Toolchain for your operating system.
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
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"
Instead of setting the environment variables every time you open a terminal window, define them in the
~/.zephyrrcfile 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.
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.
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¶
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:
Create a folder named
ncs. This folder will hold all nRF Connect SDK repositories.
Open a terminal window in the
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
- 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 (
Enter the following command to clone the project repositories:
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.
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
git checkout v0.4.0 west update
To switch to the latest state of development, enter the following commands:
git checkout master west update
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:
Open a terminal window in the
git pullor rebase your branch so that you are on the latest fw-nrfconnect-nrf master.
Navigate one folder level up to the
Initialize west with the manifest folder from the current branch of your
west init -l nrf
This will create the required
.westfolder that is linked to the manifest repository (
Enter the following command to clone or update the project repositories:
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:
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.