nRF5 SDK v17.0.2
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Advertising Module

Module for handling connectable BLE advertising. More...

Modules

 Advertising module configuration
 

Data Structures

struct  ble_adv_modes_config_t
 Options for the different advertisement modes. More...
 
struct  ble_advertising_t
 
struct  ble_adv_mode_config_t
 
struct  ble_advertising_init_t
 Initialization parameters for the Advertising Module. More...
 

Macros

#define BLE_ADVERTISING_DEF(_name)
 Macro for defining a ble_advertising instance. More...
 

Typedefs

typedef void(* ble_adv_evt_handler_t )(ble_adv_evt_t const adv_evt)
 BLE advertising event handler type.
 
typedef void(* ble_adv_error_handler_t )(uint32_t nrf_error)
 BLE advertising error handler type.
 

Enumerations

enum  ble_adv_mode_t {
  BLE_ADV_MODE_IDLE,
  BLE_ADV_MODE_DIRECTED_HIGH_DUTY,
  BLE_ADV_MODE_DIRECTED,
  BLE_ADV_MODE_FAST,
  BLE_ADV_MODE_SLOW
}
 Advertising modes. More...
 
enum  ble_adv_evt_t {
  BLE_ADV_EVT_IDLE,
  BLE_ADV_EVT_DIRECTED_HIGH_DUTY,
  BLE_ADV_EVT_DIRECTED,
  BLE_ADV_EVT_FAST,
  BLE_ADV_EVT_SLOW,
  BLE_ADV_EVT_FAST_WHITELIST,
  BLE_ADV_EVT_SLOW_WHITELIST,
  BLE_ADV_EVT_WHITELIST_REQUEST,
  BLE_ADV_EVT_PEER_ADDR_REQUEST
}
 Advertising events. More...
 

Functions

void ble_advertising_on_ble_evt (ble_evt_t const *p_ble_evt, void *p_adv)
 Function for handling BLE events. More...
 
uint32_t ble_advertising_init (ble_advertising_t *const p_advertising, ble_advertising_init_t const *const p_init)
 Function for initializing the Advertising Module. More...
 
void ble_advertising_conn_cfg_tag_set (ble_advertising_t *const p_advertising, uint8_t ble_cfg_tag)
 Function for changing the connection settings tag that will be used for upcoming connections. More...
 
uint32_t ble_advertising_start (ble_advertising_t *const p_advertising, ble_adv_mode_t advertising_mode)
 Function for starting advertising. More...
 
uint32_t ble_advertising_peer_addr_reply (ble_advertising_t *const p_advertising, ble_gap_addr_t *p_peer_addr)
 Function for setting the peer address. More...
 
uint32_t ble_advertising_whitelist_reply (ble_advertising_t *const p_advertising, ble_gap_addr_t const *p_gap_addrs, uint32_t addr_cnt, ble_gap_irk_t const *p_gap_irks, uint32_t irk_cnt)
 Function for setting a whitelist. More...
 
uint32_t ble_advertising_restart_without_whitelist (ble_advertising_t *const p_advertising)
 Function for disabling whitelist advertising. More...
 
void ble_advertising_modes_config_set (ble_advertising_t *const p_advertising, ble_adv_modes_config_t const *const p_adv_modes_config)
 Function for changing advertising modes configuration. More...
 
ret_code_t ble_advertising_advdata_update (ble_advertising_t *const p_advertising, ble_advdata_t const *const p_advdata, ble_advdata_t const *const p_srdata)
 Function for updating advertising data. More...
 

Detailed Description

Module for handling connectable BLE advertising.

The Advertising Module handles connectable advertising for your application. It can be configured with advertising modes to suit most typical use cases. Your main application can react to changes in advertising modes if an event handler is provided.

Note
The Advertising Module supports only applications with a single peripheral link.

Macro Definition Documentation

#define BLE_ADVERTISING_DEF (   _name)

Macro for defining a ble_advertising instance.

