Cefn Hoile / nRF51822

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

Committer:
rgrover1
Date:
Mon Jul 06 10:13:27 2015 +0100
Revision:
371:8f7d2137727a
Parent:
370:295f76db798e
Synchronized with git rev 2716309c
Author: Rohit Grover
Release 0.4.0
=============

This is a major release which introduces the GATT Client functionality. It
aligns with release 0.4.0 of BLE_API.

Enhancements
~~~~~~~~~~~~

* Introduce GattClient. This includes functionality for service-discovery,
connections, and attribute-reads and writes. You'll find a demo program for
LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of
the GATT client functionality hasn't been implemented yet, but the APIs have
been added.

* We've added an implementation for the abstract base class for
SecurityManager. All security related APIs have been moved into that.

* There has been a major cleanup of APIs under BLE. APIs have now been
categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.
There are accessors to get references for Gap, GattServer, GattClient, and
SecurityManager. A former call to ble.setAddress(...) is now expected to be
achieved with ble.gap().setAddress(...).

* We've cleaned up our APIs, and this has resulted in dropping some APIs like
BLE::reset().

* We've also dropped GattServer::initializeGattDatabase(). THis was added at
some point to support controllers where a commit point was needed to
indicate when the application had finished constructing the GATT database.
This API would get called internally before Gap::startAdvertising(). We now
expect the underlying port to do the equivalent of initializeGattDatabase()
implicitly upon Gap::startAdvertising().

* We've added a version of Gap::disconnect() which takes a connection handle.
The previous API (which did not take a connection handle) has been
deprecated; it will still work for situations where there's only a single
active connection. We hold on to that API to allow existing code to migrate
to the new API.

Bugfixes
~~~~~~~~

