Interactive Device Design / simpleBLEControl

mediCAL's first BLE project

Dependents:   BLE_mediCAL

Fork of nRF51822 by Nordic Semiconductor

nordic/nrf-sdk/sd_common/softdevice_handler.h@56:a1071b629aa3, 2014-09-02 (annotated)

Committer:
Rohit Grover
Date:
Tue Sep 02 15:50:05 2014 +0100
Revision:
56:a1071b629aa3
Parent:
45:3c4df37ed83e
Child:
65:98215c4f3a25
Release 0.1.0

=============



We've achieved significant gains in power consumption: the BLE_Beacon demo now

runs at around 35uA of average current broadcasting once a second at 0dB; when

not using the radio, this demo consumes around 7uA.



Features

~~~~~~~~



- Replace initialization of high-frequency external crystal clock-source with

  the use of low-frequency clock. This brings in significant gains in power

  consumption.



- Re-implement the micro-second timer on nRF51 using the app_timer module

  (which internally uses RTC). This limits the precision of the us_Timer to

  30uS; but brings in significant gains in power consumption.



- Reduce the number of available app_timers and the event depths for app-timer

  events; this will reduce memory consumption for zero-initialized data by

  around 1K.



- Remove the call to conn_params_init() at startup. This is not mandatory; and

  was causing an unnecessary re-negotiation of connection parameters a few

  seconds into every connection.



- Reduce default transmission power level to 0dbB (was 4dbB before).



- Reduce min connection interval to 50ms and max to 500ms (previous values

  were much larger).



- Replace a few instances of use of wait() with nrf_delay_us().



- onConnection() callback now receives connection-parameters applicable to the

  new connection.



- onDataSent() callback now receives a count parameter containing the number of

  times notifications were sent out since the last callback.



- A 'reason' parameter has been added to Gap::disconnect() to indicate the

  reason for disconnection; and also to the onDisconnection callback to

  receive a reason from the remote host.



- disable the app_gpiote module by default.



Bugfixes

~~~~~~~~



- onDataWritten() callback now passes an additional parameter

  (GattServer::WriteEventCallback_t) encapsulating the update. This avoids

  having to re-fetch the updated characteristic's value attribute. It also

  fixes a bug where multiple updates to the characteristic's value-attribute

  could get clobbered if they occurred in quick succession before the

  callbacks could be processed.





Compatibility

~~~~~~~~~~~~~



