third_party/openthread/repo/include/openthread/platform/ble.h

   1 /*
   2  *  Copyright (c) 2018, 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 generic OpenThread BLE driver HOST interface.
  33  *
  34  */
  35
  36 #ifndef OT_PLATFORM_BLE_H_
  37 #define OT_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 enum
  60 {
  61     /**
  62      * The size of the Bluetooth Device Address [bytes].
  63      */
  64     OT_BLE_ADDRESS_LENGTH = 6,
  65
  66     /**
  67      * Time slot duration on PHY layer in microseconds (0.625ms).
  68      */
  69     OT_BLE_TIMESLOT_UNIT = 625,
  70
  71     /**
  72      * Unit used to calculate connection interval (1.25ms)
  73      */
  74     OT_BLE_CONN_INTERVAL_UNIT = 2 * OT_BLE_TIMESLOT_UNIT,
  75
  76     /**
  77      * Minimum allowed connection interval in OT_BLE_CONN_INTERVAL_UNIT units (7.5ms).
  78      * See v4.2 [Vol 2, Part E] page 946
  79      */
  80     OT_BLE_CONN_INTERVAL_MIN = 0x0006,
  81
  82     /**
  83      * Maximum allowed connection interval in OT_BLE_CONN_INTERVAL_UNIT units (4s).
  84      * See v4.2 [Vol 2, Part E] page 946
  85      */
  86     OT_BLE_CONN_INTERVAL_MAX = 0x0C80,
  87
  88     /**
  89      * Maximum allowed slave latency in units of connection events.
  90      * See v4.2 [Vol 2, Part E] page 946
  91      */
  92     OT_BLE_CONN_SLAVE_LATENCY_MAX = 0x01F3,
  93
  94     /**
  95      * Minimum allowed connection timeout in units of 10ms (100ms).
  96      * See v4.2 [Vol 2, Part E] page 946
  97      */
  98     OT_BLE_CONN_SUPERVISOR_TIMEOUT_MIN = 0x000A,
  99
 100     /**
 101      * Maximum allowed connection timeout (32s).
 102      * See v4.2 [Vol 2, Part E] page 946
 103      */
 104     OT_BLE_CONN_SUPERVISOR_TIMEOUT_MAX = 0x0C80,
 105
 106     /**
 107      * Unit used to calculate connection supervisor timeout (10ms).
 108      */
 109     OT_BLE_CONN_SUPERVISOR_UNIT = 16 * OT_BLE_TIMESLOT_UNIT,
 110
 111     /**
 112      * Maximum length of the device name characteristic [bytes].
 113      */
 114     OT_BLE_DEV_NAME_MAX_LENGTH = 248,
 115
 116     /**
 117      * Maximum length of advertising data [bytes].
 118      */
 119     OT_BLE_ADV_DATA_MAX_LENGTH = 31,
 120
 121     /**
 122      * Maximum length of scan response data [bytes].
 123      */
 124     OT_BLE_SCAN_RESPONSE_MAX_LENGTH = 31,
 125
 126     /**
 127      * Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms).
 128      */
 129     OT_BLE_ADV_INTERVAL_MIN = 0x0020,
 130
 131     /**
 132      * Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s).
 133      */
 134     OT_BLE_ADV_INTERVAL_MAX = 0x4000,
 135
 136     /**
 137      * Unit used to calculate interval duration (0.625ms).
 138      */
 139     OT_BLE_ADV_INTERVAL_UNIT = OT_BLE_TIMESLOT_UNIT,
 140
 141     /**
 142      * Minimum allowed scan interval (2.5ms).
 143      */
 144     OT_BLE_SCAN_INTERVAL_MIN = 0x0004,
 145
 146     /**
 147      * Maximum allowed scan interval (10.24s).
 148      */
 149     OT_BLE_SCAN_INTERVAL_MAX = 0x4000,
 150
 151     /**
 152      * Unit used to calculate scan interval duration (0.625ms).
 153      */
 154     OT_BLE_SCAN_INTERVAL_UNIT = OT_BLE_TIMESLOT_UNIT,
 155
 156     /**
 157      * Minimum allowed scan window in OT_BLE_TIMESLOT_UNIT units (2.5ms).
 158      */
 159     OT_BLE_SCAN_WINDOW_MIN = 0x0004,
 160
 161     /**
 162      * Maximum allowed scan window in OT_BLE_TIMESLOT_UNIT units (10.24s).
 163      */
 164     OT_BLE_SCAN_WINDOW_MAX = 0x4000,
 165
 166     /**
 167      * Unit used to calculate scan window duration (0.625ms).
 168      */
 169     OT_BLE_SCAN_WINDOW_UNIT = OT_BLE_TIMESLOT_UNIT,
 170
 171     /**
 172      * BLE HCI code for remote user terminated connection.
 173      */
 174     OT_BLE_HCI_REMOTE_USER_TERMINATED = 0x13,
 175
 176     /**
 177      * Value of invalid/unknown handle.
 178      */
 179     OT_BLE_INVALID_HANDLE = 0x0000,
 180
 181     /**
 182      * Maximum size of BLE Characteristic [bytes].
 183      */
 184     OT_BLE_CHARACTERISTIC_MAX_LENGTH = 512,
 185
 186     /**
 187      * Maximum value of ATT_MTU [bytes].
 188      */
 189     OT_BLE_ATT_MTU_MAX = 511,
 190
 191     /**
 192      * Length of full BLE UUID in bytes.
 193      */
 194     OT_BLE_UUID_LENGTH = 16,
 195
 196     /**
 197      * Uuid of Client Configuration Characteristic Descriptor.
 198      */
 199     OT_BLE_UUID_CCCD = 0x2902,
 200
 201 };
 202
 203 /// Convert the advertising interval from [ms] to [ble symbol times].
 204 #define OT_BLE_MS_TO_TICKS(x) (((x)*1000) / OT_BLE_ADV_INTERVAL_UNIT)
 205
 206 /**
 207  * This enum represents BLE Device Address types.
 208  *
 209  */
 210 typedef enum otPlatBleAddressType
 211 {
 212     OT_BLE_ADDRESS_TYPE_PUBLIC                        = 0, ///< Bluetooth public device address.
 213     OT_BLE_ADDRESS_TYPE_RANDOM_STATIC                 = 1, ///< Bluetooth random static address.
 214     OT_BLE_ADDRESS_TYPE_RANDOM_PRIVATE_RESOLVABLE     = 2, ///< Bluetooth random private resolvable address.
 215     OT_BLE_ADDRESS_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = 3, ///< Bluetooth random private non-resolvable address.
 216 } otPlatBleAddressType;
 217
 218 /**
 219  * This enumeration defines the characterstic properties flags for a
 220  * Client Characteristic Configuration Descriptor (CCCD).
 221  *
 222  * See v4.2 [Vol 3, Part G] 3.3.1.1 Characteristic Properties - Table 3.5
 223  */
 224 typedef enum otPlatBleCccdFlags
 225 {
 226     /**
 227      * If set, permits broadcasts of the Characteristic Value using Characteristic Configuration Descriptor.
 228      */
 229     OT_BLE_CHAR_PROP_BROADCAST = (1 << 0),
 230
 231     /**
 232      * If set, permits reads of the Characteristic Value.
 233      */
 234     OT_BLE_CHAR_PROP_READ = (1 << 1),
 235
 236     /**
 237      * If set, permit writes of the Characteristic Value without response.
 238      */
 239     OT_BLE_CHAR_PROP_WRITE_NO_RESPONSE = (1 << 2),
 240
 241     /**
 242      * If set, permits writes of the Characteristic Value with response.
 243      */
 244     OT_BLE_CHAR_PROP_WRITE = (1 << 3),
 245
 246     /**
 247      * If set, permits notifications of a Characteristic Value without acknowledgement.
 248      */
 249     OT_BLE_CHAR_PROP_NOTIFY = (1 << 4),
 250
 251     /**
 252      * If set, permits indications of a Characteristic Value with acknowledgement.
 253      */
 254     OT_BLE_CHAR_PROP_INDICATE = (1 << 5),
 255
 256     /**
 257      * If set, permits signed writes to the Characteristic Value.
 258      */
 259     OT_BLE_CHAR_PROP_AUTH_SIGNED_WRITE = (1 << 6),
 260
 261     /**
 262      * If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.
 263      */
 264     OT_BLE_CHAR_PROP_EXTENDED = (1 << 7),
 265
 266 } otPlatBleCccdFlags;
 267
 268 /**
 269  * This structure represents BLE Device Address.
 270  *
 271  */
 272 typedef struct otPlatBleDeviceAddr
 273 {
 274     uint8_t mAddrType;                    ///< Bluetooth device address type.
 275     uint8_t mAddr[OT_BLE_ADDRESS_LENGTH]; ///< An 48-bit address of Bluetooth device in LSB format.
 276 } otPlatBleDeviceAddr;
 277
 278 /**
 279  * This enumeration defines flags for BLE advertisement mode.
 280  *
 281  */
 282 typedef enum otPlatBleAdvMode
 283 {
 284     /**
 285      * If set, advertising device will allow connections to be initiated.
 286      */
 287     OT_BLE_ADV_MODE_CONNECTABLE = (1 << 0),
 288
 289     /**
 290      * If set, advertising device will respond to scan requests.
 291      */
 292     OT_BLE_ADV_MODE_SCANNABLE = (1 << 1),
 293 } otPlatBleAdvMode;
 294
 295 /**
 296  * This structure represents BLE connection parameters.
 297  *
 298  */
 299 typedef struct otPlatBleGapConnParams
 300 {
 301     /**
 302      * Preferred minimum connection interval in OT_BLE_TIMESLOT_UNIT units.
 303      * Shall be in OT_BLE_CONN_INTERVAL_MIN and OT_BLE_CONN_INTERVAL_MAX range.
 304      */
 305     uint16_t mConnMinInterval;
 306
 307     /**
 308      * Preferred maximum connection interval in OT_BLE_TIMESLOT_UNIT units.
 309      * Shall be in OT_BLE_CONN_INTERVAL_MIN and OT_BLE_CONN_INTERVAL_MAX range.
 310      */
 311     uint16_t mConnMaxInterval;
 312
 313     /**
 314      * Slave Latency in number of connection events.
 315      * Shall not exceed OT_BLE_CONN_SLAVE_LATENCY_MAX value.
 316      */
 317     uint16_t mConnSlaveLatency;
 318
 319     /**
 320      * Defines connection timeout parameter in OT_BLE_CONN_SUPERVISOR_UNIT units. Shall be in
 321      * OT_BLE_CONN_SUPERVISOR_TIMEOUT_MIN and OT_BLE_CONN_SUPERVISOR_TIMEOUT_MIN range.
 322      */
 323     uint16_t mConnSupervisionTimeout;
 324
 325 } otPlatBleGapConnParams;
 326
 327 /**
 328  * This enumeration represents BLE UUID value.
 329  *
 330  */
 331 typedef enum otPlatBleUuidType
 332 {
 333     OT_BLE_UUID_TYPE_NONE = 0, ///< UUID uninitialized value.
 334     OT_BLE_UUID_TYPE_16   = 1, ///< UUID represented by 16-bit value.
 335     OT_BLE_UUID_TYPE_32   = 2, ///< UUID represented by 32-bit value.
 336     OT_BLE_UUID_TYPE_128  = 3, ///< UUID represented by 128-bit value.
 337 } otPlatBleUuidType;
 338
 339 /**
 340  * This structure represents BLE UUID value.
 341  *
 342  */
 343 typedef union otPlatBleUuidValue
 344 {
 345     uint8_t *mUuid128; ///< A pointer to 128-bit UUID value.
 346     uint32_t mUuid32;  ///< A 32-bit UUID value.
 347     uint16_t mUuid16;  ///< A 16-bit UUID value.
 348 } otPlatBleUuidValue;
 349
 350 /**
 351  * This structure represents BLE UUID.
 352  *
 353  */
 354 typedef struct otPlatBleUuid
 355 {
 356     otPlatBleUuidType  mType;  ///< A type of UUID in @p mValue.
 357     otPlatBleUuidValue mValue; ///< A value of UUID.
 358 } otPlatBleUuid;
 359
 360 /**
 361  * This structure represents GATT Characteristic.
 362  *
 363  */
 364 typedef struct otPlatBleGattCharacteristic
 365 {
 366     otPlatBleUuid mUuid;        ///< [in]  A UUID value of a characteristic.
 367     uint16_t      mHandleValue; ///< [out] Characteristic value handle.
 368     uint16_t      mHandleCccd;  ///< [out] CCCD handle or OT_BLE_INVALID_HANDLE if CCCD is not present.
 369     uint8_t       mProperties;  ///< [in]  Characteristic properties.
 370 } otPlatBleGattCharacteristic;
 371
 372 /**
 373  * This structure represents GATT Descriptor.
 374  *
 375  */
 376 typedef struct otPlatBleGattDescriptor
 377 {
 378     otPlatBleUuid mUuid;   ///< A UUID value of descriptor.
 379     uint16_t      mHandle; ///< Descriptor handle.
 380 } otPlatBleGattDescriptor;
 381
 382 /**
 383  * Registration descriptor for a GATT service.
 384  *
 385  */
 386 typedef struct otPlatBleGattService
 387 {
 388     /**
 389      * Pointer to service UUID; use BLE_UUIDxx_DECLARE macros to declare
 390      * proper UUID; NULL if there are no more characteristics in the service.
 391      */
 392     const otPlatBleUuid mUuid;
 393
 394     /**
 395      * Handle of service; written to by stack after call to
 396      * otPlatBleGattServerServicesRegister.
 397      */
 398     uint16_t mHandle;
 399
 400     /**
 401      * Array of characteristic definitions corresponding to characteristics
 402      * belonging to this service.
 403      */
 404     otPlatBleGattCharacteristic *mCharacteristics;
 405 } otPlatBleGattService;
 406
 407 /**
 408  * This structure represents an BLE packet.
 409  *
 410  */
 411 typedef struct otBleRadioPacket
 412 {
 413     uint8_t *mValue;  ///< The value of an attribute
 414     uint16_t mLength; ///< Length of the @p mValue.
 415     int8_t   mPower;  ///< Transmit/receive power in dBm.
 416 } otBleRadioPacket;
 417
 418 /**
 419  * The enum indicates the outcome of the L2CAP connection request procedure.
 420  * See Bluetooth v5.0 | Vol 3, Part A, 4.23, Table 4.20.
 421  */
 422 typedef enum otPlatBleL2capError
 423 {
 424     OT_BLE_L2C_ERROR_NONE           = 0x00, ///< Connection successful.
 425     OT_BLE_L2C_ERROR_INVALID_PSM    = 0x02, ///< Connection refused – LE_PSM not supported.
 426     OT_BLE_L2C_ERROR_NO_MEM         = 0x04, ///< Connection refused – no resources available.
 427     OT_BLE_L2C_ERROR_INVALID_PARAMS = 0x0b, ///< Connection refused – unacceptable parameters.
 428 } otPlatBleL2capError;
 429
 430 /*******************************************************************************
 431  * @section Bluetooth Low Energy management.
 432  ******************************************************************************/
 433
 434 /**
 435  * Enable the Bluetooth Low Energy radio.
 436  *
 437  * @note BLE Device should use the highest ATT_MTU supported that does not
 438  * exceed OT_BLE_ATT_MTU_MAX octets.
 439  *
 440  * @param[in] aInstance  The OpenThread instance structure.
 441  *
 442  * @retval ::OT_ERROR_NONE         Successfully enabled.
 443  * @retval ::OT_ERROR_FAILED       The BLE radio could not be enabled.
 444  */
 445 otError otPlatBleEnable(otInstance *aInstance);
 446
 447 /**
 448  * Disable the Bluetooth Low Energy radio.
 449  *
 450  * When disabled, the BLE stack will flush event queues and not generate new
 451  * events. The BLE peripheral is turned off or put into a low power sleep
 452  * state. Any dynamic memory used by the stack should be released,
 453  * but static memory may remain reserved.
 454  *
 455  * @param[in] aInstance  The OpenThread instance structure.
 456  *
 457  * @retval ::OT_ERROR_NONE        Successfully transitioned to disabled.
 458  * @retval ::OT_ERROR_FAILED      The BLE radio could not be disabled.
 459  */
 460 otError otPlatBleDisable(otInstance *aInstance);
 461
 462 /**
 463  * Reset the Bluetooth Low Energy subsystem.
 464  *
 465  * @param[in] aInstance  The OpenThread instance structure.
 466  *
 467  * @retval ::OT_ERROR_NONE        Successfully reset.
 468  * @retval ::OT_ERROR_FAILED      The BLE stack could not be reset.
 469  */
 470 otError otPlatBleReset(otInstance *aInstance);
 471
 472 /**
 473  * Check whether Bluetooth Low Energy radio is enabled or not.
 474  *
 475  * @param[in] aInstance  The OpenThread instance structure.
 476  *
 477  * @retval ::true   Bluetooth Low Energy radio is enabled.
 478  * @retval ::false  Bluetooth Low Energy radio is disabled.
 479  */
 480 bool otPlatBleIsEnabled(otInstance *aInstance);
 481
 482 /**
 483  * Callback sent when Bluetooth Low Energy is ready after being enabled.
 484  *
 485  * @param[in] aInstance  The OpenThread instance structure.
 486  */
 487 extern void otPlatBleOnEnabled(otInstance *aInstance);
 488
 489 /****************************************************************************
 490  * @section Bluetooth Low Energy GAP.
 491  ***************************************************************************/
 492
 493 /**
 494  * Gets Bluetooth Device Address.
 495  *
 496  * @param[in]  aInstance  The OpenThread instance structure.
 497  * @param[out] aAddress   The pointer to Bluetooth Device Address.
 498  *
 499  * @retval ::OT_ERROR_NONE          Request has been successfully done.
 500  * @retval ::OT_ERROR_INVALID_ARGS  Invalid parameters has been supplied.
 501  */
 502 otError otPlatBleGapAddressGet(otInstance *aInstance, otPlatBleDeviceAddr *aAddress);
 503
 504 /**
 505  * Sets Bluetooth Device Address.
 506  *
 507  * @param[in]  aInstance  The OpenThread instance structure.
 508  * @param[in] aAddress    The pointer to Bluetooth Device Address.
 509  *
 510  * @retval ::OT_ERROR_NONE          Request has been successfully done.
 511  * @retval ::OT_ERROR_INVALID_ARGS  Invalid parameters has been supplied.
 512  */
 513 otError otPlatBleGapAddressSet(otInstance *aInstance, const otPlatBleDeviceAddr *aAddress);
 514
 515 /**
 516  * Sets BLE device name and appearance that is visible as GATT Based service.
 517  *
 518  * The BLE Host stack should set the security mode 1, level 1 (no security) for
 519  * those characteristics.
 520  *
 521  * @param[in] aInstance    The OpenThread instance structure.
 522  * @param[in] aDeviceName  A pointer to device name string (null terminated).
 523  *                         Shall not exceed OT_BLE_DEV_NAME_MAX_LENGTH.
 524  * @param[in] aAppearance  The value of appearance characteristic.
 525  *
 526  * @retval ::OT_ERROR_NONE          Connection parameters have been
 527  *                                  successfully set.
 528  * @retval ::OT_ERROR_INVALID_ARGS  Invalid parameters has been supplied.
 529  */
 530 otError otPlatBleGapServiceSet(otInstance *aInstance, const char *aDeviceName, uint16_t aAppearance);
 531
 532 /**
 533  * Sets desired BLE Connection Parameters.
 534  *
 535  * @param[in] aInstance    The OpenThread instance structure.
 536  * @param[in] aConnParams  A pointer to connection parameters structure.
 537  *
 538  * @retval ::OT_ERROR_NONE          Connection parameters have been
 539  *                                  successfully set.
 540  * @retval ::OT_ERROR_INVALID_ARGS  Invalid connection parameters have been
 541  *                                  supplied.
 542  */
 543 otError otPlatBleGapConnParamsSet(otInstance *aInstance, const otPlatBleGapConnParams *aConnParams);
 544
 545 /**
 546  * Sets BLE Advertising packet content.
 547  *
 548  * @note This function shall be used only for BLE Peripheral role.
 549  *
 550  * @param[in] aInstance       The OpenThread instance structure.
 551  * @param[in] aAdvData        A pointer to advertising data content in raw format.
 552  * @param[in] aAdvDataLength  The size of advertising data.
 553  *                            Shall not exceed OT_BLE_ADV_DATA_MAX_LENGTH.
 554  *
 555  * @retval ::OT_ERROR_NONE          Advertising data has been successfully set.
 556  * @retval ::OT_ERROR_INVALID_ARGS  Invalid advertising data has been supplied.
 557  */
 558 otError otPlatBleGapAdvDataSet(otInstance *aInstance, const uint8_t *aAdvData, uint8_t aAdvDataLength);
 559
 560 /**
 561  * Sets BLE Scan Response packet content.
 562  *
 563  * @note This function shall be used only for BLE Peripheral role.
 564  *
 565  * @param[in] aInstance            The OpenThread instance structure.
 566  * @param[in] aScanResponse        A pointer to scan response data in raw format.
 567  * @param[in] aScanResponseLength  The size of scan response data.
 568  *                                 Shall not exceed OT_BLE_SCAN_RESPONSE_MAX_LENGTH.
 569  *
 570  * @retval ::OT_ERROR_NONE         Scan response data has been successfully set.
 571  * @retval ::OT_ERROR_INVALID_ARGS Invalid scan response data has been supplied.
 572  */
 573 otError otPlatBleGapScanResponseSet(otInstance *aInstance, const uint8_t *aScanResponse, uint8_t aScanResponseLength);
 574
 575 /**
 576  * Starts BLE Advertising procedure.
 577  *
 578  * The BLE device shall use undirected advertising with no filter applied.
 579  * A single BLE Advertising packet must be sent on all advertising
 580  * channels (37, 38 and 39).
 581  *
 582  * @note This function shall be used only for BLE Peripheral role.
 583  *
 584  * @param[in] aInstance  The OpenThread instance structure.
 585  * @param[in] aInterval  The interval between subsequent advertising packets
 586  *                       in OT_BLE_ADV_INTERVAL_UNIT units.
 587  *                       Shall be within OT_BLE_ADV_INTERVAL_MIN and
 588  *                       OT_BLE_ADV_INTERVAL_MAX range.
 589  * @param[in] aType      The advertisement properties as a bitmask:
 590  *                       whether it is connectable | scannable.
 591  *
 592  * @retval ::OT_ERROR_NONE           Advertising procedure has been started.
 593  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 594  * @retval ::OT_ERROR_INVALID_ARGS   Invalid interval value has been supplied.
 595  */
 596 otError otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval, uint8_t aType);
 597
 598 /**
 599  * Stops BLE Advertising procedure.
 600  *
 601  * @note This function shall be used only for BLE Peripheral role.
 602  *
 603  * @param[in] aInstance  The OpenThread instance structure.
 604  *
 605  * @retval ::OT_ERROR_NONE           Advertising procedure has been stopped.
 606  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 607  */
 608 otError otPlatBleGapAdvStop(otInstance *aInstance);
 609
 610 /**
 611  * The BLE driver calls this method to notify OpenThread that BLE Device has
 612  * been connected.
 613  *
 614  * @param[in]  aInstance     The OpenThread instance structure.
 615  * @param[in]  aConnectionId The identifier of the open connection.
 616  *
 617  */
 618 extern void otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId);
 619
 620 /**
 621  * The BLE driver calls this method to notify OpenThread that the BLE Device
 622  * has been disconnected.
 623  *
 624  * @param[in]  aInstance     The OpenThread instance structure.
 625  * @param[in]  aConnectionId The identifier of the closed connection.
 626  *
 627  */
 628 extern void otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId);
 629
 630 /**
 631  * Starts BLE Scanning procedure.
 632  *
 633  * @note This function shall be used only for BLE Central role.
 634  *
 635  * @param[in] aInstance  The OpenThread instance structure.
 636  * @param[in] aInterval  The scanning interval in OT_BLE_SCAN_INTERVAL_UNIT
 637  *                       units. Shall be in OT_BLE_SCAN_INTERVAL_MIN and
 638  *                       OT_BLE_SCAN_INTERVAL_MAX range.
 639  * @param[in] aWindow    The scanning window in OT_BLE_SCAN_WINDOW_UNIT units.
 640  *                       Shall be in OT_BLE_SCAN_WINDOW_MIN and OT_BLE_SCAN_WINDOW_MAX
 641  *                       range.
 642  *
 643  * @retval ::OT_ERROR_NONE           Scanning procedure has been started.
 644  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 645  * @retval ::OT_ERROR_INVALID_ARGS   Invalid interval or window value has been
 646  *                                   supplied.
 647  */
 648 otError otPlatBleGapScanStart(otInstance *aInstance, uint16_t aInterval, uint16_t aWindow);
 649
 650 /**
 651  * Stops BLE Scanning procedure.
 652  *
 653  * @note This function shall be used only for BLE Central role.
 654  *
 655  * @param[in] aInstance  The OpenThread instance structure.
 656  *
 657  * @retval ::OT_ERROR_NONE           Scanning procedure has been stopped.
 658  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 659  */
 660 otError otPlatBleGapScanStop(otInstance *aInstance);
 661
 662 /**
 663  * The BLE driver calls this method to notify OpenThread that an advertisement
 664  * packet has been received.
 665  *
 666  * @param[in]  aInstance  The OpenThread instance structure.
 667  * @param[in]  aAddress   An address of the advertising device.
 668  * @param[in]  aPacket    A pointer to the received packet.
 669  *
 670  */
 671 extern void otPlatBleGapOnAdvReceived(otInstance *aInstance, otPlatBleDeviceAddr *aAddress, otBleRadioPacket *aPacket);
 672
 673 /**
 674  * The BLE driver calls this method to notify OpenThread that a scan response packet has been received.
 675  *
 676  * @param[in]  aInstance  The OpenThread instance structure.
 677  * @param[in]  aAddress   An address of the advertising device.
 678  * @param[in]  aPacket    A pointer to the received packet.
 679  *
 680  */
 681 extern void otPlatBleGapOnScanRespReceived(otInstance *         aInstance,
 682                                            otPlatBleDeviceAddr *aAddress,
 683                                            otBleRadioPacket *   aPacket);
 684
 685 /**
 686  * Starts BLE Connection procedure.
 687  *
 688  * @note This function shall be used only for BLE Central role.
 689  *
 690  * @param[in] aInstance  The OpenThread instance structure.
 691  * @param[in] aAddress   An address of the advertising device.
 692  * @param[in] aInterval  The scanning interval in OT_BLE_SCAN_INTERVAL_UNIT units. Shall be in
 693  *                       OT_BLE_SCAN_INTERVAL_MIN and OT_BLE_SCAN_INTERVAL_MAX range.
 694  * @param[in] aWindow    The scanning window in OT_BLE_SCAN_WINDOW_UNIT units. Shall be in
 695  *                       OT_BLE_SCAN_WINDOW_MIN and OT_BLE_SCAN_WINDOW_MAX range.
 696  *
 697  * @retval ::OT_ERROR_NONE           Connection procedure has been started.
 698  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 699  * @retval ::OT_ERROR_INVALID_ARGS   Invalid address, interval or window value has been supplied.
 700  */
 701 otError otPlatBleGapConnect(otInstance *aInstance, otPlatBleDeviceAddr *aAddress, uint16_t aInterval, uint16_t aWindow);
 702
 703 /**
 704  * Disconnects BLE connection.
 705  *
 706  * The BLE device shall indicate the OT_BLE_HCI_REMOTE_USER_TERMINATED HCI code reason.
 707  *
 708  * @param[in] aInstance  The OpenThread instance structure.
 709  *
 710  * @retval ::OT_ERROR_NONE           Disconnection procedure has been started.
 711  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 712  */
 713 otError otPlatBleGapDisconnect(otInstance *aInstance);
 714
 715 /*******************************************************************************
 716  * @section Bluetooth Low Energy GATT Common.
 717  *******************************************************************************/
 718
 719 /**
 720  * Registers vendor specific UUID Base.
 721  *
 722  * @param[in]  aInstance  The OpenThread instance structure.
 723  * @param[in]  aUuid      A pointer to vendor specific 128-bit UUID Base.
 724  *
 725  */
 726 otError otPlatBleGattVendorUuidRegister(otInstance *aInstance, const otPlatBleUuid *aUuid);
 727
 728 /**
 729  * Reads currently use value of ATT_MTU.
 730  *
 731  * @param[in]   aInstance  The OpenThread instance structure.
 732  * @param[out]  aMtu       A pointer contains current ATT_MTU value.
 733  *
 734  * @retval ::OT_ERROR_NONE     ATT_MTU value has been placed in @p aMtu.
 735  * @retval ::OT_ERROR_FAILED   BLE Device cannot determine its ATT_MTU.
 736  */
 737 otError otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu);
 738
 739 /*******************************************************************************
 740  * @section Bluetooth Low Energy GATT Client.
 741  ******************************************************************************/
 742
 743 /**
 744  * Sends ATT Read Request.
 745  *
 746  * @note This function shall be used only for GATT Client.
 747  *
 748  * @param[in] aInstance  The OpenThread instance structure.
 749  * @param[in] aHandle    The handle of the attribute to be read.
 750  *
 751  * @retval ::OT_ERROR_NONE           ATT Write Request has been sent.
 752  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 753  * @retval ::OT_ERROR_INVALID_ARGS   Invalid handle value has been supplied.
 754  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 755  */
 756 otError otPlatBleGattClientRead(otInstance *aInstance, uint16_t aHandle);
 757
 758 /**
 759  * The BLE driver calls this method to notify OpenThread that ATT Read Response
 760  * packet has been received.
 761  *
 762  * This method is called only if @p otPlatBleGattClientRead was previously requested.
 763  *
 764  * @note This function shall be used only for GATT Client.
 765  *
 766  * @param[in] aInstance  The OpenThread instance structure.
 767  * @param[in] aPacket    A pointer to the packet contains read value.
 768  *
 769  */
 770 extern void otPlatBleGattClientOnReadResponse(otInstance *aInstance, otBleRadioPacket *aPacket);
 771
 772 /**
 773  * Sends ATT Write Request.
 774  *
 775  * @note This function shall be used only for GATT Client.
 776  *
 777  * @param[in] aInstance  The OpenThread instance structure.
 778  * @param[in] aHandle    The handle of the attribute to be written.
 779  * @param[in] aPacket    A pointer to the packet contains value to be
 780  *                       written to the attribute.
 781  *
 782  * @retval ::OT_ERROR_NONE           ATT Write Request has been sent.
 783  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 784  * @retval ::OT_ERROR_INVALID_ARGS   Invalid handle value, data or data length has been supplied.
 785  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 786  */
 787 otError otPlatBleGattClientWrite(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
 788
 789 /**
 790  * The BLE driver calls this method to notify OpenThread that ATT Write Response
 791  * packet has been received.
 792  *
 793  * This method is called only if @p otPlatBleGattClientWrite was previously requested.
 794  *
 795  * @note This function shall be used only for GATT Client.
 796  *
 797  * @param[in] aInstance  The OpenThread instance structure.
 798  * @param[in] aHandle    The handle on which ATT Write Response has been sent.
 799  *
 800  */
 801
 802 extern void otPlatBleGattClientOnWriteResponse(otInstance *aInstance, uint16_t aHandle);
 803 /**
 804  * Subscribes for characteristic indications.
 805  *
 806  * @note This function shall be used only for GATT Client.
 807  *
 808  * @param[in] aInstance    The OpenThread instance structure.
 809  * @param[in] aHandle      The handle of the attribute to be written.
 810  * @param[in] aSubscribing True if subscribing, otherwise unsubscribing.
 811  *
 812  * @retval ::OT_ERROR_NONE           Subscription has been sent.
 813  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 814  * @retval ::OT_ERROR_INVALID_ARGS   Invalid handle value, data or data length has been supplied.
 815  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 816  */
 817 otError otPlatBleGattClientSubscribeRequest(otInstance *aInstance, uint16_t aHandle, bool aSubscribing);
 818
 819 /**
 820  * The BLE driver calls this method to notify OpenThread that subscribe response
 821  * has been received.
 822  *
 823  * This method is called only if @p otPlatBleGattClienSubscribe was previously requested.
 824  *
 825  * @note This function shall be used only for GATT Client.
 826  *
 827  * @param[in] aInstance  The OpenThread instance structure.
 828  * @param[in] aHandle    The handle on which ATT Write Response has been sent.
 829  *
 830  */
 831 extern void otPlatBleGattClientOnSubscribeResponse(otInstance *aInstance, uint16_t aHandle);
 832
 833 /**
 834  * The BLE driver calls this method to notify OpenThread that an ATT Handle Value
 835  * Indication has been received.
 836  *
 837  * @note This function shall be used only for GATT Client.
 838  *
 839  * @param[in] aInstance  The OpenThread instance structure.
 840  * @param[in] aHandle    The handle on which ATT Handle Value Indication has been sent.
 841  * @param[in] aPacket    A pointer to the packet contains indicated value.
 842  *
 843  */
 844 extern void otPlatBleGattClientOnIndication(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
 845
 846 /**
 847  * Performs GATT Primary Service Discovery of all services available.
 848  *
 849  * @note This function shall be used only for GATT Client.
 850  *
 851  * @param[in] aInstance  The OpenThread instance structure.
 852  *
 853  * @retval ::OT_ERROR_NONE           Service Discovery procedure has been started.
 854  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 855  * @retval ::OT_ERROR_INVALID_ARGS   Invalid service UUID has been provided.
 856  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 857  */
 858 otError otPlatBleGattClientServicesDiscover(otInstance *aInstance);
 859
 860 /**
 861  * Performs GATT Primary Service Discovery by UUID procedure of specific service.
 862  *
 863  * @note This function shall be used only for GATT Client.
 864  *
 865  * @param[in] aInstance  The OpenThread instance structure.
 866  * @param[in] aUuid      The UUID of a service to be registered.
 867  *
 868  * @retval ::OT_ERROR_NONE           Service Discovery procedure has been started.
 869  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 870  * @retval ::OT_ERROR_INVALID_ARGS   Invalid service UUID has been provided.
 871  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 872  */
 873 otError otPlatBleGattClientServiceDiscover(otInstance *aInstance, const otPlatBleUuid *aUuid);
 874
 875 /**
 876  * The BLE driver calls this method to notify OpenThread that the next entry
 877  * from GATT Primary Service Discovery has been found.
 878  *
 879  * @note This function shall be used only for GATT Client.
 880  *
 881  * @param[in] aInstance     The OpenThread instance structure.
 882  * @param[in] aStartHandle  The start handle of a service.
 883  * @param[in] aEndHandle    The end handle of a service.
 884  * @param[in] aServiceUuid  The Uuid16 for the service entry.
 885  * @param[in] aError        The value of OT_ERROR_NONE indicates that service has been found
 886  *                          and structure @p aStartHandle and @p aEndHandle contain valid handles.
 887  *                          OT_ERROR_NOT_FOUND error should be set if service has not been found.
 888  *                          Otherwise error indicates the reason of failure is used.
 889  *
 890  */
 891 extern void otPlatBleGattClientOnServiceDiscovered(otInstance *aInstance,
 892                                                    uint16_t    aStartHandle,
 893                                                    uint16_t    aEndHandle,
 894                                                    uint16_t    aServiceUuid,
 895                                                    otError     aError);
 896
 897 /**
 898  * Performs GATT Characteristic Discovery of a service.
 899  *
 900  * @note This function shall be used only for GATT Client.
 901  *
 902  * @param[in] aInstance     The OpenThread instance structure.
 903  * @param[in] aStartHandle  The start handle of a service.
 904  * @param[in] aEndHandle    The end handle of a service.
 905  *
 906  * @retval ::OT_ERROR_NONE           Characteristic Discovery procedure has been started.
 907  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 908  * @retval ::OT_ERROR_INVALID_ARGS   Invalid start or end handle has been provided.
 909  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 910  */
 911 otError otPlatBleGattClientCharacteristicsDiscover(otInstance *aInstance, uint16_t aStartHandle, uint16_t aEndHandle);
 912
 913 /**
 914  * The BLE driver calls this method to notify OpenThread that GATT Characteristic
 915  * Discovery of a service has been done.
 916  *
 917  * In case of success, all elements inside @p aChars should have a valid mHandleValue value.
 918  *
 919  * @note This function shall be used only for GATT Client.
 920  *
 921  * @param[in] aInstance  The OpenThread instance structure.
 922  * @param[in] aChars     A pointer to discovered characteristic list.
 923  * @param[in] aCount     Number of characteristics in @p aChar list.
 924  * @param[in] aError     The value of OT_ERROR_NONE indicates that at least one characteristic
 925  *                       has been found and the total number of them is stored in @p aCount.
 926  *                       OT_ERROR_NOT_FOUND error should be set if no charactertistics are found.
 927  *                       Otherwise error indicates the reason of failure is used.
 928  *
 929  */
 930 extern void otPlatBleGattClientOnCharacteristicsDiscoverDone(otInstance *                 aInstance,
 931                                                              otPlatBleGattCharacteristic *aChars,
 932                                                              uint16_t                     aCount,
 933                                                              otError                      aError);
 934
 935 /**
 936  * Performs GATT Descriptor Discovery.
 937  *
 938  * @note This function shall be used only for GATT Client.
 939  *
 940  * @param[in] aInstance     The OpenThread instance structure.
 941  * @param[in] aStartHandle  The start handle.
 942  * @param[in] aEndHandle    The end handle.
 943  *
 944  * @retval ::OT_ERROR_NONE           Descriptor Discovery procedure has been started.
 945  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 946  * @retval ::OT_ERROR_INVALID_ARGS   Invalid start or end handle has been provided.
 947  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 948  */
 949 otError otPlatBleGattClientDescriptorsDiscover(otInstance *aInstance, uint16_t aStartHandle, uint16_t aEndHandle);
 950
 951 /**
 952  * The BLE driver calls this method to notify OpenThread that GATT Descriptor
 953  * Discovery has been done.
 954  *
 955  * @note This function shall be used only for GATT Client.
 956  *
 957  * @param[in] aInstance  The OpenThread instance structure.
 958  * @param[in] aDescs     A pointer to discovered descriptor list.
 959  * @param[in] aCount     Number of descriptors in @p aDescs list.
 960  * @param[in] aError     The value of OT_ERROR_NONE indicates that at least one descriptor
 961  *                       has been found and the total number of them is stored in @p aCount.
 962  *                       OT_ERROR_NOT_FOUND error should be set if no descriptors are found.
 963  *                       Otherwise error indicates the reason of failure is used.
 964  *
 965  */
 966 extern void otPlatBleGattClientOnDescriptorsDiscoverDone(otInstance *             aInstance,
 967                                                          otPlatBleGattDescriptor *aDescs,
 968                                                          uint16_t                 aCount,
 969                                                          otError                  aError);
 970
 971 /**
 972  * Sends Exchange MTU Request.
 973  *
 974  * @note This function shall be used only for GATT Client.
 975  *
 976  * @param[in] aInstance  The OpenThread instance structure.
 977  * @param[in] aMtu       A value of GATT Client receive MTU size.
 978  *
 979  * @retval ::OT_ERROR_NONE           Exchange MTU Request has been sent.
 980  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
 981  * @retval ::OT_ERROR_INVALID_ARGS   Invalid aMtu has been provided.
 982  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
 983  */
 984 otError otPlatBleGattClientMtuExchangeRequest(otInstance *aInstance, uint16_t aMtu);
 985
 986 /**
 987  * The BLE driver calls this method to notify OpenThread that Exchange MTU
 988  * Response has been received.
 989  *
 990  * @note This function shall be used only for GATT Client.
 991  *
 992  * @param[in] aInstance  The OpenThread instance structure.
 993  * @param[in] aMtu       Attribute server receive MTU size.
 994  * @param[in] aError     The value of OT_ERROR_NONE indicates that valid
 995  *                       Exchange MTU Response has been received. Otherwise error
 996  *                       indicates the reason of failure is used.
 997  *
 998  */
 999 extern void otPlatBleGattClientOnMtuExchangeResponse(otInstance *aInstance, uint16_t aMtu, otError aError);
1000
1001 /*******************************************************************************
1002  * @section Bluetooth Low Energy GATT Server.
1003  ******************************************************************************/
1004
1005 /**
1006  * Registers a list of GATT Services and their enclosed Characteristics.
1007  * The generated handles will be written back into this structure when the
1008  * BLE stack is enabled.
1009  *
1010  * @note This function shall be used only for GATT Server.
1011  *
1012  * @param[in]   aInstance  The OpenThread instance structure.
1013  * @param[in]   aServices  Null terminated array of service structures to register.
1014  *
1015  * @retval ::OT_ERROR_NONE           Service has been successfully registered.
1016  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
1017  * @retval ::OT_ERROR_INVALID_ARGS   Invalid service UUID has been provided.
1018  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1019  */
1020 otError otPlatBleGattServerServicesRegister(otInstance *aInstance, otPlatBleGattService *aServices);
1021
1022 /**
1023  * Sends ATT Handle Value Indication.
1024  *
1025  * @note This function shall be used only for GATT Server.
1026  *
1027  * @param[in] aInstance   The OpenThread instance structure.
1028  * @param[in] aHandle     The handle of the attribute to be indicated.
1029  * @param[in] aPacket     A pointer to the packet contains value to be indicated.
1030  *
1031  * @retval ::OT_ERROR_NONE           ATT Handle Value Indication has been sent.
1032  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state.
1033  * @retval ::OT_ERROR_INVALID_ARGS   Invalid handle value, data or data length has been supplied.
1034  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1035  */
1036 otError otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1037
1038 /**
1039  * The BLE driver calls this method to notify OpenThread that an ATT Handle
1040  * Value Confirmation has been received.
1041  *
1042  * This method is called only if @p otPlatBleGattServerIndicate was previously requested.
1043  *
1044  * @note This function shall be used only for GATT Server.
1045  *
1046  * @param[in] aInstance  The OpenThread instance structure.
1047  * @param[in] aHandle    The handle on which ATT Handle Value Confirmation has been sent.
1048  *
1049  */
1050 extern void otPlatBleGattServerOnIndicationConfirmation(otInstance *aInstance, uint16_t aHandle);
1051
1052 /**
1053  * The BLE driver calls this method to notify OpenThread that an ATT Write Request
1054  * packet has been received.
1055  *
1056  * @note This function shall be used only for GATT Server.
1057  *
1058  * @param[in] aInstance   The OpenThread instance structure.
1059  * @param[in] aHandle     The handle of the attribute to be written.
1060  * @param[in] aPacket     A pointer to the packet contains value to be written to the attribute.
1061  *
1062  */
1063 extern void otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1064
1065 /**
1066  * The BLE driver calls this method to notify OpenThread that an ATT Read Request
1067  * packet has been received.
1068  *
1069  * @note This function shall be used only for GATT Server.
1070  *
1071  * @param[in]  aInstance  The OpenThread instance structure.
1072  * @param[in]  aHandle    The handle of the attribute to be read.
1073  * @param[out] aPacket    A pointer to the packet to be filled with pointers to attribute data to be read.
1074  *
1075  */
1076 extern void otPlatBleGattServerOnReadRequest(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1077
1078 /**
1079  * The BLE driver calls this method to notify OpenThread that an ATT Subscription
1080  * Request packet has been received.
1081  *
1082  * @note This function shall be used only for GATT Server.
1083  *
1084  * @param[in] aInstance    The OpenThread instance structure.
1085  * @param[in] aHandle      The handle of the attribute to be written.
1086  * @param[in] aSubscribing True if subscribing, otherwise unsubscribing.
1087  *
1088  */
1089 extern void otPlatBleGattServerOnSubscribeRequest(otInstance *aInstance, uint16_t aHandle, bool aSubscribing);
1090
1091 /****************************************************************************
1092  * @section Bluetooth Low Energy L2CAP Connection Oriented Channels.
1093  ***************************************************************************/
1094
1095 /**
1096  * Sends LE Credit Based Connection Request.
1097  *
1098  * @note Platform layer is responsible for credits management and segmentation (MPS).
1099  *
1100  * @param[in]  aInstance  The OpenThread instance structure.
1101  * @param[in]  aPsm       The value of LE Protocol/Service Multiplexer.
1102  * @param[in]  aMtu       The value specifies the maximum SDU size (in octets) that the L2CAP
1103  *                        layer entity sending the LE Credit Based Connection Request can receive
1104  *                        on this channel.
1105  * @param[out] aCid       The source CID represents a channel endpoint on the device.
1106  *
1107  * @retval ::OT_ERROR_NONE           LE Credit Based Connection Request has been sent.
1108  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state e.g. not in the GAP connection.
1109  * @retval ::OT_ERROR_INVALID_ARGS   Invalid parameters has been supplied.
1110  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1111  *
1112  */
1113 otError otPlatBleL2capConnectionRequest(otInstance *aInstance, uint16_t aPsm, uint16_t aMtu, uint16_t *aCid);
1114
1115 /**
1116  * The BLE driver calls this method to notify OpenThread that an LE Credit Based Connection
1117  * Request packet has been received.
1118  *
1119  * @param[in]  aInstance  The OpenThread instance structure.
1120  * @param[in]  aPsm       The value of LE Protocol/Service Multiplexer.
1121  * @param[in]  aMtu       The value specifies the maximum SDU size (in octets) that the L2CAP
1122  *                        layer entity sending the LE Credit Based Connection Request can receive
1123  *                        on this channel.
1124  * @param[in]  aPeerCid   The CID represents a channel endpoint on the peer device.
1125  *
1126  */
1127 extern void otPlatBleL2capOnConnectionRequest(otInstance *aInstance, uint16_t aPsm, uint16_t aMtu, uint16_t aPeerCid);
1128
1129 /**
1130  * Sends LE Credit Based Connection Response.
1131  *
1132  * @note Platform layer is responsible for credits management and segmentation (MPS).
1133  *
1134  * @param[in]  aInstance  The OpenThread instance structure.
1135  * @param[in]  aError     The error value indicates the outcome of the connection request.
1136  * @param[in]  aMtu       The value specifies the maximum SDU size (in octets) that the L2CAP
1137  *                        layer entity sending the LE Credit Based Connection Response can receive
1138  *                        on this channel.
1139  * @param[out] aCid       The source CID represents a channel endpoint on the device. If @p aResult
1140  *                        value is different from @p OT_BLE_L2C_ERROR_NONE, this variable is
1141  *                        unused and should be set to NULL.
1142  *
1143  * @retval ::OT_ERROR_NONE           LE Credit Based Connection Response has been sent.
1144  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state e.g. not in the GAP connection.
1145  * @retval ::OT_ERROR_INVALID_ARGS   Invalid parameters has been supplied.
1146  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1147  *
1148  */
1149 otError otPlatBleL2capConnectionResponse(otInstance *        aInstance,
1150                                          otPlatBleL2capError aError,
1151                                          uint16_t            aMtu,
1152                                          uint16_t *          aCid);
1153
1154 /**
1155  * The BLE driver calls this method to notify OpenThread that an LE Credit Based Connection
1156  * Response packet has been received.
1157  *
1158  * @param[in]  aInstance  The OpenThread instance structure.
1159  * @param[in]  aError     The error value indicates the outcome of the connection request.
1160  * @param[in]  aMtu       The value specifies the maximum SDU size (in octets) that the L2CAP
1161  *                        layer entity sending the LE Credit Based Connection Response can receive
1162  *                        on this channel.
1163  * @param[in]  aPeerCid   The CID represents a channel endpoint on the peer device.
1164  *
1165  */
1166 extern void otPlatBleL2capOnConnectionResponse(otInstance *        aInstance,
1167                                                otPlatBleL2capError aError,
1168                                                uint16_t            aMtu,
1169                                                uint16_t            aPeerCid);
1170
1171 /**
1172  * Sends an SDU on an L2CAP channel.
1173  *
1174  * @note Platform layer is responsible for credits management and segmentation (MPS).
1175  *
1176  * @param[in] aInstance  The OpenThread instance structure.
1177  * @param[in] aLocalCid  The local channel endpoint ID value.
1178  * @param[in] aPeerCid   The peer channel endpoint ID value.
1179  * @param[in] aPacket    A pointer to the packet containing SDU.
1180  *
1181  * @retval ::OT_ERROR_NONE           LE Credit Based Connection Request has been sent.
1182  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state e.g. not in the GAP connection.
1183  * @retval ::OT_ERROR_INVALID_ARGS   Invalid parameters has been supplied.
1184  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1185  *
1186  */
1187 otError otPlatBleL2capSduSend(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid, otBleRadioPacket *aPacket);
1188
1189 /**
1190  * The BLE driver calls this method to notify OpenThread that an L2CAP SDU has been received.
1191  *
1192  * @note Platform layer is responsible for credits management and segmentation (MPS).
1193  *
1194  * @param[in] aInstance  The OpenThread instance structure.
1195  * @param[in] aLocalCid  The local channel endpoint ID value.
1196  * @param[in] aPeerCid   The peer channel endpoint ID value.
1197  * @param[in] aPacket    A pointer to the packet containing SDU.
1198  *
1199  */
1200 extern void otPlatBleL2capOnSduReceived(otInstance *      aInstance,
1201                                         uint16_t          aLocalCid,
1202                                         uint16_t          aPeerCid,
1203                                         otBleRadioPacket *aPacket);
1204
1205 /**
1206  * The BLE driver calls this method to notify OpenThread that an L2CAP SDU has been sent.
1207  *
1208  * @param[in] aInstance  The OpenThread instance structure.
1209  *
1210  */
1211 extern void otPlatBleL2capOnSduSent(otInstance *aInstance);
1212
1213 /**
1214  * Sends an L2CAP Disconnection Request.
1215  *
1216  * @param[in] aInstance  The OpenThread instance structure.
1217  * @param[in] aLocalCid  The local channel endpoint ID value.
1218  * @param[in] aPeerCid   The peer channel endpoint ID value.
1219  *
1220  * @retval ::OT_ERROR_NONE           L2CAP Disconnection Request has been sent.
1221  * @retval ::OT_ERROR_INVALID_STATE  BLE Device is in invalid state e.g. not in the GAP connection.
1222  * @retval ::OT_ERROR_INVALID_ARGS   Invalid parameters has been supplied.
1223  * @retval ::OT_ERROR_NO_BUFS        No available internal buffer found.
1224  *
1225  */
1226 otError otPlatBleL2capDisconnect(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid);
1227
1228 /**
1229  * The BLE driver calls this method to notify OpenThread that an L2CAP Disconnection Request has been
1230  * received.
1231  *
1232  * @note Platform layer is responsible to response with L2CAP Disconnection Response internally.
1233  *
1234  * @param[in] aInstance  The OpenThread instance structure.
1235  * @param[in] aLocalCid  The local channel endpoint ID value.
1236  * @param[in] aPeerCid   The peer channel endpoint ID value.
1237  *
1238  */
1239 extern void otPlatBleL2capOnDisconnect(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid);
1240
1241 /**
1242  * @}
1243  *
1244  */
1245
1246 #ifdef __cplusplus
1247 } // end of extern "C"
1248 #endif
1249
1250 #endif // OT_PLATFORM_BLE_H_