* None.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 371:8f7d2137727a 1 /*
rgrover1 371:8f7d2137727a 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 371:8f7d2137727a 3 * All rights reserved.
rgrover1 371:8f7d2137727a 4 *
rgrover1 371:8f7d2137727a 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 371:8f7d2137727a 6 * are permitted provided that the following conditions are met:
rgrover1 371:8f7d2137727a 7 *
rgrover1 371:8f7d2137727a 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 371:8f7d2137727a 9 * list of conditions and the following disclaimer.
rgrover1 371:8f7d2137727a 10 *
rgrover1 371:8f7d2137727a 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 371:8f7d2137727a 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 371:8f7d2137727a 13 * other materials provided with the distribution.
rgrover1 371:8f7d2137727a 14 *
rgrover1 371:8f7d2137727a 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 371:8f7d2137727a 16 * contributors to this software may be used to endorse or promote products
rgrover1 371:8f7d2137727a 17 * derived from this software without specific prior written permission.
rgrover1 371:8f7d2137727a 18 *
rgrover1 371:8f7d2137727a 19 *
rgrover1 371:8f7d2137727a 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 371:8f7d2137727a 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 371:8f7d2137727a 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 371:8f7d2137727a 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 371:8f7d2137727a 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 371:8f7d2137727a 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 371:8f7d2137727a 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 371:8f7d2137727a 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 371:8f7d2137727a 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 371:8f7d2137727a 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 371:8f7d2137727a 30 *
rgrover1 371:8f7d2137727a 31 */
rgrover1 371:8f7d2137727a 32
rgrover1 371:8f7d2137727a 33 /**
rgrover1 371:8f7d2137727a 34 @addtogroup BLE_COMMON BLE SoftDevice Common
rgrover1 371:8f7d2137727a 35 @{
rgrover1 371:8f7d2137727a 36 @defgroup ble_api Events, type definitions and API calls
rgrover1 371:8f7d2137727a 37 @{
rgrover1 371:8f7d2137727a 38
rgrover1 371:8f7d2137727a 39 @brief Module independent events, type definitions and API calls for the BLE SoftDevice.
rgrover1 371:8f7d2137727a 40
rgrover1 371:8f7d2137727a 41 */
rgrover1 371:8f7d2137727a 42
rgrover1 371:8f7d2137727a 43 #ifndef BLE_H__
rgrover1 371:8f7d2137727a 44 #define BLE_H__
rgrover1 371:8f7d2137727a 45
rgrover1 371:8f7d2137727a 46 #include "ble_ranges.h"
rgrover1 371:8f7d2137727a 47 #include "ble_types.h"
rgrover1 371:8f7d2137727a 48 #include "ble_gap.h"
rgrover1 371:8f7d2137727a 49 #include "ble_l2cap.h"
rgrover1 371:8f7d2137727a 50 #include "ble_gatt.h"
rgrover1 371:8f7d2137727a 51 #include "ble_gattc.h"
rgrover1 371:8f7d2137727a 52 #include "ble_gatts.h"
rgrover1 371:8f7d2137727a 53
rgrover1 371:8f7d2137727a 54 /** @addtogroup BLE_COMMON_ENUMERATIONS Enumerations
rgrover1 371:8f7d2137727a 55 * @{ */
rgrover1 371:8f7d2137727a 56
rgrover1 371:8f7d2137727a 57 /**
rgrover1 371:8f7d2137727a 58 * @brief Common API SVC numbers.
rgrover1 371:8f7d2137727a 59 */
rgrover1 371:8f7d2137727a 60 enum BLE_COMMON_SVCS
rgrover1 371:8f7d2137727a 61 {
rgrover1 371:8f7d2137727a 62 SD_BLE_ENABLE = BLE_SVC_BASE, /**< Enable and initialize the BLE stack */
rgrover1 371:8f7d2137727a 63 SD_BLE_EVT_GET, /**< Get an event from the pending events queue. */
rgrover1 371:8f7d2137727a 64 SD_BLE_TX_BUFFER_COUNT_GET, /**< Get the total number of available application transmission buffers from the BLE stack. */
rgrover1 371:8f7d2137727a 65 SD_BLE_UUID_VS_ADD, /**< Add a Vendor Specific UUID. */
rgrover1 371:8f7d2137727a 66 SD_BLE_UUID_DECODE, /**< Decode UUID bytes. */
rgrover1 371:8f7d2137727a 67 SD_BLE_UUID_ENCODE, /**< Encode UUID bytes. */
rgrover1 371:8f7d2137727a 68 SD_BLE_VERSION_GET, /**< Get the local version information (company id, Link Layer Version, Link Layer Subversion). */
rgrover1 371:8f7d2137727a 69 SD_BLE_USER_MEM_REPLY, /**< User Memory Reply. */
rgrover1 371:8f7d2137727a 70 SD_BLE_OPT_SET, /**< Set a BLE option. */
rgrover1 371:8f7d2137727a 71 SD_BLE_OPT_GET, /**< Get a BLE option. */
rgrover1 371:8f7d2137727a 72 };
rgrover1 371:8f7d2137727a 73
rgrover1 371:8f7d2137727a 74 /**
rgrover1 371:8f7d2137727a 75 * @brief BLE Module Independent Event IDs.
rgrover1 371:8f7d2137727a 76 */
rgrover1 371:8f7d2137727a 77 enum BLE_COMMON_EVTS
rgrover1 371:8f7d2137727a 78 {
rgrover1 371:8f7d2137727a 79 BLE_EVT_TX_COMPLETE = BLE_EVT_BASE, /**< Transmission Complete. @ref ble_evt_tx_complete_t */
rgrover1 371:8f7d2137727a 80 BLE_EVT_USER_MEM_REQUEST, /**< User Memory request. @ref ble_evt_user_mem_request_t */
rgrover1 371:8f7d2137727a 81 BLE_EVT_USER_MEM_RELEASE /**< User Memory release. @ref ble_evt_user_mem_release_t */
rgrover1 371:8f7d2137727a 82 };
rgrover1 371:8f7d2137727a 83
rgrover1 371:8f7d2137727a 84 /**@brief Common Option IDs.
rgrover1 371:8f7d2137727a 85 * IDs that uniquely identify a common option.
rgrover1 371:8f7d2137727a 86 */
rgrover1 371:8f7d2137727a 87 enum BLE_COMMON_OPTS
rgrover1 371:8f7d2137727a 88 {
rgrover1 371:8f7d2137727a 89 BLE_COMMON_OPT_RADIO_CPU_MUTEX = BLE_OPT_BASE /**< Radio CPU mutex option. @ref ble_common_opt_radio_cpu_mutex_t */
rgrover1 371:8f7d2137727a 90 };
rgrover1 371:8f7d2137727a 91 /** @} */
rgrover1 371:8f7d2137727a 92
rgrover1 371:8f7d2137727a 93 /** @addtogroup BLE_COMMON_DEFINES Defines
rgrover1 371:8f7d2137727a 94 * @{ */
rgrover1 371:8f7d2137727a 95
rgrover1 371:8f7d2137727a 96 /** @brief Required pointer alignment for BLE Events.
rgrover1 371:8f7d2137727a 97 */
rgrover1 371:8f7d2137727a 98 #define BLE_EVTS_PTR_ALIGNMENT 4
rgrover1 371:8f7d2137727a 99
rgrover1 371:8f7d2137727a 100 /** @defgroup BLE_USER_MEM_TYPES User Memory Types
rgrover1 371:8f7d2137727a 101 * @{ */
rgrover1 371:8f7d2137727a 102 #define BLE_USER_MEM_TYPE_INVALID 0x00 /**< Invalid User Memory Types. */
rgrover1 371:8f7d2137727a 103 #define BLE_USER_MEM_TYPE_GATTS_QUEUED_WRITES 0x01 /**< User Memory for GATTS queued writes. */
rgrover1 371:8f7d2137727a 104 /** @} */
rgrover1 371:8f7d2137727a 105
rgrover1 371:8f7d2137727a 106 /** @brief Maximum number of Vendor Specific UUIDs.
rgrover1 371:8f7d2137727a 107 */
rgrover1 371:8f7d2137727a 108 #define BLE_UUID_VS_MAX_COUNT 10
rgrover1 371:8f7d2137727a 109
rgrover1 371:8f7d2137727a 110 /** @} */
rgrover1 371:8f7d2137727a 111
rgrover1 371:8f7d2137727a 112 /** @addtogroup BLE_COMMON_STRUCTURES Structures
rgrover1 371:8f7d2137727a 113 * @{ */
rgrover1 371:8f7d2137727a 114
rgrover1 371:8f7d2137727a 115 /**@brief User Memory Block. */
rgrover1 371:8f7d2137727a 116 typedef struct
rgrover1 371:8f7d2137727a 117 {
rgrover1 371:8f7d2137727a 118 uint8_t *p_mem; /**< Pointer to the start of the user memory block. */
rgrover1 371:8f7d2137727a 119 uint16_t len; /**< Length in bytes of the user memory block. */
rgrover1 371:8f7d2137727a 120 } ble_user_mem_block_t;
rgrover1 371:8f7d2137727a 121
rgrover1 371:8f7d2137727a 122 /**
rgrover1 371:8f7d2137727a 123 * @brief Event structure for @ref BLE_EVT_TX_COMPLETE.
rgrover1 371:8f7d2137727a 124 */
rgrover1 371:8f7d2137727a 125 typedef struct
rgrover1 371:8f7d2137727a 126 {
rgrover1 371:8f7d2137727a 127 uint8_t count; /**< Number of packets transmitted. */
rgrover1 371:8f7d2137727a 128 } ble_evt_tx_complete_t;
rgrover1 371:8f7d2137727a 129
rgrover1 371:8f7d2137727a 130 /**@brief Event structure for @ref BLE_EVT_USER_MEM_REQUEST. */
rgrover1 371:8f7d2137727a 131 typedef struct
rgrover1 371:8f7d2137727a 132 {
rgrover1 371:8f7d2137727a 133 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */
rgrover1 371:8f7d2137727a 134 } ble_evt_user_mem_request_t;
rgrover1 371:8f7d2137727a 135
rgrover1 371:8f7d2137727a 136 /**@brief Event structure for @ref BLE_EVT_USER_MEM_RELEASE. */
rgrover1 371:8f7d2137727a 137 typedef struct
rgrover1 371:8f7d2137727a 138 {
rgrover1 371:8f7d2137727a 139 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */
rgrover1 371:8f7d2137727a 140 ble_user_mem_block_t mem_block; /**< User memory block */
rgrover1 371:8f7d2137727a 141 } ble_evt_user_mem_release_t;
rgrover1 371:8f7d2137727a 142
rgrover1 371:8f7d2137727a 143
rgrover1 371:8f7d2137727a 144 /**@brief Event structure for events not associated with a specific function module. */
rgrover1 371:8f7d2137727a 145 typedef struct
rgrover1 371:8f7d2137727a 146 {
rgrover1 371:8f7d2137727a 147 uint16_t conn_handle; /**< Connection Handle on which this event occurred. */
rgrover1 371:8f7d2137727a 148 union
rgrover1 371:8f7d2137727a 149 {
rgrover1 371:8f7d2137727a 150 ble_evt_tx_complete_t tx_complete; /**< Transmission Complete. */
rgrover1 371:8f7d2137727a 151 ble_evt_user_mem_request_t user_mem_request; /**< User Memory Request Event Parameters. */
rgrover1 371:8f7d2137727a 152 ble_evt_user_mem_release_t user_mem_release; /**< User Memory Release Event Parameters. */
rgrover1 371:8f7d2137727a 153 } params;
rgrover1 371:8f7d2137727a 154 } ble_common_evt_t;
rgrover1 371:8f7d2137727a 155
rgrover1 371:8f7d2137727a 156 /**@brief BLE Event header. */
rgrover1 371:8f7d2137727a 157 typedef struct
rgrover1 371:8f7d2137727a 158 {
rgrover1 371:8f7d2137727a 159 uint16_t evt_id; /**< Value from a BLE_<module>_EVT series. */
rgrover1 371:8f7d2137727a 160 uint16_t evt_len; /**< Length in octets excluding this header. */
rgrover1 371:8f7d2137727a 161 } ble_evt_hdr_t;
rgrover1 371:8f7d2137727a 162
rgrover1 371:8f7d2137727a 163 /**@brief Common BLE Event type, wrapping the module specific event reports. */
rgrover1 371:8f7d2137727a 164 typedef struct
rgrover1 371:8f7d2137727a 165 {
rgrover1 371:8f7d2137727a 166 ble_evt_hdr_t header; /**< Event header. */
rgrover1 371:8f7d2137727a 167 union
rgrover1 371:8f7d2137727a 168 {
rgrover1 371:8f7d2137727a 169 ble_common_evt_t common_evt; /**< Common Event, evt_id in BLE_EVT_* series. */
rgrover1 371:8f7d2137727a 170 ble_gap_evt_t gap_evt; /**< GAP originated event, evt_id in BLE_GAP_EVT_* series. */
rgrover1 371:8f7d2137727a 171 ble_l2cap_evt_t l2cap_evt; /**< L2CAP originated event, evt_id in BLE_L2CAP_EVT* series. */
rgrover1 371:8f7d2137727a 172 ble_gattc_evt_t gattc_evt; /**< GATT client originated event, evt_id in BLE_GATTC_EVT* series. */
rgrover1 371:8f7d2137727a 173 ble_gatts_evt_t gatts_evt; /**< GATT server originated event, evt_id in BLE_GATTS_EVT* series. */
rgrover1 371:8f7d2137727a 174 } evt;
rgrover1 371:8f7d2137727a 175 } ble_evt_t;
rgrover1 371:8f7d2137727a 176
rgrover1 371:8f7d2137727a 177
rgrover1 371:8f7d2137727a 178 /**
rgrover1 371:8f7d2137727a 179 * @brief Version Information.
rgrover1 371:8f7d2137727a 180 */
rgrover1 371:8f7d2137727a 181 typedef struct
rgrover1 371:8f7d2137727a 182 {
rgrover1 371:8f7d2137727a 183 uint8_t version_number; /**< Link Layer Version number for BT 4.1 spec is 7 (https://www.bluetooth.org/en-us/specification/assigned-numbers/link-layer). */
rgrover1 371:8f7d2137727a 184 uint16_t company_id; /**< Company ID, Nordic Semiconductor's company ID is 89 (0x0059) (https://www.bluetooth.org/apps/content/Default.aspx?doc_id=49708). */
rgrover1 371:8f7d2137727a 185 uint16_t subversion_number; /**< Link Layer Sub Version number, corresponds to the SoftDevice Config ID or Firmware ID (FWID). */
rgrover1 371:8f7d2137727a 186 } ble_version_t;
rgrover1 371:8f7d2137727a 187
rgrover1 371:8f7d2137727a 188 /**@brief Mutual exclusion of radio activity and CPU execution.
rgrover1 371:8f7d2137727a 189 *
rgrover1 371:8f7d2137727a 190 * This option configures the application's access to the CPU when the radio is active. The
rgrover1 371:8f7d2137727a 191 * application can configure itself to be blocked from using the CPU while the radio is
rgrover1 371:8f7d2137727a 192 * active. By default, the application will be able to share CPU time with the SoftDevice
rgrover1 371:8f7d2137727a 193 * during radio activity. This parameter structure is used together with @ref sd_ble_opt_set
rgrover1 371:8f7d2137727a 194 * to configure the @ref BLE_COMMON_OPT_RADIO_CPU_MUTEX option.
rgrover1 371:8f7d2137727a 195 *
rgrover1 371:8f7d2137727a 196 * @note Note that the application should use this option to configure the SoftDevice to block the
rgrover1 371:8f7d2137727a 197 * CPU during radio activity (i.e enable mutual exclusion) when running the SoftDevice on
rgrover1 371:8f7d2137727a 198 * hardware affected by PAN #44 "CCM may exceed real time requirements"and PAN #45 "AAR may
rgrover1 371:8f7d2137727a 199 * exceed real time requirements".
rgrover1 371:8f7d2137727a 200 *
rgrover1 371:8f7d2137727a 201 * @note Note that when acting as a scanner, the mutex is only enabled for radio TX activity.
rgrover1 371:8f7d2137727a 202 *
rgrover1 371:8f7d2137727a 203 * @note @ref sd_ble_opt_get is not supported for this option.
rgrover1 371:8f7d2137727a 204 *
rgrover1 371:8f7d2137727a 205 */
rgrover1 371:8f7d2137727a 206 typedef struct
rgrover1 371:8f7d2137727a 207 {
rgrover1 371:8f7d2137727a 208 uint8_t enable : 1; /**< Enable mutual exclusion of radio activity and the CPU execution. */
rgrover1 371:8f7d2137727a 209 } ble_common_opt_radio_cpu_mutex_t;
rgrover1 371:8f7d2137727a 210
rgrover1 371:8f7d2137727a 211 /**@brief Option structure for common options. */
rgrover1 371:8f7d2137727a 212 typedef union
rgrover1 371:8f7d2137727a 213 {
rgrover1 371:8f7d2137727a 214 ble_common_opt_radio_cpu_mutex_t radio_cpu_mutex; /**< Parameters for the option for the mutual exclusion of radio activity and CPU execution. */
rgrover1 371:8f7d2137727a 215 } ble_common_opt_t;
rgrover1 371:8f7d2137727a 216
rgrover1 371:8f7d2137727a 217 /**@brief Common BLE Option type, wrapping the module specific options. */
rgrover1 371:8f7d2137727a 218 typedef union
rgrover1 371:8f7d2137727a 219 {
rgrover1 371:8f7d2137727a 220 ble_common_opt_t common_opt; /**< Common option, opt_id in BLE_COMMON_OPT_* series. */
rgrover1 371:8f7d2137727a 221 ble_gap_opt_t gap_opt; /**< GAP option, opt_id in BLE_GAP_OPT_* series. */
rgrover1 371:8f7d2137727a 222 } ble_opt_t;
rgrover1 371:8f7d2137727a 223
rgrover1 371:8f7d2137727a 224 /**
rgrover1 371:8f7d2137727a 225 * @brief BLE GATTS init options
rgrover1 371:8f7d2137727a 226 */
rgrover1 371:8f7d2137727a 227 typedef struct
rgrover1 371:8f7d2137727a 228 {
rgrover1 371:8f7d2137727a 229 ble_gatts_enable_params_t gatts_enable_params; /**< GATTS init options @ref ble_gatts_enable_params_t. */
rgrover1 371:8f7d2137727a 230 } ble_enable_params_t;
rgrover1 371:8f7d2137727a 231
rgrover1 371:8f7d2137727a 232 /** @} */
rgrover1 371:8f7d2137727a 233
rgrover1 371:8f7d2137727a 234 /** @addtogroup BLE_COMMON_FUNCTIONS Functions
rgrover1 371:8f7d2137727a 235 * @{ */
rgrover1 371:8f7d2137727a 236
rgrover1 371:8f7d2137727a 237 /**@brief Enable the BLE stack
rgrover1 371:8f7d2137727a 238 *
rgrover1 371:8f7d2137727a 239 * @param[in] p_ble_enable_params Pointer to ble_enable_params_t
rgrover1 371:8f7d2137727a 240 *
rgrover1 371:8f7d2137727a 241 * @details This call initializes the BLE stack, no other BLE related function can be called before this one.
rgrover1 371:8f7d2137727a 242 *
rgrover1 371:8f7d2137727a 243 * @return @ref NRF_SUCCESS BLE the BLE stack has been initialized successfully
rgrover1 371:8f7d2137727a 244 * @retval @ref NRF_ERROR_INVALID_STATE the BLE stack had already been initialized and cannot be reinitialized.
rgrover1 371:8f7d2137727a 245 * @return @ref NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied.
rgrover1 371:8f7d2137727a 246 * @return @ref NRF_ERROR_INVALID_LENGTH The specified Attribute Table size is either too small or not a multiple of 4.
rgrover1 371:8f7d2137727a 247 * The minimum acceptable size is defined by @ref BLE_GATTS_ATTR_TAB_SIZE_MIN.
rgrover1 371:8f7d2137727a 248 * @return @ref NRF_ERROR_NO_MEM The Attribute Table size is too large. Decrease size in @ref ble_gatts_enable_params_t.
rgrover1 371:8f7d2137727a 249 */
rgrover1 371:8f7d2137727a 250 SVCALL(SD_BLE_ENABLE, uint32_t, sd_ble_enable(ble_enable_params_t * p_ble_enable_params));
rgrover1 371:8f7d2137727a 251
rgrover1 371:8f7d2137727a 252 /**@brief Get an event from the pending events queue.
rgrover1 371:8f7d2137727a 253 *
rgrover1 371:8f7d2137727a 254 * @param[out] p_dest Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer <b>must be 4-byte aligned in memory</b>.
rgrover1 371:8f7d2137727a 255 * @param[in, out] p_len Pointer the length of the buffer, on return it is filled with the event length.
rgrover1 371:8f7d2137727a 256 *
rgrover1 371:8f7d2137727a 257 * @details This call allows the application to pull a BLE event from the BLE stack. The application is signalled that an event is
rgrover1 371:8f7d2137727a 258 * available from the BLE stack by the triggering of the SD_EVT_IRQn interrupt.
rgrover1 371:8f7d2137727a 259 * The application is free to choose whether to call this function from thread mode (main context) or directly from the Interrupt Service Routine
rgrover1 371:8f7d2137727a 260 * that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher priority than the application, this function should be called
rgrover1 371:8f7d2137727a 261 * in a loop (until @ref NRF_ERROR_NOT_FOUND is returned) every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the BLE stack.
rgrover1 371:8f7d2137727a 262 * Failure to do so could potentially leave events in the internal queue without the application being aware of this fact.
rgrover1 371:8f7d2137727a 263 * Sizing the p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to be copied into
rgrover1 371:8f7d2137727a 264 * application memory. If the buffer provided is not large enough to fit the entire contents of the event, @ref NRF_ERROR_DATA_SIZE will be returned
rgrover1 371:8f7d2137727a 265 * and the application can then call again with a larger buffer size.
rgrover1 371:8f7d2137727a 266 * Please note that because of the variable length nature of some events, sizeof(ble_evt_t) will not always be large enough to fit certain events,
rgrover1 371:8f7d2137727a 267 * and so it is the application's responsibility to provide an amount of memory large enough so that the relevant event is copied in full.
rgrover1 371:8f7d2137727a 268 * The application may "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return.
rgrover1 371:8f7d2137727a 269 *
rgrover1 371:8f7d2137727a 270 * @note The pointer supplied must be aligned to the extend defined by @ref BLE_EVTS_PTR_ALIGNMENT
rgrover1 371:8f7d2137727a 271 *
rgrover1 371:8f7d2137727a 272 * @retval ::NRF_SUCCESS Event pulled and stored into the supplied buffer.
rgrover1 371:8f7d2137727a 273 * @retval ::NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied.
rgrover1 371:8f7d2137727a 274 * @retval ::NRF_ERROR_NOT_FOUND No events ready to be pulled.
rgrover1 371:8f7d2137727a 275 * @retval ::NRF_ERROR_DATA_SIZE Event ready but could not fit into the supplied buffer.
rgrover1 371:8f7d2137727a 276 */
rgrover1 371:8f7d2137727a 277 SVCALL(SD_BLE_EVT_GET, uint32_t, sd_ble_evt_get(uint8_t *p_dest, uint16_t *p_len));
rgrover1 371:8f7d2137727a 278
rgrover1 371:8f7d2137727a 279
rgrover1 371:8f7d2137727a 280 /**@brief Get the total number of available application transmission buffers per link in the BLE stack.
rgrover1 371:8f7d2137727a 281 *
rgrover1 371:8f7d2137727a 282 * @details This call allows the application to obtain the total number of
rgrover1 371:8f7d2137727a 283 * transmission buffers available per link for application data. Please note that
rgrover1 371:8f7d2137727a 284 * this does not give the number of free buffers, but rather the total amount of them.
rgrover1 371:8f7d2137727a 285 * The application has two options to handle its own application transmission buffers:
rgrover1 371:8f7d2137727a 286 * - Use a simple arithmetic calculation: at boot time the application should use this function
rgrover1 371:8f7d2137727a 287 * to find out the total amount of buffers available to it and store it in a variable.
rgrover1 371:8f7d2137727a 288 * Every time a packet that consumes an application buffer is sent using any of the
rgrover1 371:8f7d2137727a 289 * exposed functions in this BLE API, the application should decrement that variable.
rgrover1 371:8f7d2137727a 290 * Conversely, whenever a @ref BLE_EVT_TX_COMPLETE event is received by the application
rgrover1 371:8f7d2137727a 291 * it should retrieve the count field in such event and add that number to the same
rgrover1 371:8f7d2137727a 292 * variable storing the number of available packets.
rgrover1 371:8f7d2137727a 293 * This mechanism allows the application to be aware at any time of the number of
rgrover1 371:8f7d2137727a 294 * application packets available in the BLE stack's internal buffers, and therefore
rgrover1 371:8f7d2137727a 295 * it can know with certainty whether it is possible to send more data or it has to
rgrover1 371:8f7d2137727a 296 * wait for a @ref BLE_EVT_TX_COMPLETE event before it proceeds.
rgrover1 371:8f7d2137727a 297 * - Choose to simply not keep track of available buffers at all, and instead handle the
rgrover1 371:8f7d2137727a 298 * @ref BLE_ERROR_NO_TX_BUFFERS error by queueing the packet to be transmitted and
rgrover1 371:8f7d2137727a 299 * try again as soon as a @ref BLE_EVT_TX_COMPLETE event arrives.
rgrover1 371:8f7d2137727a 300 *
rgrover1 371:8f7d2137727a 301 * The API functions that <b>may</b> consume an application buffer depending on
rgrover1 371:8f7d2137727a 302 * the parameters supplied to them can be found below:
rgrover1 371:8f7d2137727a 303 *
rgrover1 371:8f7d2137727a 304 * - @ref sd_ble_gattc_write (write without response only)
rgrover1 371:8f7d2137727a 305 * - @ref sd_ble_gatts_hvx (notifications only)
rgrover1 371:8f7d2137727a 306 * - @ref sd_ble_l2cap_tx (all packets)
rgrover1 371:8f7d2137727a 307 *
rgrover1 371:8f7d2137727a 308 * @param[out] p_count Pointer to a uint8_t which will contain the number of application transmission buffers upon
rgrover1 371:8f7d2137727a 309 * successful return.
rgrover1 371:8f7d2137727a 310 *
rgrover1 371:8f7d2137727a 311 * @retval ::NRF_SUCCESS Number of application transmission buffers retrieved successfully.
rgrover1 371:8f7d2137727a 312 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 313 */
rgrover1 371:8f7d2137727a 314 SVCALL(SD_BLE_TX_BUFFER_COUNT_GET, uint32_t, sd_ble_tx_buffer_count_get(uint8_t *p_count));
rgrover1 371:8f7d2137727a 315
rgrover1 371:8f7d2137727a 316
rgrover1 371:8f7d2137727a 317 /**@brief Add a Vendor Specific UUID.
rgrover1 371:8f7d2137727a 318 *
rgrover1 371:8f7d2137727a 319 * @details This call enables the application to add a vendor specific UUID to the BLE stack's table,
rgrover1 371:8f7d2137727a 320 * for later use all other modules and APIs. This then allows the application to use the shorter,
rgrover1 371:8f7d2137727a 321 * 24-bit @ref ble_uuid_t format when dealing with both 16-bit and 128-bit UUIDs without having to
rgrover1 371:8f7d2137727a 322 * check for lengths and having split code paths. The way that this is accomplished is by extending the
rgrover1 371:8f7d2137727a 323 * grouping mechanism that the Bluetooth SIG standard base UUID uses for all other 128-bit UUIDs. The
rgrover1 371:8f7d2137727a 324 * type field in the @ref ble_uuid_t structure is an index (relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN)
rgrover1 371:8f7d2137727a 325 * to the table populated by multiple calls to this function, and the uuid field in the same structure
rgrover1 371:8f7d2137727a 326 * contains the 2 bytes at indices 12 and 13. The number of possible 128-bit UUIDs available to the
rgrover1 371:8f7d2137727a 327 * application is therefore the number of Vendor Specific UUIDs added with the help of this function times 65536,
rgrover1 371:8f7d2137727a 328 * although restricted to modifying bytes 12 and 13 for each of the entries in the supplied array.
rgrover1 371:8f7d2137727a 329 *
rgrover1 371:8f7d2137727a 330 * @note Bytes 12 and 13 of the provided UUID will not be used internally, since those are always replaced by
rgrover1 371:8f7d2137727a 331 * the 16-bit uuid field in @ref ble_uuid_t.
rgrover1 371:8f7d2137727a 332 *
rgrover1 371:8f7d2137727a 333 *
rgrover1 371:8f7d2137727a 334 * @param[in] p_vs_uuid Pointer to a 16-octet (128-bit) little endian Vendor Specific UUID disregarding
rgrover1 371:8f7d2137727a 335 * bytes 12 and 13.
rgrover1 371:8f7d2137727a 336 * @param[out] p_uuid_type Pointer to a uint8_t where the type field in @ref ble_uuid_t corresponding to this UUID will be stored.
rgrover1 371:8f7d2137727a 337 *
rgrover1 371:8f7d2137727a 338 * @retval ::NRF_SUCCESS Successfully added the Vendor Specific UUID.
rgrover1 371:8f7d2137727a 339 * @retval ::NRF_ERROR_INVALID_ADDR If p_vs_uuid or p_uuid_type is NULL or invalid.
rgrover1 371:8f7d2137727a 340 * @retval ::NRF_ERROR_NO_MEM If there are no more free slots for VS UUIDs.
rgrover1 371:8f7d2137727a 341 * @retval ::NRF_ERROR_FORBIDDEN If p_vs_uuid has already been added to the VS UUID table.
rgrover1 371:8f7d2137727a 342 */
rgrover1 371:8f7d2137727a 343 SVCALL(SD_BLE_UUID_VS_ADD, uint32_t, sd_ble_uuid_vs_add(ble_uuid128_t const *p_vs_uuid, uint8_t *p_uuid_type));
rgrover1 371:8f7d2137727a 344
rgrover1 371:8f7d2137727a 345
rgrover1 371:8f7d2137727a 346 /** @brief Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit @ref ble_uuid_t structure.
rgrover1 371:8f7d2137727a 347 *
rgrover1 371:8f7d2137727a 348 * @details The raw UUID bytes excluding bytes 12 and 13 (i.e. bytes 0-11 and 14-15) of p_uuid_le are compared
rgrover1 371:8f7d2137727a 349 * to the corresponding ones in each entry of the table of vendor specific UUIDs populated with @ref sd_ble_uuid_vs_add
rgrover1 371:8f7d2137727a 350 * to look for a match. If there is such a match, bytes 12 and 13 are returned as p_uuid->uuid and the index
rgrover1 371:8f7d2137727a 351 * relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN as p_uuid->type.
rgrover1 371:8f7d2137727a 352 *
rgrover1 371:8f7d2137727a 353 * @note If the UUID length supplied is 2, then the type set by this call will always be @ref BLE_UUID_TYPE_BLE.
rgrover1 371:8f7d2137727a 354 *
rgrover1 371:8f7d2137727a 355 * @param[in] uuid_le_len Length in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes).
rgrover1 371:8f7d2137727a 356 * @param[in] p_uuid_le Pointer pointing to little endian raw UUID bytes.
rgrover1 371:8f7d2137727a 357 * @param[out] p_uuid Pointer to a @ref ble_uuid_t structure to be filled in.
rgrover1 371:8f7d2137727a 358 *
rgrover1 371:8f7d2137727a 359 * @retval ::NRF_SUCCESS Successfully decoded into the @ref ble_uuid_t structure.
rgrover1 371:8f7d2137727a 360 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 361 * @retval ::NRF_ERROR_INVALID_LENGTH Invalid UUID length.
rgrover1 371:8f7d2137727a 362 * @retval ::NRF_ERROR_NOT_FOUND For a 128-bit UUID, no match in the populated table of UUIDs.
rgrover1 371:8f7d2137727a 363 */
rgrover1 371:8f7d2137727a 364 SVCALL(SD_BLE_UUID_DECODE, uint32_t, sd_ble_uuid_decode(uint8_t uuid_le_len, uint8_t const *p_uuid_le, ble_uuid_t *p_uuid));
rgrover1 371:8f7d2137727a 365
rgrover1 371:8f7d2137727a 366
rgrover1 371:8f7d2137727a 367 /** @brief Encode a @ref ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit).
rgrover1 371:8f7d2137727a 368 *
rgrover1 371:8f7d2137727a 369 * @note The pointer to the destination buffer p_uuid_le may be NULL, in which case only the validity and size of p_uuid is computed.
rgrover1 371:8f7d2137727a 370 *
rgrover1 371:8f7d2137727a 371 * @param[in] p_uuid Pointer to a @ref ble_uuid_t structure that will be encoded into bytes.
rgrover1 371:8f7d2137727a 372 * @param[out] p_uuid_le_len Pointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes).
rgrover1 371:8f7d2137727a 373 * @param[out] p_uuid_le Pointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored.
rgrover1 371:8f7d2137727a 374 *
rgrover1 371:8f7d2137727a 375 * @retval ::NRF_SUCCESS Successfully encoded into the buffer.
rgrover1 371:8f7d2137727a 376 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 377 * @retval ::NRF_ERROR_INVALID_PARAM Invalid UUID type.
rgrover1 371:8f7d2137727a 378 */
rgrover1 371:8f7d2137727a 379 SVCALL(SD_BLE_UUID_ENCODE, uint32_t, sd_ble_uuid_encode(ble_uuid_t const *p_uuid, uint8_t *p_uuid_le_len, uint8_t *p_uuid_le));
rgrover1 371:8f7d2137727a 380
rgrover1 371:8f7d2137727a 381
rgrover1 371:8f7d2137727a 382 /**@brief Get Version Information.
rgrover1 371:8f7d2137727a 383 *
rgrover1 371:8f7d2137727a 384 * @details This call allows the application to get the BLE stack version information.
rgrover1 371:8f7d2137727a 385 *
rgrover1 371:8f7d2137727a 386 * @param[out] p_version Pointer to a ble_version_t structure to be filled in.
rgrover1 371:8f7d2137727a 387 *
rgrover1 371:8f7d2137727a 388 * @retval ::NRF_SUCCESS Version information stored successfully.
rgrover1 371:8f7d2137727a 389 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 390 * @retval ::NRF_ERROR_BUSY The BLE stack is busy (typically doing a locally-initiated disconnection procedure).
rgrover1 371:8f7d2137727a 391 */
rgrover1 371:8f7d2137727a 392 SVCALL(SD_BLE_VERSION_GET, uint32_t, sd_ble_version_get(ble_version_t *p_version));
rgrover1 371:8f7d2137727a 393
rgrover1 371:8f7d2137727a 394
rgrover1 371:8f7d2137727a 395 /**@brief Provide a user memory block.
rgrover1 371:8f7d2137727a 396 *
rgrover1 371:8f7d2137727a 397 * @note This call can only be used as a response to a @ref BLE_EVT_USER_MEM_REQUEST event issued to the application.
rgrover1 371:8f7d2137727a 398 *
rgrover1 371:8f7d2137727a 399 * @param[in] conn_handle Connection handle.
rgrover1 371:8f7d2137727a 400 * @param[in,out] p_block Pointer to a user memory block structure.
rgrover1 371:8f7d2137727a 401 *
rgrover1 371:8f7d2137727a 402 * @retval ::NRF_SUCCESS Successfully queued a response to the peer.
rgrover1 371:8f7d2137727a 403 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 371:8f7d2137727a 404 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection state or no execute write request pending.
rgrover1 371:8f7d2137727a 405 * @retval ::NRF_ERROR_BUSY The BLE stack is busy. Retry at later time.
rgrover1 371:8f7d2137727a 406 */
rgrover1 371:8f7d2137727a 407 SVCALL(SD_BLE_USER_MEM_REPLY, uint32_t, sd_ble_user_mem_reply(uint16_t conn_handle, ble_user_mem_block_t const *p_block));
rgrover1 371:8f7d2137727a 408
rgrover1 371:8f7d2137727a 409 /**@brief Set a BLE option.
rgrover1 371:8f7d2137727a 410 *
rgrover1 371:8f7d2137727a 411 * @details This call allows the application to set the value of an option.
rgrover1 371:8f7d2137727a 412 *
rgrover1 371:8f7d2137727a 413 * @param[in] opt_id Option ID.
rgrover1 371:8f7d2137727a 414 * @param[in] p_opt Pointer to a ble_opt_t structure containing the option value.
rgrover1 371:8f7d2137727a 415 *
rgrover1 371:8f7d2137727a 416 * @retval ::NRF_SUCCESS Option set successfully.
rgrover1 371:8f7d2137727a 417 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 418 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 371:8f7d2137727a 419 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
rgrover1 371:8f7d2137727a 420 * @retval ::NRF_ERROR_INVALID_STATE Unable to set the parameter at this time.
rgrover1 371:8f7d2137727a 421 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed.
rgrover1 371:8f7d2137727a 422 */
rgrover1 371:8f7d2137727a 423 SVCALL(SD_BLE_OPT_SET, uint32_t, sd_ble_opt_set(uint32_t opt_id, ble_opt_t const *p_opt));
rgrover1 371:8f7d2137727a 424
rgrover1 371:8f7d2137727a 425
rgrover1 371:8f7d2137727a 426 /**@brief Get a BLE option.
rgrover1 371:8f7d2137727a 427 *
rgrover1 371:8f7d2137727a 428 * @details This call allows the application to retrieve the value of an option.
rgrover1 371:8f7d2137727a 429 *
rgrover1 371:8f7d2137727a 430 * @param[in] opt_id Option ID.
rgrover1 371:8f7d2137727a 431 * @param[out] p_opt Pointer to a ble_opt_t structure to be filled in.
rgrover1 371:8f7d2137727a 432 *
rgrover1 371:8f7d2137727a 433 * @retval ::NRF_SUCCESS Option retrieved successfully.
rgrover1 371:8f7d2137727a 434 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 371:8f7d2137727a 435 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 371:8f7d2137727a 436 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
rgrover1 371:8f7d2137727a 437 * @retval ::NRF_ERROR_INVALID_STATE Unable to retrieve the parameter at this time.
rgrover1 371:8f7d2137727a 438 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed.
rgrover1 371:8f7d2137727a 439 * @retval ::NRF_ERROR_NOT_SUPPORTED This option is not supported.
rgrover1 371:8f7d2137727a 440 *
rgrover1 371:8f7d2137727a 441 */
rgrover1 371:8f7d2137727a 442 SVCALL(SD_BLE_OPT_GET, uint32_t, sd_ble_opt_get(uint32_t opt_id, ble_opt_t *p_opt));
rgrover1 371:8f7d2137727a 443
rgrover1 371:8f7d2137727a 444 /** @} */
rgrover1 371:8f7d2137727a 445
rgrover1 371:8f7d2137727a 446 #endif /* BLE_H__ */
rgrover1 371:8f7d2137727a 447
rgrover1 371:8f7d2137727a 448 /**
rgrover1 371:8f7d2137727a 449 @}
rgrover1 371:8f7d2137727a 450 @}
rgrover1 371:8f7d2137727a 451 */