BLE

This module includes the platform abstraction for BLE Host communication.

Summary

The platform needs to implement Bluetooth LE 4.2 or higher.

Typedefs
otBleLinkCapabilities typedef
Represent BLE link capabilities.
otBleRadioPacket typedef
Represents a BLE packet.

Functions
otPlatBleDisable(otInstance *aInstance)
Disable the Bluetooth Low Energy radio.
otPlatBleEnable(otInstance *aInstance)
Enable the Bluetooth Low Energy radio.
otPlatBleGapAdvSetData(otInstance *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen)
Sets BLE Advertising data.
otPlatBleGapAdvStart(otInstance *aInstance, uint16_t aInterval)
Starts BLE Advertising procedure.
otPlatBleGapAdvStop(otInstance *aInstance)
Stops BLE Advertising procedure.
otPlatBleGapAdvUpdateData(otInstance *aInstance, uint8_t *aAdvertisementData, uint16_t aAdvertisementLen)
Updates BLE Advertising data.
otPlatBleGapDisconnect(otInstance *aInstance)
Disconnects BLE connection.
otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId)
void
The BLE driver calls this function to notify OpenThread that a BLE Central Device has been connected.
otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId)
void
The BLE driver calls this function to notify OpenThread that the BLE Central Device has been disconnected.
otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu)
Reads currently used value of ATT_MTU from the platform BLE driver.
otPlatBleGattOnMtuUpdate(otInstance *aInstance, uint16_t aMtu)
void
The BLE driver calls this function to notify OpenThread that ATT_MTU has been updated.
otPlatBleGattServerIndicate(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket)
Sends ATT Handle Value Indication.
otPlatBleGattServerOnWriteRequest(otInstance *aInstance, uint16_t aHandle, const otBleRadioPacket *aPacket)
void
The BLE driver calls this function to notify OpenThread that an ATT Write Request packet has been received.
otPlatBleGetAdvertisementBuffer(otInstance *aInstance, uint8_t **aAdvertisementBuffer)
Gets a platform-provided buffer for BLE advertising data.
otPlatBleGetLinkCapabilities(otInstance *aInstance, otBleLinkCapabilities *aBleLinkCapabilities)
void
Retrieve BLE link capabilities from the platform.
otPlatBleSupportsMultiRadio(otInstance *aInstance)
bool
Check if the platform has multi-radio support for BLE and IEEE 802.15.4.

Macros
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 0x4000
Maximum allowed interval for advertising packet in OT_BLE_ADV_INTERVAL_UNIT units (10.24s).
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_TIMESLOT_UNIT
Unit used to calculate interval duration (0.625ms).
OT_BLE_ATT_MTU_DEFAULT 23
Default ATT MTU size (used if no MTU indication is given yet, or none can be given).
OT_BLE_ATT_MTU_MAX 67
Maximum allowed ATT MTU size (MUST be >= OT_BLE_ATT_MTU_MIN).
OT_BLE_ATT_MTU_MIN 23
Minimum allowed ATT MTU size (MUST be 23).
OT_BLE_DEFAULT_POWER 0
Default Tx power value for BLE in dBm.
OT_BLE_TIMESLOT_UNIT 625
Time slot duration on PHY layer in microseconds (0.625ms).
OT_TOBLE_SERVICE_UUID 0xfffb
ToBLE service UUID (a GATT service UUID for Thread over BLE)

Structs
otBleLinkCapabilities

Represent BLE link capabilities.

otBleRadioPacket

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.

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.

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.

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() is called or a BLE Central Device connects (otPlatBleGapOnConnected()). The BLE platform is not obliged to exactly match the requested interval between subsequent advertising packets: it is a requested/desired value.

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.

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.

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().

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.

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().

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.

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.

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.

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.

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.

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.

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.

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. For more information, or to contribute to our documentation, refer to Resources.