# BLE

This module includes the platform abstraction for BLE Host communication.

## Summary

The platform needs to implement Bluetooth LE 4.2 or higher.

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga39a02513c548b3541bdb6ef4114df96a` | typedef `struct https://openthread.io/reference/struct/ot-ble-link-capabilities` Represent BLE link capabilities. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga367033ad30272919205cb6dc74c4b494` | typedef `struct https://openthread.io/reference/struct/ot-ble-radio-packet` Represents a BLE packet. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga135bb769e3fd8f7cdd019b302f6599dd(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Disable the Bluetooth Low Energy radio. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga3abd7c25c69291f8d3964fcfbe21bccc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Enable the Bluetooth Low Energy radio. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga18b04026b87eee5f6c1badd04241c812(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets BLE Advertising data. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga36e64024eddd8ed0f961ac28cb8985fe(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aInterval)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts BLE Advertising procedure. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga938000ae35b3fe153cb51c77f466289e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Stops BLE Advertising procedure. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga34bdf8990547efd17a76bb74167c98ae(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Updates BLE Advertising data. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gaa27736376c70a5e7b0e58193bbe2b048(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Disconnects BLE connection. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gadd8119c3729b73540282055ebb663e71(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aConnectionId)` | `void` The BLE driver calls this function to notify OpenThread that a BLE Central Device has been connected. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga260e91c85a0f7fe89584b4d81adc2ec6(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aConnectionId)` | `void` The BLE driver calls this function to notify OpenThread that the BLE Central Device has been disconnected. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga4d5c4514b5cde92c0fc922e97f429b11(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t *aMtu)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Reads currently used value of ATT_MTU from the platform BLE driver. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga4437a1107dab47d7a37f3e03096d3ffe(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aMtu)` | `void` The BLE driver calls this function to notify OpenThread that ATT_MTU has been updated. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga8ccf1f46a90db1321d856e78586348af(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aHandle, const https://openthread.io/reference/struct/ot-ble-radio-packet *aPacket)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends ATT Handle Value Indication. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga3d1533006e515d65400e82dfe00ccc59(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aHandle, const https://openthread.io/reference/struct/ot-ble-radio-packet *aPacket)` | `void` The BLE driver calls this function to notify OpenThread that an ATT Write Request packet has been received. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga1554c0237206ac8c2316431a99cbfc62(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t **aAdvertisementBuffer)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets a platform-provided buffer for BLE advertising data. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga1fd553a4f197adc1655e5f9cba2191b0(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-ble-link-capabilities *aBleLinkCapabilities)` | `void` Retrieve BLE link capabilities from the platform. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga2a59e3394bbea26e0932d38bfc6e84e7(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Check if the platform has multi-radio support for BLE and IEEE 802.15.4. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gad64bc29b57255e277b7f3c3ac17dfea4 160` | Default interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (100 ms). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gaeb80b3a24be9ccbd3430a888990bada7 0x4000` | Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga9f75d1a2236ef3b16f370f149a02f180 0x0020` | Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga7a2fbf80cf639c38e15d4fbcdf117303 OT_BLE_TIMESLOT_UNIT` | Unit used to calculate interval duration (0.625ms). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga1c590a11afdc81e4430f984b7b04bfbc 23` | Default ATT MTU size (used if no MTU indication is given yet, or none can be given). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga77f5e189cf7270853161922a919d7501 67` | Maximum allowed ATT MTU size (MUST be \>= OT_BLE_ATT_MTU_MIN). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gae1fa2b11a8807b50dcb5988e39283197 23` | Minimum allowed ATT MTU size (MUST be 23). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga1bea9587e17005b488cef4aaedfbefb4 0` | Default Tx power value for BLE in dBm. |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gaea9c07055da804720009f526f1cb858d 625` | Time slot duration on PHY layer in microseconds (0.625ms). |
| `https://openthread.io/reference/group/plat-ble#group__plat-ble_1gae10abe14f7765bc0a607c1d178ea596a 0xfffb` | ToBLE service UUID (a GATT service UUID for Thread over BLE) |

