2 * Copyright (c) 2018, The OpenThread Authors.
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.
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.
32 * This file defines a generic OpenThread BLE driver HOST interface.
36 #ifndef OT_PLATFORM_BLE_H_
37 #define OT_PLATFORM_BLE_H_
45 #include <openthread/error.h>
46 #include <openthread/instance.h>
49 * @addtogroup plat-ble
52 * This module includes the platform abstraction for BLE Host communication.
53 * The platform needs to implement Bluetooth LE 4.2 or higher.
62 * The size of the Bluetooth Device Address [bytes].
64 OT_BLE_ADDRESS_LENGTH = 6,
67 * Time slot duration on PHY layer in microseconds (0.625ms).
69 OT_BLE_TIMESLOT_UNIT = 625,
72 * Unit used to calculate connection interval (1.25ms)
74 OT_BLE_CONN_INTERVAL_UNIT = 2 * OT_BLE_TIMESLOT_UNIT,
77 * Minimum allowed connection interval in OT_BLE_CONN_INTERVAL_UNIT units (7.5ms).
78 * See v4.2 [Vol 2, Part E] page 946
80 OT_BLE_CONN_INTERVAL_MIN = 0x0006,
83 * Maximum allowed connection interval in OT_BLE_CONN_INTERVAL_UNIT units (4s).
84 * See v4.2 [Vol 2, Part E] page 946
86 OT_BLE_CONN_INTERVAL_MAX = 0x0C80,
89 * Maximum allowed slave latency in units of connection events.
90 * See v4.2 [Vol 2, Part E] page 946
92 OT_BLE_CONN_SLAVE_LATENCY_MAX = 0x01F3,
95 * Minimum allowed connection timeout in units of 10ms (100ms).
96 * See v4.2 [Vol 2, Part E] page 946
98 OT_BLE_CONN_SUPERVISOR_TIMEOUT_MIN = 0x000A,
101 * Maximum allowed connection timeout (32s).
102 * See v4.2 [Vol 2, Part E] page 946
104 OT_BLE_CONN_SUPERVISOR_TIMEOUT_MAX = 0x0C80,
107 * Unit used to calculate connection supervisor timeout (10ms).
109 OT_BLE_CONN_SUPERVISOR_UNIT = 16 * OT_BLE_TIMESLOT_UNIT,
112 * Maximum length of the device name characteristic [bytes].
114 OT_BLE_DEV_NAME_MAX_LENGTH = 248,
117 * Maximum length of advertising data [bytes].
119 OT_BLE_ADV_DATA_MAX_LENGTH = 31,
122 * Maximum length of scan response data [bytes].
124 OT_BLE_SCAN_RESPONSE_MAX_LENGTH = 31,
127 * Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms).
129 OT_BLE_ADV_INTERVAL_MIN = 0x0020,
132 * Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s).
134 OT_BLE_ADV_INTERVAL_MAX = 0x4000,
137 * Unit used to calculate interval duration (0.625ms).
139 OT_BLE_ADV_INTERVAL_UNIT = OT_BLE_TIMESLOT_UNIT,
142 * Minimum allowed scan interval (2.5ms).
144 OT_BLE_SCAN_INTERVAL_MIN = 0x0004,
147 * Maximum allowed scan interval (10.24s).
149 OT_BLE_SCAN_INTERVAL_MAX = 0x4000,
152 * Unit used to calculate scan interval duration (0.625ms).
154 OT_BLE_SCAN_INTERVAL_UNIT = OT_BLE_TIMESLOT_UNIT,
157 * Minimum allowed scan window in OT_BLE_TIMESLOT_UNIT units (2.5ms).
159 OT_BLE_SCAN_WINDOW_MIN = 0x0004,
162 * Maximum allowed scan window in OT_BLE_TIMESLOT_UNIT units (10.24s).
164 OT_BLE_SCAN_WINDOW_MAX = 0x4000,
167 * Unit used to calculate scan window duration (0.625ms).
169 OT_BLE_SCAN_WINDOW_UNIT = OT_BLE_TIMESLOT_UNIT,
172 * BLE HCI code for remote user terminated connection.
174 OT_BLE_HCI_REMOTE_USER_TERMINATED = 0x13,
177 * Value of invalid/unknown handle.
179 OT_BLE_INVALID_HANDLE = 0x0000,
182 * Maximum size of BLE Characteristic [bytes].
184 OT_BLE_CHARACTERISTIC_MAX_LENGTH = 512,
187 * Maximum value of ATT_MTU [bytes].
189 OT_BLE_ATT_MTU_MAX = 511,
192 * Length of full BLE UUID in bytes.
194 OT_BLE_UUID_LENGTH = 16,
197 * Uuid of Client Configuration Characteristic Descriptor.
199 OT_BLE_UUID_CCCD = 0x2902,
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)
207 * This enum represents BLE Device Address types.
210 typedef enum otPlatBleAddressType
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;
219 * This enumeration defines the characterstic properties flags for a
220 * Client Characteristic Configuration Descriptor (CCCD).
222 * See v4.2 [Vol 3, Part G] 3.3.1.1 Characteristic Properties - Table 3.5
224 typedef enum otPlatBleCccdFlags
227 * If set, permits broadcasts of the Characteristic Value using Characteristic Configuration Descriptor.
229 OT_BLE_CHAR_PROP_BROADCAST = (1 << 0),
232 * If set, permits reads of the Characteristic Value.
234 OT_BLE_CHAR_PROP_READ = (1 << 1),
237 * If set, permit writes of the Characteristic Value without response.
239 OT_BLE_CHAR_PROP_WRITE_NO_RESPONSE = (1 << 2),
242 * If set, permits writes of the Characteristic Value with response.
244 OT_BLE_CHAR_PROP_WRITE = (1 << 3),
247 * If set, permits notifications of a Characteristic Value without acknowledgement.
249 OT_BLE_CHAR_PROP_NOTIFY = (1 << 4),
252 * If set, permits indications of a Characteristic Value with acknowledgement.
254 OT_BLE_CHAR_PROP_INDICATE = (1 << 5),
257 * If set, permits signed writes to the Characteristic Value.
259 OT_BLE_CHAR_PROP_AUTH_SIGNED_WRITE = (1 << 6),
262 * If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.
264 OT_BLE_CHAR_PROP_EXTENDED = (1 << 7),
266 } otPlatBleCccdFlags;
269 * This structure represents BLE Device Address.
272 typedef struct otPlatBleDeviceAddr
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;
279 * This enumeration defines flags for BLE advertisement mode.
282 typedef enum otPlatBleAdvMode
285 * If set, advertising device will allow connections to be initiated.
287 OT_BLE_ADV_MODE_CONNECTABLE = (1 << 0),
290 * If set, advertising device will respond to scan requests.
292 OT_BLE_ADV_MODE_SCANNABLE = (1 << 1),
296 * This structure represents BLE connection parameters.
299 typedef struct otPlatBleGapConnParams
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.
305 uint16_t mConnMinInterval;
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.
311 uint16_t mConnMaxInterval;
314 * Slave Latency in number of connection events.
315 * Shall not exceed OT_BLE_CONN_SLAVE_LATENCY_MAX value.
317 uint16_t mConnSlaveLatency;
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.
323 uint16_t mConnSupervisionTimeout;
325 } otPlatBleGapConnParams;
328 * This enumeration represents BLE UUID value.
331 typedef enum otPlatBleUuidType
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.
340 * This structure represents BLE UUID value.
343 typedef union otPlatBleUuidValue
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;
351 * This structure represents BLE UUID.
354 typedef struct otPlatBleUuid
356 otPlatBleUuidType mType; ///< A type of UUID in @p mValue.
357 otPlatBleUuidValue mValue; ///< A value of UUID.
361 * This structure represents GATT Characteristic.
364 typedef struct otPlatBleGattCharacteristic
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;
373 * This structure represents GATT Descriptor.
376 typedef struct otPlatBleGattDescriptor
378 otPlatBleUuid mUuid; ///< A UUID value of descriptor.
379 uint16_t mHandle; ///< Descriptor handle.
380 } otPlatBleGattDescriptor;
383 * Registration descriptor for a GATT service.
386 typedef struct otPlatBleGattService
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.
392 const otPlatBleUuid mUuid;
395 * Handle of service; written to by stack after call to
396 * otPlatBleGattServerServicesRegister.
401 * Array of characteristic definitions corresponding to characteristics
402 * belonging to this service.
404 otPlatBleGattCharacteristic *mCharacteristics;
405 } otPlatBleGattService;
408 * This structure represents an BLE packet.
411 typedef struct otBleRadioPacket
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.
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.
422 typedef enum otPlatBleL2capError
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;
430 /*******************************************************************************
431 * @section Bluetooth Low Energy management.
432 ******************************************************************************/
435 * Enable the Bluetooth Low Energy radio.
437 * @note BLE Device should use the highest ATT_MTU supported that does not
438 * exceed OT_BLE_ATT_MTU_MAX octets.
440 * @param[in] aInstance The OpenThread instance structure.
442 * @retval ::OT_ERROR_NONE Successfully enabled.
443 * @retval ::OT_ERROR_FAILED The BLE radio could not be enabled.
445 otError otPlatBleEnable(otInstance *aInstance);
448 * Disable the Bluetooth Low Energy radio.
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.
455 * @param[in] aInstance The OpenThread instance structure.
457 * @retval ::OT_ERROR_NONE Successfully transitioned to disabled.
458 * @retval ::OT_ERROR_FAILED The BLE radio could not be disabled.
460 otError otPlatBleDisable(otInstance *aInstance);
463 * Reset the Bluetooth Low Energy subsystem.
465 * @param[in] aInstance The OpenThread instance structure.
467 * @retval ::OT_ERROR_NONE Successfully reset.
468 * @retval ::OT_ERROR_FAILED The BLE stack could not be reset.
470 otError otPlatBleReset(otInstance *aInstance);
473 * Check whether Bluetooth Low Energy radio is enabled or not.
475 * @param[in] aInstance The OpenThread instance structure.
477 * @retval ::true Bluetooth Low Energy radio is enabled.
478 * @retval ::false Bluetooth Low Energy radio is disabled.
480 bool otPlatBleIsEnabled(otInstance *aInstance);
483 * Callback sent when Bluetooth Low Energy is ready after being enabled.
485 * @param[in] aInstance The OpenThread instance structure.
487 extern void otPlatBleOnEnabled(otInstance *aInstance);
489 /****************************************************************************
490 * @section Bluetooth Low Energy GAP.
491 ***************************************************************************/
494 * Gets Bluetooth Device Address.
496 * @param[in] aInstance The OpenThread instance structure.
497 * @param[out] aAddress The pointer to Bluetooth Device Address.
499 * @retval ::OT_ERROR_NONE Request has been successfully done.
500 * @retval ::OT_ERROR_INVALID_ARGS Invalid parameters has been supplied.
502 otError otPlatBleGapAddressGet(otInstance *aInstance, otPlatBleDeviceAddr *aAddress);
505 * Sets Bluetooth Device Address.
507 * @param[in] aInstance The OpenThread instance structure.
508 * @param[in] aAddress The pointer to Bluetooth Device Address.
510 * @retval ::OT_ERROR_NONE Request has been successfully done.
511 * @retval ::OT_ERROR_INVALID_ARGS Invalid parameters has been supplied.
513 otError otPlatBleGapAddressSet(otInstance *aInstance, const otPlatBleDeviceAddr *aAddress);
516 * Sets BLE device name and appearance that is visible as GATT Based service.
518 * The BLE Host stack should set the security mode 1, level 1 (no security) for
519 * those characteristics.
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.
526 * @retval ::OT_ERROR_NONE Connection parameters have been
528 * @retval ::OT_ERROR_INVALID_ARGS Invalid parameters has been supplied.
530 otError otPlatBleGapServiceSet(otInstance *aInstance, const char *aDeviceName, uint16_t aAppearance);
533 * Sets desired BLE Connection Parameters.
535 * @param[in] aInstance The OpenThread instance structure.
536 * @param[in] aConnParams A pointer to connection parameters structure.
538 * @retval ::OT_ERROR_NONE Connection parameters have been
540 * @retval ::OT_ERROR_INVALID_ARGS Invalid connection parameters have been
543 otError otPlatBleGapConnParamsSet(otInstance *aInstance, const otPlatBleGapConnParams *aConnParams);
546 * Sets BLE Advertising packet content.
548 * @note This function shall be used only for BLE Peripheral role.
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.
555 * @retval ::OT_ERROR_NONE Advertising data has been successfully set.
556 * @retval ::OT_ERROR_INVALID_ARGS Invalid advertising data has been supplied.
558 otError otPlatBleGapAdvDataSet(otInstance *aInstance, const uint8_t *aAdvData, uint8_t aAdvDataLength);
561 * Sets BLE Scan Response packet content.
563 * @note This function shall be used only for BLE Peripheral role.
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.
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.
573 otError otPlatBleGapScanResponseSet(otInstance *aInstance, const uint8_t *aScanResponse, uint8_t aScanResponseLength);
576 * Starts BLE Advertising procedure.
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).
582 * @note This function shall be used only for BLE Peripheral role.
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.
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.
596 otError otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval, uint8_t aType);
599 * Stops BLE Advertising procedure.
601 * @note This function shall be used only for BLE Peripheral role.
603 * @param[in] aInstance The OpenThread instance structure.
605 * @retval ::OT_ERROR_NONE Advertising procedure has been stopped.
606 * @retval ::OT_ERROR_INVALID_STATE BLE Device is in invalid state.
608 otError otPlatBleGapAdvStop(otInstance *aInstance);
611 * The BLE driver calls this method to notify OpenThread that BLE Device has
614 * @param[in] aInstance The OpenThread instance structure.
615 * @param[in] aConnectionId The identifier of the open connection.
618 extern void otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId);
621 * The BLE driver calls this method to notify OpenThread that the BLE Device
622 * has been disconnected.
624 * @param[in] aInstance The OpenThread instance structure.
625 * @param[in] aConnectionId The identifier of the closed connection.
628 extern void otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId);
631 * Starts BLE Scanning procedure.
633 * @note This function shall be used only for BLE Central role.
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
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
648 otError otPlatBleGapScanStart(otInstance *aInstance, uint16_t aInterval, uint16_t aWindow);
651 * Stops BLE Scanning procedure.
653 * @note This function shall be used only for BLE Central role.
655 * @param[in] aInstance The OpenThread instance structure.
657 * @retval ::OT_ERROR_NONE Scanning procedure has been stopped.
658 * @retval ::OT_ERROR_INVALID_STATE BLE Device is in invalid state.
660 otError otPlatBleGapScanStop(otInstance *aInstance);
663 * The BLE driver calls this method to notify OpenThread that an advertisement
664 * packet has been received.
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.
671 extern void otPlatBleGapOnAdvReceived(otInstance *aInstance, otPlatBleDeviceAddr *aAddress, otBleRadioPacket *aPacket);
674 * The BLE driver calls this method to notify OpenThread that a scan response packet has been received.
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.
681 extern void otPlatBleGapOnScanRespReceived(otInstance * aInstance,
682 otPlatBleDeviceAddr *aAddress,
683 otBleRadioPacket * aPacket);
686 * Starts BLE Connection procedure.
688 * @note This function shall be used only for BLE Central role.
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.
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.
701 otError otPlatBleGapConnect(otInstance *aInstance, otPlatBleDeviceAddr *aAddress, uint16_t aInterval, uint16_t aWindow);
704 * Disconnects BLE connection.
706 * The BLE device shall indicate the OT_BLE_HCI_REMOTE_USER_TERMINATED HCI code reason.
708 * @param[in] aInstance The OpenThread instance structure.
710 * @retval ::OT_ERROR_NONE Disconnection procedure has been started.
711 * @retval ::OT_ERROR_INVALID_STATE BLE Device is in invalid state.
713 otError otPlatBleGapDisconnect(otInstance *aInstance);
715 /*******************************************************************************
716 * @section Bluetooth Low Energy GATT Common.
717 *******************************************************************************/
720 * Registers vendor specific UUID Base.
722 * @param[in] aInstance The OpenThread instance structure.
723 * @param[in] aUuid A pointer to vendor specific 128-bit UUID Base.
726 otError otPlatBleGattVendorUuidRegister(otInstance *aInstance, const otPlatBleUuid *aUuid);
729 * Reads currently use value of ATT_MTU.
731 * @param[in] aInstance The OpenThread instance structure.
732 * @param[out] aMtu A pointer contains current ATT_MTU value.
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.
737 otError otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu);
739 /*******************************************************************************
740 * @section Bluetooth Low Energy GATT Client.
741 ******************************************************************************/
744 * Sends ATT Read Request.
746 * @note This function shall be used only for GATT Client.
748 * @param[in] aInstance The OpenThread instance structure.
749 * @param[in] aHandle The handle of the attribute to be read.
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.
756 otError otPlatBleGattClientRead(otInstance *aInstance, uint16_t aHandle);
759 * The BLE driver calls this method to notify OpenThread that ATT Read Response
760 * packet has been received.
762 * This method is called only if @p otPlatBleGattClientRead was previously requested.
764 * @note This function shall be used only for GATT Client.
766 * @param[in] aInstance The OpenThread instance structure.
767 * @param[in] aPacket A pointer to the packet contains read value.
770 extern void otPlatBleGattClientOnReadResponse(otInstance *aInstance, otBleRadioPacket *aPacket);
773 * Sends ATT Write Request.
775 * @note This function shall be used only for GATT Client.
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.
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.
787 otError otPlatBleGattClientWrite(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
790 * The BLE driver calls this method to notify OpenThread that ATT Write Response
791 * packet has been received.
793 * This method is called only if @p otPlatBleGattClientWrite was previously requested.
795 * @note This function shall be used only for GATT Client.
797 * @param[in] aInstance The OpenThread instance structure.
798 * @param[in] aHandle The handle on which ATT Write Response has been sent.
802 extern void otPlatBleGattClientOnWriteResponse(otInstance *aInstance, uint16_t aHandle);
804 * Subscribes for characteristic indications.
806 * @note This function shall be used only for GATT Client.
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.
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.
817 otError otPlatBleGattClientSubscribeRequest(otInstance *aInstance, uint16_t aHandle, bool aSubscribing);
820 * The BLE driver calls this method to notify OpenThread that subscribe response
823 * This method is called only if @p otPlatBleGattClienSubscribe was previously requested.
825 * @note This function shall be used only for GATT Client.
827 * @param[in] aInstance The OpenThread instance structure.
828 * @param[in] aHandle The handle on which ATT Write Response has been sent.
831 extern void otPlatBleGattClientOnSubscribeResponse(otInstance *aInstance, uint16_t aHandle);
834 * The BLE driver calls this method to notify OpenThread that an ATT Handle Value
835 * Indication has been received.
837 * @note This function shall be used only for GATT Client.
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.
844 extern void otPlatBleGattClientOnIndication(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
847 * Performs GATT Primary Service Discovery of all services available.
849 * @note This function shall be used only for GATT Client.
851 * @param[in] aInstance The OpenThread instance structure.
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.
858 otError otPlatBleGattClientServicesDiscover(otInstance *aInstance);
861 * Performs GATT Primary Service Discovery by UUID procedure of specific service.
863 * @note This function shall be used only for GATT Client.
865 * @param[in] aInstance The OpenThread instance structure.
866 * @param[in] aUuid The UUID of a service to be registered.
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.
873 otError otPlatBleGattClientServiceDiscover(otInstance *aInstance, const otPlatBleUuid *aUuid);
876 * The BLE driver calls this method to notify OpenThread that the next entry
877 * from GATT Primary Service Discovery has been found.
879 * @note This function shall be used only for GATT Client.
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.
891 extern void otPlatBleGattClientOnServiceDiscovered(otInstance *aInstance,
892 uint16_t aStartHandle,
894 uint16_t aServiceUuid,
898 * Performs GATT Characteristic Discovery of a service.
900 * @note This function shall be used only for GATT Client.
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.
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.
911 otError otPlatBleGattClientCharacteristicsDiscover(otInstance *aInstance, uint16_t aStartHandle, uint16_t aEndHandle);
914 * The BLE driver calls this method to notify OpenThread that GATT Characteristic
915 * Discovery of a service has been done.
917 * In case of success, all elements inside @p aChars should have a valid mHandleValue value.
919 * @note This function shall be used only for GATT Client.
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.
930 extern void otPlatBleGattClientOnCharacteristicsDiscoverDone(otInstance * aInstance,
931 otPlatBleGattCharacteristic *aChars,
936 * Performs GATT Descriptor Discovery.
938 * @note This function shall be used only for GATT Client.
940 * @param[in] aInstance The OpenThread instance structure.
941 * @param[in] aStartHandle The start handle.
942 * @param[in] aEndHandle The end handle.
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.
949 otError otPlatBleGattClientDescriptorsDiscover(otInstance *aInstance, uint16_t aStartHandle, uint16_t aEndHandle);
952 * The BLE driver calls this method to notify OpenThread that GATT Descriptor
953 * Discovery has been done.
955 * @note This function shall be used only for GATT Client.
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.
966 extern void otPlatBleGattClientOnDescriptorsDiscoverDone(otInstance * aInstance,
967 otPlatBleGattDescriptor *aDescs,
972 * Sends Exchange MTU Request.
974 * @note This function shall be used only for GATT Client.
976 * @param[in] aInstance The OpenThread instance structure.
977 * @param[in] aMtu A value of GATT Client receive MTU size.
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.
984 otError otPlatBleGattClientMtuExchangeRequest(otInstance *aInstance, uint16_t aMtu);
987 * The BLE driver calls this method to notify OpenThread that Exchange MTU
988 * Response has been received.
990 * @note This function shall be used only for GATT Client.
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.
999 extern void otPlatBleGattClientOnMtuExchangeResponse(otInstance *aInstance, uint16_t aMtu, otError aError);
1001 /*******************************************************************************
1002 * @section Bluetooth Low Energy GATT Server.
1003 ******************************************************************************/
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.
1010 * @note This function shall be used only for GATT Server.
1012 * @param[in] aInstance The OpenThread instance structure.
1013 * @param[in] aServices Null terminated array of service structures to register.
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.
1020 otError otPlatBleGattServerServicesRegister(otInstance *aInstance, otPlatBleGattService *aServices);
1023 * Sends ATT Handle Value Indication.
1025 * @note This function shall be used only for GATT Server.
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.
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.
1036 otError otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1039 * The BLE driver calls this method to notify OpenThread that an ATT Handle
1040 * Value Confirmation has been received.
1042 * This method is called only if @p otPlatBleGattServerIndicate was previously requested.
1044 * @note This function shall be used only for GATT Server.
1046 * @param[in] aInstance The OpenThread instance structure.
1047 * @param[in] aHandle The handle on which ATT Handle Value Confirmation has been sent.
1050 extern void otPlatBleGattServerOnIndicationConfirmation(otInstance *aInstance, uint16_t aHandle);
1053 * The BLE driver calls this method to notify OpenThread that an ATT Write Request
1054 * packet has been received.
1056 * @note This function shall be used only for GATT Server.
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.
1063 extern void otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1066 * The BLE driver calls this method to notify OpenThread that an ATT Read Request
1067 * packet has been received.
1069 * @note This function shall be used only for GATT Server.
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.
1076 extern void otPlatBleGattServerOnReadRequest(otInstance *aInstance, uint16_t aHandle, otBleRadioPacket *aPacket);
1079 * The BLE driver calls this method to notify OpenThread that an ATT Subscription
1080 * Request packet has been received.
1082 * @note This function shall be used only for GATT Server.
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.
1089 extern void otPlatBleGattServerOnSubscribeRequest(otInstance *aInstance, uint16_t aHandle, bool aSubscribing);
1091 /****************************************************************************
1092 * @section Bluetooth Low Energy L2CAP Connection Oriented Channels.
1093 ***************************************************************************/
1096 * Sends LE Credit Based Connection Request.
1098 * @note Platform layer is responsible for credits management and segmentation (MPS).
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
1105 * @param[out] aCid The source CID represents a channel endpoint on the device.
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.
1113 otError otPlatBleL2capConnectionRequest(otInstance *aInstance, uint16_t aPsm, uint16_t aMtu, uint16_t *aCid);
1116 * The BLE driver calls this method to notify OpenThread that an LE Credit Based Connection
1117 * Request packet has been received.
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
1124 * @param[in] aPeerCid The CID represents a channel endpoint on the peer device.
1127 extern void otPlatBleL2capOnConnectionRequest(otInstance *aInstance, uint16_t aPsm, uint16_t aMtu, uint16_t aPeerCid);
1130 * Sends LE Credit Based Connection Response.
1132 * @note Platform layer is responsible for credits management and segmentation (MPS).
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
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.
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.
1149 otError otPlatBleL2capConnectionResponse(otInstance * aInstance,
1150 otPlatBleL2capError aError,
1155 * The BLE driver calls this method to notify OpenThread that an LE Credit Based Connection
1156 * Response packet has been received.
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
1163 * @param[in] aPeerCid The CID represents a channel endpoint on the peer device.
1166 extern void otPlatBleL2capOnConnectionResponse(otInstance * aInstance,
1167 otPlatBleL2capError aError,
1172 * Sends an SDU on an L2CAP channel.
1174 * @note Platform layer is responsible for credits management and segmentation (MPS).
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.
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.
1187 otError otPlatBleL2capSduSend(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid, otBleRadioPacket *aPacket);
1190 * The BLE driver calls this method to notify OpenThread that an L2CAP SDU has been received.
1192 * @note Platform layer is responsible for credits management and segmentation (MPS).
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.
1200 extern void otPlatBleL2capOnSduReceived(otInstance * aInstance,
1203 otBleRadioPacket *aPacket);
1206 * The BLE driver calls this method to notify OpenThread that an L2CAP SDU has been sent.
1208 * @param[in] aInstance The OpenThread instance structure.
1211 extern void otPlatBleL2capOnSduSent(otInstance *aInstance);
1214 * Sends an L2CAP Disconnection Request.
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.
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.
1226 otError otPlatBleL2capDisconnect(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid);
1229 * The BLE driver calls this method to notify OpenThread that an L2CAP Disconnection Request has been
1232 * @note Platform layer is responsible to response with L2CAP Disconnection Response internally.
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.
1239 extern void otPlatBleL2capOnDisconnect(otInstance *aInstance, uint16_t aLocalCid, uint16_t aPeerCid);
1247 } // end of extern "C"
1250 #endif // OT_PLATFORM_BLE_H_