| 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 | Macros | Typedefs | Functions
SoftDevice Event Handler
SDK common libraries

API for initializing and disabling the SoftDevice. More...

## Modules
| Types definitions for ANT support in SoftDevice handler.
| This file contains the declarations of types required for ANT stack support. These types will be defined when the preprocessor define ANT_STACK_SUPPORT_REQD is defined.
| Types definitions for BLE support in SoftDevice handler.
| This file contains the declarations of types required for BLE stack support. These types will be defined when the preprocessor define BLE_STACK_SUPPORT_REQD is defined.

## Macros
#define | SOFTDEVICE_SCHED_EVT_SIZE 0
#define | SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t)
#define | CHECK_RAM_START_ADDR(C_LINK_CNT, P_LINK_CNT)
| Macro for checking the RAM requirement of the SoftDevice.
#define | SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE,EVT_HANDLER)
| Macro for initializing the stack event handler. More...

## Typedefs
typedef uint32_t(* | softdevice_evt_schedule_func_t )(void)
| Type of function for passing events from the stack handler module to the scheduler.
typedef void(* | sys_evt_handler_t )(uint32_t evt_id)
| Application System (SOC) event handler type.

## Functions
uint32_t | sd_check_ram_start (uint32_t sd_req_ram_start)
| Function for checking the RAM requirement of the SoftDevice. More...
bool | softdevice_handler_is_enabled (void)
| Function for retrieving the information about SD state. More...
uint32_t | softdevice_handler_init (nrf_clock_lf_cfg_t *p_clock_lf_cfg, void *p_ble_evt_buffer, uint16_t ble_evt_buffer_size, softdevice_evt_schedule_func_t evt_schedule_func)
| Function for initializing the stack handler module. More...
uint32_t | softdevice_handler_sd_disable (void)
| Function for disabling the SoftDevice. More...
void | softdevice_handler_suspend (void)
| Function for suspending the event handler. More...
void | softdevice_handler_resume (void)
| Function for re-enabling the event handler after suspending.
bool | softdevice_handler_is_suspended (void)
| Function for retrieving the information about the event handler state. More...
uint32_t | softdevice_sys_evt_handler_set (sys_evt_handler_t sys_evt_handler)
| Function for registering for System (SOC) events. More...
uint32_t | softdevice_enable_get_default_config (uint8_t central_links_count, uint8_t periph_links_count, ble_enable_params_t *p_ble_enable_params)
| Function for fetching the default enable parameters for the SoftDevice. More...
uint32_t | softdevice_enable (ble_enable_params_t *p_ble_enable_params)
| Function for enabling the SoftDevice. More...

## Detailed Description

API for initializing and disabling the SoftDevice.

This API contains the functions and defines exposed by the SoftDevice handler library. For more information on the library and how the application should use it, please refer SoftDevice handler library.

Note
  Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if the Scheduler is to be used or not.
  Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h. So when compiling, app_scheduler.h must be available in one of the compiler include paths.

## Macro Definition Documentation

#define SOFTDEVICE_HANDLER_INIT | ( |  | CLOCK_SOURCE,
|  |  | EVT_HANDLER
| ) |  |

Value:
do \
{ \
static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))]; \
uint32_t ERR_CODE; \
ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
BLE_EVT_BUFFER, \
sizeof(BLE_EVT_BUFFER), \
EVT_HANDLER); \
APP_ERROR_CHECK(ERR_CODE); \
} while (0)

Macro for initializing the stack event handler.

It will handle dimensioning and allocation of the memory buffer required for reading events from the stack, making sure the buffer is correctly aligned. It will also connect the stack event handler to the scheduler/RTOS (if specified).

Parameters

  [in] | CLOCK_SOURCE | Low frequency clock source and accuracy (type nrf_clock_lf_cfg_t_t, see sd_softdevice_enable() for details).
  [in] | EVT_HANDLER | scheduler/RTOS event handler function.

Note
  Since this macro allocates a buffer, it must only be called once (it is OK to call it several times as long as it is from the same location, that is to do a reinitialization).

#define SOFTDEVICE_SCHED_EVT_SIZE 0

Size of button events being passed through the scheduler (is to be used for computing the maximum size of scheduler events). For SoftDevice events, this size is 0, since the events are being pulled in the event handler.

#define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t)

Size of System (SOC) event message buffer.

## Function Documentation

uint32_t sd_check_ram_start | ( | uint32_t | sd_req_ram_start | ) |

Function for checking the RAM requirement of the SoftDevice.

Call this function to check if the project settings have the correct RAM start address in respect to what the SoftDevice requires.

