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.

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

#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.

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. More...

Enumerations
enum	{ NIMBLE_NETIF_OK = 0, NIMBLE_NETIF_NOTCONN = -1, NIMBLE_NETIF_DEVERR = -2, NIMBLE_NETIF_BUSY = -3, NIMBLE_NETIF_NOMEM = -4, NIMBLE_NETIF_NOTADV = -5, NIMBLE_NETIF_NOTFOUND = -6 }
	Return codes used by the NimBLE netif module. 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. More...

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

int	nimble_netif_connect (const ble_addr_t addr, const struct ble_gap_conn_params conn_params, uint32_t timeout)
	Open a BLE connection as BLE master. More...

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

int	nimble_netif_accept (const uint8_t ad, size_t ad_len, const struct ble_gap_adv_params adv_params)
	Accept incoming connections by starting to advertise this node. More...

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

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

Macro Definition Documentation

◆ 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 85 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 160 of file nimble_netif.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return codes used by the NimBLE netif module.

Enumerator
NIMBLE_NETIF_OK	everything went fine
NIMBLE_NETIF_NOTCONN	not connected
NIMBLE_NETIF_DEVERR	internal BLE stack error
NIMBLE_NETIF_BUSY	network device is busy
NIMBLE_NETIF_NOMEM	insufficient memory
NIMBLE_NETIF_NOTADV	not advertising
NIMBLE_NETIF_NOTFOUND	no fitting entry found

Definition at line 108 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 138 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 121 of file nimble_netif.h.

Function Documentation

◆ nimble_netif_accept()

int nimble_netif_accept	(	const uint8_t *	ad,
		size_t	ad_len,
		const struct ble_gap_adv_params *	adv_params
	)

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]	adv_params	advertising (timing) parameters to use

Returns: NIMBLE_NETIF_OK on success; NIMBLE_NETIF_BUSY if already advertising; NIMBLE_NETIF_NOMEM on insufficient connection memory

◆ nimble_netif_accept_stop()

int nimble_netif_accept_stop ( void )

Stop accepting incoming connections (stop advertising) *.

Returns: NIMBLE_NETIF_OK on success; NIMBLE_NETIF_NOTADV if not currently advertising

◆ 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: NIMBLE_NETIF_OK on success; NIMBLE_NETIF_NOTFOUND if the handle is invalid; NIMBLE_NETIF_NOTCONN if context for given handle is not connected

◆ nimble_netif_connect()

int nimble_netif_connect	(	const ble_addr_t *	addr,
		const struct ble_gap_conn_params *	conn_params,
		uint32_t	timeout
	)

Open a BLE connection as BLE master.

Parameters

[in]	addr	address of the advertising BLE slave, in the NimBLE addr format (little endian)
[in]	conn_params	connection (timing) parameters
[in]	timeout	connect timeout [in ms]

Returns: the used connection handle on success; NIMBLE_NETIF_BUSY if already connected to the given address or if a connection setup procedure is in progress; NIMBLE_NETIF_NOMEM if no connection context memory is available

◆ 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: NIMBLE_NETIF_OK on success; NIMBLE_NETIF_NOTCONN if handle does not point to a connection; NIMBLE_NETIF_DEVERR if applying the given parameters failed

Detailed Description

About

Concept

Structure

Usage

Modules

Files

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NIMBLE_NETIF_MAX_CONN

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_stop()

◆ nimble_netif_close()

◆ nimble_netif_connect()

◆ nimble_netif_eventcb()

◆ nimble_netif_init()

◆ nimble_netif_update()