| ### Structs ||
|---|---|
| [otBleLinkCapabilities](https://openthread.io/reference/struct/ot-ble-link-capabilities) | Represent BLE link capabilities. |
| [otBleRadioPacket](https://openthread.io/reference/struct/ot-ble-radio-packet) | Represents a BLE packet. |

## Typedefs

### otBleLinkCapabilities

```
struct otBleLinkCapabilities otBleLinkCapabilities
```
Represent BLE link capabilities.

### otBleRadioPacket

```
struct otBleRadioPacket otBleRadioPacket
```
Represents a BLE packet.

## Functions

### otPlatBleDisable

```
otError otPlatBleDisable(
  otInstance *aInstance
)
```
Disable the Bluetooth Low Energy radio.

When disabled, the BLE stack will flush event queues and not generate new events. The BLE peripheral is turned off or put into a low power sleep state. Any dynamic memory used by the stack should be released, but static memory may remain reserved.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully transitioned to disabled. | | `OT_ERROR_FAILED` | The BLE radio could not be disabled. | |

### otPlatBleEnable

```
otError otPlatBleEnable(
  otInstance *aInstance
)
```
Enable the Bluetooth Low Energy radio.


> [!NOTE]
> **Note:** BLE Device should use the highest ATT_MTU supported that does not exceed OT_BLE_ATT_MTU_MAX octets.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully enabled. | | `OT_ERROR_FAILED` | The BLE radio could not be enabled. | |

### otPlatBleGapAdvSetData

```
otError otPlatBleGapAdvSetData(
  otInstance *aInstance,
  uint8_t *aAdvertisementData,
  uint16_t aAdvertisementLen
)
```
Sets BLE Advertising data.


> [!NOTE]
> **Note:** This function shall be used only for BLE Peripheral role. It shall only be called while advertising is not active.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aAdvertisementData` | The formatted TCAT advertisement frame. | | `[in] aAdvertisementLen` | The length of the `aAdvertisementData` frame. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Advertising data set successfully. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | | `OT_ERROR_FAILED` | Setting of data failed. | | `OT_ERROR_INVALID_ARGS` | Invalid value has been supplied. | |

### otPlatBleGapAdvStart

```
otError otPlatBleGapAdvStart(
  otInstance *aInstance,
  uint16_t aInterval
)
```
Starts BLE Advertising procedure.

The BLE device shall use undirected advertising with no filter applied. A single BLE Advertising packet must be sent on all advertising channels (37, 38 and 39). The advertising shall remain active until either [otPlatBleGapAdvStop()](https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga938000ae35b3fe153cb51c77f466289e) is called or a BLE Central Device connects ([otPlatBleGapOnConnected()](https://openthread.io/reference/group/plat-ble#group__plat-ble_1gadd8119c3729b73540282055ebb663e71)). The BLE platform is not obliged to exactly match the requested interval between subsequent advertising packets: it is a requested/desired value.


> [!NOTE]
> **Note:** This function shall be used only for BLE Peripheral role.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aInterval` | The requested interval between subsequent advertising packets in OT_BLE_ADV_INTERVAL_UNIT units. Shall be within OT_BLE_ADV_INTERVAL_MIN and OT_BLE_ADV_INTERVAL_MAX range or OT_BLE_ADV_INTERVAL_DEFAULT for a default value set at compile time. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Advertising procedure has been started. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | | `OT_ERROR_INVALID_ARGS` | Invalid interval value has been supplied. | |

### otPlatBleGapAdvStop

```
otError otPlatBleGapAdvStop(
  otInstance *aInstance
)
```
Stops BLE Advertising procedure.


> [!NOTE]
> **Note:** This function shall be used only for BLE Peripheral role.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Advertising procedure has been stopped. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | |

### otPlatBleGapAdvUpdateData

```
otError otPlatBleGapAdvUpdateData(
  otInstance *aInstance,
  uint8_t *aAdvertisementData,
  uint16_t aAdvertisementLen
)
```
Updates BLE Advertising data.


> [!NOTE]
> **Note:** This function shall be used only for BLE Peripheral role. It shall only be called while advertising is active.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aAdvertisementData` | The formatted TCAT advertisement frame. | | `[in] aAdvertisementLen` | The length of the `aAdvertisementData` frame. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Advertising data updated successfully. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | | `OT_ERROR_FAILED` | Update of data failed. | | `OT_ERROR_INVALID_ARGS` | Invalid value has been supplied. | |

### otPlatBleGapDisconnect

```
otError otPlatBleGapDisconnect(
  otInstance *aInstance
)
```
Disconnects BLE connection.

The BLE device shall use the Remote User Terminated Connection (0x13) reason code when disconnecting from the peer BLE device.

This function only triggers the disconnection procedure. When OT_ERROR_NONE is returned, the platform MUST report completion of the disconnection asynchronously, by invoking [otPlatBleGapOnDisconnected()](https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga260e91c85a0f7fe89584b4d81adc2ec6).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Disconnection procedure has been started. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | |

### otPlatBleGapOnConnected

```
void otPlatBleGapOnConnected(
  otInstance *aInstance,
  uint16_t aConnectionId
)
```
The BLE driver calls this function to notify OpenThread that a BLE Central Device has been connected.

The BLE driver MUST stop advertising before calling this function.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aConnectionId` | The identifier of the open connection. | |

### otPlatBleGapOnDisconnected

```
void otPlatBleGapOnDisconnected(
  otInstance *aInstance,
  uint16_t aConnectionId
)
```
The BLE driver calls this function to notify OpenThread that the BLE Central Device has been disconnected.

The BLE driver MUST NOT start advertising before or after this call: this is controlled explicitly via [otPlatBleGapAdvStart()](https://openthread.io/reference/group/plat-ble#group__plat-ble_1ga36e64024eddd8ed0f961ac28cb8985fe).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aConnectionId` | The identifier of the closed connection. | |

### otPlatBleGattMtuGet

```
otError otPlatBleGattMtuGet(
  otInstance *aInstance,
  uint16_t *aMtu
)
```
Reads currently used value of ATT_MTU from the platform BLE driver.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[out] aMtu` | A pointer to output the current ATT_MTU value. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | ATT_MTU value has been placed in `aMtu`. | | `OT_ERROR_FAILED` | BLE Device cannot determine its ATT_MTU. | |

### otPlatBleGattOnMtuUpdate

```
void otPlatBleGattOnMtuUpdate(
  otInstance *aInstance,
  uint16_t aMtu
)
```
The BLE driver calls this function to notify OpenThread that ATT_MTU has been updated.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aMtu` | The updated ATT_MTU value. It MUST be \>=OT_BLE_ATT_MTU_MIN. | |

### otPlatBleGattServerIndicate

```
otError otPlatBleGattServerIndicate(
  otInstance *aInstance,
  uint16_t aHandle,
  const otBleRadioPacket *aPacket
)
```
Sends ATT Handle Value Indication.


> [!NOTE]
> **Note:** This function shall be used only for GATT Server.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aHandle` | The handle of the attribute to be indicated. | | `[in] aPacket` | A pointer to the packet containing the value to be indicated. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | ATT Handle Value Indication has been sent. | | `OT_ERROR_INVALID_STATE` | BLE Device is in invalid state. | | `OT_ERROR_INVALID_ARGS` | Invalid handle value, data or data length has been supplied. | | `OT_ERROR_NO_BUFS` | No available internal buffer found. | |

### otPlatBleGattServerOnWriteRequest

```
void otPlatBleGattServerOnWriteRequest(
  otInstance *aInstance,
  uint16_t aHandle,
  const otBleRadioPacket *aPacket
)
```
The BLE driver calls this function to notify OpenThread that an ATT Write Request packet has been received.


> [!NOTE]
> **Note:** This function shall be used only for GATT Server.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[in] aHandle` | The handle of the attribute to be written. | | `[in] aPacket` | A pointer to the packet containing the value to be written to the attribute. | |

### otPlatBleGetAdvertisementBuffer

```
otError otPlatBleGetAdvertisementBuffer(
  otInstance *aInstance,
  uint8_t **aAdvertisementBuffer
)
```
Gets a platform-provided buffer for BLE advertising data.


> [!NOTE]
> **Note:** This function shall be used only for BLE Peripheral role. The platform must provide a buffer of at least `OT_TCAT_ADVERTISEMENT_MAX_LEN` bytes.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[out] aAdvertisementBuffer` | A pointer to be set to the platform-provided advertisement buffer. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the advertisement buffer. | | `OT_ERROR_NO_BUFS` | No buffer space available. | |

### otPlatBleGetLinkCapabilities

```
void otPlatBleGetLinkCapabilities(
  otInstance *aInstance,
  otBleLinkCapabilities *aBleLinkCapabilities
)
```
Retrieve BLE link capabilities from the platform.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | | `[out] aBleLinkCapabilities` | The pointer to retrieve the BLE link capabilities into. | |

### otPlatBleSupportsMultiRadio

```
bool otPlatBleSupportsMultiRadio(
  otInstance *aInstance
)
```
Check if the platform has multi-radio support for BLE and IEEE 802.15.4.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance structure. | |
| **Returns** | TRUE if the platform supports simultaneous BLE and IEEE 802.15.4 operation, FALSE otherwise. |

## Macros

### OT_BLE_ADV_INTERVAL_DEFAULT

```
 OT_BLE_ADV_INTERVAL_DEFAULT 160
```
Default interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (100 ms).

### OT_BLE_ADV_INTERVAL_MAX

```
 OT_BLE_ADV_INTERVAL_MAX 0x4000
```
Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s).

### OT_BLE_ADV_INTERVAL_MIN

```
 OT_BLE_ADV_INTERVAL_MIN 0x0020
```
Minimum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (20ms).

### OT_BLE_ADV_INTERVAL_UNIT

```
 OT_BLE_ADV_INTERVAL_UNIT OT_BLE_TIMESLOT_UNIT
```
Unit used to calculate interval duration (0.625ms).

### OT_BLE_ATT_MTU_DEFAULT

```
 OT_BLE_ATT_MTU_DEFAULT 23
```
Default ATT MTU size (used if no MTU indication is given yet, or none can be given).

It MUST be 23.

### OT_BLE_ATT_MTU_MAX

```
 OT_BLE_ATT_MTU_MAX 67
```
Maximum allowed ATT MTU size (MUST be \>= OT_BLE_ATT_MTU_MIN).

### OT_BLE_ATT_MTU_MIN

```
 OT_BLE_ATT_MTU_MIN 23
```
Minimum allowed ATT MTU size (MUST be 23).

### OT_BLE_DEFAULT_POWER

```
 OT_BLE_DEFAULT_POWER 0
```
Default Tx power value for BLE in dBm.

### OT_BLE_TIMESLOT_UNIT

```
 OT_BLE_TIMESLOT_UNIT 625
```
Time slot duration on PHY layer in microseconds (0.625ms).

### OT_TOBLE_SERVICE_UUID

```
 OT_TOBLE_SERVICE_UUID 0xfffb
```
ToBLE service UUID (a GATT service UUID for Thread over BLE)

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).