GNRC netif implementation for NimBLE, enabling the integration of NimBLE into GNRC. More...

Detailed Description

GNRC netif implementation for NimBLE, enabling the integration of NimBLE into GNRC.

About

This NimBLE submodule provides a GNRC netif wrapper for integrating NimBLE with GNRC and other network stacks using netif (e.g. CCNlite).

Concept

According to the IPv6-over-BLE standards (RFC7668 and IPSP), this module exposes a (configurable) number of point-to-point BLE connections as a single network device to BLE. Unicast traffic is only send using the corresponding BLE connection. Multicast and Broadcast packets are duplicated and send via each open BLE connection.

Structure

The netif implementation is able to handle multiple connections simultaneously. The maximum number of concurrent connections is configured during compile time, using NimBLEs MYNEWT_VAL_BLE_MAX_CONNECTIONS option. Dependent on this value, the netif implementation takes care of allocation all the memory needed. The API of this submodule uses simply integer values to reference the used connection context (like file descriptors in linux).

Like any other GNRC network device, the NimBLE netif wrapper runs in its own thread. This thread is started and configured by the common netif code. All send and get/set operations are handled by this thread. For efficiency reasons, receiving of data is however handled completely in the NimBLE host thread, from where the received data is directly passed on to the corresponding GNRC thread.

Although the wrapper hooks into GNRC using the netif interface, it does need to implement parts of the netdev interface as well. This is done where needed.

Usage

This submodule is designed to work fully asynchronous, in the same way as the NimBLE interfaces are designed. All functions in this submodule will only trigger the intended action. Once this action is complete, the module will report the result asynchronously using the configured callback.

So before using this module, make sure to register a callback using the nimble_netif_eventcb() function.

After this, this module provides functions for managing BLE connections to other devices. Once these connections are established, this module takes care of mapping IP packets to the corresponding connections.

Modules
	Connection State Management for netif
	Helper module for managing the memory needed to store the BLE connection state for the netif wrapper.

Files
file	nimble_netif.h
	GNRC netif implementation for NimBLE.

Data Structures
struct	nimble_netif_accept_cfg_t
	Parameter set used to configure accepting connections (advertising) More...

struct	nimble_netif_connect_cfg_t
	Parameter set used to configure connection initiation. More...

Macros
#define	NIMBLE_NETIF_MAX_CONN (MYNEWT_VAL_BLE_MAX_CONNECTIONS)
	The maximum number of BLE connections that can be open concurrently.

#define	NIMBLE_NETIF_CID (BLE_L2CAP_CID_IPSP)
	Default L2CAP channel ID to use.

#define	NIMBLE_NETIF_MTU (1280U)
	Default MTU size supported by the NimBLE netif wrapper.

#define	NIMBLE_NETIF_CONN_ITVL_SPACING 0
	Set to > 0 to enforce different connection intervals for each of the nodes BLE connections.

Typedefs
typedef void(*	nimble_netif_eventcb_t) (int handle, nimble_netif_event_t event, const uint8_t *addr)
	Event callback signature used for asynchronous event signaling.

Enumerations
enum	{ NIMBLE_NETIF_FLAG_LEGACY = 0x01 , NIMBLE_NETIF_FLAG_HD_MODE = 0x02 }
	Flags for enabling legacy advertisement and high-duty cycle mode when accepting incoming connections. More...

enum	nimble_netif_event_t { NIMBLE_NETIF_ACCEPTING , NIMBLE_NETIF_ACCEPT_STOP , NIMBLE_NETIF_INIT_MASTER , NIMBLE_NETIF_INIT_SLAVE , NIMBLE_NETIF_CONNECTED_MASTER , NIMBLE_NETIF_CONNECTED_SLAVE , NIMBLE_NETIF_CLOSED_MASTER , NIMBLE_NETIF_CLOSED_SLAVE , NIMBLE_NETIF_ABORT_MASTER , NIMBLE_NETIF_ABORT_SLAVE , NIMBLE_NETIF_CONN_UPDATED }
	Event types triggered by the NimBLE netif module. More...

enum	{ NIMBLE_NETIF_L2CAP_CLIENT = 0x0001 , NIMBLE_NETIF_L2CAP_SERVER = 0x0002 , NIMBLE_NETIF_L2CAP_CONNECTED = 0x0003 , NIMBLE_NETIF_GAP_MASTER = 0x0010 , NIMBLE_NETIF_GAP_SLAVE = 0x0020 , NIMBLE_NETIF_GAP_CONNECTED = 0x0030 , NIMBLE_NETIF_ADV = 0x0100 , NIMBLE_NETIF_CONNECTING = 0x4000 , NIMBLE_NETIF_UNUSED = 0x8000 , NIMBLE_NETIF_ANY = 0xffff }
	Flags describing the state of a single connection context. More...

Functions
void	nimble_netif_init (void)
	Initialize the netif implementation, spawns the netif thread.

void	nimble_netif_eventcb (nimble_netif_eventcb_t cb)
	Register a global event callback, servicing all NimBLE connections.

