Skip to content

nRF5 SDK for Mesh
Software Development Kit for Bluetooth mesh solutions using nRF51 Series and nRF52 Series

Introduction

The nRF5 SDK for Mesh is Nordic Semiconductor's implementation of the Bluetooth Mesh. It allows applications to utilize the features provided by the Bluetooth Mesh when running on Nordic's nRF5 Series chips.

The addition of mesh networking capabilities to Bluetooth Low Energy enables extended range, increases the number of nodes and a many-to-many (m:m) communication topology. In a Bluetooth mesh network every received packet is broadcasted by relays, until the packet is received by the destination node (a so called managed flooding mesh.) A simple, but effective way of spreading information across the mesh network with no single point of failure. The mesh functionality is a significant update and enables new applications for Bluetooth in smart home, lighting, beaconing and asset tracking applications.

For more information, go to nordicsemi.com.

Getting started

You can find detailed information about Bluetooth Mesh in Bluetooth SIG's introduction to Bluetooth Mesh and the Bluetooth Mesh Networking Specifications.

The following documentation sections provide detailed information about the required software toolchains and the process of building a mesh stack.

Installing the toolchain

To build the example applications, a toolchain based on either CMake is required. Install instructions are provided for macOS. The steps should be similar for other platforms.

CMake

CMake is a build management system used for managing an environment that is independent of the compiler and build system used. Version 3.6 or above is required by the mesh stack.

Install CMake using brew on macOS:

$ brew install cmake

GNU Arm Embedded Toolchain

The GNU Embedded Toolchain for Arm is a ready-to-use, open source suite of tools for C, C++ and Assembly programming targeting Arm Cortex-M and Cortex-R family of processors. It includes the GNU Compiler (GCC) and is available free of charge directly from Arm for embedded software development on Windows, Linux and macOS operating systems.

Download and install the 6-2017-q2-update version. Then make sure to add the path to your toolchain to your OS PATH environment variable:

# in ~/.bash_profile, add the following script
export PATH="<path to install directory>/gcc-arm-none-eabi-6-2017-q2-update/bin:${PATH}"

Adding the path makes it possible to run the toolchain executables from any directory using the terminal. To verify that the path is set correctly, type the following in your terminal:

$ arm-none-eabi-gcc --version

Ninja

Ninja is a small build system with a focus on speed. It differs from other build systems in two major respects: it is designed to have its input files generated by a higher-level build system, and it is designed to run builds as fast as possible.

Install Ninja using brew on macOS:

$ brew install ninja

Building the mesh stack and examples

The mesh library and example applications can be built using CMake mentioned above.

Before you continue, check Installing the toolchain for instructions on setting up the development environment for mesh.

Download the SDKs

The nRF5 SDK for Mesh now requires the nRF5 SDK to compile. You can download them using the following links:

By default, the nRF5 SDK is expected to be adjacent to the nRF5 SDK for Mesh. The directory structure should look like this:

.
├── nrf5_SDK_for_Mesh_v2.0.1_src/
└── nRF5_SDK_15.0.0_a53641a/

Adding support for nRF52832-MDK

To add support for nRF52832-MDK, you must create a support file with the name custom_board.h. This file must be located in a directory in the nRF5_SDK_15.0.0_a53641a/components/boards/ path.

The easiest way to create the custom_board.h file is to start with an existing platform definition file (for example pca10040.h) and adapt it to:

// custom_board.h

#ifndef CUSTOM_BOARD_H
#define CUSTOM_BOARD_H

#ifdef __cplusplus
extern "C" {
#endif

#include "nrf_gpio.h"

// LEDs definitions for nRF52832-MDK
#define LEDS_NUMBER    3

#define LED_START      22
#define LED_1          22
#define LED_2          23
#define LED_3          24
#define LED_4          25  // not on the board
#define LED_STOP       24

#define LEDS_ACTIVE_STATE 0

#define LEDS_INV_MASK  LEDS_MASK

#define LEDS_LIST { LED_1, LED_2, LED_3 }

#define BSP_LED_0      LED_1
#define BSP_LED_1      LED_2
#define BSP_LED_2      LED_3
#define BSP_LED_3      LED_4

#define BUTTONS_NUMBER 1
#define BUTTON_START   18
#define BUTTON_1       18
#define BUTTON_STOP    18
#define BUTTON_PULL    NRF_GPIO_PIN_PULLUP

#define BUTTONS_ACTIVE_STATE 0

#define BUTTONS_LIST { BUTTON_1}

#define BSP_BUTTON_0   BUTTON_1

#define RX_PIN_NUMBER  19
#define TX_PIN_NUMBER  20
#define CTS_PIN_NUMBER 7    // not available
#define RTS_PIN_NUMBER 5    // not available
#define HWFC           false

// Low frequency clock source to be used by the SoftDevice
#define NRF_CLOCK_LFCLKSRC      {.source        = NRF_CLOCK_LF_SRC_XTAL,            \
                                 .rc_ctiv       = 0,                                \
                                 .rc_temp_ctiv  = 0,                                \
                                 .xtal_accuracy = NRF_CLOCK_LF_XTAL_ACCURACY_20_PPM}

