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

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, a BLE SoftDevice exposes 2 APIs - sd_ble_evt_get for fetching BLE events and sd_evt_get for fetching System (SOC) events. But an ANT SoftDevice might 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>\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.
- ANT_STACK_SUPPORT_REQD to be defined, if the application needs to be run on an ANT-only 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.
- 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.