BLE Stack Event Handler

Module for initializing the BLE stack, and propagating BLE stack events to the application. More...

Macros
#define	BLE_STACK_HANDLER_SCHED_EVT_SIZE   0
#define	BLE_STACK_HANDLER_INIT(CLOCK_SOURCE, MTU_SIZE, EVT_HANDLER, USE_SCHEDULER)
	Macro for initializing the BLE stack event handler. More...

Typedefs
typedef void(*	ble_stack_evt_handler_t )(ble_evt_t *p_ble_evt)
	Application stack event handler type.
typedef uint32_t(*	ble_stack_evt_schedule_func_t )(void)
	Type of function for passing events from the BLE stack handler module to the scheduler.

Functions
uint32_t	ble_stack_handler_init (nrf_clock_lfclksrc_t clock_source, void *p_evt_buffer, uint16_t evt_buffer_size, ble_stack_evt_handler_t evt_handler, ble_stack_evt_schedule_func_t evt_schedule_func)
	Function for initializing stack module. More...

Detailed Description

Use the USE_SCHEDULER parameter of the BLE_STACK_HANDLER_INIT() macro to select if the Scheduler is to be used or not.

Note

Even if the scheduler is not used, ble_stack_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 BLE_STACK_HANDLER_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 BLE stack events, this size is 0, since the events are being pulled in the event handler.

#define BLE_STACK_HANDLER_INIT	(		CLOCK_SOURCE,
			MTU_SIZE,
			EVT_HANDLER,
			USE_SCHEDULER
	)

Value:

do                                                                                             \
    {                                                                                              \
        static uint32_t EVT_BUFFER[CEIL_DIV(sizeof(ble_evt_t) + (MTU_SIZE), sizeof(uint32_t))];    \
        uint32_t        ERR_CODE;                                                                  \
        ERR_CODE = ble_stack_handler_init((CLOCK_SOURCE),                                          \
                                          EVT_BUFFER,                                              \
                                          sizeof(EVT_BUFFER),                                      \
                                          (EVT_HANDLER),                                           \
                                          (USE_SCHEDULER) ? ble_stack_evt_schedule : NULL);        \
        APP_ERROR_CHECK(ERR_CODE);                                                                 \
    } while (0)

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

Parameters

[in]	CLOCK_SOURCE	Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t, see sd_softdevice_enable() for details).
[in]	MTU_SIZE	Maximum size of BLE transmission units to be used by this application.
[in]	EVT_HANDLER	Pointer to function to be executed when an event has been received.
[in]	USE_SCHEDULER	TRUE if the application is using the event scheduler, FALSE otherwise.

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, e.g. to do a reinitialization).

Function Documentation

uint32_t ble_stack_handler_init	(	nrf_clock_lfclksrc_t	clock_source,
		void *	p_evt_buffer,
		uint16_t	evt_buffer_size,
		ble_stack_evt_handler_t	evt_handler,
		ble_stack_evt_schedule_func_t	evt_schedule_func
	)

Enables the SoftDevice and the BLE 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 BLE_STACK_HANDLER_INIT() macro, as that will both allocate the BLE event buffer, and also align the buffer correctly.

Parameters

[in]	clock_source	Low frequency clock source to be used by the SoftDevice.
[in]	p_evt_buffer	Buffer for holding one BLE stack event. Since we are not using the heap, 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.
[in]	evt_buffer_size	Size of BLE stack event buffer.
[in]	evt_handler	Handler to be called for each received BLE stack event.
[in]	evt_schedule_func	Function for passing BLE events to the scheduler. Point to ble_stack_evt_schedule() to connect to the scheduler. Set to NULL to make the BLE stack handler module call the event handler directly from the BLE 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.