Installing on macOS¶
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.
Install Homebrew and install the required tools using the
brew command line tool.
Installing the toolchain¶
To be able to cross-compile your applications for Arm targets, you must install version 8-2019-q3-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 a set of Git repositories.
Every nRF Connect SDK release consists of a combination of these repositories at different revisions. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, fw-nrfconnect-nrf.
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,
west.yml, that determines the revision of all other repositories.
This means that fw-nrfconnect-nrf acts as the manifest repository, while the other repositories are project repositories.
You can find additional information about the repository and development model in the development model section.
See the west documentation for detailed information about the tool itself.
Install the bootstrapper for west by entering the following command:
pip3 install 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 -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
More generally, to check out an arbitrary revision, enter the following command:
west init -m https://github.com/NordicPlayground/fw-nrfconnect-nrf --mr NCS_revision
NCS_revision can be a branch (eg.
master), a tag (for example,
v1.1.0), or even a SHA (for example,
224bee9055d986fe2677149b8cbda0ff10650a6e). When not specified, it defaults to
This will clone the manifest repository fw-nrfconnect-nrf into
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.
To make sure that you have the latest changes, run
git fetch origin to fetch the latest code from the fw-nrfconnect-nrf repository.
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 v1.1.0 of the nRF Connect SDK, enter the following commands in the
git fetch origin git checkout v1.1.0 west update
To update to a particular revision (SHA), make sure that you have that particular revision locally before you check it out (by running
git fetch origin):
git fetch origin git checkout 224bee9055d986fe2677149b8cbda0ff10650a6e west update
To switch to the latest state of development, enter the following commands:
git fetch origin git checkout origin/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 -r zephyr/scripts/requirements.txt pip3 install -r nrf/scripts/requirements.txt pip3 install -r mcuboot/scripts/requirements.txt
Installing SEGGER Embedded Studio¶
You must install a special version of SEGGER Embedded Studio (SES) to be able to open and compile projects in the nRF Connect SDK.
SEGGER Embedded Studio is free of charge for use with Nordic Semiconductor devices.
To install SEGGER Embedded Studio, complete the following steps:
Download the package for your operating system from the following links:
Extract the downloaded package in the directory of your choice.
Register and activate a free license. SEGGER Embedded Studio is free of charge for use with Nordic Semiconductor devices, but you still need to request and activate a license. Complete the following steps:
Run the file
bin/emStudio. SEGGER Embedded Studio will open the Dashboard window and inform you about the missing license.
Click Activate Your Free License. A request form appears.
Fill in your information and click Request License. The license is sent to you in an email.
After you receive your license key, click Enter Activation Key to activate the license.
Copy-paste the license key and click Install License. The license activation window will close and SES will open the Project Explorer window.
Setting up the build environment¶
Before you start building and programming a sample application, you must set up your build environment.
Setting up the SES environment¶
If you plan to build with SEGGER Embedded Studio, the first time you import an nRF Connect SDK project, SES will prompt you to set the paths to the Zephyr Base directory and the GNU ARM Embedded Toolchain. This must be done only once per project.
Complete the following steps to set up the SEGGER Embedded Studio environment:
Run the file
Select File -> Open nRF Connect SDK Project.
Set the Zephyr Base directory to the full path to
ncs/zephyr. The GNU ARM Embedded Toolchain directory is the directory where you installed the toolchain (for example,
Setting up executables on macOS¶
If you start SES on macOS by running the file
bin/emStudio, make sure to complete the following steps:
Specify the path to all executables under Tools -> Options (in the nRF Connect tab).
Use this section to change the SES environment settings later as well.
Specify the path to the west tool as additional CMake option, replacing path_to_west with the path to the west executable (for example,
If you start SES from the command line, it uses the global PATH variable to find the executables. You do not need to explicitly configure the executables in SES.
Regardless of how you start SES, if you get an error that a tool or command cannot be found, first make sure that the tool is installed. If it is installed, verify that its path is configured correctly in the SES settings or in the PATH variable.
Setting up the command line build environment¶
If you want to build and program your application 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.
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.