1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines a OpenThread BLE GATT peripheral interface driver. 33 * 34 */ 35 36 #ifndef OPENTHREAD_PLATFORM_BLE_H_ 37 #define OPENTHREAD_PLATFORM_BLE_H_ 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #include <stdint.h> 44 45 #include <openthread/error.h> 46 #include <openthread/instance.h> 47 48 /** 49 * @addtogroup plat-ble 50 * 51 * @brief 52 * This module includes the platform abstraction for BLE Host communication. 53 * The platform needs to implement Bluetooth LE 4.2 or higher. 54 * 55 * @{ 56 * 57 */ 58 59 /** 60 * Time slot duration on PHY layer in microseconds (0.625ms). 61 * 62 */ 63 64 #define OT_BLE_TIMESLOT_UNIT 625 65 66 /** 67 * Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms). 68 * 69 */ 70 71 #define OT_BLE_ADV_INTERVAL_MIN 0x0020 72 73 /** 74 * Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s). 75 * 76 */ 77 78 #define OT_BLE_ADV_INTERVAL_MAX 0x4000 79 80 /** 81 * Default interval for advertising packet (ms). 82 * 83 */ 84 85 #define OT_BLE_ADV_INTERVAL_DEFAULT 100 86 87 /** 88 * Unit used to calculate interval duration (0.625ms). 89 * 90 */ 91 92 #define OT_BLE_ADV_INTERVAL_UNIT OT_BLE_TIMESLOT_UNIT 93 94 /** 95 * Maximum allowed ATT MTU size (must be >= 23). 96 * 97 */ 98 99 #define OT_BLE_ATT_MTU_MAX 67 100 101 /** 102 * Default power value for BLE. 103 */ 104 105 #define OT_BLE_DEFAULT_POWER 0 106 107 /** 108 * TOBLE service UUID 109 */ 110 111 #define OT_TOBLE_SERVICE_UUID 0xfffb 112 113 /** 114 * Represent BLE link capabilities 115 * 116 */ 117 typedef struct otBleLinkCapabilities 118 { 119 uint8_t mRsv : 6; 120 bool mL2CapDirect : 1; 121 bool mGattNotifications : 1; 122 } otBleLinkCapabilities; 123 124 /** 125 * Represents a BLE packet. 126 * 127 */ 128 typedef struct otBleRadioPacket 129 { 130 uint8_t *mValue; ///< The value of an attribute 131 uint16_t mLength; ///< Length of the @p mValue. 132 int8_t mPower; ///< Transmit/receive power in dBm. 133 } otBleRadioPacket; 134 135 /******************************************************************************* 136 * @section Bluetooth Low Energy management. 137 ******************************************************************************/ 138 139 /** 140 * Enable the Bluetooth Low Energy radio. 141 * 142 * @note BLE Device should use the highest ATT_MTU supported that does not 143 * exceed OT_BLE_ATT_MTU_MAX octets. 144 * 145 * @param[in] aInstance The OpenThread instance structure. 146 * 147 * @retval OT_ERROR_NONE Successfully enabled. 148 * @retval OT_ERROR_FAILED The BLE radio could not be enabled. 149 */ 150 otError otPlatBleEnable(otInstance *aInstance); 151 152 /** 153 * Disable the Bluetooth Low Energy radio. 154 * 155 * When disabled, the BLE stack will flush event queues and not generate new 156 * events. The BLE peripheral is turned off or put into a low power sleep 157 * state. Any dynamic memory used by the stack should be released, 158 * but static memory may remain reserved. 159 * 160 * @param[in] aInstance The OpenThread instance structure. 161 * 162 * @retval OT_ERROR_NONE Successfully transitioned to disabled. 163 * @retval OT_ERROR_FAILED The BLE radio could not be disabled. 164 * 165 */ 166 otError otPlatBleDisable(otInstance *aInstance); 167 168 /**************************************************************************** 169 * @section Bluetooth Low Energy GAP. 170 ***************************************************************************/ 171 /** 172 * Gets BLE Advertising buffer. 173 * 174 * @note This function shall be used only for BLE Peripheral role. 175 * Returned buffer should have enough space to fit max advertisement 176 * defined by specification. 177 * 178 * @param[in] aInstance The OpenThread instance structure. 179 * @param[in] aAdvertisementData The formatted TCAT advertisement frame. 180 * @param[in] aAdvertisementLen The TCAT advertisement frame length. 181 * 182 * @retval OT_ERROR_NONE Advertising procedure has been started. 183 * @retval OT_ERROR_NO_BUFS No bufferspace available. 184 * 185 */ 186 otError otPlatBleGetAdvertisementBuffer(otInstance *aInstance, uint8_t **aAdvertisementBuffer); 187 188 /** 189 * Sets BLE Advertising data. 190 * 191 * @note This function shall be used only for BLE Peripheral role. 192 * 193 * @param[in] aInstance The OpenThread instance structure. 194 * @param[in] aAdvertisementData The formatted TCAT advertisement frame. 195 * @param[in] aAdvertisementLen The TCAT advertisement frame length. 196 * 197 * @retval OT_ERROR_NONE Advertising procedure has been started. 198 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 199 * @retval OT_ERROR_INVALID_ARGS Invalid value has been supplied. 200 * 201 */ 202 otError otPlatBleGapAdvSetData(otInstance *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen); 203 204 /** 205 * Starts BLE Advertising procedure. 206 * 207 * The BLE device shall use undirected advertising with no filter applied. 208 * A single BLE Advertising packet must be sent on all advertising 209 * channels (37, 38 and 39). 210 * 211 * @note This function shall be used only for BLE Peripheral role. 212 * 213 * @param[in] aInstance The OpenThread instance structure. 214 * @param[in] aInterval The interval between subsequent advertising packets 215 * in OT_BLE_ADV_INTERVAL_UNIT units. 216 * Shall be within OT_BLE_ADV_INTERVAL_MIN and 217 * OT_BLE_ADV_INTERVAL_MAX range or OT_BLE_ADV_INTERVAL_DEFAULT 218 * for a default value set at compile time. 219 * 220 * @retval OT_ERROR_NONE Advertising procedure has been started. 221 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 222 * @retval OT_ERROR_INVALID_ARGS Invalid interval value has been supplied. 223 * 224 */ 225 otError otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval); 226 227 /** 228 * Stops BLE Advertising procedure. 229 * 230 * @note This function shall be used only for BLE Peripheral role. 231 * 232 * @param[in] aInstance The OpenThread instance structure. 233 * 234 * @retval OT_ERROR_NONE Advertising procedure has been stopped. 235 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 236 * 237 */ 238 otError otPlatBleGapAdvStop(otInstance *aInstance); 239 240 /** 241 * The BLE driver calls this method to notify OpenThread that a BLE Central Device has 242 * been connected. 243 * 244 * @param[in] aInstance The OpenThread instance structure. 245 * @param[in] aConnectionId The identifier of the open connection. 246 * 247 */ 248 extern void otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId); 249 250 /** 251 * The BLE driver calls this method to notify OpenThread that the BLE Central Device 252 * has been disconnected. 253 * 254 * @param[in] aInstance The OpenThread instance structure. 255 * @param[in] aConnectionId The identifier of the closed connection. 256 * 257 */ 258 extern void otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId); 259 260 /** 261 * Disconnects BLE connection. 262 * 263 * The BLE device shall use the Remote User Terminated Connection (0x13) reason 264 * code when disconnecting from the peer BLE device.. 265 * 266 * @param[in] aInstance The OpenThread instance structure. 267 * 268 * @retval OT_ERROR_NONE Disconnection procedure has been started. 269 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 270 * 271 */ 272 otError otPlatBleGapDisconnect(otInstance *aInstance); 273 274 /******************************************************************************* 275 * @section Bluetooth Low Energy GATT Common. 276 *******************************************************************************/ 277 278 /** 279 * Reads currently use value of ATT_MTU. 280 * 281 * @param[in] aInstance The OpenThread instance structure. 282 * @param[out] aMtu A pointer to output the current ATT_MTU value. 283 * 284 * @retval OT_ERROR_NONE ATT_MTU value has been placed in @p aMtu. 285 * @retval OT_ERROR_FAILED BLE Device cannot determine its ATT_MTU. 286 * 287 */ 288 otError otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu); 289 290 /** 291 * The BLE driver calls this method to notify OpenThread that ATT_MTU has been updated. 292 * 293 * @param[in] aInstance The OpenThread instance structure. 294 * @param[in] aMtu The updated ATT_MTU value. 295 * 296 */ 297 extern void otPlatBleGattOnMtuUpdate(otInstance *aInstance, uint16_t aMtu); 298 299 /******************************************************************************* 300 * @section Bluetooth Low Energy GATT Server. 301 ******************************************************************************/ 302 303 /** 304 * Sends ATT Handle Value Indication. 305 * 306 * @note This function shall be used only for GATT Server. 307 * 308 * @param[in] aInstance The OpenThread instance structure. 309 * @param[in] aHandle The handle of the attribute to be indicated. 310 * @param[in] aPacket A pointer to the packet contains value to be indicated. 311 * 312 * @retval OT_ERROR_NONE ATT Handle Value Indication has been sent. 313 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 314 * @retval OT_ERROR_INVALID_ARGS Invalid handle value, data or data length has been supplied. 315 * @retval OT_ERROR_NO_BUFS No available internal buffer found. 316 * 317 */ 318 otError otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 319 320 /** 321 * The BLE driver calls this method to notify OpenThread that an ATT Write Request 322 * packet has been received. 323 * 324 * @note This function shall be used only for GATT Server. 325 * 326 * @param[in] aInstance The OpenThread instance structure. 327 * @param[in] aHandle The handle of the attribute to be written. 328 * @param[in] aPacket A pointer to the packet contains value to be written to the attribute. 329 * 330 */ 331 extern void otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 332 333 /** 334 * Function to retrieve from platform BLE link capabilities. 335 * 336 * @param[in] aInstance The OpenThread instance structure. 337 * @param[out] aBleLinkCapabilities The pointer to retrieve the BLE ling capabilities. 338 * 339 */ 340 void otPlatBleGetLinkCapabilities(otInstance *aInstance, otBleLinkCapabilities *aBleLinkCapabilities); 341 342 /** 343 * Function to retrieve from platform multiradio support of BLE and IEEE. 344 * 345 * @param[in] aInstance The OpenThread instance structure. 346 * 347 */ 348 bool otPlatBleSupportsMultiRadio(otInstance *aInstance); 349 /** 350 * @} 351 * 352 */ 353 354 #ifdef __cplusplus 355 } // end of extern "C" 356 #endif 357 358 #endif // OPENTHREAD_PLATFORM_BLE_H_ 359
