BLE Central

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.

• 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 ble_stack_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 ble_stack_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 ble_stack_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 S120 SoftDevice during system initialization using sd_softdevice_enable. In the BLE Central 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 S120 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.

• LEDs common to all applications written to work on the nRFgo Motherboard (the applications inside nrf6310 folder):
  • LED 0: Scanning
  • LED 1: Connected
  • LED 7: Asserted (i.e. an assert check in the application has failed)

• Behavior when maximum number of bonds is reached: All applications that support bonding use the device manager module. When the device manager notifies the application that it cannot store a newly bonded peripheral 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 ble_stack_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.

Examples:

BLE Heart Rate Collector Example

BLE Multi-link Example