Autoconn

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

• The filter function could be more powerful. It is probably a good idea to extend this module to allow for passing custom filter functions using a function pointer
• Currently this module does not allow to use NimBLE as IP-over-BLE node and as a GATT server concurrently. This could be enabled by adding an additional callback function which exposes some/all GAP events to a user application (i.e. BLE_GAP_EVENT_SUBSCRIBE, BLE_GAP_EVENT_NOTIFY_RX, BLE_GAP_EVENT_NOTIFY_TX).
• It might make sense to get rid of the periodic switching between scanning and advertising in favor of doing both in parallel. This would simplify the code (and configuration) quite a bit. But in the past, there were severe stability issues with NimBLE doing this, so it needs to be evaluated in the future if this is a feasible option.

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]

cb

event 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]	params	timing parameters to use
[in]	ad	advertising data, if NULL it is generated
[in]	adlen	length 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]	params	new parameters to apply
[in]	ad	advertising data, if NULL it is generated
[in]	adlen	length of ad in bytes

Returns

NIMBLE_AUTOCONN_OK if everything went fine

NIMBLE_AUTOCONN_INVALID if given parameters can not be applied