nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Advertising Module

The Advertising Module handles the BLE advertising of your application. You can use it for many typical "Connectable Advertising" scenarios, like most of the SDK examples. The module covers the most common advertising behavior and can easily be adapted by enabling or disabling specific advertising modes. A simple event handler makes it possible to extend the provided advertising functionality and, for example, add indications for specific advertising modes.

Advertising modes

During initialization of the module, you decide which BLE advertising modes will be enabled.

Advertising mode Behavior
Direct After disconnecting, the application immediately attempts to reconnect to the peer that was connected most recently. This advertising mode is very useful to stay connected to one peer and seamlessly recover from accidental disconnects.
Fast The application rapidly advertises to surrounding devices for a short time.
Slow The application advertises to surrounding devices, but with a longer advertising interval than in fast advertising mode. This advertising mode conserves power and causes less traffic for other wireless devices that might be present. However, finding a device and connecting to it might take more time in slow advertising mode.
Idle The application stops advertising.

When advertising, the module will pass through the enabled advertising modes until either a connection is made or advertising times out. The flow of advertising is Direct -> Fast -> Slow -> Idle. If you start advertising in direct mode, the module first attempts direct advertising. If no information about a previous connection is available or the previous peer is not available, the module attempts fast advertising. If no peer connects before the fast advertising times out, the application moves on to a longer advertising interval, thus slow advertising. If no peer connects before the configured time-out, advertising stops.

Disabled advertising modes are skipped. You can configure the time-out thresholds and advertising intervals for all modes.

Whitelist

Whitelist advertising affects the filtering parameters for fast and slow advertising modes. The whitelist stores all devices that have been connected before. If you enable use of the whitelist, the application specifically advertises to the devices that are on the whitelist.

You can enable or disable whitelist advertising during initialization of the module. After initialization, you can temporarily disable whitelist advertising for one connection. Call ble_advertising_restart_without_whitelist to restart advertising in the current mode, but without the whitelist. However, after the device disconnects, the whitelist will take effect again. To permanently disable whitelist advertising, you must disable it in the initialization function.

Usage

During initialization of the module, enable the advertising modes that you want to use and configure the parameters. You should also provide an event handler that is called when advertising transitions to a new mode. Use the event handler to add functionality, for example to indicate such transitions to the user by flashing an LED or to power down the application when no connection is made.

If no event handler (more precisely, a NULL value) is provided during initialization, basic advertising will still work, but there will be no additional functionality. Most importantly, the application will not power down when advertising goes to BLE_ADV_MODE_IDLE state.

The event handler must also handle requests to update the whitelist (BLE_ADV_EVT_WHITELIST_REQUEST) and peer address (BLE_ADV_EVT_PEER_ADDR_REQUEST). If the peer address request event is ignored, the directed advertising mode cannot be used. Likewise, if the whitelist request event is ignored, the slow and fast advertising modes will not use the whitelist. After initialization, call ble_advertising_start to start advertising in the desired mode.