Michael Galis / nRF51822

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of nRF51822 by Nordic Semiconductor

nordic-sdk/components/softdevice/s130/include/ble.h@362:6fa0d4d555f6, 2015-07-02 (annotated)

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