#ifdef __cplusplus
}
#endif

#endif // CUSTOM_BOARD_H

Create a CMake file with the name nrf52832_mdk.cmake. This file must be located in nrf5_SDK_for_Mesh_v2.0.1_src/CMake/board/.

# nrf52832_mdk.cmake

set(nrf52832_mdk_DEFINES
    -DBOARD_CUSTOM
    -DCONFIG_GPIO_AS_PINRESET)
set(nrf52832_mdk_INCLUDE_DIRS
    "${SDK_ROOT}/components/boards")

Specify the nRF52832-MDK board for the nrf52832_xxAA platform by adapting the nrf5_SDK_for_Mesh_v2.0.1_src/CMake/Board.cmake file to:

# 
...

elseif (PLATFORM STREQUAL "nrf52832_xxAA")
    set(BOARD "pca10040" CACHE STRING "Board to build examples for.")
    set_property(CACHE BOARD PROPERTY STRINGS "pca10040" "nrf52832_mdk")
...

Building with CMake

Now you can try to build the mesh stack. Good practice is to create a build folder in the root directory for the mesh stack repository, where all artifacts generated by the Ninja build system are stored, such as:

nrf5_SDK_for_Mesh_v2.0.1_src $ mkdir build
nrf5_SDK_for_Mesh_v2.0.1_src $ cd build

Before you can build with Ninja, you must generate the correct build files with CMake.

You can specify the required TOOLCHAIN, PLATFORM and BOARD name to CMAKE. The build system will ensure a valid SOFTDEVICE for the given platform.

build$ cmake -G Ninja -DTOOLCHAIN=gccarmemb -DPLATFORM=nrf52832_xxAA -DBOARD=nrf52832_mdk ..

After the Ninja build files are generated, running ninja will build all the targets (examples and libraries)

build $ ninja

Running the example

To run examples onto your nRF52832-MDK, first connect it to your computer with a USB cable. When your board is detected, you can program examples as described below.

Programming the SoftDevice

Note

All examples built by the CMake-generated build system do not include the SoftDevice as part of the generated HEX files. Therefore, the SoftDevice must already be present on the device before flashing the HEX file for the example mesh application.

Download the SoftDevice which you chose to build mesh stack with. If you do not know the SoftDevice version that was used to build the mesh stack, check the name of the example binary.

For example, if the example's binary name is light_switch_client_nrf52832_xxAA_s132_6.0.0.hex, the required SoftDevice binary is s132_nrf52_6.0.0_softdevice.hex. To program this example run:

$ pyocd-flashtool -d debug -t nrf52 -se s132_nrf52_6.0.0_softdevice.hex

Programming the application

To program the example binary mentioned above, run:

$ pyocd-flashtool -d debug -t nrf52 -se ./build/examples/light_switch/client/light_switch_client_nrf52832_xxAA_s132_6.0.0.hex

Creating a new build

The easiest way to make a new build target is to:

  1. Copy one of the example folders, e.g., examples/beaconing to examples/my_app.

  2. Add the folder to the examples/CMakeLists.txt with a add_subdirectory("my_app") command.

  3. Modify the target name in the first line of examples/my_app/CMakeLists.txt to set(target "my_app").

  4. Generating build files with

    nrf5_SDK_for_Mesh_v2.0.1_src $ mkdir build
    nrf5_SDK_for_Mesh_v2.0.1_src $ cd build
    build $ cmake -G Ninja -DTOOLCHAIN=gccarmemb -DPLATFORM=nrf52832_xxAA -DBOARD=nrf52832_mdk ..
    

  5. Build your new target with

    build $ ninja my_app
    

More examples

Over time, more example applications will be added to the repository. You can star or watch the nrf52832-mdk repository to stay up to date.

Create an Issue

Interested in contributing to this project? Want to report a bug? Feel free and click here:

Comments