nRF Connect SDK Tutorial - Part 1 | v1.5.0

This tutorial uses an outdated version of nRF Connect SDK. We recommend using the latest version of nRF Connect SDK when getting started with development. Please see academy.nordicsemi.com for the latest content.

→ Check out the preceding part of this tutorial series before starting on this: nRF Connect SDK Tutorial series - Part 0


This part of the nRF Connect SDK Tutorial series will be short and concise and will get you up and running with nRF Connect SDK and your board as quickly as possible. The first section will demonstrate how to build and run a “hello world” sample on your board, and the second section will provide you with the most vital information for the beginning phase for your particular board.

As mentioned in Part 0, you should choose a board and set <board> and <board_variant> accordingly. This applies to this part as well, and when you see one of these variables use your chosen value instead.

Contents

1 Your first “Hello World”

1.1 Set it up

In this setup, the sample will be put outside the nrf folder. This is a modular approach than keeps the project detached from the nRF Connect SDK. Check out user workflows in the nRF Connect SDK documentation to get a deeper insight how you can structure your project in nRF Connect SDK.

  • Start by creating a folder named my_projects inside your folder of choice (e.g. C:/), inside that folder create the folder hello_world.
  • Then, create these inside the hello_world folder:
    • A folder named src with main.c inside
    • CMakeLists.txt
    • prj.conf

It should look like this:

  • Next up, copy these lines into CMakeLists.txt 

cmake_minimum_required(VERSION 3.8.2)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(NONE)

target_sources(app PRIVATE src/main.c)

  • Inside prj.conf, add this configuration

CONFIG_SERIAL=y

This config is required in order to see the logging from a serial terminal and will enable the serial driver. However, it is actually not necessary to enable it, as it's are already enabled by default in nRF Connect SDK for the listed boards. E.g. in the board folder for the nRF9160 DK (non-secure) this configuration is set inside nrf9160dk_nrf9160ns_defconfigI included it anyway to make you familiar with the prj.conf file.

The main.c file should look like this:

#include <zephyr.h>
#include <sys/printk.h>

void main(void)
{
	printk("Hello World!\n");
}

 

1.2 Build and flash - using SEGGER Embedded Studio

After this section was written, the nRF Connect for Visual Studio Code extension has been released. If you're starting a new project, I would recommend you to use that IDE for development. Check out the nRF Connect for VS Code tutorials on YouTube

There is a guide in the Toolchain Manager on how to build and run a project, Open Toolchain Manager (TM) app and click on "First step to build" to see it. Choose the one with <version> equal to v1.5.0

For the record, I will go through the process here as well.

  • Open the Toolchain Manager (TM) app and click on "Open IDE" to run SEGGER Embedded Studio (SES) Nordic Edition V5.34a. Choose the one with <version> equal to v1.5.0

Two important environment variables to set are the Zephyr base and the GNU ARM Embedded Toolchain directory, however, if you've installed nRF Connect SDK through the TM, these will be set automatically. In SES, click on Tools→Options→nRF Connect to see the values (see image below). E.g. if you're using nRF Connect SDK v1.5.0, the GNU Toolchain and the Zephyr base may be equal to respectively "C:\Users\<user name>\ncs\v1.5.0\toolchain\opt" and "C:\Users\<user name>\ncs\v1.5.0\zephyr".

  • In order to open the hello_world application in SES, click on File → Open nRF Connect SDK Project...

  • Choose the nRF Connect Options shown in the image below. Set <ncs_version> equal to v1.5.0.
    • To set "Project:" click on the three dots to the right, find the hello_world project you created in 1.1 Set it up (e.g. C:\my_projects\hello_world) and click on "Select Folder"

E.g. if you are building with the board variant nrf9160dk_nrf9160ns, it should look like this (image was taken for the nRF Connect SDK 1.4.0 version of the tutorial):

  • Connect your chosen board to your computer and turn it on. 

If you are using the nRF9160 DK, make sure SW5 is set to nRF91

