Using CMake for Nordic nRF52 projects

CMake is a popular C/C++ build system (or an “open-source, cross-platform family of tools designed to build, test and package software” according to the website) that we use at NRB Tech with firmware projects and cross-platform libraries. CMake can also be used with CLion, an excellent C/C++ IDE. Nordic officially recommends and supports Segger Embedded Studio as its IDE of choice, however CMake makes managing dependencies and unit testing much easier.

For example, a common development architecture we use at NRB Tech is to share a C library or libraries between firmware, utilities, and Apps, to reduce code duplication and bugs and ensure mission-critical code is well unit tested. With CMake it is trivial to manage this library, generating Makefiles or Xcode projects as required and integrating as a dependency into other CMake projects.

Nordic do not directly provide support for CMake in their SDK, but their mesh SDK does use CMake, and this can be adapted to use CMake for the Nordic SDK in non-mesh projects.

nRF5-cmake-scripts

Nordic’s mesh SDK was not designed for building external, custom, non-mesh projects, but with a little external support it can be used for this purpose, which is what our nRF5-cmake-scripts project does – it uses the mesh SDK scripts where possible, and defines its own functions for everything else – including adding features that Nordic’s mesh SDK doesn’t have, such as adding bootloader targets and creating DFU packages. It also defines functions for easily including many of the libraries in the Nordic SDK. Let’s have a go at creating a new project from scratch.

Installing the dependencies

• Download and install JLink

• Download and install Nordic command line tools

• Download and install ARM GNU Toolchain

  • On Mac, this can be installed via homebrew:

    brew tap ArmMbed/homebrew-formulae
    brew install arm-none-eabi-gcc

• Install nrfutil via pip (Python package manager):

  pip install nrfutil

• Install CMake and Git

Creating a CMake based Nordic firmware project

The finished project can be found here.

First, in a terminal/command window clone the base project to set up the project structure:

git clone --recurse-submodules https://github.com/NRB-Tech/nRF5-cmake-scripts-example-base.git .

Run a script to clean up the project ready for your own use (on Windows, run in git bash by right clicking in directory > "Git Bash here"):

./cleanup.sh

Copy the example CMakeLists.txt as recommended in the nRF5-cmake-scripts readme:

cmake -E copy nRF5-cmake-scripts/example/CMakeLists.txt .

_Note: You may also need to edit some of the variables in this file for your platform, such as setting NRFJPROG, MERGEHEX, NRFUTIL and PATCH_EXECUTABLE manually if they are not in your PATH._

Then we can use the script to download the dependencies:

cmake -Bcmake-build-download -G "Unix Makefiles" .
# on Windows, run `cmake -Bcmake-build-download -G "MinGW Makefiles" .`
cmake --build cmake-build-download/ --target download

Copy across some files from an SDK example project (for the nRF52840 DK, replace pca10040/s132 with pca10056/s140):

cmake -E copy toolchains/nRF5/nRF5_SDK_16.0.0_98a08e2/examples/ble_peripheral/ble_app_template/pca10040/s132/armgcc/ble_app_template_gcc_nrf52.ld src/gcc_nrf52.ld
cmake -E copy toolchains/nRF5/nRF5_SDK_16.0.0_98a08e2/examples/ble_peripheral/ble_app_template/pca10040/s132/config/sdk_config.h src/

At this point, you can open the project in CLion or your editor of choice to edit the files.

Add a file src/main.c and add some source code. Here we add some simple code to log a message.

#include "nrf_log_default_backends.h"
#include "nrf_log.h"
#include "nrf_log_ctrl.h"

int main(void) {
    ret_code_t err_code = NRF_LOG_INIT(NULL);
    APP_ERROR_CHECK(err_code);

    NRF_LOG_DEFAULT_BACKENDS_INIT();

    NRF_LOG_INFO("Hello world");
    while(true) {
        // do nothing
    }
}

Create an src/app_config.h file to override some of the default configuration in sdk_config.h:

#define NRF_LOG_BACKEND_RTT_ENABLED 1 // enable rtt
#define NRF_LOG_BACKEND_UART_ENABLED 0 // disable uart
#define NRF_LOG_DEFERRED 0 // flush logs immediately
#define NRF_LOG_ALLOW_OVERFLOW 0 // no overflow
#define SEGGER_RTT_CONFIG_DEFAULT_MODE 2 // block until processed

We are going to include the DFU bootloader too, so we need to generate keys. In terminal/command prompt:

