RPL-over-BLE for NimBLE

RPL-over-BLE for Nimble implementation. More...

Detailed Description

RPL-over-BLE for Nimble implementation.


This module implements a BLE connection manager the manages BLE connections for (multi-hop) IP over BLE networks based on meta data provided by RPL.


In their initial state, after power up or reboot, nodes start to scan for BLE advertisements containing a specific advertising data (AD) field which holds information about RPL DODAGs. For a configured amount of time, the node ranks all senders of the received advertising packets based on a given metric. After this time, the node selects the best fitting parent based on this ranking and tries to connect to that peer.

After a node has successfully opened a connection to its parent node, the node starts to advertise its own RPL context data to accept connections from potential child nodes.

This approach leads to a BLE network topology that is equal to the IP routing topology created by RPL on top.

Advertising data structure

To include RPL context information into (legacy) BLE advertisements, it must be encoded into the BLE advertising data format. This implementation uses a custom sub-format that is included into the 16-bit UUID Service Data (type: 0x16) field (Supplement to Bluetooth Core Specification CSSv8, 1.11). The 16-bit UUID in this field is set to the IPSS service ID (0x1820).

The following sub-format is used to encode the RPL context data:

byte 1: instance ID (1b)
byte 2-17: DODAG ID (16b)
byte 18: DODAG version (1b)
byte 19: RPL role (1b)
byte 20-21: rank (2b)
byte 22: number of free BLE connection slots (1b)
void free(void *ptr)
This is a no-op.

Ranking of potential parents

The currently implemented ranking metric is very simple: the potential parent node with the smallest rank is chosen. Additionally, nodes advertise the number of free BLE connection slots. In case where multiple nodes advertise the same RPL rank, the one with the largest number of open BLE connection slots is selected. The idea behind this is to balance the number of BLE connections per node, and with that also to balance the RPL DODAG.


To use this module, simply include nimble_rpble into your build. If nothing is explicitly configured, the module will use the default configuration as specified in pkg/nimble/rpble/include/nimble_rpble_params.h.

Once a node is configured as RPL root (e.g. using the rpl root .. shell command), it will automatically start to advertise itself. Non-RPL-root nodes will automatically scan for potential parent nodes and join the network as soon as they find fitting neighbors.

Implementation status

In its current state, the implementation only works for environments where a single RPL network with a single DODAG are present. The DODAG ID, instance ID, and DODAG version are currently pretty much ignored when scanning for potential parents.


file  nimble_rpble.h
 Interface for the nimble_rpble module.
file  nimble_rpble_params.h
 Default configuration for the nimble_netif_rpble module.

Data Structures

struct  nimble_rpble_cfg_t
 rpble configuration parameters More...
struct  nimble_rpble_ctx_t
 RPL DODAG information. More...


int nimble_rpble_init (const nimble_rpble_cfg_t *cfg)
 Initialize the nimble_rpble module with the given parameters. More...
int nimble_rpble_param_update (const nimble_rpble_cfg_t *cfg)
 Update the used timing parameters. More...
int nimble_rpble_eventcb (nimble_netif_eventcb_t cb)
 Register a callback that is called on BLE events. More...
int nimble_rpble_update (const nimble_rpble_ctx_t *ctx)
 Update the current RPL context. More...

Function Documentation

◆ nimble_rpble_eventcb()

int nimble_rpble_eventcb ( nimble_netif_eventcb_t  cb)

Register a callback that is called on BLE events.

The registered callback function is a simple pass-through of nimble_netif events. The callback is executed in the context of NimBLE's host thread.

[in]cbevent callback to register, set to NULL to remove

◆ nimble_rpble_init()

int nimble_rpble_init ( const nimble_rpble_cfg_t cfg)

Initialize the nimble_rpble module with the given parameters.

This function must be called only once, typically during system initialization
[in]cfgconfiguration parameters
0 on success

◆ nimble_rpble_param_update()

int nimble_rpble_param_update ( const nimble_rpble_cfg_t cfg)

Update the used timing parameters.

[in]cfgconfiguration parameters
0 on success

◆ nimble_rpble_update()

int nimble_rpble_update ( const nimble_rpble_ctx_t ctx)

Update the current RPL context.

This function is meant to be called only by the RPL implementation
[in]ctxcurrent DODAG state
0 on success
-EALREADY if the given context did not change