int	nimble_netif_connect (const ble_addr_t addr, const nimble_netif_connect_cfg_t cfg)
	Open a BLE connection as BLE master.

int	nimble_netif_close (int handle)
	Close the connection with the given handle.

int	nimble_netif_accept (const uint8_t ad, size_t ad_len, const nimble_netif_accept_cfg_t cfg)
	Accept incoming connections by starting to advertise this node.

int	nimble_netif_accept_direct (const ble_addr_t addr, const nimble_netif_accept_cfg_t cfg)
	Wait for an incoming connection from a specific peer, sending directed advertisements.

int	nimble_netif_accept_stop (void)
	Stop accepting incoming connections (stop advertising) *.

int	nimble_netif_update (int handle, const struct ble_gap_upd_params *conn_params)
	Update the connection parameters for the given connection.

int	nimble_netif_used_chanmap (int handle, uint8_t map[5])
	Get the currently used channel map for the given connection as bitmap.

Macro Definition Documentation

◆ NIMBLE_NETIF_CID

#define NIMBLE_NETIF_CID (BLE_L2CAP_CID_IPSP)

Default L2CAP channel ID to use.

Definition at line 94 of file nimble_netif.h.

◆ NIMBLE_NETIF_CONN_ITVL_SPACING

#define NIMBLE_NETIF_CONN_ITVL_SPACING 0

Set to > 0 to enforce different connection intervals for each of the nodes BLE connections.

Enabling this option will enforce that every BLE connection a node maintains, independent of the nodes role, uses a different connection interval. The value of NIMBLE_NETIF_CONN_ITVL_SPACING specifies the minimum spacing between connection intervals as multiple of 1,25ms. E.g. a value of 2 will force each connection to use a connection interval that is at least 2.5ms different from all other used connection intervals.

If a node is the coordinator of a connection, it will generate a connection interval for each new connection based on a random value by adhering to the spacing constraint.

If a node is the subordinate of a new connection, it will check if the given connection interval is fulfilling the spacing constraint with respect to already existing connections of that node. If the connection interval of the new connection is not properly spaced, the node will drop the connection right away, giving the coordinator node the possibly to reconnect with a different connection interval.

Definition at line 170 of file nimble_netif.h.

◆ NIMBLE_NETIF_MAX_CONN

#define NIMBLE_NETIF_MAX_CONN (MYNEWT_VAL_BLE_MAX_CONNECTIONS)

The maximum number of BLE connections that can be open concurrently.

Note: This value must be <= MYNEWT_VAL_BLE_MAX_CONNECTIONS

Definition at line 87 of file nimble_netif.h.

◆ NIMBLE_NETIF_MTU

#define NIMBLE_NETIF_MTU (1280U)

Default MTU size supported by the NimBLE netif wrapper.

Definition at line 104 of file nimble_netif.h.

Typedef Documentation

◆ nimble_netif_eventcb_t

typedef void(* nimble_netif_eventcb_t) (int handle, nimble_netif_event_t event, const uint8_t *addr)

Event callback signature used for asynchronous event signaling.

Note: The event callback is always executed in NimBLE's host thread

Parameters

[in]	handle	handle to the connection that triggered the event
[in]	event	type of the event
[in]	addr	BLE address of the peer in the effected connection

Definition at line 215 of file nimble_netif.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Flags for enabling legacy advertisement and high-duty cycle mode when accepting incoming connections.

Enumerator
NIMBLE_NETIF_FLAG_LEGACY	use legacy advertising mode
NIMBLE_NETIF_FLAG_HD_MODE	use high duty cycle mode, only valid for direct advertising

Definition at line 111 of file nimble_netif.h.

◆ anonymous enum

anonymous enum

Flags describing the state of a single connection context.

Enumerator
NIMBLE_NETIF_L2CAP_CLIENT	L2CAP client.
NIMBLE_NETIF_L2CAP_SERVER	L2CAP server.
NIMBLE_NETIF_L2CAP_CONNECTED	L2CAP is connected.
NIMBLE_NETIF_GAP_MASTER	GAP master.
NIMBLE_NETIF_GAP_SLAVE	GAP slave.
NIMBLE_NETIF_GAP_CONNECTED	GAP is connected.
NIMBLE_NETIF_ADV	currently advertising
NIMBLE_NETIF_CONNECTING	connection in progress
NIMBLE_NETIF_UNUSED	context unused
NIMBLE_NETIF_ANY	match any state

Definition at line 193 of file nimble_netif.h.

◆ nimble_netif_event_t

enum nimble_netif_event_t

Event types triggered by the NimBLE netif module.