nrfutil keys generate keys/dfu_private.key
nrfutil keys display --key pk --format code keys/dfu_private.key --out_file keys/dfu_public_key.c

Now we need to create a file src/CMakeLists.txt to build our targets:

set(NRF5_LINKER_SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/gcc_${NRF_FAMILY})

# DFU requirements
# List the softdevice versions previously used, or use FALSE if no previous softdevices
set(PREVIOUS_SOFTDEVICES FALSE)
# Set the location to the DFU private key
set(PRIVATE_KEY ${CMAKE_CURRENT_SOURCE_DIR}/../keys/dfu_private.key)
set(PUBLIC_KEY ${CMAKE_CURRENT_SOURCE_DIR}/../keys/dfu_public_key.c)
# Set the App validation type. [NO_VALIDATION|VALIDATE_GENERATED_CRC|VALIDATE_GENERATED_SHA256|VALIDATE_ECDSA_P256_SHA256]
set(APP_VALIDATION_TYPE NO_VALIDATION)
# Set the Soft Device validation type. [NO_VALIDATION|VALIDATE_GENERATED_CRC|VALIDATE_GENERATED_SHA256|VALIDATE_ECDSA_P256_SHA256]
set(SD_VALIDATION_TYPE NO_VALIDATION)
# The bootloader version (user defined)
set(BOOTLOADER_VERSION 1)
# The DFU version string (firmware version string)
set(DFU_VERSION_STRING "${VERSION_STRING}")

# Set the target name
set(target example)

# add the required libraries for this example
nRF5_addLog()
nRF5_addSeggerRTT()
nRF5_addAppError()

# include files
list(APPEND SOURCE_FILES
        main.c
        )
list(APPEND INCLUDE_DIRS
        "${CMAKE_CURRENT_SOURCE_DIR}"
        )

nRF5_addExecutable(${target} "${SOURCE_FILES}" "${INCLUDE_DIRS}" "${NRF5_LINKER_SCRIPT}")

# make sdk_config.h import app_config.h
target_compile_definitions(${target} PRIVATE USE_APP_CONFIG)

# Here you can set a list of user variables to be defined in the bootloader makefile (which you have modified yourself)
set(bootloader_vars "")

# add the secure bootloader build target
nRF5_addSecureBootloader(${target} "${PUBLIC_KEY}" "${bootloader_vars}")
# add the bootloader merge target
nRF5_addBootloaderMergeTarget(${target} ${DFU_VERSION_STRING} ${PRIVATE_KEY} ${PREVIOUS_SOFTDEVICES} ${APP_VALIDATION_TYPE} ${SD_VALIDATION_TYPE} ${BOOTLOADER_VERSION})
# add the bootloader merged flash target
nRF5_addFlashTarget(bl_merge_${target} "${CMAKE_CURRENT_BINARY_DIR}/${target}_bl_merged.hex")
# Add the Bootloader + SoftDevice + App package target
nRF5_addDFU_BL_SD_APP_PkgTarget(${target} ${DFU_VERSION_STRING} ${PRIVATE_KEY} ${PREVIOUS_SOFTDEVICES} ${APP_VALIDATION_TYPE} ${SD_VALIDATION_TYPE} ${BOOTLOADER_VERSION})
# Add the App package target
nRF5_addDFU_APP_PkgTarget(${target} ${DFU_VERSION_STRING} ${PRIVATE_KEY} ${PREVIOUS_SOFTDEVICES} ${APP_VALIDATION_TYPE})

# print the size of consumed RAM and flash - does not yet work on Windows
if(NOT ${CMAKE_HOST_SYSTEM_NAME} STREQUAL "Windows")
    nRF5_print_size(${target} ${NRF5_LINKER_SCRIPT} TRUE)
endif()

Then we are ready to build and run our example. First, run JLink tools to get the RTT output:

cmake -Bcmake-build-debug -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug .
# On Windows, run `cmake -Bcmake-build-debug -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug .` 
# If you get an error that the compiler cannot be found, ensure it is present in your PATH (try running `arm-none-eabi-gcc`). Windows users, see the dependencies section.
cmake --build cmake-build-debug/ --target START_JLINK_RTT

Then, build the merge and flash target:

cmake --build cmake-build-debug/ --target flash_bl_merge_example

You should see the "Hello world" log output in the RTT console! From here you can add source code and include SDK libraries with the macros provided in nRF5-cmake-scripts/includes/libraries.cmake.

NRB Tech uses CMake to create well tested products utilising cross-platform code. If you are looking at creating a new product, or want to work on a diverse range of cross platform product development, get in touch.