Note
  This function is called using the CHECK_RAM_START_ADDR_INTERN macro and should not be called directly.

uint32_t softdevice_enable | ( | ble_enable_params_t * | p_ble_enable_params | ) |

Function for enabling the SoftDevice.

This function calls the sd_ble_enable SVC call. It has been abstracted to give feedback on the app_ram_base. If the app_ram_base is too low, this function will return an error. Using a app_ram_base that is too high will not fail, but will result in RAM that is never used. If the DEBUG macro is enabled, this function will provide the correct app_ram_base as mandated by the SoftDevice. This is useful to tweak the RAM use of your application.

Parameters

  [in] | p_ble_enable_params | Parameters for configuring links and bandwidths.

Return values

  NRF_SUCCESS | If the operation was successful.

uint32_t softdevice_enable_get_default_config | ( | uint8_t | central_links_count,
|  | uint8_t | periph_links_count,
|  | ble_enable_params_t * | p_ble_enable_params
| ) |  |

Function for fetching the default enable parameters for the SoftDevice.

The default enable parameters will work for most projects in the SDK. They are not optimized with regards to RAM use. This function is meant as a way to abstract the details of p_ble_enable_params needed by softdevice_enable. You might want to tweak the struct returned by this function or fill in the entire ble_enable_params_t instead of fetching it from this function.

Parameters

  [in] | central_links_count | Number of central links used by the application.
  [in] | periph_links_count | Number of peripheral links used by the application.
  [out] | p_ble_enable_params | Default ble_enable_params_t to be used by softdevice_enable.

Return values

  NRF_SUCCESS | If the operation was successful.

uint32_t softdevice_handler_init | ( | nrf_clock_lf_cfg_t * | p_clock_lf_cfg,
|  | void * | p_ble_evt_buffer,
|  | uint16_t | ble_evt_buffer_size,
|  | softdevice_evt_schedule_func_t | evt_schedule_func
| ) |  |

Function for initializing the stack handler module.

Enables the SoftDevice and the stack event interrupt handler.

Note
  This function must be called before calling any function in the SoftDevice API.
  Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro, as that will both allocate the event buffer, and also align the buffer correctly.

Parameters

  [in] | p_clock_lf_cfg | Low frequency clock source to be used by the SoftDevice.
  [in] | p_ble_evt_buffer | Buffer for holding one BLE stack event. Since heap is not being used, this buffer must be provided by the application. The buffer must be large enough to hold the biggest stack event the application is supposed to handle. The buffer must be aligned to a 4 byte boundary. This parameter is unused if BLE stack support is not required.
  [in] | ble_evt_buffer_size | Size of SoftDevice BLE event buffer. This parameter is unused if BLE stack support is not required.
  [in] | evt_schedule_func | Function for passing events to the scheduler. Point to ble_ant_stack_evt_schedule() to connect to the scheduler. Set to NULL to make the stack handler module call the event handler directly from the stack event interrupt handler.

Return values

  NRF_SUCCESS | Successful initialization.
  NRF_ERROR_INVALID_PARAM | Invalid parameter (buffer not aligned to a 4 byte boundary) or NULL.

bool softdevice_handler_is_enabled | ( | void |  | ) |

Function for retrieving the information about SD state.

The information about current state of softdevice.

Return values

  false | SD is not initialized and SD commands should not be called.
  true | SD is already initialized

bool softdevice_handler_is_suspended | ( | void |  | ) |

Function for retrieving the information about the event handler state.

Return values

  false | Event handler is active.
  true | Event handler is suspended and events from SD will not be pulled.

uint32_t softdevice_handler_sd_disable | ( | void |  | ) |

Function for disabling the SoftDevice.

This function will disable the SoftDevice. It will also update the internal state of this module.

void softdevice_handler_suspend | ( | void |  | ) |

Function for suspending the event handler.

When event handler is disabled, no new events are pulled from SoftDevice. Application can suspend pulling incoming events when its event queue is full.

uint32_t softdevice_sys_evt_handler_set | ( | sys_evt_handler_t | sys_evt_handler | ) |

Function for registering for System (SOC) events.

The application should use this function to register for receiving System (SOC) events from the SoftDevice. If the application does not call this function, then any System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once the application has registered for the events, it is not possible to possible to cancel the registration. However, it is possible to register a different function for handling the events at any point of time.

Parameters

  [in] | sys_evt_handler | Function to be called for each received System (SOC) event.

Return values

  NRF_SUCCESS | Successful registration.
  NRF_ERROR_NULL | Null pointer provided as input.