Installing the nRF Connect SDK manually

The recommended way to get started with the nRF Connect SDK is to use nRF Connect for Desktop. See the Installing the nRF Connect SDK through nRF Connect for Desktop section for information about how to install the nRF Connect SDK through nRF Connect for Desktop.

Note

If you use nRF Connect for Desktop to install the nRF Connect SDK, you can skip this section of the documentation. If you prefer to install the toolchain manually, or if you run into problems during the installation process, see the following documentation for instructions.

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

The steps Install the required tools and Install the toolchain are similar to the installation steps in Zephyr’s Getting Started Guide. If you already have your system set up to work with the Zephyr OS, you can skip these steps.

See Supported operating systems for information on the supported operating systems and Zephyr features.

Install the required tools

The installation process is different depending on your operating system.

The recommended way for installing the required tools on Windows is to use Chocolatey, a package manager for Windows. Chocolatey installs the tools so that you can use them from a Windows command prompt.

To install the required tools, complete the following steps:

  1. Install chocolatey.

  2. Open a cmd.exe window as Administrator. To do so, press the Windows key, type “cmd.exe”, right-click the result, and choose Run as Administrator.

  3. Disable global confirmation to avoid having to confirm the installation of individual programs:

    choco feature enable -n allowGlobalConfirmation
    
  4. Use choco to install the required dependencies:

    choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
    choco install ninja gperf python git
    
  5. Close the window and open a new cmd.exe window as a regular user to continue.

In addition to these required tools, install the GN meta-build system if you are interested in building Matter (formerly Project Connected Home over IP, Project CHIP) applications. This system generates the Ninja files that the nRF Connect SDK uses.

To install the GN tool, complete the following steps:

  1. Download the latest version of the GN binary archive for Windows from the GN website.

  2. Extract the zip archive.

  3. Ensure that the GN tool is added to your PATH environment variable. See Setting Variables for instructions if needed.

Install west

To manage the combination of repositories and versions, the nRF Connect SDK uses Zephyr’s west.

To install west, enter the following command:

pip3 install west

You only need to do this once.

Get 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, sdk-nrf.

Note

The latest state of development is on the master branch of the sdk-nrf repository. To ensure a usable state, the sdk-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.

The main repository, sdk-nrf, contains a west manifest file, west.yml, that determines the revision of all other repositories. This means that sdk-nrf acts as the manifest repository, while the other repositories are project repositories.

For more information about the repository and development model, see the development model section.

Tip

If you cloned the nRF Connect SDK repositories before they were moved to the nrfconnect GitHub organization and want to update them, follow the instructions in Pointing the repositories to the right remotes after they were moved.

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 command window in the ncs folder.

  3. Determine what revision of the nRF Connect SDK you want to work with. The recommended way is to work with a specific release.

    • To work with a specific release, the revision is the corresponding tag (for example, v1.6.1). You can find the tag in the Release notes of the release.

    • To work with a development tag, the revision is the corresponding tag (for example, v1.2.99-dev1)

    • To work with a branch, the revision is the branch name (for example, master to work with the latest state of development).

    • To work with a specific state, the revision is the SHA (for example, 224bee9055d986fe2677149b8cbda0ff10650a6e).

  4. Initialize west with the revision of the nRF Connect SDK that you want to check out, replacing NCS_revision with the revision:

    west init -m https://github.com/nrfconnect/sdk-nrf --mr NCS_revision

    For example, to check out the v1.6.1 release, enter the following command:

    west init -m https://github.com/nrfconnect/sdk-nrf --mr v1.6.1

    To check out the latest state of development, enter the following command:

    west init -m https://github.com/nrfconnect/sdk-nrf --mr master
    

    Note

    If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need more information.

    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 sdk-nrf repository and running west update changes the version of the nRF Connect SDK that you work with.

    This will clone the manifest repository sdk-nrf into nrf.

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

    west update
    
  6. Export a Zephyr CMake package. This allows CMake to automatically load the boilerplate code required for building nRF Connect SDK applications:

    west zephyr-export
    

Your directory structure now looks similar to this:

ncs
 |___ .west
 |___ bootloader
 |___ modules
 |___ nrf
 |___ nrfxlib
 |___ zephyr
 |___ ...

Note that there are additional folders, and that the structure might change. The full set of repositories and folders is defined in the manifest file.

Install additional Python dependencies

The nRF Connect SDK requires additional Python packages to be installed.

Use the following commands to install the requirements for each repository.

