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.

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

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, 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.

Installing west

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

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
    • 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

      Note

      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 master.

    This will clone the manifest repository fw-nrfconnect-nrf into 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. 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. Running 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 ncs/nrf directory:

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

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

  1. Download the package for your operating system from the following links:

  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.

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:

  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

Setting up executables on macOS

If you start SES on macOS by running the file bin/emStudio, make sure to complete the following steps:

  1. Specify the path to all executables under Tools -> Options (in the nRF Connect tab).

    nRF Connect SDK options in SES on Windows

    nRF Connect SDK options in SES (Windows)

    Use this section to change the SES environment settings later as well.

  2. Specify the path to the west tool as additional CMake option, replacing path_to_west with the path to the west executable (for example, /usr/local/bin/west):

    -DWEST=path_to_west

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