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.
otPlatBleGapDisconnect(otInstance *aInstance)
Disconnects BLE connection.
otPlatBleGapOnConnected(otInstance *aInstance, uint16_t aConnectionId)
void
The BLE driver calls this method to notify OpenThread that a BLE Central Device has been connected.
otPlatBleGapOnDisconnected(otInstance *aInstance, uint16_t aConnectionId)
void
The BLE driver calls this method to notify OpenThread that the BLE Central Device has been disconnected.
otPlatBleGattMtuGet(otInstance *aInstance, uint16_t *aMtu)
Reads currently use value of ATT_MTU.
otPlatBleGattOnMtuUpdate(otInstance *aInstance, uint16_t aMtu)
void
The BLE driver calls this method 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 method to notify OpenThread that an ATT Write Request packet has been received.
otPlatBleGetAdvertisementBuffer(otInstance *aInstance, uint8_t **aAdvertisementBuffer)
Gets BLE Advertising buffer.
otPlatBleGetLinkCapabilities(otInstance *aInstance, otBleLinkCapabilities *aBleLinkCapabilities)
void
Function to retrieve from platform BLE link capabilities.
otPlatBleSupportsMultiRadio(otInstance *aInstance)
bool
Function to retrieve from platform multiradio support of BLE and IEEE.

Macros
OT_BLE_ADV_INTERVAL_DEFAULT 100
Default interval for advertising packet (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_MAX 67
Maximum allowed ATT MTU size (must be >= 23).
OT_BLE_DEFAULT_POWER 0
Default power value for BLE.
OT_BLE_TIMESLOT_UNIT 625
Time slot duration on PHY layer in microseconds (0.625ms).
OT_TOBLE_SERVICE_UUID 0xfffb
TOBLE service UUID.

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 TCAT advertisement frame length.
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 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).

Details
Parameters
[in] aInstance
The OpenThread instance structure.
[in] aInterval
The 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.

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

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 method to notify OpenThread that a BLE Central Device has been connected.

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 method to notify OpenThread that the BLE Central Device has been disconnected.

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 use value of ATT_MTU.

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 method to notify OpenThread that ATT_MTU has been updated.

Details
Parameters
[in] aInstance
The OpenThread instance structure.
[in] aMtu
The updated ATT_MTU value.

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 contains 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 method 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 contains value to be written to the attribute.

otPlatBleGetAdvertisementBuffer

otError otPlatBleGetAdvertisementBuffer(
  otInstance *aInstance,
  uint8_t **aAdvertisementBuffer
)

Gets BLE Advertising buffer.

Details
Parameters
[in] aInstance
The OpenThread instance structure.
[in] aAdvertisementData
The formatted TCAT advertisement frame.
[in] aAdvertisementLen
The TCAT advertisement frame length.
Return Values
OT_ERROR_NONE
Advertising procedure has been started.
OT_ERROR_NO_BUFS
No bufferspace available.

otPlatBleGetLinkCapabilities

void otPlatBleGetLinkCapabilities(
  otInstance *aInstance,
  otBleLinkCapabilities *aBleLinkCapabilities
)

Function to retrieve from platform BLE link capabilities.

Details
Parameters
[in] aInstance
The OpenThread instance structure.
[out] aBleLinkCapabilities
The pointer to retrieve the BLE ling capabilities.

otPlatBleSupportsMultiRadio

bool otPlatBleSupportsMultiRadio(
  otInstance *aInstance
)

Function to retrieve from platform multiradio support of BLE and IEEE.

Details
Parameters
[in] aInstance
The OpenThread instance structure.

Macros

OT_BLE_ADV_INTERVAL_DEFAULT

 OT_BLE_ADV_INTERVAL_DEFAULT 100

Default interval for advertising packet (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_MAX

 OT_BLE_ATT_MTU_MAX 67

Maximum allowed ATT MTU size (must be >= 23).

OT_BLE_DEFAULT_POWER

 OT_BLE_DEFAULT_POWER 0

Default power value for BLE.

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.

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.