Parameters
_nameName of the instance.

Enumeration Type Documentation

Advertising events.

These events are propagated to the main application if a handler was provided during initialization of the Advertising Module. Events for modes that are not used can be ignored. Similarly, BLE_ADV_EVT_WHITELIST_REQUEST and BLE_ADV_EVT_PEER_ADDR_REQUEST can be ignored if whitelist and direct advertising is not used.

Enumerator
BLE_ADV_EVT_IDLE 

Idle; no connectable advertising is ongoing.

BLE_ADV_EVT_DIRECTED_HIGH_DUTY 

Direct advertising mode has started.

BLE_ADV_EVT_DIRECTED 

Directed advertising (low duty cycle) has started.

BLE_ADV_EVT_FAST 

Fast advertising mode has started.

BLE_ADV_EVT_SLOW 

Slow advertising mode has started.

BLE_ADV_EVT_FAST_WHITELIST 

Fast advertising mode using the whitelist has started.

BLE_ADV_EVT_SLOW_WHITELIST 

Slow advertising mode using the whitelist has started.

BLE_ADV_EVT_WHITELIST_REQUEST 

Request a whitelist from the main application. For whitelist advertising to work, the whitelist must be set when this event occurs.

BLE_ADV_EVT_PEER_ADDR_REQUEST 

Request a peer address from the main application. For directed advertising to work, the peer address must be set when this event occurs.

Advertising modes.

Enumerator
BLE_ADV_MODE_IDLE 

Idle; no connectable advertising is ongoing.

BLE_ADV_MODE_DIRECTED_HIGH_DUTY 

Directed advertising (high duty cycle) attempts to connect to the most recently disconnected peer.

BLE_ADV_MODE_DIRECTED 

Directed advertising (low duty cycle) attempts to connect to the most recently disconnected peer.

BLE_ADV_MODE_FAST 

Fast advertising will connect to any peer device, or filter with a whitelist if one exists.

BLE_ADV_MODE_SLOW 

Slow advertising is similar to fast advertising. By default, it uses a longer advertising interval and time-out than fast advertising. However, these options are defined by the user.

Function Documentation

ret_code_t ble_advertising_advdata_update ( ble_advertising_t *const  p_advertising,
ble_advdata_t const *const  p_advdata,
ble_advdata_t const *const  p_srdata 
)

Function for updating advertising data.

This function can be called if you wish to reconfigure the advertising data The update will be effective even if advertising has already been started.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]p_advdataPointer to the structure for specifying the content of advertising data. Or null if there should be no advertising data.
[in]p_srdataPointer to the structure for specifying the content of scan response data. Or null if there should be no advertising data.
Return values
@refNRF_ERROR_NULL If advertising instance was null. If both p_advdata and p_srdata are null.
@refNRF_ERROR_INVALID_STATE If advertising instance was not initialized.
@refNRF_SUCCESS or any error from ble_advdata_encode or sd_ble_gap_adv_set_configure().
void ble_advertising_conn_cfg_tag_set ( ble_advertising_t *const  p_advertising,
uint8_t  ble_cfg_tag 
)

Function for changing the connection settings tag that will be used for upcoming connections.

See sd_ble_cfg_set for more details about changing connection settings. If this function is never called, BLE_CONN_CFG_TAG_DEFAULT will be used.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]ble_cfg_tagConfiguration for the connection settings (see sd_ble_cfg_set).
uint32_t ble_advertising_init ( ble_advertising_t *const  p_advertising,
ble_advertising_init_t const *const  p_init 
)

Function for initializing the Advertising Module.

Encodes the required advertising data and passes it to the stack. Also builds a structure to be passed to the stack when starting advertising. Most of the supplied data is copied into a local structure where it is manipulated depending on what advertising modes are started in ble_advertising_start. The exception is advdata_t::uuids_more_available, advdata_t::uuids_complete, and advdata_t::uuids_solicited which are stored as pointers. The main application must store these UUIDs.

