nRF OpenMesh (formerly nRF51-ble-broadcast-mesh)

Bluetooth Low Energy based rebroadcasting mesh implementation on the nRF5x called nRF OpenMesh. Works with SoftDevice S110 v8.x (for nRF51) and S132 v3.0.0 (for nRF52) with Timeslot API, and the nRF51 SDK8.1 and the nRF5x SDK 12.0.0 Offers an API for implementing your own mesh enabled application, operating concurrently with regular BLE applications.

Usage

In addition to two provided examples, there is a template project under nRF51/examples/. This may be used as a basis for your own applications, or you could choose to do it yourself from scratch. In theory, the framework should be compatible with most SoftDevice based projects, but some restrictions to hardware and software modules apply, see Resource allocation for details. The framework adds a Mesh GATT service to the SoftDevice GATT server which contain all mesh-global states. This service may be accessed by external nodes, just as any other GATT service, through a connection established via the SoftDevice. See section GATT service for details about structure and access.

Serial interface

The framework also has support for external control via SPI or UART. The serial interface is based on the nRF8001 SPI interface, with different opcodes. An application controller framework using SPI is available under application_controller, with an Arduino example to get you started. Note that the application controller requires the ble-sdk-arduino framework. This allows you to operate an Arduino along with an nRF51 dev kit in the mesh, making it easier to create mesh applications. Each nRF51 example project has a separate target (named "nRF51822 xxAA serial") that incorporates the serial interface with the rest of the project.

Getting started

The framework requires nRF51 SDK 8.1 and nRF5 SDK 12.0.0, and can be built with both Keil uVision and GCC-arm-none-eabi.

The example projects utilizes the non-pack version of the SDK, available at Nordic Semiconductor’s developer portal. Clone this repo into <SDK8-folder>/examples/<Project-folder> for nRF51 and into <SDK12-folder>/examples/<Project-folder> for nRF52

This will ensure that all references to the SDK are correctly placed, so that you don’t have to change all references to the SDK in the project files. If you still want to clone the repo into a different folder than suggested, you need to change the location of all the files under the Lib group in Keil uVision, in addition to the include paths under the menu Target options → C/C++ → Include Paths (or in the project-local makefiles for GCC).

Integrating with existing applications

The framework is built to be compatible with most existing SDK example projects, and as of v0.6.9, it is also compatible with the SDK module APP_TIMER right out of the box. In order to be compatible with the APP_TIMER module, the framework makes use of the Quadrature Decoder hardware interrupt handler for asynchronous processing. Applications which already use this hardware module must be altered to use a different interrupt for mesh processing. All async-behavior is contained in the event_handler.c file.

We’ve written a short guide to include it in existing projects with as few changes to existing code as possible. The guide uses the ble_app_proximity example from the SDK as reference, and shows a step by step approach to overcoming typical problems with integration:

Guide to integrating rbc_mesh into existing projects

Basic concepts

A rebroadcasting mesh network works by flooding all messages to all nodes in the network through broadcasts. Each time a device receives a broadcast message from some other device in the mesh, it repeats the message, or rebroadcasts it, letting its neighbors hear the new message. The neighbors rebroadcast the message to their neighbors, and the process is repeated until all devices in the mesh have received the message. This lets wireless devices talk to each other without being within direct radio range, as devices between them help relaying the messages.

The Rebroadcasting Mesh framework (hereby referred to as "the framework" or rbc_mesh) provides a connection-less, rebroadcasting infrastructure for synchronizing states across a set of BLE enabled nodes. All nodes receive all messages that are transmitted within their range, and any node may update the mesh-global states. There is no hierarchy, and no directed data links.

The framework resides on top of the nRF51 SoftDevice, utilizing the Timeslot API to allocate radio time. The framework will attempt to allocate as much time as possible, in order to listen for other nodes' messages.

All nodes in the mesh share a set of indexed data slots. The data contained at each index is propagated through the mesh with version numbers, with the objective of synchronizing the same version of the data across all nodes in the mesh. Each time a node overwrites a value, it increments the version number, and all nodes that receive a broadcast message with a version number that is higher than the one in its database, will adapt this new version of the value.

The value propagation is controlled by an implementation of the IETF RFC6206 "Trickle", a flood control algorithm for lossy, low power networks. The Trickle algorithm dynamically decides intervals at which a value will be broadcast by a node, based on how many consistent messages the node picks up, and when the last update to the state it manages was. The Trickle algorithm dynamically adapts to node density and value update frequency.

The framework provides each handle-value pair with one Trickle-instance (an isolated version of the algorithm), and utilizes a Least-recently-used cache- system to store the values. When a value falls out of the "data cache", the device stops retransmitting it, and when the value falls out of the larger "handle cache", the device also forgets which version of the value it saw last.

The mesh can be interfaced by regular BLE devices through a GATT characteristic in the Softdevice. The application is responsible for advertising and managing the external connection, and the "BLE Gateway example" displays a way to achieve such behavior.

Architecture details

Using the framework

A brief introduction to the Trickle mechanic, and overview of the API and the internal structure of the system.

How the mesh works

Detailed description of Trickle, the usage of the Softdevice (including GATT characteristic syntax) and the on-air packets.

About

The "nRF OpenMesh" was created in collaboration with The Norwegian University of Science and Technology (NTNU), as part of a master’s thesis pre-study. The project is not part of the official Nordic Semiconductor SDK. Developers are welcome to contribute and provide feedback.