Simple connection manager that automatically opens BLE connections to any node that fits some given filter criteria. More...

Detailed Description

Simple connection manager that automatically opens BLE connections to any node that fits some given filter criteria.

Warning
This feature is experimental!

WARNING

This module is highly experimental! Expect bugs, instabilities and sudden API changes :-)

About

This NimBLE submodule implements a connection manager for BLE. It takes care of scanning, advertising, and opening connections to neighboring nodes. For this autoconn periodically switches between advertising and scanning mode, hence from accepting incoming connection requests to scanning actively for new neighbors.

Concept

The IETF and BT SIG standards describing IP-over-BLE only describe how to transfer IP data over L2CAP connection oriented channels. But they do not say anything about when BLE connections should be established between two BLE nodes in the first place. While this can be done manually (e.g. via RIOTs ble shell command), this is certainly no option in massive M2M deployments.

To enable nodes to automatically connect to their neighbors, autoconn implements a naive strategy which makes nodes to connect to any neighbor they see, as long as the neighbor signals a predefined set of capabilities.

In particular, neighbors are simply filtered by looking at the 16-bit service UUIDs included in the Incomplete List of 16-bit Service UUIDs field in the advertising data that is received from neighbors.

The logical network topology (as seen by IP) is formed by the established BLE link layer connections. It is important to node, that the autoconn module will form a random topology on the link layer, as no further context information is used for the connection decisions. This can potentially lead to fragmented, non-connected sub-networks in larger deployments!

State Machine

Autoconn implements a state machine, that switches a nodes role periodically between scanning and advertising. To make sure, that nodes always have a chance to see each other, especially when booted at the same point in time, the intervals of each role consist of a constant amount of time plus a random interval. This way two nodes will eventually see each other and be able to establish a connection.

All timing values for the interval duration and the maximum amount of the random offset are configurable.

Usage

In the current state, the filtering of neighbors is hard coded into the autoconn module. Two options are implemented:

  1. connect to any neighbor capable of IP-over-BLE -> BLE_GATT_SVC_IPSS UUID included in the BLE_GAP_AD_UUID16_INCOMP field of the received advertising data
  2. connect to any neighbor capable of NDN-over-BLE -> BLE_GATT_SVC_NDNSS UUID included in the BLE_GAP_AD_UUID16_INCOMP field of the received advertising data

The active filter used in autoconn is selected using one of two submodules during build time:

  1. USEMDOULE += nimble_autoconn_ipsp
  2. ‘USEMODULE += nibmle_autoconn_ndnsp’
Note
The NDN support service (NDNSP) is defined by us and it is not at all standardized nor sanctioned by the BT SIG. For experimental use only...

Implementation Status

Files

file  nimble_autoconn.h
 Simple automated connection manager for NimBLE netif.
 
file  nimble_autoconn_params.h
 Default configuration for the nimble_autoconn module.
 

Data Structures

struct  nimble_autoconn_params_t
 Set of configuration parameters needed to run autoconn. More...
 

Enumerations

enum  { NIMBLE_AUTOCONN_OK = 0, NIMBLE_AUTOCONN_PARAMERR = -1, NIMBLE_AUTOCONN_ADERR = -2 }
 Return codes used by the autoconn module. More...
 

Functions

int nimble_autoconn_init (const nimble_autoconn_params_t *params, const uint8_t *ad, size_t adlen)
 Initialize and enable the autoconn module. More...
 
void nimble_autoconn_eventcb (nimble_netif_eventcb_t cb)
 Register a callback that is called on netif events. More...
 
int nimble_autoconn_update (const nimble_autoconn_params_t *params, const uint8_t *ad, size_t adlen)
 Update the used parameters (timing and node ID) More...
 
void nimble_autoconn_enable (void)
 Enable automated creation of new BLE connections.
 
void nimble_autoconn_disable (void)
 Disable the automated connection management. More...
 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return codes used by the autoconn module.

Enumerator
NIMBLE_AUTOCONN_OK 

like a walk in the park

NIMBLE_AUTOCONN_PARAMERR 

invalid parameters given

NIMBLE_AUTOCONN_ADERR 

error generating advertising data

Definition at line 123 of file nimble_autoconn.h.

Function Documentation

◆ nimble_autoconn_disable()

void nimble_autoconn_disable ( void  )

Disable the automated connection management.

Note
All existing connections are kept, only the scanning and advertising is canceled

◆ nimble_autoconn_eventcb()

void nimble_autoconn_eventcb ( nimble_netif_eventcb_t  cb)

Register a callback that is called on netif 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.

Parameters
[in]cbevent callback to register, may be NULL

◆ nimble_autoconn_init()

int nimble_autoconn_init ( const nimble_autoconn_params_t params,
const uint8_t *  ad,
size_t  adlen 
)

Initialize and enable the autoconn module.

Warning
This function must only be called once. Typically this is during system initialization or at the beginning of the user application. Use nimble_autoconn_update() to update parameters at runtime.
Autoconn expects nimble_netif to be initialized. So make sure nimble_netif_init() was called before calling nimble_autoconn_init().
Parameters
[in]paramstiming parameters to use
[in]adadvertising data, if NULL it is generated
[in]adlenlength of ad in bytes

◆ nimble_autoconn_update()

int nimble_autoconn_update ( const nimble_autoconn_params_t params,
const uint8_t *  ad,
size_t  adlen 
)

Update the used parameters (timing and node ID)

Parameters
[in]paramsnew parameters to apply
[in]adadvertising data, if NULL it is generated
[in]adlenlength of ad in bytes
Returns
NIMBLE_AUTOCONN_OK if everything went fine
NIMBLE_AUTOCONN_INVALID if given parameters can not be applied