Introduction to Nordic nRF5 SDK and Softdevice

What is the difference between SDK and Softdevice? How can we select SDK and Softdevice versions? Do the SoC, SDK, and Softdevice have version compatibility problems? How can we understand the SDK directory structure? Where is the SDK documentation? Where is the Softdevice user manual? How can we select an SDK example to start our Bluetooth LE development journey? This article will cover the above topics.

Nordic currently has two fully independent SDK: nRF5 SDK and nRF Connect SDK. In general, nRF5 SDK is recommended for developing nRF51/52 products and nRF Connect SDK is recommended for developing new products such as nRF91/nRF53. This article will introduce the nRF5 SDK. Strictly speaking, nRF5 SDK is a product zip file. Different versions have different product packs, which are shown below.

Apart from this basic nRF5 SDK, Nordic has also launched some customized nRF5 SDK for some vertical applications. These SDKs and the basic nRF5 SDK use the same software architecture, the same driver and library, and the same coding style. For developers, if they are familiar with the nRF5 SDK, they can also work with these customized SDKs quickly. Nordic offers the following types of tailored SDKs:

1. nRF5 SDK for Mesh is used for developing Bluetooth Mesh applications. Download
2. nRF5 SDK for Thread and ZigBee is used to develop ZigBee or Thread applications. Download
3. nRF5 SDK HK is used for developing Apple Homekit applications. Please be aware that you can only get the Homekit SDK via a private devzone ticket after you get Apple’s official grant.
4. Thingy:52 SDK is used for developing Nordic Thingy:52 sensors kit. Download
5. nRFready Smart Remote 3 is used for developing Bluetooth TV remote control with voice commands. Download
6. nRFready Desktop 2 is used for developing Bluetooth or 2.4G wireless keyboards and mice. Get the SDK from your local sales.

If your application is one of the six vertical applications above, it is recommended that you pick one of the customized SDKs, otherwise, the basic nRF5 SDK shall always be selected. This article would only cover the contents of the basic nRF5 SDK. It would not involve the other customized SDKs.

1. Overview of nRF5 SDK and Softdevice

• Download nRF5 SDK here
• nRF5 SDK is the software development kit for Nordic nRF51/52 series SoCs. Softdevice is the name of the Nordic Bluetooth protocol stack (plus ANT protocol stack in some cases). For the convenience of users, each version of nRF5 SDK is released together with the tested and working Softdevice. Please go to the <InstallFolder>\components\softdevice directory to view the supported Softdevice types and versions in this specific version of SDK.
• nRF5 SDK version numbers are like nRF51 SDK v9.0.0, nRF51 SDK v10.0.0, nRF5 SDK v11.0.0, nRF5 SDK v12.0.0...the latest version is nRF5 SDK v16.0.0. SDK9/10 only support nRF51 series chips. SDK11/12 support both nRF51 and nRF52 series chips, while SDK13/14/15/16 only support nRF52 series chips. By the way, each version has a dedicated version of device family pack (or called nRF MDK) for Keil. If you need to install multiple versions of nRF5 SDKs, you would install different versions of device family packs on your PC at the same time. Please install them in order from lower versions to higher versions. If you don’t follow it, you might get a compilation error. If so, please completely uninstall the previous device family pack first, and then reinstall all packs in the order from low to high.
• Generally, we recommend using the latest SDK to develop your applications. Because the latest SDK is characterized by more features, more compatibility and more reliability. Specifically, nRF5 SDK v16.0.0 is recommended for nRF52 series, while nRF5 SDK v12.3.0 is recommended for nRF51 series (SDK12.3.0 is already the highest version of SDK to support nRF51). However, the latest version of SDK takes up more Flash and RAM resources, which is designed for more advanced applications. In order to make full use of some resource constrained nRF5 devices, old versions of SDK can also be used for the new customers. A frequently asked question by the old customers is: should I upgrade my SDK? It depends on your needs and testing results. As long as your code passes all the test cases and it behaves stable and reliable, there is no need to upgrade the SDK. In other words, in the case of you want to add the features introduced in the newer SDKs or find some problems which cannot be fixed in the old SDKs, you need to upgrade your SDK. Please check out <InstallFolder>\documentation\release_notes.txt to view the new features of the latest SDK.
• Softdevice naming rule one. Softdevice is composed of two protocol stacks: Bluetooth LE and ANT. Bluetooth LE has two roles: central (or called master) and peripheral (or called slave). Therefore, different types of Softdevice must be distinguished by its naming. Nordic uses Sxyz to denote different Softdevice, where
  • x – denotes the type of protocol. 1 indicates the Bluetooth LE protocol. 2 indicates the ANT protocol. 3 indicates a combined Bluetooth LE and ANT protocol.
  • y – denotes the Bluetooth LE role. 1 indicates the slave role. 2 indicates the master role. 3 indicates a combined master and slave roles.
  • z – denotes the SoC family. 0 indicates nRF51 series. 2 or 3 indicates nRF52 series.

Example interpretation is shown below

S130, which denotes nRF51 Bluetooth LE protocol stack supporting both central and peripheral roles.

S112, which denotes nRF52 Bluetooth LE protocol stack only supporting slave role.

S132, which denotes nRF52 Bluetooth LE protocol stack supporting both central and peripheral roles.

S212, which denotes nRF52 ANT protocol stack

S332, which denotes nRF52 combined Bluetooth LE and ANT protocol stack and supports both BLE master and slave roles.

