| 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
Advertising Module
This information applies to the following SoftDevices: S130, S132, S332

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 advertising modes will be enabled.

Advertising mode | Behavior
--- | ---
Directed | 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. This is only allowed very briefly since it has a high chance of blocking other wireless traffic.
Directed Slow | After the initial "Directed" advertising burst, The application can continue advertising directly to its last peer, but with lower duty cycle compared to "Directed" above.
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 -> Direct Slow -> 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 "Direct Slow", "Fast", and "Slow". "Direct" is a one-shot burst, and "Idle" is not advertising so it does not have an interval or timeout.

# 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 when advertising starts, or to power down the application when no peer is found.

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 fast and slow advertising modes will not use the whitelist. When replying to the BLE_ADV_EVT_WHITELIST_REQUEST event, the application must provide the whitelist in one of the following ways:

- If the application uses Peer Manager: Retrieve the whitelist by calling pm_whitelist_get (pm_whitelist_set must have been called before). Then, call ble_advertising_whitelist_reply with the output of pm_whitelist_get.
- If the application does not use Peer Manager: If you are using the S13x SoftDevice v2.x, construct your whitelist and call ble_advertising_whitelist_reply. If you are using the S13x SoftDevice v3.x, call sd_ble_gap_whitelist_set. Then, call ble_advertising_whitelist_reply (you only need to provide the counts).

After initialization, call ble_advertising_start to start advertising in the desired mode.

# Message Sequence Chart

In the sequence chart below, All modes are enabled, and all events are triggered.

## Message Sequence Chart Example

Let's look at a small example for a typical application. It does not use all the features, only BLE_ADV_MODE_FAST. In this example, the application advertises, establishes a connection and then later disconnects. Advertising is triggered again but no peer is found and the application goes to sleep.