nRF5 Software Development Kit (SDK) tutorial

Overview

The nRF5 SDK contains a broad selection of drivers,  libraries, board definition files ,communication protocol stacks such as the SoftDevices for BLE  and a large set of examples for the Nordic Semiconductor devices and development boards. The SDK must be downloaded as it will be the foundation for your firmware development targeting the nRF5 devices.

Which IDE to choose ?

The SDK does not come with an Integrated Development Environment(IDE), you get to choose which IDE and compiler to use. There are five different methods to program the Nordic Semiconductor  nRF5x devices. Here is a brief overview on the advantage and disadvantages :

  1. Segger Embedded Studio (SES) :  Completely license free, no code size limitations, no restrictions whatsoever. SEGGER and Nordic Semiconductor have signed an agreement in late 2017 that entitles developers to use Embedded Studio with Nordic nRF5x chips for both commercial and non-commercial uses .The nRF5 SDK already contains out of the box examples developed in SES.  Embedded Studio is a complete all-in-one solution for managing, building, testing and deploying embedded applications. It supports everything from a powerful project manager and source code editor, included C/C++ compilers based on GCC, as well as CLANG/LLVM and an integrated debugger with advanced debug information windows and direct J-Link integration, right through to version control features for automatic deployment of finished application. The SES is supported on Windows, Linux and OSX.
  2. GNU ARM GCC : This approach is also license free, with no limitation . It’s based on the industry standard GNU Arm Embedded Toolchain. The nRF5 SDK comes with  examples delivered as makefiles which uses the toolchain. You could use your favorite choice of IDE (Ex: Eclipse) in this approach. This method is only recommended for advanced developers as it involves heavy setup procedures. This approach is cross-platform when it comes to the development environment(Linux, OSX, and Windows ).
  3. Keil µVision :  Keil  is a popular IDE for software development solution for ARM-based microcontrollers and includes all components that you need to create, build, and debug embedded applications. It  is also  quite user friendly , However, you need to purchase a license to use it . The free ” Lite” version has both code size limitation, which means you won’t be able to generate an executable if your program size exceeded 32Kb and also features limitations. Keil only works on Windows machines.
  4. IAR Embedded Workbench:  Mature and well-established IDE but similar to Keil requires an expensive license. The IAR workbench only works on Windows machines.
  5. ARM mbed online IDE : This is your best bet if you just want to create a quick proof of concept prototypes on a supported development board. All you need to get started is to create an account (which is completely free) and start working on your application online using their online C/C++ compiler.   Your application will be based on the Mbed OS  and its drivers /libraries. The level of abstraction offered by Mbed OS is amazing, you can create functioning prototypes very quickly. Keep in mind that the debugging capabilities of the online platform is weak. Not recommended for production-level development.
comparision_IDE_nRF5x

Comparison between the different methods available to program the nRF5x chips

The method used in this course is number 1 , which is using the license-free mature  Segger Embedded Studio (SES)  Integrated Development Environment(IDE). The procedures to download, setup, link it with the nRF5 SDK,  and acquire the free license of the IDE are elaborated in LabA-5. Migration between projects done in SES,GNU GCC, or Keil or IAR is possible , since they all use the same backbones drivers, libraries, protocols stacks of nRF5 SDK offered by Nordic Semiconductor.

The nRF5  SDK is available as a .zip-archive file and can be downloaded free of charge from Nordic Semiconductor website

SDK_versions

nRF5 SDK versions (Select the one which support your development kit)

Which version to choose ?

Your choice of SDK version will  strongly depend on the development board you are using . Please keep in mind that it’s not always going to be the latest one. The latest nRF5 SDK version at the time of writing this post is  v15.0.0 . It support the five Nordic Semiconductor development boards shown below

Supported Boards_nRF5 SDK v15.0.0

nRF5 SDK v15.0.0 Supported Boards

 

The above information was obtained from http://infocenter.nordicsemi.com -> Software Development Kit -> nRF5 SDK -> nRF5 SDK v15.0.0 -> SDK Release Notes

For instance, the nRF5 SDK v15 is the right choice  if you are using the nRF52-DK (Board ID PCA10040) or the nRF52840-DK (Board ID PCA100056) . However, if you are using the nRF51-DK (Board ID  PCA10028) or the nRF51-Dongle (Board ID  PCA10031) you need to use nRF5 SDK v12.3.0 .

nRF5_SDK_v12.3.0 Supports PCA10028 and PCA10031

 

For a 3’rd party development board (Not produced by Nordic Semiconductor), the correct SDK version can is determined  by  finding  the Nordic chip used by the board  (nRF5xxxx)and its IC revision number ( Engineering A, Engineering B, Engineering C, 1,2, or 3 ) , these information are usually found in the datasheet or the user guide of the development board. Once these information are found go to http://infocenter.nordicsemi.com/ .  Select nRF51 Series or nRF51 Series,  then select Compatibility matrix -> nRF5x Series IC revisions compatibility with SDK and SoftDevices.

