Wendy Warne
updates
Fork of
nrf51-sdk
by 
Lancaster University
Embed:
(wiki syntax)
Show/hide line numbers
ble_gap.h
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /** 00034 @addtogroup BLE_GAP Generic Access Profile (GAP) 00035 @{ 00036 @brief Definitions and prototypes for the GAP interface. 00037 */ 00038 00039 #ifndef BLE_GAP_H__ 00040 #define BLE_GAP_H__ 00041 00042 #include "ble_types.h" 00043 #include "ble_ranges.h" 00044 #include "nrf_svc.h" 00045 00046 /**@addtogroup BLE_GAP_ENUMERATIONS Enumerations 00047 * @{ */ 00048 00049 /**@brief GAP API SVC numbers. 00050 */ 00051 enum BLE_GAP_SVCS 00052 { 00053 SD_BLE_GAP_ADDRESS_SET = BLE_GAP_SVC_BASE, /**< Set own Bluetooth Address. */ 00054 SD_BLE_GAP_ADDRESS_GET, /**< Get own Bluetooth Address. */ 00055 SD_BLE_GAP_ADV_DATA_SET, /**< Set Advertising Data. */ 00056 SD_BLE_GAP_ADV_START, /**< Start Advertising. */ 00057 SD_BLE_GAP_ADV_STOP, /**< Stop Advertising. */ 00058 SD_BLE_GAP_CONN_PARAM_UPDATE, /**< Connection Parameter Update. */ 00059 SD_BLE_GAP_DISCONNECT, /**< Disconnect. */ 00060 SD_BLE_GAP_TX_POWER_SET, /**< Set TX Power. */ 00061 SD_BLE_GAP_APPEARANCE_SET, /**< Set Appearance. */ 00062 SD_BLE_GAP_APPEARANCE_GET, /**< Get Appearance. */ 00063 SD_BLE_GAP_PPCP_SET, /**< Set PPCP. */ 00064 SD_BLE_GAP_PPCP_GET, /**< Get PPCP. */ 00065 SD_BLE_GAP_DEVICE_NAME_SET, /**< Set Device Name. */ 00066 SD_BLE_GAP_DEVICE_NAME_GET, /**< Get Device Name. */ 00067 SD_BLE_GAP_AUTHENTICATE, /**< Initiate Pairing/Bonding. */ 00068 SD_BLE_GAP_SEC_PARAMS_REPLY, /**< Reply with Security Parameters. */ 00069 SD_BLE_GAP_AUTH_KEY_REPLY, /**< Reply with an authentication key. */ 00070 SD_BLE_GAP_ENCRYPT, /**< Initiate encryption procedure. */ 00071 SD_BLE_GAP_SEC_INFO_REPLY, /**< Reply with Security Information. */ 00072 SD_BLE_GAP_CONN_SEC_GET, /**< Obtain connection security level. */ 00073 SD_BLE_GAP_RSSI_START, /**< Start reporting of changes in RSSI. */ 00074 SD_BLE_GAP_RSSI_STOP, /**< Stop reporting of changes in RSSI. */ 00075 SD_BLE_GAP_SCAN_START, /**< Start Scanning. */ 00076 SD_BLE_GAP_SCAN_STOP, /**< Stop Scanning. */ 00077 SD_BLE_GAP_CONNECT, /**< Connect. */ 00078 SD_BLE_GAP_CONNECT_CANCEL, /**< Cancel ongoing connection procedure. */ 00079 SD_BLE_GAP_RSSI_GET, /**< Get the last RSSI sample. */ 00080 }; 00081 00082 /**@brief GAP Event IDs. 00083 * IDs that uniquely identify an event coming from the stack to the application. 00084 */ 00085 enum BLE_GAP_EVTS 00086 { 00087 BLE_GAP_EVT_CONNECTED = BLE_GAP_EVT_BASE, /**< Connection established. @ref ble_gap_evt_connected_t */ 00088 BLE_GAP_EVT_DISCONNECTED, /**< Disconnected from peer. @ref ble_gap_evt_disconnected_t */ 00089 BLE_GAP_EVT_CONN_PARAM_UPDATE, /**< Connection Parameters updated. ble_gap_evt_conn_param_update_t */ 00090 BLE_GAP_EVT_SEC_PARAMS_REQUEST, /**< Request to provide security parameters. @ref ble_gap_evt_sec_params_request_t */ 00091 BLE_GAP_EVT_SEC_INFO_REQUEST, /**< Request to provide security information. @ref ble_gap_evt_sec_info_request_t */ 00092 BLE_GAP_EVT_PASSKEY_DISPLAY, /**< Request to display a passkey to the user. @ref ble_gap_evt_passkey_display_t */ 00093 BLE_GAP_EVT_AUTH_KEY_REQUEST, /**< Request to provide an authentication key. @ref ble_gap_evt_auth_key_request_t */ 00094 BLE_GAP_EVT_AUTH_STATUS, /**< Authentication procedure completed with status. @ref ble_gap_evt_auth_status_t */ 00095 BLE_GAP_EVT_CONN_SEC_UPDATE, /**< Connection security updated. @ref ble_gap_evt_conn_sec_update_t */ 00096 BLE_GAP_EVT_TIMEOUT, /**< Timeout expired. @ref ble_gap_evt_timeout_t */ 00097 BLE_GAP_EVT_RSSI_CHANGED, /**< RSSI report. @ref ble_gap_evt_rssi_changed_t */ 00098 BLE_GAP_EVT_ADV_REPORT, /**< Advertising report. @ref ble_gap_evt_adv_report_t */ 00099 BLE_GAP_EVT_SEC_REQUEST, /**< Security Request. @ref ble_gap_evt_sec_request_t */ 00100 BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST, /**< Connection Parameter Update Request. @ref ble_gap_evt_conn_param_update_request_t */ 00101 BLE_GAP_EVT_SCAN_REQ_REPORT, /**< Scan request report. @ref ble_gap_evt_scan_req_report_t */ 00102 }; 00103 00104 /**@brief GAP Option IDs. 00105 * IDs that uniquely identify a GAP option. 00106 */ 00107 enum BLE_GAP_OPTS 00108 { 00109 BLE_GAP_OPT_CH_MAP = BLE_GAP_OPT_BASE, /**< Channel Map. @ref ble_gap_opt_ch_map_t */ 00110 BLE_GAP_OPT_LOCAL_CONN_LATENCY, /**< Local connection latency. @ref ble_gap_opt_local_conn_latency_t */ 00111 BLE_GAP_OPT_PASSKEY, /**< Set passkey. @ref ble_gap_opt_passkey_t */ 00112 BLE_GAP_OPT_PRIVACY, /**< Custom privacy. @ref ble_gap_opt_privacy_t */ 00113 BLE_GAP_OPT_SCAN_REQ_REPORT, /**< Scan request report. @ref ble_gap_opt_scan_req_report_t */ 00114 BLE_GAP_OPT_COMPAT_MODE /**< Compatibility mode. @ref ble_gap_opt_compat_mode_t */ 00115 }; 00116 /** @} */ 00117 00118 /**@addtogroup BLE_GAP_DEFINES Defines 00119 * @{ */ 00120 00121 /**@defgroup BLE_ERRORS_GAP SVC return values specific to GAP 00122 * @{ */ 00123 #define BLE_ERROR_GAP_UUID_LIST_MISMATCH (NRF_GAP_ERR_BASE + 0x000) /**< UUID list does not contain an integral number of UUIDs. */ 00124 #define BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST (NRF_GAP_ERR_BASE + 0x001) /**< Use of Whitelist not permitted with discoverable advertising. */ 00125 #define BLE_ERROR_GAP_INVALID_BLE_ADDR (NRF_GAP_ERR_BASE + 0x002) /**< The upper two bits of the address do not correspond to the specified address type. */ 00126 #define BLE_ERROR_GAP_WHITELIST_IN_USE (NRF_GAP_ERR_BASE + 0x003) /**< Attempt to overwrite the whitelist while already in use by another operation. */ 00127 /**@} */ 00128 00129 00130 /**@defgroup BLE_GAP_ROLES GAP Roles 00131 * @note Not explicitly used in peripheral API, but will be relevant for central API. 00132 * @{ */ 00133 #define BLE_GAP_ROLE_INVALID 0x0 /**< Invalid Role. */ 00134 #define BLE_GAP_ROLE_PERIPH 0x1 /**< Peripheral Role. */ 00135 #define BLE_GAP_ROLE_CENTRAL 0x2 /**< Central Role. */ 00136 /**@} */ 00137 00138 00139 /**@defgroup BLE_GAP_TIMEOUT_SOURCES GAP Timeout sources 00140 * @{ */ 00141 #define BLE_GAP_TIMEOUT_SRC_ADVERTISING 0x00 /**< Advertising timeout. */ 00142 #define BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST 0x01 /**< Security request timeout. */ 00143 #define BLE_GAP_TIMEOUT_SRC_SCAN 0x02 /**< Scanning timeout. */ 00144 #define BLE_GAP_TIMEOUT_SRC_CONN 0x03 /**< Connection timeout. */ 00145 /**@} */ 00146 00147 00148 /**@defgroup BLE_GAP_ADDR_TYPES GAP Address types 00149 * @{ */ 00150 #define BLE_GAP_ADDR_TYPE_PUBLIC 0x00 /**< Public address. */ 00151 #define BLE_GAP_ADDR_TYPE_RANDOM_STATIC 0x01 /**< Random Static address. */ 00152 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE 0x02 /**< Private Resolvable address. */ 00153 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE 0x03 /**< Private Non-Resolvable address. */ 00154 /**@} */ 00155 00156 /**@defgroup BLE_GAP_ADDR_CYCLE_MODES GAP Address cycle modes 00157 * @{ */ 00158 #define BLE_GAP_ADDR_CYCLE_MODE_NONE 0x00 /**< Set addresses directly, no automatic address cycling. */ 00159 #define BLE_GAP_ADDR_CYCLE_MODE_AUTO 0x01 /**< Automatically generate and update private addresses. */ 00160 /** @} */ 00161 00162 /**@brief The default interval in seconds at which a private address is refreshed when address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO. */ 00163 #define BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S (60 * 15) 00164 00165 /** @brief BLE address length. */ 00166 #define BLE_GAP_ADDR_LEN 6 00167 00168 00169 /**@defgroup BLE_GAP_AD_TYPE_DEFINITIONS GAP Advertising and Scan Response Data format 00170 * @note Found at https://www.bluetooth.org/Technical/AssignedNumbers/generic_access_profile.htm 00171 * @{ */ 00172 #define BLE_GAP_AD_TYPE_FLAGS 0x01 /**< Flags for discoverability. */ 00173 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_MORE_AVAILABLE 0x02 /**< Partial list of 16 bit service UUIDs. */ 00174 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_COMPLETE 0x03 /**< Complete list of 16 bit service UUIDs. */ 00175 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_MORE_AVAILABLE 0x04 /**< Partial list of 32 bit service UUIDs. */ 00176 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_COMPLETE 0x05 /**< Complete list of 32 bit service UUIDs. */ 00177 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_MORE_AVAILABLE 0x06 /**< Partial list of 128 bit service UUIDs. */ 00178 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_COMPLETE 0x07 /**< Complete list of 128 bit service UUIDs. */ 00179 #define BLE_GAP_AD_TYPE_SHORT_LOCAL_NAME 0x08 /**< Short local device name. */ 00180 #define BLE_GAP_AD_TYPE_COMPLETE_LOCAL_NAME 0x09 /**< Complete local device name. */ 00181 #define BLE_GAP_AD_TYPE_TX_POWER_LEVEL 0x0A /**< Transmit power level. */ 00182 #define BLE_GAP_AD_TYPE_CLASS_OF_DEVICE 0x0D /**< Class of device. */ 00183 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C 0x0E /**< Simple Pairing Hash C. */ 00184 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R 0x0F /**< Simple Pairing Randomizer R. */ 00185 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_TK_VALUE 0x10 /**< Security Manager TK Value. */ 00186 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_OOB_FLAGS 0x11 /**< Security Manager Out Of Band Flags. */ 00187 #define BLE_GAP_AD_TYPE_SLAVE_CONNECTION_INTERVAL_RANGE 0x12 /**< Slave Connection Interval Range. */ 00188 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_16BIT 0x14 /**< List of 16-bit Service Solicitation UUIDs. */ 00189 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_128BIT 0x15 /**< List of 128-bit Service Solicitation UUIDs. */ 00190 #define BLE_GAP_AD_TYPE_SERVICE_DATA 0x16 /**< Service Data - 16-bit UUID. */ 00191 #define BLE_GAP_AD_TYPE_PUBLIC_TARGET_ADDRESS 0x17 /**< Public Target Address. */ 00192 #define BLE_GAP_AD_TYPE_RANDOM_TARGET_ADDRESS 0x18 /**< Random Target Address. */ 00193 #define BLE_GAP_AD_TYPE_APPEARANCE 0x19 /**< Appearance. */ 00194 #define BLE_GAP_AD_TYPE_ADVERTISING_INTERVAL 0x1A /**< Advertising Interval. */ 00195 #define BLE_GAP_AD_TYPE_LE_BLUETOOTH_DEVICE_ADDRESS 0x1B /**< LE Bluetooth Device Address. */ 00196 #define BLE_GAP_AD_TYPE_LE_ROLE 0x1C /**< LE Role. */ 00197 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C256 0x1D /**< Simple Pairing Hash C-256. */ 00198 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R256 0x1E /**< Simple Pairing Randomizer R-256. */ 00199 #define BLE_GAP_AD_TYPE_SERVICE_DATA_32BIT_UUID 0x20 /**< Service Data - 32-bit UUID. */ 00200 #define BLE_GAP_AD_TYPE_SERVICE_DATA_128BIT_UUID 0x21 /**< Service Data - 128-bit UUID. */ 00201 #define BLE_GAP_AD_TYPE_3D_INFORMATION_DATA 0x3D /**< 3D Information Data. */ 00202 #define BLE_GAP_AD_TYPE_MANUFACTURER_SPECIFIC_DATA 0xFF /**< Manufacturer Specific Data. */ 00203 /**@} */ 00204 00205 00206 /**@defgroup BLE_GAP_ADV_FLAGS GAP Advertisement Flags 00207 * @{ */ 00208 #define BLE_GAP_ADV_FLAG_LE_LIMITED_DISC_MODE (0x01) /**< LE Limited Discoverable Mode. */ 00209 #define BLE_GAP_ADV_FLAG_LE_GENERAL_DISC_MODE (0x02) /**< LE General Discoverable Mode. */ 00210 #define BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED (0x04) /**< BR/EDR not supported. */ 00211 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_CONTROLLER (0x08) /**< Simultaneous LE and BR/EDR, Controller. */ 00212 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_HOST (0x10) /**< Simultaneous LE and BR/EDR, Host. */ 00213 #define BLE_GAP_ADV_FLAGS_LE_ONLY_LIMITED_DISC_MODE (BLE_GAP_ADV_FLAG_LE_LIMITED_DISC_MODE | BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED) /**< LE Limited Discoverable Mode, BR/EDR not supported. */ 00214 #define BLE_GAP_ADV_FLAGS_LE_ONLY_GENERAL_DISC_MODE (BLE_GAP_ADV_FLAG_LE_GENERAL_DISC_MODE | BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED) /**< LE General Discoverable Mode, BR/EDR not supported. */ 00215 /**@} */ 00216 00217 00218 /**@defgroup BLE_GAP_ADV_INTERVALS GAP Advertising interval max and min 00219 * @{ */ 00220 #define BLE_GAP_ADV_INTERVAL_MIN 0x0020 /**< Minimum Advertising interval in 625 us units, i.e. 20 ms. */ 00221 #define BLE_GAP_ADV_NONCON_INTERVAL_MIN 0x00A0 /**< Minimum Advertising interval in 625 us units for non connectable mode, i.e. 100 ms. */ 00222 #define BLE_GAP_ADV_INTERVAL_MAX 0x4000 /**< Maximum Advertising interval in 625 us units, i.e. 10.24 s. */ 00223 /**@} */ 00224 00225 00226 /**@defgroup BLE_GAP_SCAN_INTERVALS GAP Scan interval max and min 00227 * @{ */ 00228 #define BLE_GAP_SCAN_INTERVAL_MIN 0x0004 /**< Minimum Scan interval in 625 us units, i.e. 2.5 ms. */ 00229 #define BLE_GAP_SCAN_INTERVAL_MAX 0x4000 /**< Maximum Scan interval in 625 us units, i.e. 10.24 s. */ 00230 /** @} */ 00231 00232 00233 /**@defgroup BLE_GAP_SCAN_WINDOW GAP Scan window max and min 00234 * @{ */ 00235 #define BLE_GAP_SCAN_WINDOW_MIN 0x0004 /**< Minimum Scan window in 625 us units, i.e. 2.5 ms. */ 00236 #define BLE_GAP_SCAN_WINDOW_MAX 0x4000 /**< Maximum Scan window in 625 us units, i.e. 10.24 s. */ 00237 /** @} */ 00238 00239 00240 /**@defgroup BLE_GAP_SCAN_TIMEOUT GAP Scan timeout max and min 00241 * @{ */ 00242 #define BLE_GAP_SCAN_TIMEOUT_MIN 0x0001 /**< Minimum Scan timeout in seconds. */ 00243 #define BLE_GAP_SCAN_TIMEOUT_MAX 0xFFFF /**< Maximum Scan timeout in seconds. */ 00244 /** @} */ 00245 00246 00247 /**@brief Maximum size of advertising data in octets. */ 00248 #define BLE_GAP_ADV_MAX_SIZE 31 00249 00250 00251 /**@defgroup BLE_GAP_ADV_TYPES GAP Advertising types 00252 * @{ */ 00253 #define BLE_GAP_ADV_TYPE_ADV_IND 0x00 /**< Connectable undirected. */ 00254 #define BLE_GAP_ADV_TYPE_ADV_DIRECT_IND 0x01 /**< Connectable directed. */ 00255 #define BLE_GAP_ADV_TYPE_ADV_SCAN_IND 0x02 /**< Scannable undirected. */ 00256 #define BLE_GAP_ADV_TYPE_ADV_NONCONN_IND 0x03 /**< Non connectable undirected. */ 00257 /**@} */ 00258 00259 00260 /**@defgroup BLE_GAP_ADV_FILTER_POLICIES GAP Advertising filter policies 00261 * @{ */ 00262 #define BLE_GAP_ADV_FP_ANY 0x00 /**< Allow scan requests and connect requests from any device. */ 00263 #define BLE_GAP_ADV_FP_FILTER_SCANREQ 0x01 /**< Filter scan requests with whitelist. */ 00264 #define BLE_GAP_ADV_FP_FILTER_CONNREQ 0x02 /**< Filter connect requests with whitelist. */ 00265 #define BLE_GAP_ADV_FP_FILTER_BOTH 0x03 /**< Filter both scan and connect requests with whitelist. */ 00266 /**@} */ 00267 00268 00269 /**@defgroup BLE_GAP_ADV_TIMEOUT_VALUES GAP Advertising timeout values 00270 * @{ */ 00271 #define BLE_GAP_ADV_TIMEOUT_LIMITED_MAX 180 /**< Maximum advertising time in limited discoverable mode (TGAP(lim_adv_timeout) = 180s). */ 00272 #define BLE_GAP_ADV_TIMEOUT_GENERAL_UNLIMITED 0 /**< Unlimited advertising in general discoverable mode. */ 00273 /**@} */ 00274 00275 00276 /**@defgroup BLE_GAP_DISC_MODES GAP Discovery modes 00277 * @{ */ 00278 #define BLE_GAP_DISC_MODE_NOT_DISCOVERABLE 0x00 /**< Not discoverable discovery Mode. */ 00279 #define BLE_GAP_DISC_MODE_LIMITED 0x01 /**< Limited Discovery Mode. */ 00280 #define BLE_GAP_DISC_MODE_GENERAL 0x02 /**< General Discovery Mode. */ 00281 /**@} */ 00282 00283 /**@defgroup BLE_GAP_IO_CAPS GAP IO Capabilities 00284 * @{ */ 00285 #define BLE_GAP_IO_CAPS_DISPLAY_ONLY 0x00 /**< Display Only. */ 00286 #define BLE_GAP_IO_CAPS_DISPLAY_YESNO 0x01 /**< Display and Yes/No entry. */ 00287 #define BLE_GAP_IO_CAPS_KEYBOARD_ONLY 0x02 /**< Keyboard Only. */ 00288 #define BLE_GAP_IO_CAPS_NONE 0x03 /**< No I/O capabilities. */ 00289 #define BLE_GAP_IO_CAPS_KEYBOARD_DISPLAY 0x04 /**< Keyboard and Display. */ 00290 /**@} */ 00291 00292 00293 /**@defgroup BLE_GAP_AUTH_KEY_TYPES GAP Authentication Key Types 00294 * @{ */ 00295 #define BLE_GAP_AUTH_KEY_TYPE_NONE 0x00 /**< No key (may be used to reject). */ 00296 #define BLE_GAP_AUTH_KEY_TYPE_PASSKEY 0x01 /**< 6-digit Passkey. */ 00297 #define BLE_GAP_AUTH_KEY_TYPE_OOB 0x02 /**< Out Of Band data. */ 00298 /**@} */ 00299 00300 /**@defgroup BLE_GAP_SEC_STATUS GAP Security status 00301 * @{ */ 00302 #define BLE_GAP_SEC_STATUS_SUCCESS 0x00 /**< Procedure completed with success. */ 00303 #define BLE_GAP_SEC_STATUS_TIMEOUT 0x01 /**< Procedure timed out. */ 00304 #define BLE_GAP_SEC_STATUS_PDU_INVALID 0x02 /**< Invalid PDU received. */ 00305 #define BLE_GAP_SEC_STATUS_RFU_RANGE1_BEGIN 0x03 /**< Reserved for Future Use range #1 begin. */ 00306 #define BLE_GAP_SEC_STATUS_RFU_RANGE1_END 0x80 /**< Reserved for Future Use range #1 end. */ 00307 #define BLE_GAP_SEC_STATUS_PASSKEY_ENTRY_FAILED 0x81 /**< Passkey entry failed (user cancelled or other). */ 00308 #define BLE_GAP_SEC_STATUS_OOB_NOT_AVAILABLE 0x82 /**< Out of Band Key not available. */ 00309 #define BLE_GAP_SEC_STATUS_AUTH_REQ 0x83 /**< Authentication requirements not met. */ 00310 #define BLE_GAP_SEC_STATUS_CONFIRM_VALUE 0x84 /**< Confirm value failed. */ 00311 #define BLE_GAP_SEC_STATUS_PAIRING_NOT_SUPP 0x85 /**< Pairing not supported. */ 00312 #define BLE_GAP_SEC_STATUS_ENC_KEY_SIZE 0x86 /**< Encryption key size. */ 00313 #define BLE_GAP_SEC_STATUS_SMP_CMD_UNSUPPORTED 0x87 /**< Unsupported SMP command. */ 00314 #define BLE_GAP_SEC_STATUS_UNSPECIFIED 0x88 /**< Unspecified reason. */ 00315 #define BLE_GAP_SEC_STATUS_REPEATED_ATTEMPTS 0x89 /**< Too little time elapsed since last attempt. */ 00316 #define BLE_GAP_SEC_STATUS_INVALID_PARAMS 0x8A /**< Invalid parameters. */ 00317 #define BLE_GAP_SEC_STATUS_RFU_RANGE2_BEGIN 0x8B /**< Reserved for Future Use range #2 begin. */ 00318 #define BLE_GAP_SEC_STATUS_RFU_RANGE2_END 0xFF /**< Reserved for Future Use range #2 end. */ 00319 /**@} */ 00320 00321 /**@defgroup BLE_GAP_SEC_STATUS_SOURCES GAP Security status sources 00322 * @{ */ 00323 #define BLE_GAP_SEC_STATUS_SOURCE_LOCAL 0x00 /**< Local failure. */ 00324 #define BLE_GAP_SEC_STATUS_SOURCE_REMOTE 0x01 /**< Remote failure. */ 00325 /**@} */ 00326 00327 /**@defgroup BLE_GAP_CP_LIMITS GAP Connection Parameters Limits 00328 * @{ */ 00329 #define BLE_GAP_CP_MIN_CONN_INTVL_NONE 0xFFFF /**< No new minimum connction interval specified in connect parameters. */ 00330 #define BLE_GAP_CP_MIN_CONN_INTVL_MIN 0x0006 /**< Lowest mimimum connection interval permitted, in units of 1.25 ms, i.e. 7.5 ms. */ 00331 #define BLE_GAP_CP_MIN_CONN_INTVL_MAX 0x0C80 /**< Highest minimum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */ 00332 #define BLE_GAP_CP_MAX_CONN_INTVL_NONE 0xFFFF /**< No new maximum connction interval specified in connect parameters. */ 00333 #define BLE_GAP_CP_MAX_CONN_INTVL_MIN 0x0006 /**< Lowest maximum connection interval permitted, in units of 1.25 ms, i.e. 7.5 ms. */ 00334 #define BLE_GAP_CP_MAX_CONN_INTVL_MAX 0x0C80 /**< Highest maximum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */ 00335 #define BLE_GAP_CP_SLAVE_LATENCY_MAX 0x01F3 /**< Highest slave latency permitted, in connection events. */ 00336 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_NONE 0xFFFF /**< No new supervision timeout specified in connect parameters. */ 00337 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MIN 0x000A /**< Lowest supervision timeout permitted, in units of 10 ms, i.e. 100 ms. */ 00338 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MAX 0x0C80 /**< Highest supervision timeout permitted, in units of 10 ms, i.e. 32 s. */ 00339 /**@} */ 00340 00341 00342 /**@brief GAP device name maximum length. */ 00343 #define BLE_GAP_DEVNAME_MAX_LEN 31 00344 00345 /**@brief Disable RSSI events for connections */ 00346 #define BLE_GAP_RSSI_THRESHOLD_INVALID 0xFF 00347 00348 /**@defgroup BLE_GAP_CONN_SEC_MODE_SET_MACROS GAP attribute security requirement setters 00349 * 00350 * See @ref ble_gap_conn_sec_mode_t. 00351 * @{ */ 00352 /**@brief Set sec_mode pointed to by ptr to have no access rights.*/ 00353 #define BLE_GAP_CONN_SEC_MODE_SET_NO_ACCESS(ptr) do {(ptr)->sm = 0; (ptr)->lv = 0;} while(0) 00354 /**@brief Set sec_mode pointed to by ptr to require no protection, open link.*/ 00355 #define BLE_GAP_CONN_SEC_MODE_SET_OPEN(ptr) do {(ptr)->sm = 1; (ptr)->lv = 1;} while(0) 00356 /**@brief Set sec_mode pointed to by ptr to require encryption, but no MITM protection.*/ 00357 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_NO_MITM(ptr) do {(ptr)->sm = 1; (ptr)->lv = 2;} while(0) 00358 /**@brief Set sec_mode pointed to by ptr to require encryption and MITM protection.*/ 00359 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_WITH_MITM(ptr) do {(ptr)->sm = 1; (ptr)->lv = 3;} while(0) 00360 /**@brief Set sec_mode pointed to by ptr to require signing or encryption, no MITM protection needed.*/ 00361 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_NO_MITM(ptr) do {(ptr)->sm = 2; (ptr)->lv = 1;} while(0) 00362 /**@brief Set sec_mode pointed to by ptr to require signing or encryption with MITM protection.*/ 00363 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_WITH_MITM(ptr) do {(ptr)->sm = 2; (ptr)->lv = 2;} while(0) 00364 /**@} */ 00365 00366 00367 /**@brief GAP Security Random Number Length. */ 00368 #define BLE_GAP_SEC_RAND_LEN 8 00369 00370 /**@brief GAP Security Key Length. */ 00371 #define BLE_GAP_SEC_KEY_LEN 16 00372 00373 /**@brief GAP Passkey Length. */ 00374 #define BLE_GAP_PASSKEY_LEN 6 00375 00376 /**@brief Maximum amount of addresses in a whitelist. */ 00377 #define BLE_GAP_WHITELIST_ADDR_MAX_COUNT (8) 00378 00379 /**@brief Maximum amount of IRKs in a whitelist. 00380 * @note The number of IRKs is limited to 8, even if the hardware supports more. 00381 */ 00382 #define BLE_GAP_WHITELIST_IRK_MAX_COUNT (8) 00383 00384 /**@defgroup GAP_SEC_MODES GAP Security Modes 00385 * @{ */ 00386 #define BLE_GAP_SEC_MODE 0x00 /**< No key (may be used to reject). */ 00387 /**@} */ 00388 00389 /**@} */ 00390 00391 /**@addtogroup BLE_GAP_STRUCTURES Structures 00392 * @{ */ 00393 00394 /**@brief Bluetooth Low Energy address. */ 00395 typedef struct 00396 { 00397 uint8_t addr_type; /**< See @ref BLE_GAP_ADDR_TYPES. */ 00398 uint8_t addr[BLE_GAP_ADDR_LEN]; /**< 48-bit address, LSB format. */ 00399 } ble_gap_addr_t; 00400 00401 00402 /**@brief GAP connection parameters. 00403 * 00404 * @note When ble_conn_params_t is received in an event, both min_conn_interval and 00405 * max_conn_interval will be equal to the connection interval set by the central. 00406 * 00407 * @note If both conn_sup_timeout and max_conn_interval are specified, then the following constraint applies: 00408 * conn_sup_timeout * 4 > (1 + slave_latency) * max_conn_interval 00409 * that corresponds to the following Bluetooth Spec requirement: 00410 * The Supervision_Timeout in milliseconds shall be larger than 00411 * (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds. 00412 */ 00413 typedef struct 00414 { 00415 uint16_t min_conn_interval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/ 00416 uint16_t max_conn_interval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/ 00417 uint16_t slave_latency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/ 00418 uint16_t conn_sup_timeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/ 00419 } ble_gap_conn_params_t; 00420 00421 00422 /**@brief GAP connection security modes. 00423 * 00424 * Security Mode 0 Level 0: No access permissions at all (this level is not defined by the Bluetooth Core specification).\n 00425 * Security Mode 1 Level 1: No security is needed (aka open link).\n 00426 * Security Mode 1 Level 2: Encrypted link required, MITM protection not necessary.\n 00427 * Security Mode 1 Level 3: MITM protected encrypted link required.\n 00428 * Security Mode 2 Level 1: Signing or encryption required, MITM protection not necessary.\n 00429 * Security Mode 2 Level 2: MITM protected signing required, unless link is MITM protected encrypted.\n 00430 */ 00431 typedef struct 00432 { 00433 uint8_t sm : 4; /**< Security Mode (1 or 2), 0 for no permissions at all. */ 00434 uint8_t lv : 4; /**< Level (1, 2 or 3), 0 for no permissions at all. */ 00435 00436 } ble_gap_conn_sec_mode_t; 00437 00438 00439 /**@brief GAP connection security status.*/ 00440 typedef struct 00441 { 00442 ble_gap_conn_sec_mode_t sec_mode; /**< Currently active security mode for this connection.*/ 00443 uint8_t encr_key_size; /**< Length of currently active encryption key, 7 to 16 octets (only applicable for bonding procedures). */ 00444 } ble_gap_conn_sec_t; 00445 00446 00447 /**@brief Identity Resolving Key. */ 00448 typedef struct 00449 { 00450 uint8_t irk[BLE_GAP_SEC_KEY_LEN]; /**< Array containing IRK. */ 00451 } ble_gap_irk_t; 00452 00453 00454 /**@brief Whitelist structure. */ 00455 typedef struct 00456 { 00457 ble_gap_addr_t **pp_addrs; /**< Pointer to an array of device address pointers, pointing to addresses to be used in whitelist. NULL if none are given. */ 00458 uint8_t addr_count; /**< Count of device addresses in array, up to @ref BLE_GAP_WHITELIST_ADDR_MAX_COUNT. */ 00459 ble_gap_irk_t **pp_irks; /**< Pointer to an array of Identity Resolving Key (IRK) pointers, each pointing to an IRK in the whitelist. NULL if none are given. */ 00460 uint8_t irk_count; /**< Count of IRKs in array, up to @ref BLE_GAP_WHITELIST_IRK_MAX_COUNT. */ 00461 } ble_gap_whitelist_t; 00462 00463 /**@brief Channel mask for RF channels used in advertising and scanning. */ 00464 typedef struct 00465 { 00466 uint8_t ch_37_off : 1; /**< Setting this bit to 1 will turn off advertising on channel 37 */ 00467 uint8_t ch_38_off : 1; /**< Setting this bit to 1 will turn off advertising on channel 38 */ 00468 uint8_t ch_39_off : 1; /**< Setting this bit to 1 will turn off advertising on channel 39 */ 00469 } ble_gap_adv_ch_mask_t; 00470 00471 /**@brief GAP advertising parameters.*/ 00472 typedef struct 00473 { 00474 uint8_t type; /**< See @ref BLE_GAP_ADV_TYPES. */ 00475 ble_gap_addr_t *p_peer_addr; /**< For @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND mode only, known peer address. */ 00476 uint8_t fp; /**< Filter Policy, see @ref BLE_GAP_ADV_FILTER_POLICIES. */ 00477 ble_gap_whitelist_t *p_whitelist; /**< Pointer to whitelist, NULL if no whitelist or the current active whitelist is to be used. */ 00478 uint16_t interval; /**< Advertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s), see @ref BLE_GAP_ADV_INTERVALS. 00479 - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for high duty cycle directed advertising. 00480 - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, set @ref BLE_GAP_ADV_INTERVAL_MIN <= interval <= @ref BLE_GAP_ADV_INTERVAL_MAX for low duty cycle advertising.*/ 00481 uint16_t timeout; /**< Advertising timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables timeout. See also @ref BLE_GAP_ADV_TIMEOUT_VALUES. If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for High duty cycle directed advertising. */ 00482 ble_gap_adv_ch_mask_t channel_mask; /**< Advertising channel mask. @see ble_gap_channel_mask_t for documentation. */ 00483 } ble_gap_adv_params_t; 00484 00485 00486 /**@brief GAP scanning parameters. */ 00487 typedef struct 00488 { 00489 uint8_t active : 1; /**< If 1, perform active scanning (scan requests). */ 00490 uint8_t selective : 1; /**< If 1, ignore unknown devices (non whitelisted). */ 00491 ble_gap_whitelist_t * p_whitelist; /**< Pointer to whitelist, NULL if no whitelist or the current active whitelist is to be used. */ 00492 uint16_t interval; /**< Scan interval between 0x0004 and 0x4000 in 0.625ms units (2.5ms to 10.24s). */ 00493 uint16_t window; /**< Scan window between 0x0004 and 0x4000 in 0.625ms units (2.5ms to 10.24s). */ 00494 uint16_t timeout; /**< Scan timeout between 0x0001 and 0xFFFF in seconds, 0x0000 disables timeout. */ 00495 } ble_gap_scan_params_t; 00496 00497 00498 /** @brief Keys that can be exchanged during a bonding procedure. */ 00499 typedef struct 00500 { 00501 uint8_t enc : 1; /**< Long Term Key and Master Identification. */ 00502 uint8_t id : 1; /**< Identity Resolving Key and Identity Address Information. */ 00503 uint8_t sign : 1; /**< Connection Signature Resolving Key. */ 00504 } ble_gap_sec_kdist_t; 00505 00506 00507 /**@brief GAP security parameters. */ 00508 typedef struct 00509 { 00510 uint8_t bond : 1; /**< Perform bonding. */ 00511 uint8_t mitm : 1; /**< Man In The Middle protection required. */ 00512 uint8_t io_caps : 3; /**< IO capabilities, see @ref BLE_GAP_IO_CAPS. */ 00513 uint8_t oob : 1; /**< Out Of Band data available. */ 00514 uint8_t min_key_size; /**< Minimum encryption key size in octets between 7 and 16. If 0 then not applicable in this instance. */ 00515 uint8_t max_key_size; /**< Maximum encryption key size in octets between min_key_size and 16. */ 00516 ble_gap_sec_kdist_t kdist_periph; /**< Key distribution bitmap: keys that the peripheral device will distribute. */ 00517 ble_gap_sec_kdist_t kdist_central; /**< Key distribution bitmap: keys that the central device will distribute. */ 00518 } ble_gap_sec_params_t; 00519 00520 00521 /**@brief GAP Encryption Information. */ 00522 typedef struct 00523 { 00524 uint8_t ltk[BLE_GAP_SEC_KEY_LEN]; /**< Long Term Key. */ 00525 uint8_t auth : 1; /**< Authenticated Key. */ 00526 uint8_t ltk_len : 7; /**< LTK length in octets. */ 00527 } ble_gap_enc_info_t; 00528 00529 00530 /**@brief GAP Master Identification. */ 00531 typedef struct 00532 { 00533 uint16_t ediv; /**< Encrypted Diversifier. */ 00534 uint8_t rand[BLE_GAP_SEC_RAND_LEN]; /**< Random Number. */ 00535 } ble_gap_master_id_t; 00536 00537 00538 /**@brief GAP Signing Information. */ 00539 typedef struct 00540 { 00541 uint8_t csrk[BLE_GAP_SEC_KEY_LEN]; /**< Connection Signature Resolving Key. */ 00542 } ble_gap_sign_info_t; 00543 00544 00545 /**@brief Event structure for @ref BLE_GAP_EVT_CONNECTED. */ 00546 typedef struct 00547 { 00548 ble_gap_addr_t peer_addr; /**< Bluetooth address of the peer device. */ 00549 ble_gap_addr_t own_addr; /**< Bluetooth address of the local device used during connection setup. */ 00550 #if !defined(TARGET_MCU_NRF51_16K_S110) && !defined(TARGET_MCU_NRF51_32K_S110) 00551 uint8_t role; /**< BLE role for this connection, see @ref BLE_GAP_ROLES */ 00552 #endif 00553 uint8_t irk_match :1; /**< If 1, peer device's address resolved using an IRK. */ 00554 uint8_t irk_match_idx :7; /**< Index in IRK list where the address was matched. */ 00555 ble_gap_conn_params_t conn_params; /**< GAP Connection Parameters. */ 00556 } ble_gap_evt_connected_t; 00557 00558 00559 /**@brief Event structure for @ref BLE_GAP_EVT_DISCONNECTED. */ 00560 typedef struct 00561 { 00562 uint8_t reason; /**< HCI error code, see @ref BLE_HCI_STATUS_CODES. */ 00563 } ble_gap_evt_disconnected_t; 00564 00565 00566 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_PARAM_UPDATE. */ 00567 typedef struct 00568 { 00569 ble_gap_conn_params_t conn_params; /**< GAP Connection Parameters. */ 00570 } ble_gap_evt_conn_param_update_t; 00571 00572 00573 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST. */ 00574 typedef struct 00575 { 00576 ble_gap_sec_params_t peer_params; /**< Initiator Security Parameters. */ 00577 } ble_gap_evt_sec_params_request_t; 00578 00579 00580 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_INFO_REQUEST. */ 00581 typedef struct 00582 { 00583 ble_gap_addr_t peer_addr; /**< Bluetooth address of the peer device. */ 00584 ble_gap_master_id_t master_id; /**< Master Identification for LTK lookup. */ 00585 uint8_t enc_info : 1; /**< If 1, Encryption Information required. */ 00586 uint8_t id_info : 1; /**< If 1, Identity Information required. */ 00587 uint8_t sign_info : 1; /**< If 1, Signing Information required. */ 00588 } ble_gap_evt_sec_info_request_t; 00589 00590 00591 /**@brief Event structure for @ref BLE_GAP_EVT_PASSKEY_DISPLAY. */ 00592 typedef struct 00593 { 00594 uint8_t passkey[BLE_GAP_PASSKEY_LEN]; /**< 6-digit passkey in ASCII ('0'-'9' digits only). */ 00595 } ble_gap_evt_passkey_display_t; 00596 00597 00598 /**@brief Event structure for @ref BLE_GAP_EVT_AUTH_KEY_REQUEST. */ 00599 typedef struct 00600 { 00601 uint8_t key_type; /**< See @ref BLE_GAP_AUTH_KEY_TYPES. */ 00602 } ble_gap_evt_auth_key_request_t; 00603 00604 00605 /**@brief Security levels supported. 00606 * @note See Bluetooth Specification Version 4.1 Volume 3, Part C, Chapter 10. 00607 */ 00608 typedef struct 00609 { 00610 uint8_t lv1 : 1; /**< If 1: Level 1 is supported. */ 00611 uint8_t lv2 : 1; /**< If 1: Level 2 is supported. */ 00612 uint8_t lv3 : 1; /**< If 1: Level 3 is supported. */ 00613 } ble_gap_sec_levels_t; 00614 00615 00616 /**@brief Encryption Key. */ 00617 typedef struct 00618 { 00619 ble_gap_enc_info_t enc_info; /**< Encryption Information. */ 00620 ble_gap_master_id_t master_id; /**< Master Identification. */ 00621 } ble_gap_enc_key_t; 00622 00623 00624 /**@brief Identity Key. */ 00625 typedef struct 00626 { 00627 ble_gap_irk_t id_info; /**< Identity Information. */ 00628 ble_gap_addr_t id_addr_info; /**< Identity Address Information. */ 00629 } ble_gap_id_key_t; 00630 00631 00632 /**@brief Security Keys. */ 00633 typedef struct 00634 { 00635 ble_gap_enc_key_t *p_enc_key; /**< Encryption Key, or NULL. */ 00636 ble_gap_id_key_t *p_id_key; /**< Identity Key, or NULL. */ 00637 ble_gap_sign_info_t *p_sign_key; /**< Signing Key, or NULL. */ 00638 } ble_gap_sec_keys_t; 00639 00640 00641 /**@brief Security key set (both Peripheral and Central keys). 00642 * Note that when distributing Bluetooth addresses pertaining to the local device those 00643 * will have to be filled in by the user. */ 00644 typedef struct 00645 { 00646 ble_gap_sec_keys_t keys_periph; /**< Keys distributed by the device in the Peripheral role. */ 00647 ble_gap_sec_keys_t keys_central; /**< Keys distributed by the device in the Central role. */ 00648 } ble_gap_sec_keyset_t; 00649 00650 00651 /**@brief Event structure for @ref BLE_GAP_EVT_AUTH_STATUS. */ 00652 typedef struct 00653 { 00654 uint8_t auth_status; /**< Authentication status, see @ref BLE_GAP_SEC_STATUS. */ 00655 uint8_t error_src : 2; /**< On error, source that caused the failure, see @ref BLE_GAP_SEC_STATUS_SOURCES. */ 00656 uint8_t bonded : 1; /**< Procedure resulted in a bond. */ 00657 ble_gap_sec_levels_t sm1_levels; /**< Levels supported in Security Mode 1. */ 00658 ble_gap_sec_levels_t sm2_levels; /**< Levels supported in Security Mode 2. */ 00659 ble_gap_sec_kdist_t kdist_periph; /**< Bitmap stating which keys were exchanged (distributed) by the peripheral. */ 00660 ble_gap_sec_kdist_t kdist_central; /**< Bitmap stating which keys were exchanged (distributed) by the central. */ 00661 } ble_gap_evt_auth_status_t; 00662 00663 00664 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_SEC_UPDATE. */ 00665 typedef struct 00666 { 00667 ble_gap_conn_sec_t conn_sec; /**< Connection security level. */ 00668 } ble_gap_evt_conn_sec_update_t; 00669 00670 00671 /**@brief Event structure for @ref BLE_GAP_EVT_TIMEOUT. */ 00672 typedef struct 00673 { 00674 uint8_t src; /**< Source of timeout event, see @ref BLE_GAP_TIMEOUT_SOURCES. */ 00675 } ble_gap_evt_timeout_t; 00676 00677 00678 /**@brief Event structure for @ref BLE_GAP_EVT_RSSI_CHANGED. */ 00679 typedef struct 00680 { 00681 int8_t rssi; /**< Received Signal Strength Indication in dBm. */ 00682 } ble_gap_evt_rssi_changed_t; 00683 00684 00685 /**@brief Event structure for @ref BLE_GAP_EVT_ADV_REPORT. */ 00686 typedef struct 00687 { 00688 ble_gap_addr_t peer_addr; /**< Bluetooth address of the peer device. */ 00689 int8_t rssi; /**< Received Signal Strength Indication in dBm. */ 00690 uint8_t scan_rsp : 1; /**< If 1, the report corresponds to a scan response and the type field may be ignored. */ 00691 uint8_t type : 2; /**< See @ref BLE_GAP_ADV_TYPES. Only valid if the scan_rsp field is 0. */ 00692 uint8_t dlen : 5; /**< Advertising or scan response data length. */ 00693 uint8_t data[BLE_GAP_ADV_MAX_SIZE]; /**< Advertising or scan response data. */ 00694 } ble_gap_evt_adv_report_t; 00695 00696 00697 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_REQUEST. */ 00698 typedef struct 00699 { 00700 uint8_t bond : 1; /**< Perform bonding. */ 00701 uint8_t mitm : 1; /**< Man In The Middle protection required. */ 00702 } ble_gap_evt_sec_request_t; 00703 00704 00705 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST. */ 00706 typedef struct 00707 { 00708 ble_gap_conn_params_t conn_params; /**< GAP Connection Parameters. */ 00709 } ble_gap_evt_conn_param_update_request_t; 00710 00711 00712 /**@brief Event structure for @ref BLE_GAP_EVT_SCAN_REQ_REPORT. */ 00713 typedef struct 00714 { 00715 int8_t rssi; /**< Received Signal Strength Indication in dBm. */ 00716 ble_gap_addr_t peer_addr; /**< Bluetooth address of the peer device. */ 00717 } ble_gap_evt_scan_req_report_t; 00718 00719 00720 00721 /**@brief GAP event structure. */ 00722 typedef struct 00723 { 00724 uint16_t conn_handle; /**< Connection Handle on which event occured. */ 00725 union /**< union alternative identified by evt_id in enclosing struct. */ 00726 { 00727 ble_gap_evt_connected_t connected; /**< Connected Event Parameters. */ 00728 ble_gap_evt_disconnected_t disconnected; /**< Disconnected Event Parameters. */ 00729 ble_gap_evt_conn_param_update_t conn_param_update; /**< Connection Parameter Update Parameters. */ 00730 ble_gap_evt_sec_params_request_t sec_params_request; /**< Security Parameters Request Event Parameters. */ 00731 ble_gap_evt_sec_info_request_t sec_info_request; /**< Security Information Request Event Parameters. */ 00732 ble_gap_evt_passkey_display_t passkey_display; /**< Passkey Display Event Parameters. */ 00733 ble_gap_evt_auth_key_request_t auth_key_request; /**< Authentication Key Request Event Parameters. */ 00734 ble_gap_evt_auth_status_t auth_status; /**< Authentication Status Event Parameters. */ 00735 ble_gap_evt_conn_sec_update_t conn_sec_update; /**< Connection Security Update Event Parameters. */ 00736 ble_gap_evt_timeout_t timeout; /**< Timeout Event Parameters. */ 00737 ble_gap_evt_rssi_changed_t rssi_changed; /**< RSSI Event parameters. */ 00738 ble_gap_evt_adv_report_t adv_report; /**< Advertising Report Event Parameters. */ 00739 ble_gap_evt_sec_request_t sec_request; /**< Security Request Event Parameters. */ 00740 ble_gap_evt_conn_param_update_request_t conn_param_update_request; /**< Connection Parameter Update Parameters. */ 00741 ble_gap_evt_scan_req_report_t scan_req_report; /**< Scan Request Report parameters. */ 00742 } params; /**< Event Parameters. */ 00743 00744 } ble_gap_evt_t; 00745 00746 00747 /**@brief Channel Map option. 00748 * Used with @ref sd_ble_opt_get to get the current channel map 00749 * or @ref sd_ble_opt_set to set a new channel map. When setting the 00750 * channel map, it applies to all current and future connections. When getting the 00751 * current channel map, it applies to a single connection and the connection handle 00752 * must be supplied. 00753 * 00754 * @note Setting the channel map may take some time, depending on connection parameters. 00755 * The time taken may be different for each connection and the get operation will 00756 * return the previous channel map until the new one has taken effect. 00757 * 00758 * @note After setting the channel map, by spec it can not be set again until at least 1 s has passed. 00759 * See Bluetooth Specification Version 4.1 Volume 2, Part E, Section 7.3.46. 00760 * 00761 * @retval ::NRF_SUCCESS Get or set successful. 00762 * @retval ::NRF_ERROR_BUSY Channel map was set again before enough time had passed. 00763 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 00764 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied for get. 00765 * @retval ::NRF_ERROR_NOT_SUPPORTED Returned by sd_ble_opt_set in peripheral-only SoftDevices. 00766 * 00767 */ 00768 typedef struct 00769 { 00770 uint16_t conn_handle; /**< Connection Handle (only applicable for get) */ 00771 uint8_t ch_map[5]; /**< Channel Map (37-bit). */ 00772 } ble_gap_opt_ch_map_t; 00773 00774 00775 /**@brief Local connection latency option. 00776 * 00777 * Local connection latency is a feature which enables the slave to improve 00778 * current consumption by ignoring the slave latency set by the peer. The 00779 * local connection latency can only be set to a multiple of the slave latency, 00780 * and cannot be longer than half of the supervision timeout. 00781 * 00782 * Used with @ref sd_ble_opt_set to set the local connection latency. The 00783 * @ref sd_ble_opt_get is not supported for this option, but the actual 00784 * local connection latency (unless set to NULL) is set as a return parameter 00785 * when setting the option. 00786 * 00787 * @note The latency set will be truncated down to the closest slave latency event 00788 * multiple, or the nearest multiple before half of the supervision timeout. 00789 * 00790 * @note The local connection latency is disabled by default, and needs to be enabled for new 00791 * connections and whenever the connection is updated. 00792 * 00793 * @retval ::NRF_SUCCESS Set successfully. 00794 * @retval ::NRF_ERROR_NOT_SUPPORTED Get is not supported. 00795 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle parameter. 00796 */ 00797 typedef struct 00798 { 00799 uint16_t conn_handle; /**< Connection Handle */ 00800 uint16_t requested_latency; /**< Requested local connection latency. */ 00801 uint16_t * p_actual_latency; /**< Pointer to storage for the actual local connection latency (can be set to NULL to skip return value). */ 00802 } ble_gap_opt_local_conn_latency_t; 00803 00804 00805 /**@brief Passkey Option. 00806 * 00807 * Structure containing the passkey to be used during pairing. This can be used with @ref 00808 * sd_ble_opt_set to make the SoftDevice use a pre-programmed passkey for authentication 00809 * instead of generating a random one. 00810 * 00811 * @note @ref sd_ble_opt_get is not supported for this option. 00812 * 00813 */ 00814 typedef struct 00815 { 00816 uint8_t * p_passkey; /**< Pointer to 6-digit ASCII string (digit 0..9 only, no NULL termination) passkey to be used during pairing. If this is NULL, the SoftDevice will generate a random passkey if required.*/ 00817 } ble_gap_opt_passkey_t; 00818 00819 00820 /**@brief Custom Privacy Option. 00821 * 00822 * This structure is used with both @ref sd_ble_opt_set (as input) and with 00823 * @ref sd_ble_opt_get (as output). 00824 * 00825 * Structure containing: 00826 * - A pointer to an IRK to set (if input), or a place to store a read IRK (if output). 00827 * - A private address refresh cycle. 00828 * 00829 * @note The specified address cycle interval is used when the address cycle mode is 00830 * @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO. If 0 is given, the address will not be automatically 00831 * refreshed at all. The default interval is @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S. 00832 * 00833 * @note If the current address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address will immediately be 00834 * refreshed when a custom privacy option is set. A new address can be generated manually by calling 00835 * @ref sd_ble_gap_address_set with the same type again. 00836 * 00837 * @note If the IRK is updated, the new IRK becomes the one to be distributed in all 00838 * bonding procedures performed after @ref sd_ble_opt_set returns. 00839 * 00840 * @retval ::NRF_SUCCESS Set or read successfully. 00841 * @retval ::NRF_ERROR_INVALID_ADDR The pointer to IRK storage is invalid. 00842 */ 00843 typedef struct 00844 { 00845 ble_gap_irk_t * p_irk; /**< When input: Pointer to custom IRK, or NULL to use/reset to the device's default IRK. When output: Pointer to where the current IRK is to be stored, or NULL to not read out the IRK. */ 00846 uint16_t interval_s; /**< When input: Custom private address cycle interval in seconds. When output: The current private address cycle interval. */ 00847 } ble_gap_opt_privacy_t; 00848 00849 00850 /**@brief Scan request report option. 00851 * 00852 * This can be used with @ref sd_ble_opt_set to make the SoftDevice send 00853 * @ref BLE_GAP_EVT_SCAN_REQ_REPORT events. 00854 * 00855 * @note Due to the limited space reserved for scan request report events, 00856 * not all received scan requests will be reported. 00857 * 00858 * @note If whitelisting is used, only whitelisted requests are reported. 00859 * 00860 * @retval ::NRF_SUCCESS Set successfully. 00861 * @retval ::NRF_ERROR_INVALID_STATE When advertising is ongoing while the option is set. 00862 */ 00863 typedef struct 00864 { 00865 uint8_t enable : 1; /**< Enable scan request reports. */ 00866 } ble_gap_opt_scan_req_report_t; 00867 00868 /**@brief Compatibility mode option. 00869 * 00870 * This can be used with @ref sd_ble_opt_set to enable and disable 00871 * compatibility modes. Compatibility modes are disabled by default. 00872 * 00873 * @note Compatibility mode 1 enables interoperability with devices that do not support 00874 * a value of 0 for the WinOffset parameter in the Link Layer CONNECT_REQ packet. 00875 * 00876 * @retval ::NRF_SUCCESS Set successfully. 00877 * @retval ::NRF_ERROR_INVALID_STATE When connection creation is ongoing while mode 1 is set. 00878 */ 00879 typedef struct 00880 { 00881 uint8_t mode_1_enable : 1; /**< Enable compatibility mode 1.*/ 00882 } ble_gap_opt_compat_mode_t; 00883 00884 00885 /**@brief Option structure for GAP options. */ 00886 typedef union 00887 { 00888 ble_gap_opt_ch_map_t ch_map; /**< Parameters for the Channel Map option. */ 00889 ble_gap_opt_local_conn_latency_t local_conn_latency; /**< Parameters for the Local connection latency option */ 00890 ble_gap_opt_passkey_t passkey; /**< Parameters for the Passkey option.*/ 00891 ble_gap_opt_privacy_t privacy; /**< Parameters for the Custom privacy option. */ 00892 ble_gap_opt_scan_req_report_t scan_req_report; /**< Parameters for the scan request report option.*/ 00893 ble_gap_opt_compat_mode_t compat_mode; /**< Parameters for the compatibility mode option.*/ 00894 } ble_gap_opt_t; 00895 /**@} */ 00896 00897 00898 /**@addtogroup BLE_GAP_FUNCTIONS Functions 00899 * @{ */ 00900 00901 /**@brief Set local Bluetooth address. 00902 * 00903 * @note If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address type is required to 00904 * be @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE or 00905 * @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE. The given address is ignored and the 00906 * SoftDevice will generate a new private address automatically every 00907 * @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S seconds. If this API 00908 * call is used again with the same parameters, the SoftDevice will immediately 00909 * generate a new private address to replace the current address. 00910 * 00911 * @note If the application wishes to use a @ref BLE_GAP_ADDR_TYPE_PUBLIC or 00912 * @ref BLE_GAP_ADDR_TYPE_RANDOM_STATIC address, the cycle mode must be 00913 * @ref BLE_GAP_ADDR_CYCLE_MODE_NONE. 00914 * 00915 * @note If this API function is called while advertising or scanning, the softdevice will immediately update the 00916 * advertising or scanning address without the need to stop the procedure in the following cases: 00917 * - If the previously set address is of type @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address 00918 * is also of type @ref BLE_GAP_ADDR_TYPE_PUBLIC 00919 * - If the previously set address is not @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address is 00920 * also not @ref BLE_GAP_ADDR_TYPE_PUBLIC. 00921 * If the address is changed from a @ref BLE_GAP_ADDR_TYPE_PUBLIC address to another type or from 00922 * another type to a @ref BLE_GAP_ADDR_TYPE_PUBLIC address, the change will take effect the next 00923 * time an advertising or scanning procedure is started. 00924 * 00925 * @note If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_NONE and the application is 00926 * using privacy, the application must take care to generate and set new private addresses 00927 * periodically to comply with the Privacy specification in Bluetooth Core Spec. 00928 * 00929 * @param[in] addr_cycle_mode Address cycle mode, see @ref BLE_GAP_ADDR_CYCLE_MODES. 00930 * @param[in] p_addr Pointer to address structure. 00931 * 00932 * @retval ::NRF_SUCCESS Address successfully set. 00933 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00934 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameters. 00935 * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid address. 00936 * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. 00937 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 00938 */ 00939 SVCALL(SD_BLE_GAP_ADDRESS_SET, uint32_t, sd_ble_gap_address_set(uint8_t addr_cycle_mode, const ble_gap_addr_t *p_addr)); 00940 00941 00942 /**@brief Get local Bluetooth address. 00943 * 00944 * @param[out] p_addr Pointer to address structure to be filled in. 00945 * 00946 * @retval ::NRF_SUCCESS Address successfully retrieved. 00947 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00948 */ 00949 SVCALL(SD_BLE_GAP_ADDRESS_GET, uint32_t, sd_ble_gap_address_get(ble_gap_addr_t *p_addr)); 00950 00951 00952 /**@brief Set, clear or update advertising and scan response data. 00953 * 00954 * @note The format of the advertising data will be checked by this call to ensure interoperability. 00955 * Limitations imposed by this API call to the data provided include having a flags data type in the scan response data and 00956 * duplicating the local name in the advertising data and scan response data. 00957 * 00958 * @note To clear the advertising data and set it to a 0-length packet, simply provide a valid pointer (p_data/p_sr_data) with its corresponding 00959 * length (dlen/srdlen) set to 0. 00960 * 00961 * @note The call will fail if p_data and p_sr_data are both NULL since this would have no effect. 00962 * 00963 * @param[in] p_data Raw data to be placed in advertising packet. If NULL, no changes are made to the current advertising packet data. 00964 * @param[in] dlen Data length for p_data. Max size: @ref BLE_GAP_ADV_MAX_SIZE octets. Should be 0 if p_data is NULL, can be 0 if p_data is not NULL. 00965 * @param[in] p_sr_data Raw data to be placed in scan response packet. If NULL, no changes are made to the current scan response packet data. 00966 * @param[in] srdlen Data length for p_sr_data. Max size: @ref BLE_GAP_ADV_MAX_SIZE octets. Should be 0 if p_sr_data is NULL, can be 0 if p_data is not NULL. 00967 * 00968 * @retval ::NRF_SUCCESS Advertising data successfully updated or cleared. 00969 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00970 * @retval ::NRF_ERROR_INVALID_FLAGS Invalid combination of advertising flags supplied. 00971 * @retval ::NRF_ERROR_INVALID_DATA Invalid data type(s) supplied, check the advertising data format specification. 00972 * @retval ::NRF_ERROR_INVALID_LENGTH Invalid data length(s) supplied. 00973 * @retval ::NRF_ERROR_NOT_SUPPORTED Unsupported data type. 00974 * @retval ::BLE_ERROR_GAP_UUID_LIST_MISMATCH Invalid UUID list supplied. 00975 */ 00976 SVCALL(SD_BLE_GAP_ADV_DATA_SET, uint32_t, sd_ble_gap_adv_data_set(uint8_t const *p_data, uint8_t dlen, uint8_t const *p_sr_data, uint8_t srdlen)); 00977 00978 00979 /**@brief Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). 00980 * 00981 * @note An application can start an advertising procedure for broadcasting purposes while a connection 00982 * is active. After a @ref BLE_GAP_EVT_CONNECTED event is received, this function may therefore 00983 * be called to start a broadcast advertising procedure. The advertising procedure 00984 * cannot however be connectable (it must be of type @ref BLE_GAP_ADV_TYPE_ADV_SCAN_IND or 00985 * @ref BLE_GAP_ADV_TYPE_ADV_NONCONN_IND). @note Only one advertiser may be active at any time. 00986 * 00987 * @note To use the currently active whitelist set p_adv_params->p_whitelist to NULL. 00988 * 00989 * @param[in] p_adv_params Pointer to advertising parameters structure. 00990 * 00991 * @retval ::NRF_SUCCESS The BLE stack has started advertising. 00992 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00993 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 00994 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check the accepted ranges and limits. 00995 * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid Bluetooth address supplied. 00996 * @retval ::BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST Discoverable mode and whitelist incompatible. 00997 * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. 00998 * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it. 00999 */ 01000 SVCALL(SD_BLE_GAP_ADV_START, uint32_t, sd_ble_gap_adv_start(ble_gap_adv_params_t const *p_adv_params)); 01001 01002 01003 /**@brief Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). 01004 * 01005 * @retval ::NRF_SUCCESS The BLE stack has stopped advertising. 01006 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (most probably not in advertising state). 01007 */ 01008 SVCALL(SD_BLE_GAP_ADV_STOP, uint32_t, sd_ble_gap_adv_stop(void)); 01009 01010 01011 /**@brief Update connection parameters. 01012 * 01013 * @details In the central role this will initiate a Link Layer connection parameter update procedure, 01014 * otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for 01015 * the central to perform the procedure. In both cases, and regardless of success or failure, the application 01016 * will be informed of the result with a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE event. 01017 * 01018 * @details This function can be used as a central both to reply to a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST or to start the procedure unrequested. 01019 * 01020 * @param[in] conn_handle Connection handle. 01021 * @param[in] p_conn_params Pointer to desired connection parameters. If NULL is provided on a peripheral role, 01022 * the parameters in the PPCP characteristic of the GAP service will be used instead. 01023 * If NULL is provided on a central role and in response to a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST, the peripheral request will be rejected 01024 * 01025 * @retval ::NRF_SUCCESS The Connection Update procedure has been started successfully. 01026 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01027 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints. 01028 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01029 * @retval ::NRF_ERROR_BUSY Procedure already in progress or not allowed at this time, process pending events and wait for pending procedures to complete and retry. 01030 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01031 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. 01032 */ 01033 SVCALL(SD_BLE_GAP_CONN_PARAM_UPDATE, uint32_t, sd_ble_gap_conn_param_update(uint16_t conn_handle, ble_gap_conn_params_t const *p_conn_params)); 01034 01035 01036 /**@brief Disconnect (GAP Link Termination). 01037 * 01038 * @details This call initiates the disconnection procedure, and its completion will be communicated to the application 01039 * with a @ref BLE_GAP_EVT_DISCONNECTED event. 01040 * 01041 * @param[in] conn_handle Connection handle. 01042 * @param[in] hci_status_code HCI status code, see @ref BLE_HCI_STATUS_CODES (accepted values are @ref BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION and @ref BLE_HCI_CONN_INTERVAL_UNACCEPTABLE). 01043 * 01044 * @retval ::NRF_SUCCESS The disconnection procedure has been started successfully. 01045 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01046 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01047 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (disconnection is already in progress). 01048 */ 01049 SVCALL(SD_BLE_GAP_DISCONNECT, uint32_t, sd_ble_gap_disconnect(uint16_t conn_handle, uint8_t hci_status_code)); 01050 01051 01052 /**@brief Set the radio's transmit power. 01053 * 01054 * @param[in] tx_power Radio transmit power in dBm (accepted values are -40, -30, -20, -16, -12, -8, -4, 0, and 4 dBm). 01055 * 01056 * @note -40 dBm will not actually give -40 dBm, but will instead be remapped to -30 dBm. 01057 * 01058 * @retval ::NRF_SUCCESS Successfully changed the transmit power. 01059 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01060 */ 01061 SVCALL(SD_BLE_GAP_TX_POWER_SET, uint32_t, sd_ble_gap_tx_power_set(int8_t tx_power)); 01062 01063 01064 /**@brief Set GAP Appearance value. 01065 * 01066 * @param[in] appearance Appearance (16-bit), see @ref BLE_APPEARANCES. 01067 * 01068 * @retval ::NRF_SUCCESS Appearance value set successfully. 01069 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01070 */ 01071 SVCALL(SD_BLE_GAP_APPEARANCE_SET, uint32_t, sd_ble_gap_appearance_set(uint16_t appearance)); 01072 01073 01074 /**@brief Get GAP Appearance value. 01075 * 01076 * @param[out] p_appearance Pointer to appearance (16-bit) to be filled in, see @ref BLE_APPEARANCES. 01077 * 01078 * @retval ::NRF_SUCCESS Appearance value retrieved successfully. 01079 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01080 */ 01081 SVCALL(SD_BLE_GAP_APPEARANCE_GET, uint32_t, sd_ble_gap_appearance_get(uint16_t *p_appearance)); 01082 01083 01084 /**@brief Set GAP Peripheral Preferred Connection Parameters. 01085 * 01086 * @param[in] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure with the desired parameters. 01087 * 01088 * @retval ::NRF_SUCCESS Peripheral Preferred Connection Parameters set successfully. 01089 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01090 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01091 */ 01092 SVCALL(SD_BLE_GAP_PPCP_SET, uint32_t, sd_ble_gap_ppcp_set(ble_gap_conn_params_t const *p_conn_params)); 01093 01094 01095 /**@brief Get GAP Peripheral Preferred Connection Parameters. 01096 * 01097 * @param[out] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure where the parameters will be stored. 01098 * 01099 * @retval ::NRF_SUCCESS Peripheral Preferred Connection Parameters retrieved successfully. 01100 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01101 */ 01102 SVCALL(SD_BLE_GAP_PPCP_GET, uint32_t, sd_ble_gap_ppcp_get(ble_gap_conn_params_t *p_conn_params)); 01103 01104 01105 /**@brief Set GAP device name. 01106 * 01107 * @param[in] p_write_perm Write permissions for the Device Name characteristic, see @ref ble_gap_conn_sec_mode_t. 01108 * @param[in] p_dev_name Pointer to a UTF-8 encoded, <b>non NULL-terminated</b> string. 01109 * @param[in] len Length of the UTF-8, <b>non NULL-terminated</b> string pointed to by p_dev_name in octets (must be smaller or equal than @ref BLE_GAP_DEVNAME_MAX_LEN). 01110 * 01111 * @retval ::NRF_SUCCESS GAP device name and permissions set successfully. 01112 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01113 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01114 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied. 01115 */ 01116 SVCALL(SD_BLE_GAP_DEVICE_NAME_SET, uint32_t, sd_ble_gap_device_name_set(ble_gap_conn_sec_mode_t const *p_write_perm, uint8_t const *p_dev_name, uint16_t len)); 01117 01118 01119 /**@brief Get GAP device name. 01120 * 01121 * @param[out] p_dev_name Pointer to an empty buffer where the UTF-8 <b>non NULL-terminated</b> string will be placed. Set to NULL to obtain the complete device name length. 01122 * @param[in,out] p_len Length of the buffer pointed by p_dev_name, complete device name length on output. 01123 * 01124 * @note If the device name is longer than the size of the supplied buffer, 01125 * p_len will return the complete device name length, 01126 * and not the number of bytes actually returned in p_dev_name. 01127 * The application may use this information to allocate a suitable buffer size. 01128 * 01129 * @retval ::NRF_SUCCESS GAP device name retrieved successfully. 01130 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01131 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied. 01132 */ 01133 SVCALL(SD_BLE_GAP_DEVICE_NAME_GET, uint32_t, sd_ble_gap_device_name_get(uint8_t *p_dev_name, uint16_t *p_len)); 01134 01135 01136 /**@brief Initiate the GAP Authentication procedure. 01137 * 01138 * @param[in] conn_handle Connection handle. 01139 * @param[in] p_sec_params Pointer to the @ref ble_gap_sec_params_t structure with the security parameters to be used during the pairing or bonding procedure. 01140 * In the peripheral role, only the timeout, bond and mitm fields of this structure are used. 01141 * In the central role, this pointer may be NULL to reject a Security Request. 01142 * 01143 * @details In the central role, this function will send an SMP Pairing Request (or an SMP Pairing Failed if rejected), 01144 * otherwise in the peripheral role, an SMP Security Request will be sent. 01145 * 01146 * @note Calling this function may result in the following events depending on the outcome and parameters: @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST, 01147 * @ref BLE_GAP_EVT_SEC_INFO_REQUEST, @ref BLE_GAP_EVT_AUTH_KEY_REQUEST, @ref BLE_GAP_EVT_CONN_SEC_UPDATE, @ref BLE_GAP_EVT_AUTH_STATUS. 01148 * 01149 * 01150 * @retval ::NRF_SUCCESS Successfully initiated authentication procedure. 01151 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01152 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01153 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01154 * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. 01155 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01156 * @retval ::NRF_ERROR_TIMEOUT A SMP timout has occured, and further SMP operations on this link is prohibited. 01157 */ 01158 SVCALL(SD_BLE_GAP_AUTHENTICATE, uint32_t, sd_ble_gap_authenticate(uint16_t conn_handle, ble_gap_sec_params_t const *p_sec_params)); 01159 01160 01161 /**@brief Reply with GAP security parameters. 01162 * 01163 * @param[in] conn_handle Connection handle. 01164 * @param[in] sec_status Security status, see @ref BLE_GAP_SEC_STATUS. 01165 * @param[in] p_sec_params Pointer to a @ref ble_gap_sec_params_t security parameters structure. In the central role this must be set to NULL, as the parameters have 01166 * already been provided during a previous call to @ref sd_ble_gap_authenticate. 01167 * @param[in,out] p_sec_keyset Pointer to a @ref ble_gap_sec_keyset_t security keyset structure. Any keys distributed as a result of the ongoing security procedure 01168 * will be stored into the memory referenced by the pointers inside this structure. The keys will be stored and available to the application 01169 * upon reception of a @ref BLE_GAP_EVT_AUTH_STATUS event. 01170 * The pointer to the ID key data distributed by the <b>local device</b> constitutes however an exception. It can either point to ID key data 01171 * filled in by the user before calling this function, in which case a user-supplied Bluetooth address and IRK will be distributed, 01172 * or the pointer to the ID key data structure can be NULL, in which case the device's configured (or default, if none is configured) 01173 * Bluetooth address and IRK will be distributed. 01174 * 01175 * @details This function is only used to reply to a @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST, calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE. 01176 * @note If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters. 01177 * 01178 * @retval ::NRF_SUCCESS Successfully accepted security parameter from the application. 01179 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01180 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01181 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01182 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01183 */ 01184 SVCALL(SD_BLE_GAP_SEC_PARAMS_REPLY, uint32_t, sd_ble_gap_sec_params_reply(uint16_t conn_handle, uint8_t sec_status, ble_gap_sec_params_t const *p_sec_params, ble_gap_sec_keyset_t const *p_sec_keyset)); 01185 01186 01187 /**@brief Reply with an authentication key. 01188 * 01189 * @param[in] conn_handle Connection handle. 01190 * @param[in] key_type See @ref BLE_GAP_AUTH_KEY_TYPES. 01191 * @param[in] p_key If key type is @ref BLE_GAP_AUTH_KEY_TYPE_NONE, then NULL. 01192 * If key type is @ref BLE_GAP_AUTH_KEY_TYPE_PASSKEY, then a 6-byte ASCII string (digit 0..9 only, no NULL termination). 01193 * If key type is @ref BLE_GAP_AUTH_KEY_TYPE_OOB, then a 16-byte OOB key value in Little Endian format. 01194 * 01195 * @details This function is only used to reply to a @ref BLE_GAP_EVT_AUTH_KEY_REQUEST, calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE. 01196 * @note If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters. 01197 * 01198 * @retval ::NRF_SUCCESS Authentication key successfully set. 01199 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01200 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01201 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01202 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01203 */ 01204 SVCALL(SD_BLE_GAP_AUTH_KEY_REPLY, uint32_t, sd_ble_gap_auth_key_reply(uint16_t conn_handle, uint8_t key_type, uint8_t const *p_key)); 01205 01206 01207 /**@brief Initiate GAP Encryption procedure. 01208 * 01209 * @param[in] conn_handle Connection handle. 01210 * @param[in] p_master_id Pointer to a @ref ble_gap_master_id_t master identification structure. 01211 * @param[in] p_enc_info Pointer to a @ref ble_gap_enc_info_t encryption information structure. 01212 * 01213 * @details In the central role, this function will initiate the encryption procedure using the encryption information provided. 01214 * 01215 * @note Calling this function may result in the following event depending on the outcome and parameters: @ref BLE_GAP_EVT_CONN_SEC_UPDATE. 01216 * 01217 * @retval ::NRF_SUCCESS Successfully initiated authentication procedure. 01218 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01219 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01220 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01221 * @retval ::BLE_ERROR_INVALID_ROLE Operation is not supported in the Peripheral role. 01222 * @retval ::NRF_ERROR_BUSY Procedure already in progress or not allowed at this time, wait for pending procedures to complete and retry. 01223 */ 01224 SVCALL(SD_BLE_GAP_ENCRYPT, uint32_t, sd_ble_gap_encrypt(uint16_t conn_handle, ble_gap_master_id_t const *p_master_id, ble_gap_enc_info_t const *p_enc_info)); 01225 01226 01227 /**@brief Reply with GAP security information. 01228 * 01229 * @param[in] conn_handle Connection handle. 01230 * @param[in] p_enc_info Pointer to a @ref ble_gap_enc_info_t encryption information structure. May be NULL to signal none is available. 01231 * @param[in] p_id_info Pointer to a @ref ble_gap_irk_t identity information structure. May be NULL to signal none is available. 01232 * @param[in] p_sign_info Pointer to a @ref ble_gap_sign_info_t signing information structure. May be NULL to signal none is available. 01233 * 01234 * @details This function is only used to reply to a @ref BLE_GAP_EVT_SEC_INFO_REQUEST, calling it at other times will result in @ref NRF_ERROR_INVALID_STATE. 01235 * @note If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters. 01236 * @note Data signing is not yet supported, and p_sign_info must therefore be NULL. 01237 * 01238 * @retval ::NRF_SUCCESS Successfully accepted security information. 01239 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01240 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01241 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01242 */ 01243 SVCALL(SD_BLE_GAP_SEC_INFO_REPLY, uint32_t, sd_ble_gap_sec_info_reply(uint16_t conn_handle, ble_gap_enc_info_t const *p_enc_info, ble_gap_irk_t const *p_id_info, ble_gap_sign_info_t const *p_sign_info)); 01244 01245 01246 /**@brief Get the current connection security. 01247 * 01248 * @param[in] conn_handle Connection handle. 01249 * @param[out] p_conn_sec Pointer to a @ref ble_gap_conn_sec_t structure to be filled in. 01250 * 01251 * @retval ::NRF_SUCCESS Current connection security successfully retrieved. 01252 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01253 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01254 */ 01255 SVCALL(SD_BLE_GAP_CONN_SEC_GET, uint32_t, sd_ble_gap_conn_sec_get(uint16_t conn_handle, ble_gap_conn_sec_t *p_conn_sec)); 01256 01257 01258 /**@brief Start reporting the received signal strength to the application. 01259 * 01260 * A new event is reported whenever the RSSI value changes, until @ref sd_ble_gap_rssi_stop is called. 01261 * 01262 * @param[in] conn_handle Connection handle. 01263 * @param[in] threshold_dbm Minimum change in dBm before triggering the @ref BLE_GAP_EVT_RSSI_CHANGED event. Events are disabled if threshold_dbm equals @ref BLE_GAP_RSSI_THRESHOLD_INVALID. 01264 * @param[in] skip_count Number of RSSI samples with a change of threshold_dbm or more before sending a new @ref BLE_GAP_EVT_RSSI_CHANGED event. 01265 * 01266 * @retval ::NRF_SUCCESS Successfully activated RSSI reporting. 01267 * @retval ::NRF_ERROR_INVALID_STATE Disconnection in progress. Invalid state to perform operation. 01268 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01269 */ 01270 SVCALL(SD_BLE_GAP_RSSI_START, uint32_t, sd_ble_gap_rssi_start(uint16_t conn_handle, uint8_t threshold_dbm, uint8_t skip_count)); 01271 01272 01273 /**@brief Stop reporting the received signal strength. 01274 * 01275 * @note An RSSI change detected before the call but not yet received by the application 01276 * may be reported after @ref sd_ble_gap_rssi_stop has been called. 01277 * 01278 * @param[in] conn_handle Connection handle. 01279 * 01280 * @retval ::NRF_SUCCESS Successfully deactivated RSSI reporting. 01281 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01282 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01283 */ 01284 SVCALL(SD_BLE_GAP_RSSI_STOP, uint32_t, sd_ble_gap_rssi_stop(uint16_t conn_handle)); 01285 01286 01287 /**@brief Get the received signal strength for the last connection event. 01288 * 01289 * @param[in] conn_handle Connection handle. 01290 * @param[out] p_rssi Pointer to the location where the RSSI measurement shall be stored. 01291 * 01292 * @ref sd_ble_gap_rssi_start must be called to start reporting RSSI before using this function. @ref NRF_ERROR_NOT_FOUND 01293 * will be returned until RSSI was sampled for the first time after calling @ref sd_ble_gap_rssi_start. 01294 * 01295 * @retval ::NRF_SUCCESS Successfully read the RSSI. 01296 * @retval ::NRF_ERROR_NOT_FOUND No sample is available. 01297 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01298 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied. 01299 * @retval ::NRF_ERROR_INVALID_STATE RSSI reporting is not ongoing, or disconnection in progress. 01300 */ 01301 SVCALL(SD_BLE_GAP_RSSI_GET, uint32_t, sd_ble_gap_rssi_get(uint16_t conn_handle, int8_t *p_rssi)); 01302 01303 01304 /**@brief Start scanning (GAP Discovery procedure, Observer Procedure). 01305 * 01306 * @note To use the currently active whitelist set p_scan_params->p_whitelist to NULL. 01307 * 01308 * @param[in] p_scan_params Pointer to scan parameters structure. 01309 * 01310 * @retval ::NRF_SUCCESS Successfully initiated scanning procedure. 01311 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 01312 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01313 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01314 * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. 01315 * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it. 01316 */ 01317 SVCALL(SD_BLE_GAP_SCAN_START, uint32_t, sd_ble_gap_scan_start(ble_gap_scan_params_t const *p_scan_params)); 01318 01319 01320 /**@brief Stop scanning (GAP Discovery procedure, Observer Procedure). 01321 * 01322 * @retval ::NRF_SUCCESS Successfully stopped scanning procedure. 01323 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (most probably not in scanning state). 01324 */ 01325 SVCALL(SD_BLE_GAP_SCAN_STOP, uint32_t, sd_ble_gap_scan_stop(void)); 01326 01327 01328 /**@brief Create a connection (GAP Link Establishment). 01329 * 01330 * @note To use the currently active whitelist set p_scan_params->p_whitelist to NULL. 01331 * 01332 * @param[in] p_peer_addr Pointer to peer address. If the selective bit is set in @ref ble_gap_scan_params_t, then this must be NULL. 01333 * @param[in] p_scan_params Pointer to scan parameters structure. 01334 * @param[in] p_conn_params Pointer to desired connection parameters. 01335 * 01336 * @retval ::NRF_SUCCESS Successfully initiated connection procedure. 01337 * @retval ::NRF_ERROR_INVALID_ADDR Invalid parameter(s) pointer supplied. 01338 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 01339 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01340 * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid Peer address. 01341 * @retval ::NRF_ERROR_NO_MEM limit of available connections reached. 01342 * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. If another connection is being established wait for the corresponding 01343 * @ref BLE_GAP_EVT_CONNECTED event before calling again. 01344 * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it. 01345 */ 01346 SVCALL(SD_BLE_GAP_CONNECT, uint32_t, sd_ble_gap_connect(ble_gap_addr_t const *p_peer_addr, ble_gap_scan_params_t const *p_scan_params, ble_gap_conn_params_t const *p_conn_params)); 01347 01348 01349 /**@brief Cancel a connection establishment. 01350 * 01351 * @retval ::NRF_SUCCESS Successfully cancelled an ongoing connection procedure. 01352 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. 01353 */ 01354 SVCALL(SD_BLE_GAP_CONNECT_CANCEL, uint32_t, sd_ble_gap_connect_cancel(void)); 01355 01356 /** @} */ 01357 01358 #endif // BLE_GAP_H__ 01359 01360 /** 01361 @} 01362 */
Generated on Tue Jul 12 2022 13:49:03 by
1.7.2