Module for automated bluetooth advertising. More...

Detailed Description

Module for automated bluetooth advertising.

Advertising is restarted on disconnect events automatically. Defaults to the following characteristics:

General discoverable mode (BLE_GAP_DISC_MODE_GEN)
Undirected connectable mode (BLE_GAP_CONN_MODE_UND)
No expiration (BLE_HS_FOREVER)
No name

Files
file	nimble_autoadv.h

file	nimble_autoadv_params.h
	Default configuration for the nimble_autoadv module.

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

Macros
#define	CONFIG_NIMBLE_AUTOADV_DEVICE_NAME "NimBLE on RIOT"
	Name of the device for the advertising procedure.

#define	CONFIG_NIMBLE_AUTOADV_START_MANUALLY 0
	If an application is calling functions from nimble, e.g.

#define	CONFIG_NIMBLE_AUTOADV_FLAG_FIELD 1
	Include the advetisement flag field.

Functions
void	nimble_autoadv_init (const nimble_autoadv_cfg_t *cfg)
	Initialize autoadv module.

void	nimble_autoadv_cfg_update (nimble_autoadv_cfg_t *cfg)
	Set struct for additional arguments specifying the particulars of the advertising procedure.

void	nimble_autoadv_get_cfg (nimble_autoadv_cfg_t *cfg)
	Gets struct for additional arguments specifying the particulars of the advertising procedure.

int	nimble_autoadv_add_field (uint8_t type, const void *data, size_t data_len)
	Add a new field to the given advertising data.

void	nimble_autoadv_set_gap_cb (ble_gap_event_fn cb, void cb_arg)
	Set the callback for gap events.

void	nimble_autoadv_start (ble_addr_t *addr)
	Start the automated advertising procedure.

void	nimble_autoadv_stop (void)
	Stop the automated advertising procedure.

void	nimble_autoadv_reset (nimble_autoadv_cfg_t *cfg)
	Reset all data regarding the advertising process.

int	nimble_autoadv_get_adv_instance (void)
	Return the advertisement instance.

NimBLE Auto Advertisement Configuration Flags
Flags for enabling legacy advertisement and high-duty cycle mode when accepting incoming connections
#define	NIMBLE_AUTOADV_FLAG_LEGACY (1 << 0)
	use legacy advertising mode

#define	NIMBLE_AUTOADV_FLAG_HD_MODE (1 << 1)
	use high duty cycle mode, only ignored if no direct advertising

#define	NIMBLE_AUTOADV_FLAG_CONNECTABLE (1 << 2)
	if connectable advertisement

#define	NIMBLE_AUTOADV_FLAG_SCANNABLE (1 << 3)
	if scannable advertisement

#define	NIMBLE_AUTOADV_FLAG_ANONYMOUS (1 << 4)
	if anonymous advertisement ignore if no 'nimble_adv_ex'

#define	NIMBLE_AUTOADV_FLAG_SCAN_REQ_NOTIF (1 << 5)
	enable scan-request notification ignore if no 'nimble_adv_ex'

Macro Definition Documentation

◆ CONFIG_NIMBLE_AUTOADV_DEVICE_NAME

#define CONFIG_NIMBLE_AUTOADV_DEVICE_NAME "NimBLE on RIOT"

Name of the device for the advertising procedure.

If this is not defined, it will be defined as NULL, resulting in not configuring a name at all.

Definition at line 43 of file nimble_autoadv.h.

◆ CONFIG_NIMBLE_AUTOADV_FLAG_FIELD

#define CONFIG_NIMBLE_AUTOADV_FLAG_FIELD 1

Include the advetisement flag field.

If this is not defined, it will be defined as 1, resulting in including the field. The Flags data type shall be included when any of the Flag bits are non-zero and the advertising packet is connectable, otherwise the Flags data type may be omitted.

Definition at line 67 of file nimble_autoadv.h.

◆ CONFIG_NIMBLE_AUTOADV_START_MANUALLY

#define CONFIG_NIMBLE_AUTOADV_START_MANUALLY 0

If an application is calling functions from nimble, e.g.

ble_svc_gap_device_name_set(), CONFIG_NIMBLE_AUTOADV_START_MANUALLY should be set to 1 and then the application should call nimble_autoadv_start(NULL) after all of its nimble calls to prevent errors like BLE_HS_EBUSY.

Defined as 0 by default.

Definition at line 56 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_ANONYMOUS

#define NIMBLE_AUTOADV_FLAG_ANONYMOUS (1 << 4)

if anonymous advertisement ignore if no 'nimble_adv_ex'

Definition at line 84 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_CONNECTABLE

#define NIMBLE_AUTOADV_FLAG_CONNECTABLE (1 << 2)

if connectable advertisement

Definition at line 81 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_HD_MODE

#define NIMBLE_AUTOADV_FLAG_HD_MODE (1 << 1)

use high duty cycle mode, only ignored if no direct advertising

