| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Typedefs | Enumerations | Functions
Advertising Module
BLE libraries

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_adv_mode_config_t
struct | ble_adv_init_t
| Initialization parameters for the Advertising Module. More...

## Typedefs
typedef void(* | ble_advertising_evt_handler_t )(ble_adv_evt_t const adv_evt)
| BLE advertising event handler type.
typedef void(* | ble_advertising_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, BLE_ADV_MODE_DIRECTED_SLOW, BLE_ADV_MODE_FAST, BLE_ADV_MODE_SLOW }
| Advertising modes. More...
enum | ble_adv_evt_t { BLE_ADV_EVT_IDLE, BLE_ADV_EVT_DIRECTED, BLE_ADV_EVT_DIRECTED_SLOW, 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 (const ble_evt_t *const p_ble_evt)
| Function for handling BLE events. More...
void | ble_advertising_on_sys_evt (uint32_t sys_evt)
| Function for handling system events. More...
uint32_t | ble_advertising_init (ble_advdata_t const *p_advdata, ble_advdata_t const *p_srdata, ble_adv_modes_config_t const *p_config, ble_advertising_evt_handler_t const evt_handler, ble_advertising_error_handler_t const error_handler)
| Function for initializing the Advertising Module. More...
uint32_t | ble_advertising_start (ble_adv_mode_t advertising_mode)
| Function for starting advertising. More...
uint32_t | ble_advertising_peer_addr_reply (ble_gap_addr_t *p_peer_addr)
| Function for setting the peer address. More...
uint32_t | ble_advertising_whitelist_reply (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 (void)
| Function for disabling whitelist advertising. 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.

The application must propagate BLE stack events to this module by calling ble_advertising_on_ble_evt() and system events by calling ble_advertising_on_sys_evt().

## Enumeration Type Documentation

enum ble_adv_evt_t

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 | Direct advertising mode has started.
BLE_ADV_EVT_DIRECTED_SLOW | 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.

enum ble_adv_mode_t

Advertising modes.

Enumerator
BLE_ADV_MODE_IDLE | Idle; no connectable advertising is ongoing.
BLE_ADV_MODE_DIRECTED | Directed advertising attempts to connect to the most recently disconnected peer.
BLE_ADV_MODE_DIRECTED_SLOW | 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

uint32_t ble_advertising_init | ( | ble_advdata_t const * | p_advdata,
|  | ble_advdata_t const * | p_srdata,
|  | ble_adv_modes_config_t const * | p_config,
|  | ble_advertising_evt_handler_t const | evt_handler,
|  | ble_advertising_error_handler_t const | error_handler
| ) |  |

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. The supplied advertising data is copied to a local structure and is manipulated depending on what advertising modes are started in ble_advertising_start.

Parameters

  [in] | p_advdata | Advertising data: name, appearance, discovery flags, and more.
  [in] | p_srdata | Scan response data: Supplement to advertising data.
  [in] | p_config | Select which advertising modes and intervals will be utilized.
  [in] | evt_handler | Event handler that will be called upon advertising events.
  [in] | error_handler | Error handler that will propogate internal errors to the main applications.

Return values

  NRF_SUCCESS | If initialization was successful. Otherwise, an error code is returned.

void ble_advertising_on_ble_evt | ( | const ble_evt_t *const | p_ble_evt | ) |

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_evt | BLE stack event.

void ble_advertising_on_sys_evt | ( | uint32_t | sys_evt | ) |

Function for handling system events.

This function must be called to handle system events that are relevant for the Advertising Module. Specifically, the advertising module can not use the softdevice as long as there are pending writes to the flash memory. This event handler is designed to delay advertising until there is no flash operation.

Parameters

  [in] | sys_evt | System event.

uint32_t ble_advertising_peer_addr_reply | ( | 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_peer_addr | Pointer to a peer address.

Return values

  @ref | NRF_SUCCESS Successfully stored the peer address pointer in the advertising module.
  @ref | NRF_ERROR_INVALID_STATE If a reply was not expected.

uint32_t ble_advertising_restart_without_whitelist | ( | void |  | ) |

Function for disabling whitelist advertising.

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

Return values

  @ref | NRF_SUCCESS On success, else an error message propogated from the Softdevice.

uint32_t ble_advertising_start | ( | 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] | advertising_mode | Advertising mode.

Return values

  @ref | NRF_SUCCESS On success, else an error code indicating reason for failure.
  @ref | NRF_ERROR_INVALID_STATE If the module is not initialized.

uint32_t ble_advertising_whitelist_reply | ( | 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_gap_addrs | The list of GAP addresses to whitelist.
  [in] | addr_cnt | The number of GAP addresses to whitelist.
  [in] | p_gap_irks | The list of peer IRK to whitelist.
  [in] | irk_cnt | The number of peer IRK to whitelist.

Return values

  @ref | NRF_SUCCESS If the operation was successful.
  @ref | NRF_ERROR_INVALID_STATE If a call to this function was made without a BLE_ADV_EVT_WHITELIST_REQUEST event being received.