Francesco Pavoni
BLE_Nano nRF51 Central heart rate
Embed:
(wiki syntax)
Show/hide line numbers
ble.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 * 4. This software must only be used in a processor manufactured by Nordic 00020 * Semiconductor ASA, or in a processor manufactured by a third party that 00021 * is used in combination with a processor manufactured by Nordic Semiconductor. 00022 * 00023 * 00024 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00025 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00026 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00027 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00028 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00029 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00030 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00031 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00032 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00033 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00034 * 00035 */ 00036 00037 /** 00038 @addtogroup BLE_COMMON BLE SoftDevice Common 00039 @{ 00040 @defgroup ble_api Events, type definitions and API calls 00041 @{ 00042 00043 @brief Module independent events, type definitions and API calls for the BLE SoftDevice. 00044 00045 */ 00046 00047 #ifndef BLE_H__ 00048 #define BLE_H__ 00049 00050 #include "ble_ranges.h" 00051 #include "ble_types.h" 00052 #include "ble_gap.h" 00053 #include "ble_l2cap.h" 00054 #include "ble_gatt.h" 00055 #include "ble_gattc.h" 00056 #include "ble_gatts.h" 00057 00058 #ifdef __cplusplus 00059 extern "C" { 00060 #endif 00061 00062 /** @addtogroup BLE_COMMON_ENUMERATIONS Enumerations 00063 * @{ */ 00064 00065 /** 00066 * @brief Common API SVC numbers. 00067 */ 00068 enum BLE_COMMON_SVCS 00069 { 00070 SD_BLE_ENABLE = BLE_SVC_BASE, /**< Enable and initialize the BLE stack */ 00071 SD_BLE_EVT_GET, /**< Get an event from the pending events queue. */ 00072 SD_BLE_TX_PACKET_COUNT_GET, /**< Get the total number of available application transmission packets for a particular connection. */ 00073 SD_BLE_UUID_VS_ADD, /**< Add a Vendor Specific UUID. */ 00074 SD_BLE_UUID_DECODE, /**< Decode UUID bytes. */ 00075 SD_BLE_UUID_ENCODE, /**< Encode UUID bytes. */ 00076 SD_BLE_VERSION_GET, /**< Get the local version information (company id, Link Layer Version, Link Layer Subversion). */ 00077 SD_BLE_USER_MEM_REPLY, /**< User Memory Reply. */ 00078 SD_BLE_OPT_SET, /**< Set a BLE option. */ 00079 SD_BLE_OPT_GET, /**< Get a BLE option. */ 00080 }; 00081 00082 /** 00083 * @brief BLE Module Independent Event IDs. 00084 */ 00085 enum BLE_COMMON_EVTS 00086 { 00087 BLE_EVT_TX_COMPLETE = BLE_EVT_BASE, /**< Transmission Complete. @ref ble_evt_tx_complete_t */ 00088 BLE_EVT_USER_MEM_REQUEST, /**< User Memory request. @ref ble_evt_user_mem_request_t */ 00089 BLE_EVT_USER_MEM_RELEASE /**< User Memory release. @ref ble_evt_user_mem_release_t */ 00090 }; 00091 00092 /**@brief BLE connection bandwidth types. 00093 * Bandwidth types supported by the SoftDevice in packets per connection interval. 00094 */ 00095 enum BLE_CONN_BWS 00096 { 00097 BLE_CONN_BW_NONE = 0, 00098 BLE_CONN_BW_LOW, 00099 BLE_CONN_BW_MID, 00100 BLE_CONN_BW_HIGH 00101 }; 00102 00103 /**@brief Common Option IDs. 00104 * IDs that uniquely identify a common option. 00105 */ 00106 enum BLE_COMMON_OPTS 00107 { 00108 BLE_COMMON_OPT_CONN_BW = BLE_OPT_BASE, /**< Bandwidth configuration @ref ble_common_opt_conn_bw_t */ 00109 BLE_COMMON_OPT_PA_LNA /**< PA and LNA options */ 00110 }; 00111 00112 /** @} */ 00113 00114 /** @addtogroup BLE_COMMON_DEFINES Defines 00115 * @{ */ 00116 00117 /** @brief Required pointer alignment for BLE Events. 00118 */ 00119 #define BLE_EVTS_PTR_ALIGNMENT 4 00120 00121 /** @defgroup BLE_USER_MEM_TYPES User Memory Types 00122 * @{ */ 00123 #define BLE_USER_MEM_TYPE_INVALID 0x00 /**< Invalid User Memory Types. */ 00124 #define BLE_USER_MEM_TYPE_GATTS_QUEUED_WRITES 0x01 /**< User Memory for GATTS queued writes. */ 00125 /** @} */ 00126 00127 /** @defgroup BLE_UUID_VS_COUNTS Vendor Specific UUID counts 00128 * @{ 00129 */ 00130 #define BLE_UUID_VS_COUNT_MIN 1 /**< Minimum VS UUID count. */ 00131 #define BLE_UUID_VS_COUNT_DEFAULT 0 /**< Use the default VS UUID count (10 for this version of the SoftDevice). */ 00132 /** @} */ 00133 00134 /** @} */ 00135 00136 /** @addtogroup BLE_COMMON_STRUCTURES Structures 00137 * @{ */ 00138 00139 /**@brief User Memory Block. */ 00140 typedef struct 00141 { 00142 uint8_t *p_mem; /**< Pointer to the start of the user memory block. */ 00143 uint16_t len; /**< Length in bytes of the user memory block. */ 00144 } ble_user_mem_block_t; 00145 00146 /** 00147 * @brief Event structure for @ref BLE_EVT_TX_COMPLETE. 00148 */ 00149 typedef struct 00150 { 00151 uint8_t count; /**< Number of packets transmitted. */ 00152 } ble_evt_tx_complete_t; 00153 00154 /**@brief Event structure for @ref BLE_EVT_USER_MEM_REQUEST. */ 00155 typedef struct 00156 { 00157 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */ 00158 } ble_evt_user_mem_request_t; 00159 00160 /**@brief Event structure for @ref BLE_EVT_USER_MEM_RELEASE. */ 00161 typedef struct 00162 { 00163 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */ 00164 ble_user_mem_block_t mem_block; /**< User memory block */ 00165 } ble_evt_user_mem_release_t; 00166 00167 00168 /**@brief Event structure for events not associated with a specific function module. */ 00169 typedef struct 00170 { 00171 uint16_t conn_handle; /**< Connection Handle on which this event occurred. */ 00172 union 00173 { 00174 ble_evt_tx_complete_t tx_complete; /**< Transmission Complete. */ 00175 ble_evt_user_mem_request_t user_mem_request; /**< User Memory Request Event Parameters. */ 00176 ble_evt_user_mem_release_t user_mem_release; /**< User Memory Release Event Parameters. */ 00177 } params; 00178 } ble_common_evt_t; 00179 00180 /**@brief BLE Event header. */ 00181 typedef struct 00182 { 00183 uint16_t evt_id; /**< Value from a BLE_<module>_EVT series. */ 00184 uint16_t evt_len; /**< Length in octets including this header. */ 00185 } ble_evt_hdr_t; 00186 00187 /**@brief Common BLE Event type, wrapping the module specific event reports. */ 00188 typedef struct 00189 { 00190 ble_evt_hdr_t header; /**< Event header. */ 00191 union 00192 { 00193 ble_common_evt_t common_evt; /**< Common Event, evt_id in BLE_EVT_* series. */ 00194 ble_gap_evt_t gap_evt; /**< GAP originated event, evt_id in BLE_GAP_EVT_* series. */ 00195 ble_l2cap_evt_t l2cap_evt; /**< L2CAP originated event, evt_id in BLE_L2CAP_EVT* series. */ 00196 ble_gattc_evt_t gattc_evt; /**< GATT client originated event, evt_id in BLE_GATTC_EVT* series. */ 00197 ble_gatts_evt_t gatts_evt; /**< GATT server originated event, evt_id in BLE_GATTS_EVT* series. */ 00198 } evt; 00199 } ble_evt_t; 00200 00201 00202 /** 00203 * @brief Version Information. 00204 */ 00205 typedef struct 00206 { 00207 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). */ 00208 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). */ 00209 uint16_t subversion_number; /**< Link Layer Sub Version number, corresponds to the SoftDevice Config ID or Firmware ID (FWID). */ 00210 } ble_version_t; 00211 00212 /* @brief: Configuration parameters for the PA and LNA. */ 00213 typedef struct 00214 { 00215 uint8_t enable :1; /**< Enable toggling for this amplifier */ 00216 uint8_t active_high :1; /**< Set the pin to be active high */ 00217 uint8_t gpio_pin :6; /**< The GPIO pin to toggle for this amplifier */ 00218 } ble_pa_lna_cfg_t; 00219 00220 /* 00221 * @brief PA & LNA GPIO toggle configuration 00222 * 00223 * This option configures the SoftDevice to toggle pins when the radio is active for use with a power amplifier and/or 00224 * a low noise amplifier. 00225 * 00226 * Toggling the pins is achieved by using two PPI channels and a GPIOTE channel. The hardware channel IDs are provided 00227 * by the application and should be regarded as reserved as long as any PA/LNA toggling is enabled. 00228 * 00229 * @note @ref sd_ble_opt_get is not supported for this option. 00230 * @note This feature is only supported for nRF52, on nRF51 @ref NRF_ERROR_NOT_SUPPORTED will always be returned. 00231 * @note Setting this option while the radio is in use (i.e. any of the roles are active) may have undefined consequences 00232 * and must be avoided by the application. 00233 * 00234 */ 00235 typedef struct 00236 { 00237 ble_pa_lna_cfg_t pa_cfg; /**< Power Amplifier configuration */ 00238 ble_pa_lna_cfg_t lna_cfg; /**< Low Noise Amplifier configuration */ 00239 00240 uint8_t ppi_ch_id_set; /**< PPI channel used for radio pin setting */ 00241 uint8_t ppi_ch_id_clr; /**< PPI channel used for radio pin clearing */ 00242 uint8_t gpiote_ch_id; /**< GPIOTE channel used for radio pin toggling */ 00243 } ble_common_opt_pa_lna_t; 00244 00245 /** 00246 * @brief BLE connection bandwidth configuration parameters 00247 */ 00248 typedef struct 00249 { 00250 uint8_t conn_bw_tx; /**< Connection bandwidth configuration for transmission, see @ref BLE_CONN_BWS.*/ 00251 uint8_t conn_bw_rx; /**< Connection bandwidth configuration for reception, see @ref BLE_CONN_BWS.*/ 00252 } ble_conn_bw_t; 00253 00254 /**@brief BLE connection specific bandwidth configuration parameters. 00255 * 00256 * This can be used with @ref sd_ble_opt_set to set the bandwidth configuration to be used when creating connections. 00257 * 00258 * Call @ref sd_ble_opt_set with this option prior to calling @ref sd_ble_gap_adv_start or @ref sd_ble_gap_connect. 00259 * 00260 * The bandwidth configurations set via @ref sd_ble_opt_set are maintained separately for central and peripheral 00261 * connections. The given configurations are used for all future connections of the role indicated in this structure 00262 * unless they are changed by subsequent @ref sd_ble_opt_set calls. 00263 * 00264 * @note When this option is not used, the SoftDevice will use the default options: 00265 * - @ref BLE_CONN_BW_HIGH for @ref BLE_GAP_ROLE_PERIPH connections (both transmission and reception). 00266 * - @ref BLE_CONN_BW_MID for @ref BLE_GAP_ROLE_CENTRAL connections (both transmisison and reception). 00267 * This option allows the application to selectively override these defaults for each role. 00268 * 00269 * @note The global memory pool configuration can be set with the @ref ble_conn_bw_counts_t configuration parameter, which 00270 * is provided to @ref sd_ble_enable. 00271 * 00272 * @note Please refer to SoftDevice Specification for more information on bandwidth configuration. 00273 * 00274 * @mscs 00275 * @mmsc{@ref BLE_COMMON_CONF_BW} 00276 * @endmscs 00277 * 00278 * @retval ::NRF_SUCCESS Set successfully. 00279 * @retval ::BLE_ERROR_INVALID_ROLE The role is invalid. 00280 * @retval ::NRF_ERROR_INVALID_PARAM Invalid bandwidth configuration parameters. 00281 * @retval ::NRF_ERROR_NOT_SUPPORTED If the combination of role and bandwidth configuration is not supported. 00282 */ 00283 typedef struct 00284 { 00285 uint8_t role; /**< BLE role of the connection, see @ref BLE_GAP_ROLES. */ 00286 ble_conn_bw_t conn_bw; /**< Bandwidth configuration parameters. */ 00287 } ble_common_opt_conn_bw_t; 00288 00289 /**@brief Option structure for common options. */ 00290 typedef union 00291 { 00292 ble_common_opt_conn_bw_t conn_bw; /**< Parameters for the connection bandwidth option. */ 00293 ble_common_opt_pa_lna_t pa_lna; /**< Parameters for controlling PA and LNA pin toggling. */ 00294 } ble_common_opt_t; 00295 00296 /**@brief Common BLE Option type, wrapping the module specific options. */ 00297 typedef union 00298 { 00299 ble_common_opt_t common_opt; /**< COMMON options, opt_id in @ref BLE_COMMON_OPTS series. */ 00300 ble_gap_opt_t gap_opt; /**< GAP option, opt_id in @ref BLE_GAP_OPTS series. */ 00301 } ble_opt_t; 00302 00303 /** 00304 * @brief BLE bandwidth count parameters 00305 * 00306 * These parameters are used to configure the memory pools allocated within the SoftDevice for application packets 00307 * (both transmission and reception) for all connections. 00308 * 00309 * @note The sum of all three counts must add up to the sum of @ref ble_gap_enable_params_t::central_conn_count and 00310 * @ref ble_gap_enable_params_t::periph_conn_count in @ref ble_gap_enable_params_t. 00311 */ 00312 typedef struct { 00313 uint8_t high_count; /**< Total number of high bandwidth TX or RX memory pools available to the application at runtime for all active connections. */ 00314 uint8_t mid_count; /**< Total number of medium bandwidth TX or RX memory pools available to the application at runtime for all active connections. */ 00315 uint8_t low_count; /**< Total number of low bandwidth TX or RX memory pools available to the application at runtime for all active connections. */ 00316 } ble_conn_bw_count_t; 00317 00318 /** 00319 * @brief BLE bandwidth global memory pool configuration parameters 00320 * 00321 * These configuration parameters are used to set the amount of memory dedicated to application packets for 00322 * all connections. The application should specify the most demanding configuration for the intended use. 00323 * 00324 * Please refer to the SoftDevice Specification for more information on bandwidth configuration. 00325 * 00326 * @note Each connection created at runtime requires both a TX and an RX memory pool. By the use of these configuration 00327 * parameters, the application can decide the size and total number of the global memory pools that will be later 00328 * available for connection creation. 00329 * 00330 * @mscs 00331 * @mmsc{@ref BLE_COMMON_CONF_BW} 00332 * @endmscs 00333 * 00334 */ 00335 typedef struct { 00336 ble_conn_bw_count_t tx_counts; /**< Global memory pool configuration for transmission.*/ 00337 ble_conn_bw_count_t rx_counts; /**< Global memory pool configuration for reception.*/ 00338 } ble_conn_bw_counts_t; 00339 00340 /** 00341 * @brief BLE Common Initialization parameters. 00342 * 00343 * @note If @ref p_conn_bw_counts is NULL the SoftDevice will assume default bandwidth configuration for all connections. 00344 * To fit a custom bandwidth configuration requirement, the application developer may have to specify a custom memory 00345 * pool configuration here. See @ref ble_common_opt_conn_bw_t for bandwidth configuration of individual connections. 00346 * Please refer to the SoftDevice Specification for more information on bandwidth configuration. 00347 */ 00348 typedef struct 00349 { 00350 uint16_t vs_uuid_count; /**< Maximum number of 128-bit, Vendor Specific UUID bases to allocate. */ 00351 ble_conn_bw_counts_t *p_conn_bw_counts; /**< Bandwidth configuration parameters or NULL for defaults. */ 00352 } ble_common_enable_params_t; 00353 00354 /** 00355 * @brief BLE Initialization parameters. 00356 */ 00357 typedef struct 00358 { 00359 ble_common_enable_params_t common_enable_params; /**< Common init parameters @ref ble_common_enable_params_t. */ 00360 ble_gap_enable_params_t gap_enable_params; /**< GAP init parameters @ref ble_gap_enable_params_t. */ 00361 ble_gatts_enable_params_t gatts_enable_params; /**< GATTS init parameters @ref ble_gatts_enable_params_t. */ 00362 } ble_enable_params_t; 00363 00364 /** @} */ 00365 00366 /** @addtogroup BLE_COMMON_FUNCTIONS Functions 00367 * @{ */ 00368 00369 /**@brief Enable the BLE stack 00370 * 00371 * @param[in, out] p_ble_enable_params Pointer to ble_enable_params_t 00372 * @param[in, out] p_app_ram_base Pointer to a variable containing the start address of the application RAM region 00373 * (APP_RAM_BASE). On return, this will contain the minimum start address of the application RAM region required by the 00374 * SoftDevice for this configuration. Calling @ref sd_ble_enable() with *p_app_ram_base set to 0 can be used during 00375 * development to find out how much memory a specific configuration will need. 00376 * 00377 * @note The memory requirement for a specific configuration will not increase between SoftDevices with the same major 00378 * version number. 00379 * 00380 * @note At runtime the IC's RAM is split into 2 regions: The SoftDevice RAM region is located between 0x20000000 and 00381 * APP_RAM_BASE-1 and the application's RAM region is located between APP_RAM_BASE and the start of the call stack. 00382 * 00383 * @details This call initializes the BLE stack, no other BLE related function can be called before this one. 00384 * 00385 * @mscs 00386 * @mmsc{@ref BLE_COMMON_ENABLE} 00387 * @endmscs 00388 * 00389 * @retval ::NRF_SUCCESS The BLE stack has been initialized successfully. 00390 * @retval ::NRF_ERROR_INVALID_STATE The BLE stack had already been initialized and cannot be reinitialized. 00391 * @retval ::NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied. 00392 * @retval ::NRF_ERROR_INVALID_LENGTH The specified Attribute Table size is either too small or not a multiple of 4. 00393 * The minimum acceptable size is defined by @ref BLE_GATTS_ATTR_TAB_SIZE_MIN. 00394 * @retval ::NRF_ERROR_INVALID_PARAM Incorrectly configured VS UUID count or connection count parameters. 00395 * @retval ::NRF_ERROR_NO_MEM The amount of memory assigned to the SoftDevice by *p_app_ram_base is not 00396 * large enough to fit this configuration's memory requirement. Check *p_app_ram_base 00397 * and set the start address of the application RAM region accordingly. 00398 * @retval ::NRF_ERROR_CONN_COUNT The requested number of connections exceeds the maximum supported by the SoftDevice. 00399 * Please refer to the SoftDevice Specification for more information on role configuration. 00400 */ 00401 SVCALL(SD_BLE_ENABLE, uint32_t, sd_ble_enable(ble_enable_params_t * p_ble_enable_params, uint32_t * p_app_ram_base)); 00402 00403 /**@brief Get an event from the pending events queue. 00404 * 00405 * @param[out] p_dest Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. 00406 * This buffer <b>must be 4-byte aligned in memory</b>. 00407 * @param[in, out] p_len Pointer the length of the buffer, on return it is filled with the event length. 00408 * 00409 * @details This call allows the application to pull a BLE event from the BLE stack. The application is signaled that 00410 * an event is available from the BLE stack by the triggering of the SD_EVT_IRQn interrupt. 00411 * The application is free to choose whether to call this function from thread mode (main context) or directly from the 00412 * Interrupt Service Routine that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher 00413 * priority than the application, this function should be called in a loop (until @ref NRF_ERROR_NOT_FOUND is returned) 00414 * every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the BLE stack. Failure to do so 00415 * could potentially leave events in the internal queue without the application being aware of this fact. Sizing the 00416 * p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to 00417 * be copied into application memory. If the buffer provided is not large enough to fit the entire contents of the event, 00418 * @ref NRF_ERROR_DATA_SIZE will be returned and the application can then call again with a larger buffer size. 00419 * Please note that because of the variable length nature of some events, sizeof(ble_evt_t) will not always be large 00420 * enough to fit certain events, and so it is the application's responsibility to provide an amount of memory large 00421 * enough so that the relevant event is copied in full. The application may "peek" the event length by providing p_dest 00422 * as a NULL pointer and inspecting the value of *p_len upon return: 00423 * 00424 * \code 00425 * uint16_t len; 00426 * errcode = sd_ble_evt_get(NULL, &len); 00427 * \endcode 00428 * 00429 * @note The pointer supplied must be aligned to the extend defined by @ref BLE_EVTS_PTR_ALIGNMENT 00430 * 00431 * @mscs 00432 * @mmsc{@ref BLE_COMMON_IRQ_EVT_MSC} 00433 * @mmsc{@ref BLE_COMMON_THREAD_EVT_MSC} 00434 * @endmscs 00435 * 00436 * @retval ::NRF_SUCCESS Event pulled and stored into the supplied buffer. 00437 * @retval ::NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied. 00438 * @retval ::NRF_ERROR_NOT_FOUND No events ready to be pulled. 00439 * @retval ::NRF_ERROR_DATA_SIZE Event ready but could not fit into the supplied buffer. 00440 */ 00441 SVCALL(SD_BLE_EVT_GET, uint32_t, sd_ble_evt_get(uint8_t *p_dest, uint16_t *p_len)); 00442 00443 00444 /**@brief Get the total number of available guaranteed application transmission packets for a particular connection. 00445 * 00446 * @details This call allows the application to obtain the total number of guaranteed application transmission packets 00447 * available for a connection. Please note that this does not return the number of free packets, but rather the total 00448 * amount of them for that particular connection. The application has two options to handle transmitting application packets: 00449 * - Use a simple arithmetic calculation: after connection creation time the application should use this function to 00450 * find out the total amount of guaranteed packets available to it and store it in a variable. 00451 * Every time a packet is successfully queued for a transmission on this connection using any of the exposed functions in 00452 * this BLE API, the application should decrement that variable. Conversely, whenever a @ref BLE_EVT_TX_COMPLETE event 00453 * with the conn_handle matching the particular connection is received by the application, it should retrieve the count 00454 * field in such event and add that number to the same variable storing the number of available guaranteed packets. This 00455 * mechanism allows the application to be aware at any time of the number of guaranteed application packets available for 00456 * each of the active connections, and therefore it can know with certainty whether it is possible to send more data or 00457 * it has to wait for a @ref BLE_EVT_TX_COMPLETE event before it proceeds. 00458 * The application can still pursue transmissions when the number of guaranteed application packets available is smaller 00459 * than or equal to zero, but successful queuing of the tranmsission is not guaranteed. 00460 * - Choose to simply not keep track of available packets at all, and instead handle the @ref BLE_ERROR_NO_TX_PACKETS error 00461 * by queueing the packet to be transmitted and try again as soon as a @ref BLE_EVT_TX_COMPLETE event arrives. 00462 * 00463 * The API functions that <b>may</b> consume an application packet depending on the parameters supplied to them can be found below: 00464 * - @ref sd_ble_gattc_write (write without response only) 00465 * - @ref sd_ble_gatts_hvx (notifications only) 00466 * - @ref sd_ble_l2cap_tx (all packets) 00467 * 00468 * @param[in] conn_handle Connection handle. 00469 * @param[out] p_count Pointer to a uint8_t which will contain the number of application transmission packets upon 00470 * successful return. 00471 * @mscs 00472 * @mmsc{@ref BLE_COMMON_APP_BUFF_MSC} 00473 * @endmscs 00474 * 00475 * @retval ::NRF_SUCCESS Number of application transmission packets retrieved successfully. 00476 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00477 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00478 */ 00479 SVCALL(SD_BLE_TX_PACKET_COUNT_GET, uint32_t, sd_ble_tx_packet_count_get(uint16_t conn_handle, uint8_t *p_count)); 00480 00481 00482 /**@brief Add a Vendor Specific UUID. 00483 * 00484 * @details This call enables the application to add a vendor specific UUID to the BLE stack's table, for later use 00485 * all other modules and APIs. This then allows the application to use the shorter, 24-bit @ref ble_uuid_t format 00486 * when dealing with both 16-bit and 128-bit UUIDs without having to check for lengths and having split code paths. 00487 * The way that this is accomplished is by extending the grouping mechanism that the Bluetooth SIG standard base 00488 * UUID uses for all other 128-bit UUIDs. The type field in the @ref ble_uuid_t structure is an index (relative to 00489 * @ref BLE_UUID_TYPE_VENDOR_BEGIN) to the table populated by multiple calls to this function, and the uuid field 00490 * in the same structure contains the 2 bytes at indices 12 and 13. The number of possible 128-bit UUIDs available to 00491 * the application is therefore the number of Vendor Specific UUIDs added with the help of this function times 65536, 00492 * although restricted to modifying bytes 12 and 13 for each of the entries in the supplied array. 00493 * 00494 * @note Bytes 12 and 13 of the provided UUID will not be used internally, since those are always replaced by 00495 * the 16-bit uuid field in @ref ble_uuid_t. 00496 * 00497 * @note If a UUID is already present in the BLE stack's internal table, the corresponding index will be returned in 00498 * p_uuid_type along with an NRF_SUCCESS error code. 00499 * 00500 * @param[in] p_vs_uuid Pointer to a 16-octet (128-bit) little endian Vendor Specific UUID disregarding 00501 * bytes 12 and 13. 00502 * @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. 00503 * 00504 * @retval ::NRF_SUCCESS Successfully added the Vendor Specific UUID. 00505 * @retval ::NRF_ERROR_INVALID_ADDR If p_vs_uuid or p_uuid_type is NULL or invalid. 00506 * @retval ::NRF_ERROR_NO_MEM If there are no more free slots for VS UUIDs. 00507 */ 00508 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)); 00509 00510 00511 /** @brief Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit @ref ble_uuid_t structure. 00512 * 00513 * @details The raw UUID bytes excluding bytes 12 and 13 (i.e. bytes 0-11 and 14-15) of p_uuid_le are compared 00514 * to the corresponding ones in each entry of the table of vendor specific UUIDs populated with @ref sd_ble_uuid_vs_add 00515 * to look for a match. If there is such a match, bytes 12 and 13 are returned as p_uuid->uuid and the index 00516 * relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN as p_uuid->type. 00517 * 00518 * @note If the UUID length supplied is 2, then the type set by this call will always be @ref BLE_UUID_TYPE_BLE. 00519 * 00520 * @param[in] uuid_le_len Length in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes). 00521 * @param[in] p_uuid_le Pointer pointing to little endian raw UUID bytes. 00522 * @param[out] p_uuid Pointer to a @ref ble_uuid_t structure to be filled in. 00523 * 00524 * @retval ::NRF_SUCCESS Successfully decoded into the @ref ble_uuid_t structure. 00525 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00526 * @retval ::NRF_ERROR_INVALID_LENGTH Invalid UUID length. 00527 * @retval ::NRF_ERROR_NOT_FOUND For a 128-bit UUID, no match in the populated table of UUIDs. 00528 */ 00529 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)); 00530 00531 00532 /** @brief Encode a @ref ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit). 00533 * 00534 * @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. 00535 * 00536 * @param[in] p_uuid Pointer to a @ref ble_uuid_t structure that will be encoded into bytes. 00537 * @param[out] p_uuid_le_len Pointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes). 00538 * @param[out] p_uuid_le Pointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored. 00539 * 00540 * @retval ::NRF_SUCCESS Successfully encoded into the buffer. 00541 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00542 * @retval ::NRF_ERROR_INVALID_PARAM Invalid UUID type. 00543 */ 00544 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)); 00545 00546 00547 /**@brief Get Version Information. 00548 * 00549 * @details This call allows the application to get the BLE stack version information. 00550 * 00551 * @param[out] p_version Pointer to a ble_version_t structure to be filled in. 00552 * 00553 * @retval ::NRF_SUCCESS Version information stored successfully. 00554 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00555 * @retval ::NRF_ERROR_BUSY The BLE stack is busy (typically doing a locally-initiated disconnection procedure). 00556 */ 00557 SVCALL(SD_BLE_VERSION_GET, uint32_t, sd_ble_version_get(ble_version_t *p_version)); 00558 00559 00560 /**@brief Provide a user memory block. 00561 * 00562 * @note This call can only be used as a response to a @ref BLE_EVT_USER_MEM_REQUEST event issued to the application. 00563 * 00564 * @param[in] conn_handle Connection handle. 00565 * @param[in,out] p_block Pointer to a user memory block structure. 00566 * 00567 * @mscs 00568 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_PEER_CANCEL_MSC} 00569 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_AUTH_MSC} 00570 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_NOAUTH_MSC} 00571 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_BUF_AUTH_MSC} 00572 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_BUF_NOAUTH_MSC} 00573 * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_QUEUE_FULL_MSC} 00574 * @endmscs 00575 * 00576 * @retval ::NRF_SUCCESS Successfully queued a response to the peer. 00577 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00578 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection state or no execute write request pending. 00579 * @retval ::NRF_ERROR_BUSY The BLE stack is busy. Retry at later time. 00580 */ 00581 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)); 00582 00583 /**@brief Set a BLE option. 00584 * 00585 * @details This call allows the application to set the value of an option. 00586 * 00587 * @mscs 00588 * @mmsc{@ref BLE_GAP_PERIPH_BONDING_STATIC_PK_MSC} 00589 * @mmsc{@ref BLE_COMMON_CONF_BW} 00590 * @endmscs 00591 * 00592 * @param[in] opt_id Option ID, see @ref BLE_COMMON_OPTS and @ref BLE_GAP_OPTS. 00593 * @param[in] p_opt Pointer to a ble_opt_t structure containing the option value. 00594 * 00595 * @retval ::NRF_SUCCESS Option set successfully. 00596 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00597 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00598 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints. 00599 * @retval ::NRF_ERROR_INVALID_STATE Unable to set the parameter at this time. 00600 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed. 00601 */ 00602 SVCALL(SD_BLE_OPT_SET, uint32_t, sd_ble_opt_set(uint32_t opt_id, ble_opt_t const *p_opt)); 00603 00604 00605 /**@brief Get a BLE option. 00606 * 00607 * @details This call allows the application to retrieve the value of an option. 00608 * 00609 * @param[in] opt_id Option ID, see @ref BLE_COMMON_OPTS and @ref BLE_GAP_OPTS. 00610 * @param[out] p_opt Pointer to a ble_opt_t structure to be filled in. 00611 * 00612 * @retval ::NRF_SUCCESS Option retrieved successfully. 00613 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00614 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00615 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints. 00616 * @retval ::NRF_ERROR_INVALID_STATE Unable to retrieve the parameter at this time. 00617 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed. 00618 * @retval ::NRF_ERROR_NOT_SUPPORTED This option is not supported. 00619 * 00620 */ 00621 SVCALL(SD_BLE_OPT_GET, uint32_t, sd_ble_opt_get(uint32_t opt_id, ble_opt_t *p_opt)); 00622 00623 /** @} */ 00624 #ifdef __cplusplus 00625 } 00626 #endif 00627 #endif /* BLE_H__ */ 00628 00629 /** 00630 @} 00631 @} 00632 */ 00633
Generated on Wed Jul 13 2022 07:07:19 by
1.7.2