Open a command prompt 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 bootloader/mcuboot/scripts/requirements.txt

Install the toolchain

To be able to cross-compile your applications for Arm targets, you must install version 9-2019-q4-major of the GNU Arm Embedded Toolchain.

Important

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

Other versions of the nRF Connect SDK might require a different toolchain version.

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. We recommend to use the folder c:\gnuarmemb on Windows and ~/gnuarmemb on Linux or macOS.

    Make sure that the folder name does not contain any spaces or special characters.

  3. If you want to build and program applications from the command line, define the environment variables for the GNU Arm Embedded toolchain. Depending on your operating system:

    Open a command prompt and enter the following commands (assuming that you have installed the toolchain to c:\gnuarmemb; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):

    set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
    set GNUARMEMB_TOOLCHAIN_PATH=c:\gnuarmemb
  4. Set the environment variables persistently. Depending on your operating system:

    Add the environment variables as system environment variables or define them in the %userprofile%\zephyrrc.cmd file as described in Set up the command-line build environment. This lets you avoid setting them every time you open a command prompt.

Install the SEGGER Embedded Studio Nordic Edition

You must install the SEGGER Embedded Studio (SES) Nordic Edition 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 the SEGGER Embedded Studio Nordic Edition, complete the following steps:

  1. Download the package for your operating system:

  2. Extract the downloaded package in the directory of your choice.

  3. 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:

    1. Run the file bin/emStudio. SEGGER Embedded Studio will open the Dashboard window and inform you about the missing license.

      SEGGER Embedded Studio Dashboard notification about missing license

      No commercial-use license detected SES prompt

    2. Click Activate Your Free License. A request form appears.

    3. Fill in your information and click Request License. The license is sent to you in an email.

    4. After you receive your license key, click Enter Activation Key to activate the license.

    5. Copy-paste the license key and click Install License. The license activation window will close and SES will open the Project Explorer window.

Note

Notifications about newer versions of SES are disabled in the SES Nordic Edition. This is because of the custom nRF Connect SDK options that are available only in the Nordic Edition. You will not be able to use SES with the nRF Connect SDK if you install the latest standard version of SES.

When you move to a newer release of the nRF Connect SDK, check the Required tools page for the given release to see if you are using the minimum required version of SES Nordic Edition. If you need to install the latest version of the SES Nordic Edition, follow the steps described above and make sure to set up the build environment in SES once more.

Set up the build environment in SES

Before you start building and programming a sample application, you must set up your build environment.

  1. Set up the SES environment. If you plan to build with SEGGER Embedded Studio, the first time you import an nRF Connect SDK project, SES might prompt you to set the paths to the Zephyr Base directory and the GNU ARM Embedded Toolchain. You only need to do this once. Complete the following steps:

    1. Run the file bin/emStudio.

    2. Select File > Open nRF Connect SDK Project.

      Open nRF Connect SDK Project menu

      Open nRF Connect SDK Project menu

    3. 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, c:/gnuarmemb).

      Zephyr Base Not Set prompt

      Zephyr Base Not Set prompt

  2. Set up executables. The process is different depending on your operating system.

    Make sure the locations of executable tools are added to the PATH variable, including Python, CMake, Ninja, and DTC. On Windows, SES uses the PATH variable to find executables if they are not set in SES.

  3. Change the SES environment settings. If you want to change the SES environment settings, click Tools > Options and select the nRF Connect tab, as shown on the following screenshot from the Windows installation.

nRF Connect SDK options in SES on Windows

nRF Connect SDK options in SES (Windows)

If you want to configure tools that are not listed in the SES options, add them to the PATH variable.

Set up the command-line build environment

The default build environment for the nRF Connect SDK is SES. However, you can also build and program your application from the command line. You have to set up your build environment by defining the required environment variables every time you open a new command prompt or terminal window.

See Important Build System Variables for more information about the various relevant environment variables.

Define the required environment variables as follows, depending on your operating system:

Navigate to the ncs folder and enter the following command: zephyr\zephyr-env.cmd

If you need to define additional environment variables, create the file %userprofile%\zephyrrc.cmd and add the variables there. This file is loaded automatically when you run the above command. See Option 3: Using zephyrrc files for more information.

You must also make sure that nrfjprog (part of the nRF Command Line Tools) is installed and its path is added to the environment variables. The west command programs the development kit by using nrfjprog by default. For more information on nrfjprog, see Programming SoCs with nrfjprog.