Compatible with revision 0.1.0 of the BLE_API.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bogdanm 0:eff01767de02 1 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
bogdanm 0:eff01767de02 2 *
bogdanm 0:eff01767de02 3 * The information contained herein is property of Nordic Semiconductor ASA.
bogdanm 0:eff01767de02 4 * Terms and conditions of usage are described in detail in NORDIC
bogdanm 0:eff01767de02 5 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
bogdanm 0:eff01767de02 6 *
bogdanm 0:eff01767de02 7 * Licensees are granted free, non-transferable use of the information. NO
bogdanm 0:eff01767de02 8 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
bogdanm 0:eff01767de02 9 * the file.
bogdanm 0:eff01767de02 10 *
bogdanm 0:eff01767de02 11 */
bogdanm 0:eff01767de02 12
bogdanm 0:eff01767de02 13 /** @file
bogdanm 0:eff01767de02 14 *
bogdanm 0:eff01767de02 15 * @defgroup softdevice_handler SoftDevice Event Handler
bogdanm 0:eff01767de02 16 * @{
bogdanm 0:eff01767de02 17 * @ingroup app_common
bogdanm 0:eff01767de02 18 * @brief API for initializing and disabling the SoftDevice
bogdanm 0:eff01767de02 19 *
bogdanm 0:eff01767de02 20 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
bogdanm 0:eff01767de02 21 * For more information on the library and how the application should use it, please refer
bogdanm 0:eff01767de02 22 * @ref lib_softdevice_handler.
bogdanm 0:eff01767de02 23 *
bogdanm 0:eff01767de02 24 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
bogdanm 0:eff01767de02 25 * the @ref app_scheduler is to be used or not.
bogdanm 0:eff01767de02 26 *
bogdanm 0:eff01767de02 27 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
bogdanm 0:eff01767de02 28 * So when compiling, app_scheduler.h must be available in one of the compiler include
bogdanm 0:eff01767de02 29 * paths.
bogdanm 0:eff01767de02 30 */
bogdanm 0:eff01767de02 31
bogdanm 0:eff01767de02 32 #ifndef SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 33 #define SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 34
bogdanm 0:eff01767de02 35 #include <stdlib.h>
Rohit Grover 37:c29c330d942c 36 #include "nordic_common.h"
bogdanm 0:eff01767de02 37 #include "nrf_sdm.h"
bogdanm 0:eff01767de02 38 #include "app_error.h"
bogdanm 0:eff01767de02 39 #include "app_scheduler.h"
bogdanm 0:eff01767de02 40 #include "app_util.h"
bogdanm 0:eff01767de02 41 #include "ble_stack_handler_types.h"
bogdanm 0:eff01767de02 42 #include "ant_stack_handler_types.h"
bogdanm 0:eff01767de02 43
Rohit Grover 45:3c4df37ed83e 44 #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 45 extern "C" {
Rohit Grover 45:3c4df37ed83e 46 #endif // #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 47
bogdanm 0:eff01767de02 48 #define SOFTDEVICE_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 SoftDevice events, this size is 0, since the events are being pulled in the event handler. */
bogdanm 0:eff01767de02 49 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
bogdanm 0:eff01767de02 50
bogdanm 0:eff01767de02 51 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
bogdanm 0:eff01767de02 52 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
bogdanm 0:eff01767de02 53
bogdanm 0:eff01767de02 54 /**@brief Application System (SOC) event handler type. */
bogdanm 0:eff01767de02 55 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
bogdanm 0:eff01767de02 56
bogdanm 0:eff01767de02 57
bogdanm 0:eff01767de02 58 /**@brief Macro for initializing the stack event handler.
bogdanm 0:eff01767de02 59 *
bogdanm 0:eff01767de02 60 * @details It will handle dimensioning and allocation of the memory buffer required for reading
bogdanm 0:eff01767de02 61 * events from the stack, making sure the buffer is correctly aligned. It will also
bogdanm 0:eff01767de02 62 * connect the stack event handler to the scheduler (if specified).
bogdanm 0:eff01767de02 63 *
bogdanm 0:eff01767de02 64 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
bogdanm 0:eff01767de02 65 * see sd_softdevice_enable() for details).
bogdanm 0:eff01767de02 66 * @param[in] USE_SCHEDULER TRUE if the application is using the event scheduler, FALSE
bogdanm 0:eff01767de02 67 * otherwise.
bogdanm 0:eff01767de02 68 *
bogdanm 0:eff01767de02 69 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
bogdanm 0:eff01767de02 70 * several times as long as it is from the same location, that is to do a
bogdanm 0:eff01767de02 71 * reinitialization).
bogdanm 0:eff01767de02 72 */
bogdanm 0:eff01767de02 73 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
Rohit Grover 56:a1071b629aa3 74 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, USE_SCHEDULER) \
bogdanm 0:eff01767de02 75 do \
bogdanm 0:eff01767de02 76 { \
Rohit Grover 56:a1071b629aa3 77 static uint32_t EVT_BUFFER[CEIL_DIV(MAX(MAX(BLE_STACK_EVT_MSG_BUF_SIZE, ANT_STACK_EVT_STRUCT_SIZE), SYS_EVT_MSG_BUF_SIZE), sizeof(uint32_t))]; \
bogdanm 0:eff01767de02 78 uint32_t ERR_CODE; \
Rohit Grover 56:a1071b629aa3 79 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), EVT_BUFFER, sizeof(EVT_BUFFER), (USE_SCHEDULER) ? softdevice_evt_schedule : NULL); \
bogdanm 0:eff01767de02 80 APP_ERROR_CHECK(ERR_CODE); \
bogdanm 0:eff01767de02 81 } while (0)
bogdanm 0:eff01767de02 82
bogdanm 0:eff01767de02 83
bogdanm 0:eff01767de02 84 /**@brief Function for initializing the stack handler module.
bogdanm 0:eff01767de02 85 *
bogdanm 0:eff01767de02 86 * @details Enables the SoftDevice and the stack event interrupt handler.
bogdanm 0:eff01767de02 87 *
bogdanm 0:eff01767de02 88 * @note This function must be called before calling any function in the SoftDevice API.
bogdanm 0:eff01767de02 89 *
bogdanm 0:eff01767de02 90 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
bogdanm 0:eff01767de02 91 * as that will both allocate the event buffer, and also align the buffer correctly.
bogdanm 0:eff01767de02 92 *
bogdanm 0:eff01767de02 93 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice.
bogdanm 0:eff01767de02 94 * @param[in] p_evt_buffer Buffer for holding one stack event. Since heap is not being
bogdanm 0:eff01767de02 95 * used, this buffer must be provided by the application. The
bogdanm 0:eff01767de02 96 * buffer must be large enough to hold the biggest stack event the
bogdanm 0:eff01767de02 97 * application is supposed to handle. The buffer must be aligned to
bogdanm 0:eff01767de02 98 * a 4 byte boundary. This parameter is unused if neither BLE nor
bogdanm 0:eff01767de02 99 * ANT stack support is required.
bogdanm 0:eff01767de02 100 * @param[in] evt_buffer_size Size of SoftDevice event buffer. This parameter is unused if
bogdanm 0:eff01767de02 101 * BLE stack support is not required.
bogdanm 0:eff01767de02 102 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
bogdanm 0:eff01767de02 103 * ble_ant_stack_evt_schedule() to connect to the scheduler.
bogdanm 0:eff01767de02 104 * Set to NULL to make the stack handler module call the event
bogdanm 0:eff01767de02 105 * handler directly from the stack event interrupt handler.
bogdanm 0:eff01767de02 106 *
bogdanm 0:eff01767de02 107 * @retval NRF_SUCCESS Successful initialization.
bogdanm 0:eff01767de02 108 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
bogdanm 0:eff01767de02 109 * boundary) or NULL.
bogdanm 0:eff01767de02 110 */
bogdanm 0:eff01767de02 111 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source,
bogdanm 0:eff01767de02 112 void * p_evt_buffer,
bogdanm 0:eff01767de02 113 uint16_t evt_buffer_size,
bogdanm 0:eff01767de02 114 softdevice_evt_schedule_func_t evt_schedule_func);
bogdanm 0:eff01767de02 115
bogdanm 0:eff01767de02 116
bogdanm 0:eff01767de02 117 /**@brief Function for disabling the SoftDevice.
bogdanm 0:eff01767de02 118 *
bogdanm 0:eff01767de02 119 * @details This function will disable the SoftDevice. It will also update the internal state
bogdanm 0:eff01767de02 120 * of this module.
bogdanm 0:eff01767de02 121 */
bogdanm 0:eff01767de02 122 uint32_t softdevice_handler_sd_disable(void);
bogdanm 0:eff01767de02 123
bogdanm 0:eff01767de02 124
bogdanm 0:eff01767de02 125 /**@brief Function for registering for System (SOC) events.
bogdanm 0:eff01767de02 126 *
bogdanm 0:eff01767de02 127 * @details The application should use this function to register for receiving System (SOC)
bogdanm 0:eff01767de02 128 * events from the SoftDevice. If the application does not call this function, then any
bogdanm 0:eff01767de02 129 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
bogdanm 0:eff01767de02 130 * the application has registered for the events, it is not possible to possible to
bogdanm 0:eff01767de02 131 * cancel the registration. However, it is possible to register a different function for
bogdanm 0:eff01767de02 132 * handling the events at any point of time.
bogdanm 0:eff01767de02 133 *
bogdanm 0:eff01767de02 134 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
bogdanm 0:eff01767de02 135 *
bogdanm 0:eff01767de02 136 * @retval NRF_SUCCESS Successful registration.
bogdanm 0:eff01767de02 137 * @retval NRF_ERROR_NULL Null pointer provided as input.
bogdanm 0:eff01767de02 138 */
bogdanm 0:eff01767de02 139 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
bogdanm 0:eff01767de02 140
bogdanm 0:eff01767de02 141
bogdanm 0:eff01767de02 142 // Functions for connecting the Stack Event Handler to the scheduler:
bogdanm 0:eff01767de02 143 /**@cond NO_DOXYGEN */
bogdanm 0:eff01767de02 144 void intern_softdevice_events_execute(void);
bogdanm 0:eff01767de02 145
bogdanm 0:eff01767de02 146 static __INLINE void softdevice_evt_get(void * p_event_data, uint16_t event_size)
bogdanm 0:eff01767de02 147 {
bogdanm 0:eff01767de02 148 APP_ERROR_CHECK_BOOL(event_size == 0);
bogdanm 0:eff01767de02 149 intern_softdevice_events_execute();
bogdanm 0:eff01767de02 150 }
bogdanm 0:eff01767de02 151
bogdanm 0:eff01767de02 152 static __INLINE uint32_t softdevice_evt_schedule(void)
bogdanm 0:eff01767de02 153 {
bogdanm 0:eff01767de02 154 return app_sched_event_put(NULL, 0, softdevice_evt_get);
bogdanm 0:eff01767de02 155 }
bogdanm 0:eff01767de02 156 /**@endcond */
bogdanm 0:eff01767de02 157
Rohit Grover 45:3c4df37ed83e 158 #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 159 }
Rohit Grover 45:3c4df37ed83e 160 #endif // #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 161
bogdanm 0:eff01767de02 162 #endif // SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 163
bogdanm 0:eff01767de02 164 /** @} */