This information applies to the following SoftDevices: S132, S140
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_execute() 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: A SoftDevice must be enabled with the required configuration parameters before it can be used. The default stack configuration can be customized with sd_ble_cfg_set before the SoftDevice is enabled. Most examples in the SDK use the default configuration with some modifications. When adapting an example, all of the default values may be overwritten. However, remember that changes might alter the size of the BLE stack RAM, which will change the application's start RAM address. If you provide an incorrect RAM start address when calling nrf_sdh_ble_enable, the function returns an error along with the new correct RAM start address.
- Note
- When setting connection-specific configurations using sd_ble_cfg_set, you must create a tag for each configuration. This tag must be supplied when calling sd_ble_gap_adv_start() and sd_ble_gap_connect(). If your application uses the Advertising Module, you must call ble_advertising_conn_cfg_tag_set before starting advertising.
- BLE stack interrupt handler: All applications include the SoftDevice 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 and all registered BLE stack event observers, such as BLE services and modules, through callback functions.
- Service BLE stack event handlers: Services may implement their own BLE stack event handlers. These must be called when SWI2_IRQHandler (in SoftDevice 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 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 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