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 * Represents a BLE packet. 109 * 110 */ 111 typedef struct otBleRadioPacket 112 { 113 uint8_t *mValue; ///< The value of an attribute 114 uint16_t mLength; ///< Length of the @p mValue. 115 int8_t mPower; ///< Transmit/receive power in dBm. 116 } otBleRadioPacket; 117 118 /******************************************************************************* 119 * @section Bluetooth Low Energy management. 120 ******************************************************************************/ 121 122 /** 123 * Enable the Bluetooth Low Energy radio. 124 * 125 * @note BLE Device should use the highest ATT_MTU supported that does not 126 * exceed OT_BLE_ATT_MTU_MAX octets. 127 * 128 * @param[in] aInstance The OpenThread instance structure. 129 * 130 * @retval OT_ERROR_NONE Successfully enabled. 131 * @retval OT_ERROR_FAILED The BLE radio could not be enabled. 132 */ 133 otError otPlatBleEnable(otInstance *aInstance); 134 135 /** 136 * Disable the Bluetooth Low Energy radio. 137 * 138 * When disabled, the BLE stack will flush event queues and not generate new 139 * events. The BLE peripheral is turned off or put into a low power sleep 140 * state. Any dynamic memory used by the stack should be released, 141 * but static memory may remain reserved. 142 * 143 * @param[in] aInstance The OpenThread instance structure. 144 * 145 * @retval OT_ERROR_NONE Successfully transitioned to disabled. 146 * @retval OT_ERROR_FAILED The BLE radio could not be disabled. 147 * 148 */ 149 otError otPlatBleDisable(otInstance *aInstance); 150 151 /**************************************************************************** 152 * @section Bluetooth Low Energy GAP. 153 ***************************************************************************/ 154 155 /** 156 * Starts BLE Advertising procedure. 157 * 158 * The BLE device shall use undirected advertising with no filter applied. 159 * A single BLE Advertising packet must be sent on all advertising 160 * channels (37, 38 and 39). 161 * 162 * @note This function shall be used only for BLE Peripheral role. 163 * 164 * @param[in] aInstance The OpenThread instance structure. 165 * @param[in] aInterval The interval between subsequent advertising packets 166 * in OT_BLE_ADV_INTERVAL_UNIT units. 167 * Shall be within OT_BLE_ADV_INTERVAL_MIN and 168 * OT_BLE_ADV_INTERVAL_MAX range or OT_BLE_ADV_INTERVAL_DEFAULT 169 * for a default value set at compile time. 170 * 171 * @retval OT_ERROR_NONE Advertising procedure has been started. 172 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 173 * @retval OT_ERROR_INVALID_ARGS Invalid interval value has been supplied. 174 * 175 */ 176 otError otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval); 177 178 /** 179 * Stops BLE Advertising procedure. 180 * 181 * @note This function shall be used only for BLE Peripheral role. 182 * 183 * @param[in] aInstance The OpenThread instance structure. 184 * 185 * @retval OT_ERROR_NONE Advertising procedure has been stopped. 186 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 187 * 188 */ 189 otError otPlatBleGapAdvStop(otInstance *aInstance); 190 191 /** 192 * The BLE driver calls this method to notify OpenThread that a BLE Central Device has 193 * been connected. 194 * 195 * @param[in] aInstance The OpenThread instance structure. 196 * @param[in] aConnectionId The identifier of the open connection. 197 * 198 */ 199 extern void otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId); 200 201 /** 202 * The BLE driver calls this method to notify OpenThread that the BLE Central Device 203 * has been disconnected. 204 * 205 * @param[in] aInstance The OpenThread instance structure. 206 * @param[in] aConnectionId The identifier of the closed connection. 207 * 208 */ 209 extern void otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId); 210 211 /** 212 * Disconnects BLE connection. 213 * 214 * The BLE device shall use the Remote User Terminated Connection (0x13) reason 215 * code when disconnecting from the peer BLE device.. 216 * 217 * @param[in] aInstance The OpenThread instance structure. 218 * 219 * @retval OT_ERROR_NONE Disconnection procedure has been started. 220 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 221 * 222 */ 223 otError otPlatBleGapDisconnect(otInstance *aInstance); 224 225 /******************************************************************************* 226 * @section Bluetooth Low Energy GATT Common. 227 *******************************************************************************/ 228 229 /** 230 * Reads currently use value of ATT_MTU. 231 * 232 * @param[in] aInstance The OpenThread instance structure. 233 * @param[out] aMtu A pointer to output the current ATT_MTU value. 234 * 235 * @retval OT_ERROR_NONE ATT_MTU value has been placed in @p aMtu. 236 * @retval OT_ERROR_FAILED BLE Device cannot determine its ATT_MTU. 237 * 238 */ 239 otError otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu); 240 241 /** 242 * The BLE driver calls this method to notify OpenThread that ATT_MTU has been updated. 243 * 244 * @param[in] aInstance The OpenThread instance structure. 245 * @param[in] aMtu The updated ATT_MTU value. 246 * 247 */ 248 extern void otPlatBleGattOnMtuUpdate(otInstance *aInstance, uint16_t aMtu); 249 250 /******************************************************************************* 251 * @section Bluetooth Low Energy GATT Server. 252 ******************************************************************************/ 253 254 /** 255 * Sends ATT Handle Value Indication. 256 * 257 * @note This function shall be used only for GATT Server. 258 * 259 * @param[in] aInstance The OpenThread instance structure. 260 * @param[in] aHandle The handle of the attribute to be indicated. 261 * @param[in] aPacket A pointer to the packet contains value to be indicated. 262 * 263 * @retval OT_ERROR_NONE ATT Handle Value Indication has been sent. 264 * @retval OT_ERROR_INVALID_STATE BLE Device is in invalid state. 265 * @retval OT_ERROR_INVALID_ARGS Invalid handle value, data or data length has been supplied. 266 * @retval OT_ERROR_NO_BUFS No available internal buffer found. 267 * 268 */ 269 otError otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 270 271 /** 272 * The BLE driver calls this method to notify OpenThread that an ATT Write Request 273 * packet has been received. 274 * 275 * @note This function shall be used only for GATT Server. 276 * 277 * @param[in] aInstance The OpenThread instance structure. 278 * @param[in] aHandle The handle of the attribute to be written. 279 * @param[in] aPacket A pointer to the packet contains value to be written to the attribute. 280 * 281 */ 282 extern void otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket); 283 284 /** 285 * @} 286 * 287 */ 288 289 #ifdef __cplusplus 290 } // end of extern "C" 291 #endif 292 293 #endif // OPENTHREAD_PLATFORM_BLE_H_ 294