If you are using the nRF5340 DK, you may encounter some an error similar to "The operation attempted is unavailable due to readback protection..". Check out Readback protection, and click on the nrfjprog tab to get instructions how to recover the network and application core.

  • To build and flash the application, choose Build → Build and Run.

  • Then, download, install and start a terminal (e.g. Termite) to show the serial output
    • To check what COM port to use: Press the Windows key + Q, search for "Device Manager" and open it. The COM ports are listed under "Ports (COM & LPT)"
    • Open the terminal(s) with the COM port(s) you found and choose the following Port configurations
    • After resetting the board, you should see the following log inside one of the terminals:

      *** Booting Zephyr OS build v2.4.99-ncs1  ***
      Hello World!

    1.3 Build and flash - using west

    After this section was written, the nRF Connect for Visual Studio Code extension has been released. If you're starting a new project, I would recommend you to use that IDE for development. Check out the nRF Connect for VS Code tutorials on YouTube

    If you've installed nRF Connect SDK through the Toolchain Manager it is not necessary to set any environmental variables since everything is set automatically upon installation and runs out of the box. Please skip section 1.3.1 and go straight to section 1.3.2 Build and flash if this is the case for you.

    1.3.1 Set the environment variables

    In order to build the application using west, some environment variables need to be set, specifically the toolchain and the Zephyr base. Even though you're not using the TM and are building any of the samples or applications directly in the nrf folder it is not necessary to set the Zephyr base, since the CMake tool will locate it automatically when building your application through west build. However, in this tutorial, we keep the project detached from the SDK and the environmental variable ZEPHYR_BASE needs to be set (if nRF Connect SDK is installed manually).

    If you follow the nRF Connect SDK documentation you'll be told to set environmental variables through the cmd file zephyr-env.cmd. This is a nice way of doing it if you are working with different projects, and don't want the env. variables to interfere, but you'll have to run the cmd file every time you open the command line.

    For this tutorial, let's add the toolchain environmental variables to the whole system instead. Follow these steps:

    • Open cmd, running as administrator

    • Run the following commands:
      • setx -m ZEPHYR_TOOLCHAIN_VARIANT "gnuarmemb"
      • setx -m GNUARMEMB_TOOLCHAIN_PATH c:\gnuarmemb

    C:\WINDOWS\system32>setx -m ZEPHYR_TOOLCHAIN_VARIANT "gnuarmemb" && setx -m GNUARMEMB_TOOLCHAIN_PATH c:\gnuarmemb
    
    SUCCESS: Specified value was saved.
    
    SUCCESS: Specified value was saved.

    • Reopen the command line and check that the env. variables are set correctly:

    C:\my_projects\hello_world>echo %GNUARMEMB_TOOLCHAIN_PATH% & echo %ZEPHYR_TOOLCHAIN_VARIANT%
    c:\gnuarmemb
    gnuarmemb

    Let's set the Zephyr base.

    • Open the command line inside <folder_of_choice>/my_projects/hello_world
    • Run the command set ZEPHYR_BASE=C:\Nordic_SDK\ncs\zephyr (change the path if you have put the nRF Connect SDK somewhere else)

    C:\my_projects\hello_world>set ZEPHYR_BASE=C:\Nordic_SDK\ncs\zephyr

    • Check that it's set correctly by running echo %ZEPHYR_BASE%

    C:\my_projects\hello_world>echo %ZEPHYR_BASE%
    C:\Nordic_SDK\ncs\zephyr

    There are mainly two different ways of setting ZEPHYR BASE, by using set or setx. The former one (set), which is used above, will set it temporary and immediately in the current shell and the latter (setx), which was used when setting the toolchain env. variables, will set it permanently with the need to reopen the shell. Pick the option that suits you best.

    1.3.2 Build and flash

    Let's get the sample running.

    • Open the TM Bash shell by clicking on the downward pointing arrow and "Open bash". Choose the one where <version> is equal to v1.5.0.

    It is important to open the shell (either bash or the command prompt) from the Toolchain Manager when building your project, since all the tools from C:\Users\<user_name>\ncs\v1.5.0\toolchain will only be accessible then.

    • In the bash shell, run cd C:/my_projects/hello_world. Use another path if you've placed your sample somewhere else.
    • Run the command west build -b <board_variant> to build the application with west:

    ... MINGW64 /c/my_projects/hello_world
    $ west build -b <board_variant>
    -- west build: build configuration:
           source directory: C:\my_projects\hello_world
           build directory: C:\my_projects\hello_world\build (created)
    .
    .
    .

    If the build process was successful, you should see a folder named build inside the hello_world folder:

    The build folder should contain the following files and folders (it may vary slightly depending on the choice of <board_variant>):

    The last step remains, flashing the project onto the chip.

    If you are using the nRF9160DK, make sure SW5 is set to nRF91

    If you are using the nRF5340 DK, you may encounter some an error similar to "The operation attempted is unavailable due to readback protection..". Check out Readback protection, and click on the west tab to get instructions how to recover the network and application core.

    • The flashing is done by running the command west flash, either from the project folder or the build directory.
      • If you have chosen a custom name for the build folder, you have to run the command from the build folder
    • Verify that everything works by checking that the terminal outputs "Hello World!"

    2. Board-specific

    2.1 nRF9160 DK

    2.1.1 Build a Cellular IoT example

    The nRF9160 SiP incorporates an LTE modem, which makes it possible to run cellular IoT applications. The modem always operates in a non-secure domain (read more about this in External domain access control on the infocenter), and the application must do the same in order to communicate with it. Therefore, all the samples in <..>/nrf/samples/nrf9160 as well as the nrf9160 specific samples in <..>/nrf/applications, have to be built as nonsecure in order to work.

    To build a sample as non-secure, the board nrf9160dk_nrf9160ns (corresponds to <board_variant>) must be used. When building an application using this board, the following configurations will be set:

    → CONFIG_TRUSTED_EXECUTION_NONSECURE: This will make the application non-secure and make it run in the non-secure domain

    → CONFIG_SPM: This will build the SPM sample.

    To get a deeper understanding of secure/non-secure environments, jump forward to section 1.6 Secure vs. nonsecure in part 2 of this tutorial series.

    After the build process is complete, the file merged.hex (<..>nrf\samples\nrf9160\<sample>\build\zephyr\merged.hex) is generated, which contains both the SPM sample in addition to the application. When running west flash, this hex file will be chosen and get programmed onto the chip. Similarly in SES, if you program the chip through Build→Build Solution,  the merged.hex file will get flashed.

    Let's try to build the AT Client sample on the nRF9160 DK using SES. It is demonstrated how to build this sample in the nRF Connect SDK documentation, but for the record, let's do it again:

    • Follow section 1.2 Build and flash - using SEGGER Embedded Studio and program the AT Client sample onto the nRF9160. Choose these nRF Connect Options (make sure SW5 is set to nRF91):
      • nRF Connect SDK Release: 1.5.0
      • Project: at_client
        • You will find this if you check the option Cellular
      • Board Name: nrf9160dk_nrf9160ns
        • (remember ns at the end!)
      • Build Directory: C:/Users/<user_name>/ncs/v1.5.0/nrf/samples/nrf9160/at_client/build_nrf9160dk_nrf9160ns
        • This will get set automatically

    Your ncs location may differ, open the Toolchain Manager app and click on settings to see the location.

    • When you've flashed the sample, open a terminal, reset the chip and verify that you see the following output:

    *** Booting Zephyr OS build v2.4.99-ncs1  ***
    Flash regions		Domain		Permissions
    00 00 0x00000 0x08000 	Secure		rwxl
    01 31 0x08000 0x100000 	Non-Secure	rwxl
    
    Non-secure callable region 0 placed in flash region 0 with size 32.
    
    SRAM region		Domain		Permissions
    00 07 0x00000 0x10000 	Secure		rwxl
    08 31 0x10000 0x40000 	Non-Secure	rwxl
    
    Peripheral		Domain		Status
    00 NRF_P0               Non-Secure	OK
    ..
    ..
    ..
    25 NRF_GPIOTE1          Non-Secure	OK
    
    SPM: NS image at 0xc000
    SPM: NS MSP at 0x2001c350
    SPM: NS reset vector at 0xf171
    SPM: prepare to jump to Non-Secure image.
    *** Booting Zephyr OS build v2.4.99-ncs1  ***
    The AT host sample started

    Check out the section AT Client→Building and running for more generic explanations and instructions on how to test the example to see if everything works as expected.

    If you would like to use west instead, follow the steps below

    • Open the TM bash shell, redirect to <..>\ncs\v1.5.0\nrf\samples\nrf9160\at_client and run the command west build -b nrf9160dk_nrf9160ns
    • Connect and turn on the nRF91 DK and make sure SW5 is set to nRF91
    • From <..>\ncs\v1.5.0\nrf\samples\nrf9160\at_client, run west flash
    • Use a serial terminal to verify that the program works

    2.1.2 Common issues

    → If you are encountering any errors, you may have to update the modem firmware to the latest version, check out nRF9160 DK Getting Started→Updating the modem firmware for instructions on how to do this. 

    → If you have problems connecting the nRF9160 to nRF Cloud, you may have to update the nRF for Cloud certificates, check out nRF9160 DK Getting Started→Updating the nRF Cloud certificate for guidance on how this can be achieved.

    → Be aware that PSM and/or eDRX is not supported on all networks yet, or that some networks do not allow roaming SIM cards to use those features. As a consequence, applications such as the Asset Tracker won't work correctly.

    2.1.3 Useful resources

     nRF9160 DK Getting Started

    → Working with nRF9160

    https://webinars.nordicsemi.com/videos-1

    2.2 nRF5340 DK

    2.2.1 Build a BLE example

    The nRF5340 SoC incorporates two processors, the network core and the application core. The Bluetooth LE controller has to run on the network core while the Bluetooth LE host usually runs on the application core in addition to the application (Read more about the Bluetooth LE Stack Architecture and the Bluetooth LE Layers in the Zephyr documentation). As mentioned in the NCS documentation, Working with nRF5340, the network core has to be programmed with the Bluetooth: HCI RPMsg sample in order to run a Bluetooth LE sample on the nRF5340. If that is done, the application core can be programmed with any of the samples in <..>\nrf\samples\bluetooth.

    Let's demonstrate how to build the Bluetooth LE Peripheral LBS sample on the nRF5340 DK using SES:

    • Connect the nRF5340 DK to your computer and turn it on
    • Follow section 1.2 Build and flash - using SEGGER Embedded Studio and program the Peripheral LBS sample onto the nRF5340 application core. Choose these nRF Connect Options:
      • nRF Connect SDK Release: 1.5.0
      • Project: peripheral_lbs
        • You will find this if you check the option "Getting Started"
      • Board Name: nrf5340dk_nrf5340_cpuapp
      • Build Directory: C:/Users/<user_name>/ncs/v1.5.0/nrf/samples/bluetooth/peripheral_lbs/build_nrf5340dk_nrf5340_cpuapp
        • This will get set automatically

    Your ncs location may differ, open the Toolchain Manager app and click on settings to see the location.

    Next we need to program the HCI RPMsg sample. When building Bluetooth LE samples in nRF Connect SDK v1.5.0 with the nRF53, the hci_rpmsg sample will automatically get added as a child image. You can see the generated build output for the hci_rpmsg sample inside nrf\samples\bluetooth\peripheral_lbs\build_nrf5340dk_nrf5340_cpuapp\hci_rpmsg. In order for the Bluetooth LE sample to function properly on the nRF53 the hex file <build folder>\zephyr\merged.hex has to get programmed onto the application core and the hex file <build folder>hci_rpmsg\zephyr\merged_CPUNET.hex has to get programmed onto the network core. However, SES V5.10d will only flash merged.hex onto the application core, and the other hex file needs to get flashed manually using nrfjprog. Follow the steps below to achieve this:

    • Open the command line through the Toolchain Manager:

    • Run the following commands:

    cd nrf\samples\bluetooth\peripheral_lbs\build_nrf5340dk_nrf5340_cpuapp\hci_rpmsg\zephyr
    nrfjprog -f NRF53 --coprocessor CP_NETWORK --eraseall && nrfjprog -f NRF53 --coprocessor CP_NETWORK --program merged_CPUNET.hex
    nrfjprog --pinreset

    • To check that the Bluetooth LE application is working and advertising, install nRF Connect for Mobile on your phone and check for an advertising device with the name "Nordic_Blinky"

    If you are using west, you don't need to program the network core separately, as west will manage it for you. Follow the steps below to build and program a Bluetooth LE example with west:

    • Open the TM bash shell by following the first steps in 1.3.2 Build and flash
    • Redirect to <..>\ncs\nrf\samples\bluetooth\peripheral_lbs and run the command west build -b nrf5340dk_nrf5340_cpuapp && west flash
    • Verify that the sample is working by checking if the device is advertising

    2.2.2 Useful resources

    → Working with nRF5340

    → NUS on nRF Connect SDK: The Nordic UART Service with the nRF Connect SDK

    → nRFConnect SDK Bluetooth LE tutorial part 1: Custom Service in Peripheral role

    If you have any questions regarding this tutorial, please create a ticket in DevZone.


    → Check out the next part of this tutorial series: nRF Connect SDK Tutorial - Part 2