| 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
Bluetooth low energy examples
This information applies to the following SoftDevices: S130, S132, S332

The SDK provides example applications that implement BLE profiles and demonstrate the use of BLE services.

We have two types of example application designs:

- Using Scheduler: Events are passed from interrupt level to the main loop (thread mode) using a Scheduler.

- App Low only: All service and application code executes in App Low interrupt level.

In both designs, the example applications have many similarities:

- Main function: The main function consists of a number of init function calls, followed by a small main loop. In an "App Low only" application, the main loop only handles power management. In Scheduler applications, the main loop contains a call to app_sched_schedule() in addition to the power management.

Note
  For more information of low power modes used in the example applications, see Power Management section in the documentation of the Power Profiling Application.

- Service initialization: All applications contain a function named services_init. This function will initialize all services to be used by the application.

- BLE stack initialization: The SoftDevice must be initialized with several parameters. Most examples in the SDK use the default configuration softdevice_enable_get_default_config. In cases where you do not want to use this default setup, remember that the ble_enable_params parameter directly affects the start address of the application's RAM. Before calling softdevice_enable, you can call the CHECK_RAM_START_ADDR macro, which will check the correct setting of the RAM start address compared to the SoftDevice setting that is passed to the macro.

- BLE stack interrupt handler: All applications include the SoftDevice Event Handler module, which contains a BLE stack interrupt handler (SWI2_IRQHandler). This interrupt handler will be called each time the stack wants to pass an event to the application. The handler reads the stack event, and passes the event to the application through a callback function. In applications using the Scheduler, this callback function is always named ble_evt_schedule(), and in applications not using the Scheduler, it is always named ble_evt_dispatch(). The callback function dispatches the event to the BLE stack event handler of all its services and modules having such a handler (either directly, or through the Scheduler). Optionally, it may also dispatch the event to an application specific BLE stack event handler.

- Service BLE stack event handlers: Services may implement their own BLE stack event handlers. These must be called when SWI2_IRQHandler (in SoftDevice Event Handler) receives a BLE event (see previous point). The handlers will react to events that are relevant to the service, while ignoring all others.

- Application BLE stack event handler: Optionally the application may implement its own BLE stack event handler. This must be called when SWI2_IRQHandler (in SoftDevice Event Handler) receives a BLE event. The handler will react to events that are relevant to the application, while ignoring all others.

- Service event handlers: The application may provide event handlers to services, letting the service inform the application about events inside the service. For some services this is optional, while for others it is mandatory.

- Service error handlers: To some services, the application may provide an error handler, letting the service inform the application about errors.

- Error handler: Applications may implement an error handler callback function named app_error_fault_handler that is called when fatal errors occur. See the Error module for more information.

In an application using the Scheduler, instead of calling service/application event handlers directly from the SoftDevice Event Handler callback function, the callback function passes "wrapper" events to the Scheduler, and the "wrapper" event handler will call the service/application event handlers, thus making all service/application event handlers execute in thread mode.

When initializing the Application Timer module, applications using the Scheduler must supply a pointer to the app_sched_timer_event_schedule() function to app_timer_init(). This function will transfer execution of timer timeout handlers to the main loop by using the Scheduler.

See Schedule handling library for illustrations showing the flow of events for various application scenarios, both with and without the Scheduler.

Examples:

BLE Central

BLE Central & Peripheral

BLE Peripheral

BLE Secure DFU Bootloader