Parameters
[out]p_advertisingAdvertising Module instance. This structure must be supplied by the application. It is initialized by this function and will later be used to identify this particular module instance.
[in]p_initInformation needed to initialize the module.
Return values
NRF_SUCCESSIf initialization was successful.
NRF_ERROR_INVALID_PARAMIf the advertising configuration in p_init is invalid.
Returns
If functions from other modules return errors to this function, the SoftDevice Global Error Codes are propagated.
void ble_advertising_modes_config_set ( ble_advertising_t *const  p_advertising,
ble_adv_modes_config_t const *const  p_adv_modes_config 
)

Function for changing advertising modes configuration.

This function can be called if you wish to reconfigure the advertising modes that the Advertising Module will cycle through. Enable or disable modes as listed in ble_adv_mode_t; or change the duration of the advertising and use of whitelist.

Keep in mind that ble_adv_modes_config_t is also supplied when calling ble_advertising_init. Calling ble_advertising_modes_config_set is only necessary if your application requires this behaviour to change.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]p_adv_modes_configStruct to keep track of disabled and enabled advertising modes, as well as time-outs and intervals.
void ble_advertising_on_ble_evt ( ble_evt_t const *  p_ble_evt,
void *  p_adv 
)

Function for handling BLE events.

This function must be called from the BLE stack event dispatcher for the module to handle BLE events that are relevant for the Advertising Module.

Parameters
[in]p_ble_evtBLE stack event.
[in]p_advAdvertising Module instance.
uint32_t ble_advertising_peer_addr_reply ( ble_advertising_t *const  p_advertising,
ble_gap_addr_t p_peer_addr 
)

Function for setting the peer address.

The peer address must be set by the application upon receiving a BLE_ADV_EVT_PEER_ADDR_REQUEST event. Without the peer address, the directed advertising mode will not be run.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]p_peer_addrPointer to a peer address.
Return values
@refNRF_SUCCESS Successfully stored the peer address pointer in the Advertising Module.
@refNRF_ERROR_INVALID_STATE If a reply was not expected.
uint32_t ble_advertising_restart_without_whitelist ( ble_advertising_t *const  p_advertising)

Function for disabling whitelist advertising.

This function temporarily disables whitelist advertising. Calling this function resets the current time-out countdown.

Parameters
[in]p_advertisingAdvertising Module instance.
Return values
@refNRF_SUCCESS On success, else an error message propogated from the Softdevice.
uint32_t ble_advertising_start ( ble_advertising_t *const  p_advertising,
ble_adv_mode_t  advertising_mode 
)

Function for starting advertising.

You can start advertising in any of the advertising modes that you enabled during initialization.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]advertising_modeAdvertising mode.
Return values
@refNRF_SUCCESS On success, else an error code indicating reason for failure.
@refNRF_ERROR_INVALID_STATE If the module is not initialized.
uint32_t ble_advertising_whitelist_reply ( ble_advertising_t *const  p_advertising,
ble_gap_addr_t const *  p_gap_addrs,
uint32_t  addr_cnt,
ble_gap_irk_t const *  p_gap_irks,
uint32_t  irk_cnt 
)

Function for setting a whitelist.

The whitelist must be set by the application upon receiving a BLE_ADV_EVT_WHITELIST_REQUEST event. Without the whitelist, the whitelist advertising for fast and slow modes will not be run.

Parameters
[in]p_advertisingAdvertising Module instance.
[in]p_gap_addrsThe list of GAP addresses to whitelist.
[in]addr_cntThe number of GAP addresses to whitelist.
[in]p_gap_irksThe list of peer IRK to whitelist.
[in]irk_cntThe number of peer IRK to whitelist.
Return values
@refNRF_SUCCESS If the operation was successful.
@refNRF_ERROR_INVALID_STATE If a call to this function was made without a BLE_ADV_EVT_WHITELIST_REQUEST event being received.

Documentation feedback | Developer Zone | Subscribe | Updated