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 #ifndef OPENTHREAD_PLATFORM_BLE_H_ 36 #define OPENTHREAD_PLATFORM_BLE_H_ 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 #include <stdint.h> 43 44 #include <openthread/error.h> 45 #include <openthread/instance.h> 46 47 /** 48 * @addtogroup plat-ble 49 * 50 * @brief 51 * This module includes the platform abstraction for BLE Host communication. 52 * The platform needs to implement Bluetooth LE 4.2 or higher. 53 * 54 * @{ 55 */ 56 57 /** 58 * Time slot duration on PHY layer in microseconds (0.625ms). 59 */ 60 61 #define OT_BLE_TIMESLOT_UNIT 625 62 63 /** 64 * Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms). 65 */ 66 67 #define OT_BLE_ADV_INTERVAL_MIN 0x0020 68 69 /** 70 * Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s). 71 */ 72 73 #define OT_BLE_ADV_INTERVAL_MAX 0x4000 74 75 /** 76 * Default interval for advertising packet (ms). 77 */ 78 79 #define OT_BLE_ADV_INTERVAL_DEFAULT 100 80 81 /** 82 * Unit used to calculate interval duration (0.625ms). 83 */ 84 85 #define OT_BLE_ADV_INTERVAL_UNIT OT_BLE_TIMESLOT_UNIT 86 87 /** 88 * Maximum allowed ATT MTU size (must be >= 23). 89 */ 90 91 #define OT_BLE_ATT_MTU_MAX 67 92 93 /** 94 * Default power value for BLE. 95 */ 96 97 #define OT_BLE_DEFAULT_POWER 0 98 99 /** 100 * TOBLE service UUID 101 */ 102 103 #define OT_TOBLE_SERVICE_UUID 0xfffb 104 105 /** 106 * Represent BLE link capabilities 107 */ 108 typedef struct otBleLinkCapabilities 109 { 110 uint8_t mRsv : 6; 111 bool mL2CapDirect : 1; 112 bool mGattNotifications : 1; 113 } otBleLinkCapabilities; 114 115 /** 116 * Represents a BLE packet. 117 */ 118 typedef struct otBleRadioPacket 119 { 120 uint8_t *mValue; ///< The value of an attribute 121 uint16_t mLength; ///< Length of the @p mValue. 122 int8_t mPower; ///< Transmit/receive power in dBm. 123 } otBleRadioPacket; 124 125 /******************************************************************************* 126 * @section Bluetooth Low Energy management. 127 ******************************************************************************/ 128 129 /** 130 * Enable the Bluetooth Low Energy radio. 131 * 132 * @note BLE Device should use the highest ATT_MTU supported that does not 133 * exceed OT_BLE_ATT_MTU_MAX octets. 134 * 135 * @param[in] aInstance The OpenThread instance structure. 136 * 137 * @retval OT_ERROR_NONE Successfully enabled. 138 * @retval OT_ERROR_FAILED The BLE radio could not be enabled. 139 */ 140 otError otPlatBleEnable(otInstance *aInstance); 141 142 /** 143 * Disable the Bluetooth Low Energy radio. 144 * 145 * When disabled, the BLE stack will flush event queues and not generate new 146 * events. The BLE peripheral is turned off or put into a low power sleep 147 * state. Any dynamic memory used by the stack should be released, 148 * but static memory may remain reserved. 149 * 150 * @param[in] aInstance The OpenThread instance structure. 151 * 152 * @retval OT_ERROR_NONE Successfully transitioned to disabled. 153 * @retval OT_ERROR_FAILED The BLE radio could not be disabled. 154 */ 155 otError otPlatBleDisable(otInstance *aInstance); 156 157 /**************************************************************************** 158 * @section Bluetooth Low Energy GAP. 159 ***************************************************************************/ 160 /** 161 * Gets BLE Advertising buffer. 162 * 163 * @note This function shall be used only for BLE Peripheral role. 164 * Returned buffer should have enough space to fit max advertisement 165 * defined by specification. 166 * 167 * @param[in] aInstance The OpenThread instance structure. 168 * @param[in] aAdvertisementData The formatted TCAT advertisement frame. 169 * @param[in] aAdvertisementLen The TCAT advertisement frame length. 170 * 171 * @retval OT_ERROR_NONE Advertising procedure has been started. 172 * @retval OT_ERROR_NO_BUFS No bufferspace available. 173 */ 174 otError otPlatBleGetAdvertisementBuffer(otInstance *aInstance, uint8_t **aAdvertisementBuffer); 175 176 /** 177 * Sets BLE Advertising data. 178 * 179 * @note This function shall be used only for BLE Peripheral role. 180 * 181 * @param[in] aInstance The OpenThread instance structure. 182 * @param[in] aAdvertisementData The formatted TCAT advertisement frame. 183 * @param[in] aAdvertisementLen The TCAT advertisement frame length. 184 * 185 * @retval OT_ERROR_NONE Advertising procedure has been started. 186 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 187 * @retval OT_ERROR_INVALID_ARGS Invalid value has been supplied. 188 */ 189 otError otPlatBleGapAdvSetData(otInstance *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen); 190 191 /** 192 * Starts BLE Advertising procedure. 193 * 194 * The BLE device shall use undirected advertising with no filter applied. 195 * A single BLE Advertising packet must be sent on all advertising 196 * channels (37, 38 and 39). 197 * 198 * @note This function shall be used only for BLE Peripheral role. 199 * 200 * @param[in] aInstance The OpenThread instance structure. 201 * @param[in] aInterval The interval between subsequent advertising packets 202 * in OT_BLE_ADV_INTERVAL_UNIT units. 203 * Shall be within OT_BLE_ADV_INTERVAL_MIN and 204 * OT_BLE_ADV_INTERVAL_MAX range or OT_BLE_ADV_INTERVAL_DEFAULT 205 * for a default value set at compile time. 206 * 207 * @retval OT_ERROR_NONE Advertising procedure has been started. 208 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 209 * @retval OT_ERROR_INVALID_ARGS Invalid interval value has been supplied. 210 */ 211 otError otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval); 212 213 /** 214 * Stops BLE Advertising procedure. 215 * 216 * @note This function shall be used only for BLE Peripheral role. 217 * 218 * @param[in] aInstance The OpenThread instance structure. 219 * 220 * @retval OT_ERROR_NONE Advertising procedure has been stopped. 221 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 222 */ 223 otError otPlatBleGapAdvStop(otInstance *aInstance); 224 225 /** 226 * The BLE driver calls this method to notify OpenThread that a BLE Central Device has 227 * been connected. 228 * 229 * @param[in] aInstance The OpenThread instance structure. 230 * @param[in] aConnectionId The identifier of the open connection. 231 */ 232 extern void otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId); 233 234 /** 235 * The BLE driver calls this method to notify OpenThread that the BLE Central Device 236 * has been disconnected. 237 * 238 * @param[in] aInstance The OpenThread instance structure. 239 * @param[in] aConnectionId The identifier of the closed connection. 240 */ 241 extern void otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId); 242 243 /** 244 * Disconnects BLE connection. 245 * 246 * The BLE device shall use the Remote User Terminated Connection (0x13) reason 247 * code when disconnecting from the peer BLE device.. 248 * 249 * @param[in] aInstance The OpenThread instance structure. 250 * 251 * @retval OT_ERROR_NONE Disconnection procedure has been started. 252 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 253 */ 254 otError otPlatBleGapDisconnect(otInstance *aInstance); 255 256 /******************************************************************************* 257 * @section Bluetooth Low Energy GATT Common. 258 *******************************************************************************/ 259 260 /** 261 * Reads currently use value of ATT_MTU. 262 * 263 * @param[in] aInstance The OpenThread instance structure. 264 * @param[out] aMtu A pointer to output the current ATT_MTU value. 265 * 266 * @retval OT_ERROR_NONE ATT_MTU value has been placed in @p aMtu. 267 * @retval OT_ERROR_FAILED BLE Device cannot determine its ATT_MTU. 268 */ 269 otError otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu); 270 271 /** 272 * The BLE driver calls this method to notify OpenThread that ATT_MTU has been updated. 273 * 274 * @param[in] aInstance The OpenThread instance structure. 275 * @param[in] aMtu The updated ATT_MTU value. 276 */ 277 extern void otPlatBleGattOnMtuUpdate(otInstance *aInstance, uint16_t aMtu); 278 279 /******************************************************************************* 280 * @section Bluetooth Low Energy GATT Server. 281 ******************************************************************************/ 282 283 /** 284 * Sends ATT Handle Value Indication. 285 * 286 * @note This function shall be used only for GATT Server. 287 * 288 * @param[in] aInstance The OpenThread instance structure. 289 * @param[in] aHandle The handle of the attribute to be indicated. 290 * @param[in] aPacket A pointer to the packet contains value to be indicated. 291 * 292 * @retval OT_ERROR_NONE ATT Handle Value Indication has been sent. 293 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 294 * @retval OT_ERROR_INVALID_ARGS Invalid handle value, data or data length has been supplied. 295 * @retval OT_ERROR_NO_BUFS No available internal buffer found. 296 */ 297 otError otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 298 299 /** 300 * The BLE driver calls this method to notify OpenThread that an ATT Write Request 301 * packet has been received. 302 * 303 * @note This function shall be used only for GATT Server. 304 * 305 * @param[in] aInstance The OpenThread instance structure. 306 * @param[in] aHandle The handle of the attribute to be written. 307 * @param[in] aPacket A pointer to the packet contains value to be written to the attribute. 308 */ 309 extern void otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 310 311 /** 312 * Function to retrieve from platform BLE link capabilities. 313 * 314 * @param[in] aInstance The OpenThread instance structure. 315 * @param[out] aBleLinkCapabilities The pointer to retrieve the BLE ling capabilities. 316 */ 317 void otPlatBleGetLinkCapabilities(otInstance *aInstance, otBleLinkCapabilities *aBleLinkCapabilities); 318 319 /** 320 * Function to retrieve from platform multiradio support of BLE and IEEE. 321 * 322 * @param[in] aInstance The OpenThread instance structure. 323 */ 324 bool otPlatBleSupportsMultiRadio(otInstance *aInstance); 325 /** 326 * @} 327 */ 328 329 #ifdef __cplusplus 330 } // end of extern "C" 331 #endif 332 333 #endif // OPENTHREAD_PLATFORM_BLE_H_ 334