Example : Suppose you have a 3’rd party development board which hosts  the Nordic Semiconductor nRF51822 chip revision 3 . The correct SDK to chose from should be bigger than 8.0.0 and less or equal to 12.3.0(Preferably the later 12.3.0) , as obtained from the comparability matrix from Nordic Info Center.

Example : Compatible SDK version for an nRF51822 chip revision 3

Exploring the nRF5 SDK

Once you have identified the right version of the SDK that suites your development board or device( Explained in the previous step), follow the following steps to take a brief view of what comes in the SDK.

1.Download the .zip-archive file of the suitable SDK version  from here website

nRF5 SDK v15.0.0 Download

Download SDK v15.0.0 for nRF52 series

In the screenshot above, we are assuming a development targeting the nRF52 series chips such as the ones hosted on the nRF52840-DK or nRF52-DK development boards.

2. Create a folder called nordic_semi on your local disk ( it’s preferable to place it as close as possible to the root directory and avoid paths which contains white spaces).

Extract_nRF5SDK

Extract the archived file of the nRF5 SDK locally.

 

3. After the extraction is complete , browse inside the SDK :

SDK_top_level

nRF5 SDK v 15.0.0 Top Level Directory Content

 

The directories contain the following :

A. components :  This is the core folder inside the SKD. It contains communication protocols APIs (IEEE 802.15.4,  ANT, BLE, etc.. ), boards definition files, drivers abstraction layer, a large set of  a very powerful libraries(56) ,  Softdevices binary files, and  toolchains configuration files .

components directory inside the nRF5 SDK

 

B. config : This folder contains a  generic sdk_config.h file that has all available static configuration options for each supported device ( For the nRF5 v 15.0.0 its only the nRF52 series ). It also contains a generic linker files for Segger Embedded Studio flash_placement.xml and ARM GCC generic_gcc_nrf52.ld . These linker files contain information about the memory sections present on the supported SoCs.

config directory inside the nRF5 SDK

 

Snapshot of the content of sdk_config and flash_placement

The SDK configuration header file sdk_config.h helps to manage the static configuration of a firmware that is built on top of nRF5 SDK. All projects must contain a sdk_config.h  file in which only the used modules are enabled. The configuration file consists of the SDK modules configuration part, which is common for all projects, and an application-specific configuration section.

C. documentation : As the name suggests, the SDK documentation links are placed here.  The most recommended place for documentation when it comes to Nordic nRF5x chips is the Nordic Semi info center http://infocenter.nordicsemi.com/ .What you have in this directory is just a link to it.

nRF5 SDK documentation directory

 

D. examples : Ready for deployment rich set of well-written examples.

nRF5 SDK examples directory

The examples covers a lot of topics :

  • IEEE 802.15.4 LR-WPAN wireless personal area networks examples.
  • ANT examples (Propitiatory short range wireless protocol).
  • Bluetooth Low Energy examples(Central role, peripheral role, both , and DFU).
  • Cryptographic examples.
  • Device Firmware Update (DFU) examples.
  • Direct Test Mode(DTM) examples.
  • Internet of things (IoT) examples.
  • Nordic proprietary protocols exmples(Gazell  , Enhanced ShockBurst)
  • Near Field Communication (NFC) examples.
  • Hardware Peripherals examples ( UART, I2C, Timers, PWM, etc..)

Not all examples are available for all development kits. Open the readme file inside the examples directory  and see which examples are supported by which boards .

nRF5 SDK examples compatibility matrix

One important note to remember regarding the nRF5 SDK examples, each example folder has several separate subfodlers, which is for the different supported development boards. See the screenshot below as an example

UART hardware peripheral example directory layout

Inside each board project directory (ex: pca10056) you will find  project sub-directories for the supported IDEs.

E. external : source code files for 3’rd party  libraries, protocol stacks  and utilities ( Lwip, FatFs, cJson, etc…)

nRF5 SDK external directory

 

E. external_tools : The CMSIS Configuration Wizard is shipped here . The Configuration Wizard  provides a user-friednly method to  enable/disable modules(libraries, drivers, softdevices, features) from the SDK config file sdk_config.h without the need to do that manually . You need to have Java installed on your machine in order to use the CMSIS Configuration Wizard .

CMSIS Configuration Wizard available in the external_tools subdirectory of the SDK

 

CMSIS Configuration Wizard

 

F. integration: legacy drivers for backward comparability.

G. modules: This directory contains the implementation of most hardware peripherals drivers, bootup codes, and exceptions vector tables.