Enumerator
NIMBLE_NETIF_ACCEPTING	accepting incoming connections
NIMBLE_NETIF_ACCEPT_STOP	stop accepting incoming connections
NIMBLE_NETIF_INIT_MASTER	conn. procedure started (as master)
NIMBLE_NETIF_INIT_SLAVE	conn. procedure started (as slave)
NIMBLE_NETIF_CONNECTED_MASTER	connection established as master
NIMBLE_NETIF_CONNECTED_SLAVE	connection established as slave
NIMBLE_NETIF_CLOSED_MASTER	connection closed (we were master)
NIMBLE_NETIF_CLOSED_SLAVE	connection closed (we were slave)
NIMBLE_NETIF_ABORT_MASTER	connection est. abort (as master)
NIMBLE_NETIF_ABORT_SLAVE	connection est. abort (as slave)
NIMBLE_NETIF_CONN_UPDATED	connection parameter update done

Definition at line 176 of file nimble_netif.h.

Function Documentation

◆ nimble_netif_accept()

int nimble_netif_accept	(	const uint8_t *	ad,
		size_t	ad_len,
		const nimble_netif_accept_cfg_t *	cfg
	)

Accept incoming connections by starting to advertise this node.

Parameters

[in]	ad	advertising data (in BLE AD format)
[in]	ad_len	length of `ad` in bytes
[in]	cfg	advertising parameters to use

Returns: 0 on success; -EALREADY if already advertising; -ENOMEM on insufficient connection memory; -EINVAL on invalid configuration parameters; -ECANCELED on other errors

◆ nimble_netif_accept_direct()

int nimble_netif_accept_direct	(	const ble_addr_t *	addr,
		const nimble_netif_accept_cfg_t *	cfg
	)

Wait for an incoming connection from a specific peer, sending directed advertisements.

Parameters

[in]	addr	BLE address of the target peer
[in]	cfg	advertising parameters to use

Returns: 0 on success; -EALREADY if already advertising; -ENOMEM on insufficient connection memory; -EINVAL on invalid configuration parameters; -ECANCELED on other errors

◆ nimble_netif_accept_stop()

int nimble_netif_accept_stop ( void )

Stop accepting incoming connections (stop advertising) *.

Returns: 0 on success; -EALREADY if not currently advertising; -EIO on other NimBLE errors

◆ nimble_netif_close()

int nimble_netif_close ( int handle )

Close the connection with the given handle.

Parameters

[in] handle handle for the connection to be closed

Returns: 0 on success; -EINVAL if the handle is invalid; -ENOTCONN if context for given handle is not connected; -EIO on all other NimBLE errors

◆ nimble_netif_connect()

int nimble_netif_connect	(	const ble_addr_t *	addr,
		const nimble_netif_connect_cfg_t *	cfg
	)

Open a BLE connection as BLE master.

Parameters

[in]	addr	address of the advertising BLE slave, in the NimBLE addr format (little endian)
[in]	cfg	connection parameters

Returns: the used connection handle on success; -EBUSY if already connected to the given address or if a connection setup procedure is in progress; -ENOMEM if no connection context memory is available; -ECANCELED if unable to find valid connection interval; -EINVAL if unable to apply given PHY mode; -EIO on all other NimBLE errors

◆ nimble_netif_eventcb()

void nimble_netif_eventcb ( nimble_netif_eventcb_t cb )

Register a global event callback, servicing all NimBLE connections.

Note: The event callback is always executed in NimBLE's host thread

Parameters

[in] cb event callback to register, may be NULL

◆ nimble_netif_init()

void nimble_netif_init ( void )

Initialize the netif implementation, spawns the netif thread.

This function is meant to be called once during system initialization, i.e. auto-init.

◆ nimble_netif_update()

int nimble_netif_update	(	int	handle,
		const struct ble_gap_upd_params *	conn_params
	)

Update the connection parameters for the given connection.

Parameters

[in]	handle	connection handle
[in]	conn_params	new connection parameters to apply

Returns: 0 on success; -ENOTCONN if handle does not point to a connection; -ECANCELED if applying the given parameters failed

◆ nimble_netif_used_chanmap()

int nimble_netif_used_chanmap	(	int	handle,
		uint8_t	map[5]
	)

Get the currently used channel map for the given connection as bitmap.

Parameters

[in]	handle	connection handle
[out]	map	used channel map, map[0] denotes channels 0 to 7, map[1] chan 8-15, ..., map[5] channels 33 to 36. must be able to hold 5 bytes.

Returns: 0 on success; -ENOTCONN if handle dos not point to a connection; -ECANCELED if reading the channel map failed otherwise

Detailed Description

About

Concept

Structure

Usage

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NIMBLE_NETIF_CID

◆ NIMBLE_NETIF_CONN_ITVL_SPACING

◆ NIMBLE_NETIF_MAX_CONN

◆ NIMBLE_NETIF_MTU

Typedef Documentation

◆ nimble_netif_eventcb_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ nimble_netif_event_t

Function Documentation

◆ nimble_netif_accept()

◆ nimble_netif_accept_direct()

◆ nimble_netif_accept_stop()

◆ nimble_netif_close()

◆ nimble_netif_connect()

◆ nimble_netif_eventcb()

◆ nimble_netif_init()

◆ nimble_netif_update()

◆ nimble_netif_used_chanmap()