Example applications implementing BLE profiles and demonstrating 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 Power profiling example.

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

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.

Assert handler: BLE applications must implement an assert handler callback function named assert_nrf_callback. This assert handler function will be passed to the S130 SoftDevice during system initialization using sd_softdevice_enable. In the BLE Peripheral example applications the assert_nrf_callback is propagating all asserts to the app_error_handler. If different actions are required for application error and BLE S130 SoftDevice asserts a dedicated assert_nrf_callback should be implemented.

Error handler: Applications must implement an error handler callback function named app_error_handler. This is called directly from the application APP_ERROR_HANDLER macro (implemented in app_error.h). And indirectly from APP_ERROR_CHECK and APP_ERROR_CHECK_BOOL.

Behavior when maximum number of bonds is reached: All applications that support bonding use the bond manager module. When the bond manager notifies the application that it cannot store a newly bonded master into the flash, the application will assert. When this happens, allow the device to go into System Off mode and then press Button 1. This will wake up the application and clear all existing bonds. The bonds can also be cleared by power-cycling the board by keeping the Button 1 pressed.

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:

Heart Rate Application

Heart Rate Application with RTX

Multiprotocol Application

Glucose Application

Cycling Speed and Cadence Application

Current Time Application

Blood Pressure Application

Alert Notification Application

HID Keyboard Application

HID Mouse Application