• Softdevice naming rule two. It inherits rule one, but the last 2 digits of the softdevice number refer to the chip model. For example, S140 means this softdevice can only run on nRF52840. Due to big Flash size of 52840, there is no need to make different softdevice variants for 52840. One S140 is sufficient which supports all the features of BLE protocol, such as long range, master and slave, multilink and advertising extension.
• The softdevice version number are like 1.0.0, 2.0.0, 3.0.0... The latest version of S110 is 8.0.0. The latest version of S130 is 2.0.1. The latest version of S132/S140/S112/S113 is 7.0.1.
• SDK and softdevice compatibility. No need to view the compatibility table. Explore the SDK directly and use the native Softdevice in the SDK directly, which are fully tested and work with the related SDK examples directly. For example, the native S132 in SDK15.2.0 can be found in the following folder.
  
  

When you download SDK in the Nordic official website, it will automatically bind the native softdevice or a higher version if possible. If a higher version is recommended in this case, please use this higher version instead of the native version. Take SDK15.2.0 as an instance, the native version is 6.1.0 and the recommended version is 6.1.1. Use 6.1.1 instead in this case.

Note: sometimes there are some minor bugs in the softdevice. At this time, Nordic would release the bug-fixed softdevice separately. For example, the version of the S140 softdevice included in nRF5 SDK v15.2.0 is 6.1.0. Generally, it is fine to directly use this version of softdevice, but there is a small bug in the central role of this version of softdevice. Therefore, Nordic has released version 6.1.1 separately. Users need to download this version of softdevice separately from the official website. 

• SDK and chip compatibility. If you are using the latest revision of Nordic chip, there is no so-called compatibility problem. You can download the latest SDK directly. If unfortunately, you still have old revision chips in stock. In this case you might need to use some old versions of SDK. Please refer to the Compatibility Matrix for details. Take nRF52832 as an example, you can get it from here.
  
  

The compatibility table exists since the latest SDK serves the latest chip. And the latest SDK assume that some bugs of the earlier revisions have been fixed. Thus the latest SDK will not contain the workarounds (or patches) for the old chip revisions, which may result in some problems if you run the latest SDK on the old revisions.

2. Interpretation of nRF5 SDK Directory Structure

Taking SDK16.0.0 as an example, the directory structure of nRF5 SDK is as follows:

-components. This directory contains the SDK source code developed by Nordic. You’d better not modify any files in this directory during product development!  This rule also applies to the driver source code. The components directory structure is as follows:

-modules. Nordic has 2 different sets of chip peripheral drivers. SDK14 and previous versions of SDK use nrf_drv legacy peripheral drivers. And SDK15/16 uses nrfx new peripheral drivers (nrfx drivers are used in both nRF5 SDK and nRF Connect SDK). In SDK15/16, nrfx driver source code is listed in the following directory:

SDK14 or earlier versions have the driver source codes in the following place:

-examples. This directory has rich application examples, including Bluetooth LE application examples, peripheral application examples, and DFU bootloader examples. In general, you can find the example you require in most cases. The examples directory structure is shown below.

The two frequently used directories are: \ble_peripheral and \peripheral. The \ble_peripheral directory contains many Bluetooth LE slave role examples, while \peripheral contains examples on how to use peripherals. The \ble_peripheral directory structure is as follows:

The \peripheral directory structure is shown below. Many developers asked, “where I can get the documentation of SoC peripheral driver APIs” Because they need to follow the documents to develop applications. In Nordic, we not only provide the documentation but also the examples. We recommend reading the example code directly, which is more efficient.

Deprecated and experimental directories are often seen in nRF5 SDK. Their meanings are shown below.

\deprecated. The contents of this directory have been discarded and a new version will replace them.In order to be compatible with the old products, SDK still retains them. For example,  components\drivers_nrf\twi_master\deprecated. If you are a new user, please don’t use the API in the \deprecated directory.

\experimental. Some new features/new examples have not been tested on a large scale in the market since they have only been launched for a short time. In this case, Nordic will prefix these new features/new examples with "experimental", for example: examples\ble_peripheral\experimental\ble_app_cli. There might be bugs in it. The user is expected to perform enough tests to guarantee the product quality. In other words, if it passes all the test cases, use it freely and confidently.

3. nRF5 SDK and Softdevice documentation

• No matter it’s an SDK API or Softdevice API, it is recommended to check the API description provided by SDK first. Please be aware that API description is usually placed in the header file, not in the .c file. Each API has a detailed description of the parameters, usage and tips. For example, sd_ble_gatts_hvx API description can be found in header file ble_gatts.h:

• Softdevice has a separate spec to describe the working principles, resource usage, performance parameters, and precautions of Softdevice usage. It is recommended that every developer read the spec. You can find the spec in nRF52 series/nRF51 series directories of infocenter.
• SDK has both online and offline documentation. Their contents are identical. Offline documents are generated through online documentation to facilitate users with poor networks. You can choose one of them by your needs. Access the online documentation here.

Taking SDK16.0.0 online helping document as an example, its main interface is as follows. Expand the directories on the left panel and you will find that the documentation directory level corresponds to the SDK directory level one by one.

Therefore, if you have any questions about SDK, you can directly check the description of the corresponding online or offline documentation. For example, if you want to know what’s the purpose of this example: <Install folder>\examples\peripheral\spi , you can directly find the corresponding entry of the help document here. After reading the document, you will understand that this is an example showing how to use SPI master.

4. Select an SDK Example to Start your Bluetooth LE Development Journey

Nordic nRF5 SDK has rich application examples. You can start your development from one of these examples. All examples are found in the <InstallFolder>\examples directory. Its online documentation can be accessed here.

For example, <InstallFolder>\examples\ble_peripheral\ble_app_uart, the description of this example can be found here. By viewing the description, we know that this example uses Bluetooth as a pass-through communication media or emulate Bluetooth as an UART. If your application is just like this Bluetooth UART communication, you can start your development from this example.

By viewing all related examples, I believe you can find the right examples shortly. Now you can start your Bluetooth LE development journey from the chosen examples.