Definition at line 80 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_LEGACY

#define NIMBLE_AUTOADV_FLAG_LEGACY (1 << 0)

use legacy advertising mode

Definition at line 78 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_SCAN_REQ_NOTIF

#define NIMBLE_AUTOADV_FLAG_SCAN_REQ_NOTIF (1 << 5)

enable scan-request notification ignore if no 'nimble_adv_ex'

Definition at line 86 of file nimble_autoadv.h.

◆ NIMBLE_AUTOADV_FLAG_SCANNABLE

#define NIMBLE_AUTOADV_FLAG_SCANNABLE (1 << 3)

if scannable advertisement

Definition at line 82 of file nimble_autoadv.h.

Function Documentation

◆ nimble_autoadv_add_field()

int nimble_autoadv_add_field	(	uint8_t	type,
		const void *	data,
		size_t	data_len
	)

Add a new field to the given advertising data.

     If there is an active advertising process, it will be restarted.

Parameters

[in]	type	field type to add
[in]	data	payload for the field
[in]	data_len	length of the payload in bytes

Returns: BLUETIL_AD_OK if the new field was added; BLUETIL_AD_NOMEM if there is not enough space to write add field

◆ nimble_autoadv_cfg_update()

void nimble_autoadv_cfg_update ( nimble_autoadv_cfg_t * cfg )

Set struct for additional arguments specifying the particulars of the advertising procedure.

Uses memcpy internally.

If there is an active advertising process, it will be restarted.

Parameters

[in] cfg struct with customized additional arguments

◆ nimble_autoadv_get_adv_instance()

int nimble_autoadv_get_adv_instance ( void )

Return the advertisement instance.

Note: The advertisement instance is set automatically by the build-system

Returns: The advertisement instance

◆ nimble_autoadv_get_cfg()

void nimble_autoadv_get_cfg ( nimble_autoadv_cfg_t * cfg )

Gets struct for additional arguments specifying the particulars of the advertising procedure.

Uses memcpy internally.

Parameters

[in] cfg struct to copy current configuration into

◆ nimble_autoadv_init()

void nimble_autoadv_init ( const nimble_autoadv_cfg_t * cfg )

Initialize autoadv module.

Parameters

[in] cfg struct to copy current configuration into

◆ nimble_autoadv_reset()

void nimble_autoadv_reset ( nimble_autoadv_cfg_t * cfg )

Reset all data regarding the advertising process.

Parameters

[in] cfg struct to copy current configuration into

◆ nimble_autoadv_set_gap_cb()

void nimble_autoadv_set_gap_cb	(	ble_gap_event_fn *	cb,
		void *	cb_arg
	)

Set the callback for gap events.

Callback is used for the logic when to start the advertising procedure.

If there is an active advertising process, it will be restarted.

Parameters

[in]	cb	The callback to associate with this advertising procedure. If advertising ends, the event is reported through this callback. If advertising results in a connection, the connection inherits this callback as its event-reporting mechanism.
[in]	cb_arg	The optional argument to pass to the callback function.

◆ nimble_autoadv_start()

void nimble_autoadv_start ( ble_addr_t * addr )

Start the automated advertising procedure.

     Needs to be called manually when CONFIG_NIMBLE_AUTOADV_START_MANUALLY was
     set to true and after every call of nimble_autoadv_stop() to start
     advertising again.

Parameters

[in] addr addr for directed advertisement, can be NULL

◆ nimble_autoadv_stop()

void nimble_autoadv_stop ( void )

Stop the automated advertising procedure.

After calling this, you have to call nimble_autoadv_start(NULL) manually to restart the process.

Detailed Description

Files

Data Structures

Macros

Functions

NimBLE Auto Advertisement Configuration Flags

Macro Definition Documentation

◆ CONFIG_NIMBLE_AUTOADV_DEVICE_NAME

◆ CONFIG_NIMBLE_AUTOADV_FLAG_FIELD

◆ CONFIG_NIMBLE_AUTOADV_START_MANUALLY

◆ NIMBLE_AUTOADV_FLAG_ANONYMOUS

◆ NIMBLE_AUTOADV_FLAG_CONNECTABLE

◆ NIMBLE_AUTOADV_FLAG_HD_MODE

◆ NIMBLE_AUTOADV_FLAG_LEGACY

◆ NIMBLE_AUTOADV_FLAG_SCAN_REQ_NOTIF

◆ NIMBLE_AUTOADV_FLAG_SCANNABLE

Function Documentation

◆ nimble_autoadv_add_field()

◆ nimble_autoadv_cfg_update()

◆ nimble_autoadv_get_adv_instance()

◆ nimble_autoadv_get_cfg()

◆ nimble_autoadv_init()

◆ nimble_autoadv_reset()

◆ nimble_autoadv_set_gap_cb()

◆ nimble_autoadv_start()

◆ nimble_autoadv_stop()