Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nRF51822 by
ble.h
00001 /* Copyright (c) 2011 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is confidential property of Nordic Semiconductor. The use, 00004 * copying, transfer or disclosure of such information is prohibited except by express written 00005 * agreement with Nordic Semiconductor. 00006 * 00007 */ 00008 /** 00009 @addtogroup BLE_COMMON BLE SoftDevice Common 00010 @{ 00011 @defgroup ble_api Events, type definitions and API calls 00012 @{ 00013 00014 @brief Module independent events, type definitions and API calls for the S110 SoftDevice. 00015 00016 */ 00017 00018 #ifndef BLE_H__ 00019 #define BLE_H__ 00020 00021 #include "nordic_global.h" 00022 #include "ble_ranges.h" 00023 #include "ble_types.h" 00024 #include "ble_gap.h" 00025 #include "ble_l2cap.h" 00026 #include "ble_gatt.h" 00027 #include "ble_gattc.h" 00028 #include "ble_gatts.h" 00029 00030 /** 00031 * @brief Common API SVC numbers. 00032 */ 00033 enum BLE_COMMON_SVCS 00034 { 00035 SD_BLE_EVT_GET = BLE_SVC_BASE, /**< Get an event from the pending events queue. */ 00036 SD_BLE_TX_BUFFER_COUNT_GET, /**< Get the total number of available application transmission buffers from the stack. */ 00037 SD_BLE_UUID_VS_ADD, /**< Add a Vendor Specific UUID. */ 00038 SD_BLE_UUID_DECODE, /**< Decode UUID bytes. */ 00039 SD_BLE_UUID_ENCODE, /**< Encode UUID bytes. */ 00040 SD_BLE_VERSION_GET, /**< Get the local version information (company id, LMP Version, LMP Subversion). */ 00041 SD_BLE_USER_MEM_REPLY, /**< User Memory Reply. */ 00042 }; 00043 00044 /** @brief Required pointer alignment for BLE Events. 00045 */ 00046 #define BLE_EVTS_PTR_ALIGNMENT 4 00047 00048 /** @defgroup BLE_USER_MEM_TYPES User Memory Types 00049 * @{ */ 00050 #define BLE_USER_MEM_TYPE_INVALID 0x00 /**< Invalid User Memory Types. */ 00051 #define BLE_USER_MEM_TYPE_GATTS_QUEUED_WRITES 0x01 /**< User Memory for GATTS queued writes. */ 00052 /** @} */ 00053 00054 /** @brief Maximum number of Vendor Specific UUIDs. 00055 */ 00056 #define BLE_UUID_VS_MAX_COUNT 10 00057 00058 /** 00059 * @brief BLE Module Independent Event IDs. 00060 */ 00061 enum BLE_COMMON_EVTS 00062 { 00063 BLE_EVT_TX_COMPLETE = BLE_EVT_BASE, /**< Transmission Complete. */ 00064 BLE_EVT_USER_MEM_REQUEST, /**< User Memory request. */ 00065 BLE_EVT_USER_MEM_RELEASE /**< User Memory release. */ 00066 }; 00067 00068 /**@brief User Memory Block. */ 00069 typedef struct 00070 { 00071 uint8_t* p_mem; /**< Pointer to the start of the user memory block. */ 00072 uint16_t len; /**< Length in bytes of the user memory block. */ 00073 } ble_user_mem_block_t; 00074 00075 /** 00076 * @brief TX complete event. 00077 */ 00078 typedef struct 00079 { 00080 uint8_t count; /**< Number of packets transmitted. */ 00081 } ble_evt_tx_complete_t; 00082 00083 /**@brief Event structure for BLE_EVT_USER_MEM_REQUEST. */ 00084 typedef struct 00085 { 00086 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */ 00087 } ble_evt_user_mem_request_t; 00088 00089 /**@brief Event structure for BLE_EVT_USER_MEM_RELEASE. */ 00090 typedef struct 00091 { 00092 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */ 00093 ble_user_mem_block_t mem_block; /**< User memory block */ 00094 } ble_evt_user_mem_release_t; 00095 00096 00097 /**@brief Event structure for events not associated with a specific function module. */ 00098 typedef struct 00099 { 00100 uint16_t conn_handle; /**< Connection Handle on which this event occured. */ 00101 union 00102 { 00103 ble_evt_tx_complete_t tx_complete; /**< Transmission Complete. */ 00104 ble_evt_user_mem_request_t user_mem_request; /**< User Memory Request Event Parameters. */ 00105 ble_evt_user_mem_release_t user_mem_release; /**< User Memory Release Event Parameters. */ 00106 } params; 00107 } ble_common_evt_t; 00108 00109 /**@brief BLE Event header. */ 00110 typedef struct 00111 { 00112 uint16_t evt_id; /**< Value from a BLE_<module>_EVT series. */ 00113 uint16_t evt_len; /**< Length in octets excluding this header. */ 00114 } ble_evt_hdr_t; 00115 00116 /**@brief Common BLE Event type, wrapping the module specific event reports. */ 00117 typedef struct 00118 { 00119 ble_evt_hdr_t header; /**< Event header. */ 00120 union 00121 { 00122 ble_common_evt_t common_evt; /**< Common Event, evt_id in BLE_EVT_* series. */ 00123 ble_gap_evt_t gap_evt; /**< GAP originated event, evt_id in BLE_GAP_EVT_* series. */ 00124 ble_l2cap_evt_t l2cap_evt; /**< L2CAP originated event, evt_id in BLE_L2CAP_EVT* series. */ 00125 ble_gattc_evt_t gattc_evt; /**< GATT client originated event, evt_id in BLE_GATTC_EVT* series. */ 00126 ble_gatts_evt_t gatts_evt; /**< GATT server originated event, evt_id in BLE_GATTS_EVT* series. */ 00127 } evt; 00128 } ble_evt_t; 00129 00130 00131 /** 00132 * @brief Version Information. 00133 */ 00134 typedef struct 00135 { 00136 uint8_t version_number; /**< LMP Version number for BT 4.0 spec is 6 (https://www.bluetooth.org/technical/assignednumbers/link_layer.htm). */ 00137 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). */ 00138 uint16_t subversion_number; /**< LMP Sub Version number corresponds to the SoftDevice Config ID. */ 00139 } ble_version_t; 00140 00141 00142 /**@brief Get an event from the pending events queue. 00143 * 00144 * @param[in] p_dest Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer <b>must be 4-byte aligned in memory</b>. 00145 * @param[in, out] p_len Pointer the length of the buffer, on return it is filled with the event length. 00146 * 00147 * @details This call allows the application to pull a BLE event from the BLE stack. The application is signalled that an event is 00148 * available from the BLE Stack by the triggering of the SD_EVT_IRQn interrupt (mapped to IRQ 22). 00149 * The application is free to choose whether to call this function from thread mode (main context) or directly from the Interrupt Service Routine 00150 * that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher priority than the application, this function should be called 00151 * in a loop (until @ref NRF_ERROR_NOT_FOUND is returned) every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the stack. 00152 * Failure to do so could potentially leave events in the internal queue without the application being aware of this fact. 00153 * Sizing the p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to be copied into 00154 * application memory. If the buffer provided is not large enough to fit the entire contents of the event, @ref NRF_ERROR_DATA_SIZE will be returned 00155 * and the application can then call again with a larger buffer size. 00156 * Please note that because of the variable length nature of some events, sizeof(ble_evt_t) will not always be large enough to fit certain events, 00157 * and so it is the application's responsability to provide an amount of memory large enough so that the relevant event is copied in full. 00158 * The application may "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return. 00159 * 00160 * @note The pointer supplied must be aligned to the extend defined by @ref BLE_EVTS_PTR_ALIGNMENT 00161 * 00162 * @return @ref NRF_SUCCESS Event pulled and stored into the supplied buffer. 00163 * @return @ref NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied. 00164 * @return @ref NRF_ERROR_NOT_FOUND No events ready to be pulled. 00165 * @return @ref NRF_ERROR_DATA_SIZE Event ready but could not fit into the supplied buffer. 00166 */ 00167 SVCALL(SD_BLE_EVT_GET, uint32_t, sd_ble_evt_get(uint8_t* p_dest, uint16_t *p_len)); 00168 00169 00170 /**@brief Get the total number of available application transmission buffers in the BLE stack. 00171 * 00172 * @details This call allows the application to obtain the total number of 00173 * transmission buffers available for application data. Please note that 00174 * this does not give the number of free buffers, but rather the total amount of them. 00175 * The application has two options to handle its own application transmission buffers: 00176 * - Use a simple arithmetic calculation: at boot time the application should use this function 00177 * to find out the total amount of buffers available to it and store it in a variable. 00178 * Every time a packet that consumes an application buffer is sent using any of the 00179 * exposed functions in this BLE API, the application should decrement that variable. 00180 * Conversely, whenever a @ref BLE_EVT_TX_COMPLETE event is received by the application 00181 * it should retrieve the count field in such event and add that number to the same 00182 * variable storing the number of available packets. 00183 * This mechanism allows the application to be aware at any time of the number of 00184 * application packets available in the BLE stack's internal buffers, and therefore 00185 * it can know with certainty whether it is possible to send more data or it has to 00186 * wait for a @ref BLE_EVT_TX_COMPLETE event before it proceeds. 00187 * - Choose to simply not keep track of available buffers at all, and instead handle the 00188 * @ref BLE_ERROR_NO_TX_BUFFERS error by queueing the packet to be transmitted and 00189 * try again as soon as a @ref BLE_EVT_TX_COMPLETE event arrives. 00190 * 00191 * The API functions that <b>may</b> consume an application buffer depending on 00192 * the parameters supplied to them can be found below: 00193 * 00194 * - @ref sd_ble_gattc_write (write witout response only) 00195 * - @ref sd_ble_gatts_hvx (notifications only) 00196 * - @ref sd_ble_l2cap_tx (all packets) 00197 * 00198 * @param[out] p_count Pointer to a uint8_t which will contain the number of application transmission buffers upon 00199 * successful return. 00200 * 00201 * @return @ref NRF_SUCCESS Number of application transmission buffers retrieved successfully. 00202 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00203 */ 00204 SVCALL(SD_BLE_TX_BUFFER_COUNT_GET, uint32_t, sd_ble_tx_buffer_count_get(uint8_t* p_count)); 00205 00206 00207 /**@brief Add a Vendor Specific UUID. 00208 * 00209 * @details This call enables the application to add a vendor specific UUID to the BLE stack's table, 00210 * for later use all other modules and APIs. This then allows the application to use the shorter, 00211 * 24-bit @ref ble_uuid_t format when dealing with both 16-bit and 128-bit UUIDs without having to 00212 * check for lengths and having split code paths. The way that this is accomplished is by extending the 00213 * grouping mechanism that the Bluetooth SIG standard base UUID uses for all other 128-bit UUIDs. The 00214 * type field in the @ref ble_uuid_t structure is an index (relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN) 00215 * to the table populated by multiple calls to this function, and the uuid field in the same structure 00216 * contains the 2 bytes at indices 12 and 13. The number of possible 128-bit UUIDs available to the 00217 * application is therefore the number of Vendor Specific UUIDs added with the help of this function times 65536, 00218 * although restricted to modifying bytes 12 and 13 for each of the entries in the supplied array. 00219 * 00220 * @note Bytes 12 and 13 of the provided UUID will not be used internally, since those are always replaced by 00221 * the 16-bit uuid field in @ref ble_uuid_t. 00222 * 00223 * 00224 * @param[in] p_vs_uuid Pointer to a 16-octet (128-bit) little endian Vendor Specific UUID disregarding 00225 * bytes 12 and 13. 00226 * @param[out] p_uuid_type Pointer where the type field in @ref ble_uuid_t corresponding to this UUID will be stored. 00227 * 00228 * @return @ref NRF_SUCCESS Successfully added the Vendor Specific UUID. 00229 * @return @ref NRF_ERROR_INVALID_ADDR If p_vs_uuid or p_uuid_type is NULL or invalid. 00230 * @return @ref NRF_ERROR_NO_MEM If there are no more free slots for VS UUIDs. 00231 * @return @ref NRF_ERROR_FORBIDDEN If p_vs_uuid has already been added to the VS UUID table. 00232 */ 00233 SVCALL(SD_BLE_UUID_VS_ADD, uint32_t, sd_ble_uuid_vs_add(ble_uuid128_t const * const p_vs_uuid, uint8_t * const p_uuid_type)); 00234 00235 00236 /** @brief Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit @ref ble_uuid_t structure. 00237 * 00238 * @details The raw UUID bytes excluding bytes 12 and 13 (i.e. bytes 0-11 and 14-15) of p_uuid_le are compared 00239 * to the corresponding ones in each entry of the table of vendor specific UUIDs pouplated with @ref sd_ble_uuid_vs_add 00240 * to look for a match. If there is such a match, bytes 12 and 13 are returned as p_uuid->uuid and the index 00241 * relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN as p_uuid->type. 00242 * 00243 * @note If the UUID length supplied is 2, then the type set by this call will always be @ref BLE_UUID_TYPE_BLE. 00244 * 00245 * @param[in] uuid_le_len Length in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes). 00246 * @param[in] p_uuid_le Pointer pointing to little endian raw UUID bytes. 00247 * @param[in,out] p_uuid Pointer to a @ref ble_uuid_t structure to be filled in. 00248 * 00249 * @return @ref NRF_SUCCESS Successfully decoded into the @ref ble_uuid_t structure. 00250 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00251 * @return @ref NRF_ERROR_INVALID_LENGTH Invalid UUID length. 00252 * @return @ref NRF_ERROR_NOT_FOUND For a 128-bit UUID, no match in the populated table of UUIDs. 00253 */ 00254 SVCALL(SD_BLE_UUID_DECODE, uint32_t, sd_ble_uuid_decode(uint8_t uuid_le_len, uint8_t const * const p_uuid_le, ble_uuid_t * const p_uuid)); 00255 00256 00257 /** @brief Encode a @ref ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit). 00258 * 00259 * @note The pointer to the destination buffer p_uuid_le may be NULL, in which case only the validitiy and size of p_uuid is computed. 00260 * 00261 * @param[in] p_uuid Pointer to a @ref ble_uuid_t structure that will be encoded into bytes. 00262 * @param[out] p_uuid_le_len Pointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes). 00263 * @param[out] p_uuid_le Pointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored. 00264 * 00265 * @return @ref NRF_SUCCESS Successfully encoded into the buffer. 00266 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00267 * @return @ref NRF_ERROR_INVALID_PARAM Invalid UUID type. 00268 */ 00269 SVCALL(SD_BLE_UUID_ENCODE, uint32_t, sd_ble_uuid_encode(ble_uuid_t const * const p_uuid, uint8_t * const p_uuid_le_len, uint8_t * const p_uuid_le)); 00270 00271 00272 /**@brief Get Version Information. 00273 * 00274 * @details This call allows the application to get the BLE stack version information. 00275 * 00276 * @param[in] p_version Pointer to ble_version_t structure to be filled in. 00277 * 00278 * @return @ref NRF_SUCCESS Version information stored successfully. 00279 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00280 * @return @ref NRF_ERROR_BUSY The stack is busy (typically doing a locally-initiated disconnection procedure). 00281 */ 00282 SVCALL(SD_BLE_VERSION_GET, uint32_t, sd_ble_version_get(ble_version_t * p_version)); 00283 00284 00285 /**@brief Provide a user memory block. 00286 * 00287 * @note This call can only be used as a response to a @ref BLE_EVT_USER_MEM_REQUEST event issued to the application. 00288 * 00289 * @param[in] conn_handle Connection handle. 00290 * @param[in] p_block Pointer to a user memory block structure. 00291 * 00292 * @return @ref NRF_SUCCESS Successfully queued a response to the peer. 00293 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00294 * @return @ref NRF_ERROR_INVALID_STATE No execute write request pending. 00295 */ 00296 SVCALL(SD_BLE_USER_MEM_REPLY, uint32_t, sd_ble_user_mem_reply(uint16_t conn_handle, ble_user_mem_block_t *p_block)); 00297 00298 #endif /* BLE_H__ */ 00299 00300 /** 00301 @} 00302 @} 00303 */
Generated on Tue Jul 12 2022 18:44:25 by
