SoftDevice Handler Library

This library is used for initializing and disabling the SoftDevice and also propagating SoftDevice events to the application.

This library module contains the following functionalities.

• Initializing the SoftDevice and enabling the SoftDevice event interrupt.
• Disabling the SoftDevice.
• Receiving events from the SoftDevice and forwarding them to the application using interface functions that must be defined by the application. This module works with SoftDevices that have BLE, ANT, or BLE and ANT functionalities.

Depending on the type of SoftDevice, the APIs used to fetch events from it will vary. For example, the S110 SoftDevice exposes 2 APIs - sd_ble_evt_get for fetching BLE events and sd_evt_get for fetching System (SOC) events. But the S210 SoftDevice does not have an API named sd_ble_evt_get. Instead it exposes sd_ant_event_get for fetching ANT events and sd_evt_get for fetching System (SOC) events. Depending on the type of SoftDevice, SoftDevice Event Handler helps the application use the correct APIs for fetching SoftDevice events.

The API exposed by this module is present in <InstallFolder>\Nordic\nrf51\components\softdevice\common in the files softdevice_handler.h, ant_stack_handler_types.h, and ble_stack_handler_types.h.

Expectations from the application/developer using this library

This module has the following expectations from the application.

Preprocessor defines

This module uses conditional compilation. It expects certain preprocessor macros to be defined as follows.

• BLE_STACK_SUPPORT_REQD to be defined, if the application needs to be run on a BLE-only SoftDevice (for example, S110 SoftDevice).
• ANT_STACK_SUPPORT_REQD to be defined, if the application needs to be run on an ANT-only SoftDevice (for example, S210 SoftDevice).
• Both BLE_STACK_SUPPORT_REQD and ANT_STACK_SUPPORT_REQD to be defined, if the application needs to be run on a SoftDevice with both BLE and ANT support. (for example, S310 SoftDevice).
• If neither BLE_STACK_SUPPORT_REQD nor ANT_STACK_SUPPORT_REQD is defined, the module will only be capable of fetching system (SOC) events from the SoftDevice.

Subscription to events

The application should subscribe for events using the function softdevice_xxx_evt_handler_set, where xxx can be ble (for BLE events), ant (for ANT events), or sys (for system (SOC) events).

No direct calls to sd_softdevice_disable and sd_softdevice_enable

When the application needs to disable the SoftDevice, it must use the function softdevice_handler_sd_disable and not directly call the function sd_softdevice_disable that is provided by the SoftDevice. If this is not done, this module will not be aware that the SoftDevice was disabled. This will result in the SoftDevice returning the error code NRF_ERROR_SOFTDEVICE_NOT_ENABLED when this module tries to fetch BLE or ANT events. This in turn will result in a call to app_error_handler function defined by the application.

Similarly, if the application needs to enable the SoftDevice, it must do so using the function softdevice_handler_init function. If this is not done, this module will never fetch the BLE or ANT events.