Angle of Arrival/Departure#

These APIs are to a stack implementing BLE's angle of arrival and angle of departure functionality.

They are designed for use by the Silicon Labs BLE stack only at this time and may cause problems if accessed directly.

Modules#

RAIL_BLE_AoxConfig_t

RAIL_BLE_AoxAntennaPortPins_t

RAIL_BLE_AoxAntennaConfig_t

Enumerations#

enum
RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT = 0
RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT = 1
RAIL_BLE_AOX_OPTIONS_CONN_SHIFT = 2
RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT = 3
}

Angle of Arrival/Departure options bit fields.

Functions#

bool
RAIL_BLE_LockCteBuffer(RAIL_Handle_t railHandle, bool lock)

Lock/unlock the CTE buffer from the application's perspective.

bool
RAIL_BLE_CteBufferIsLocked(RAIL_Handle_t railHandle)

Determine whether the CTE buffer is currently locked or not.

uint8_t
RAIL_BLE_GetCteSampleOffset(RAIL_Handle_t railHandle)

Get the offset into CTE sample of CTE data.

uint32_t
RAIL_BLE_GetCteSampleRate(RAIL_Handle_t railHandle)

Get the effective sample rate used by the ADC to capture the CTE samples.

RAIL_BLE_ConfigAox(RAIL_Handle_t railHandle, const RAIL_BLE_AoxConfig_t *aoxConfig)

Configure Angle of Arrival/Departure (AoX) functionality.

RAIL_BLE_InitCte(RAIL_Handle_t railHandle)

Perform one time initialization of AoX registers.

RAIL_BLE_ConfigAoxAntenna(RAIL_Handle_t railHandle, RAIL_BLE_AoxAntennaConfig_t *antennaConfig)

Perform initialization of AoX antenna GPIO pins.

Macros#

#define

The maximum number of GPIO pins used for AoX Antenna switching.

#define
RAIL_BLE_AOX_OPTIONS_LOCK_CTE_BUFFER_SHIFT RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT
#define

Disable the AoX feature.

#define
RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE (1U << RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT)

Sets one of the two AoX sampling/switching modes: 1 us or 2 us window.

#define
RAIL_BLE_AOX_OPTIONS_CONNLESS (1U << RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT)

Enables connectionless AoX Rx packets.

#define
RAIL_BLE_AOX_OPTIONS_CONN (1U << RAIL_BLE_AOX_OPTIONS_CONN_SHIFT)

Enables connection based AoX Rx packets.

#define
RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK (1U << RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT)

Disables CTE buffer lock.

#define
RAIL_BLE_AOX_OPTIONS_ENABLED (RAIL_BLE_AOX_OPTIONS_CONN | RAIL_BLE_AOX_OPTIONS_CONNLESS)

Enables connection based or connectionless AoX Rx packets.

Enumeration Documentation#

RAIL_BLE_AoxOptions_t#

RAIL_BLE_AoxOptions_t

Angle of Arrival/Departure options bit fields.

Enumerator
RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT

Shift position of RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE bit.

RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT

Shift position of RAIL_BLE_AOX_OPTIONS_CONNLESS bit.

RAIL_BLE_AOX_OPTIONS_CONN_SHIFT

Shift position of RAIL_BLE_AOX_OPTIONS_CONN bit.

RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT

Shift position of RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK bit.


Definition at line 631 of file protocol/ble/rail_ble.h

Function Documentation#

RAIL_BLE_LockCteBuffer#

bool RAIL_BLE_LockCteBuffer (RAIL_Handle_t railHandle, bool lock)

Lock/unlock the CTE buffer from the application's perspective.

Parameters
[in]railHandle

A RAIL instance handle.

[in]lock

Lock the CTE buffer if true and unlock it if false.

The radio will write to the buffer only if the bit is NOT set at the beginning of the sampling period. The radio will set the bit once the sampling period starts to indicate that some CTE data has been collected, which will not be overwritten during the next sampling period, unless the buffer is unlocked by the application.

Returns

  • true if the CTE buffer is locked after the call, otherwise false.


Definition at line 760 of file protocol/ble/rail_ble.h

RAIL_BLE_CteBufferIsLocked#

bool RAIL_BLE_CteBufferIsLocked (RAIL_Handle_t railHandle)

Determine whether the CTE buffer is currently locked or not.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • true if CTE buffer is locked and false otherwise.


Definition at line 768 of file protocol/ble/rail_ble.h

RAIL_BLE_GetCteSampleOffset#

uint8_t RAIL_BLE_GetCteSampleOffset (RAIL_Handle_t railHandle)

Get the offset into CTE sample of CTE data.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • The offset of CTE data in a CTE sample in bytes. On unsupported platforms this returns 0.


Definition at line 777 of file protocol/ble/rail_ble.h

RAIL_BLE_GetCteSampleRate#

uint32_t RAIL_BLE_GetCteSampleRate (RAIL_Handle_t railHandle)

Get the effective sample rate used by the ADC to capture the CTE samples.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • The actual sample rate used to capture the CTE in samples per second. On unsupported platforms this returns 0.


Definition at line 786 of file protocol/ble/rail_ble.h

RAIL_BLE_ConfigAox#

RAIL_Status_t RAIL_BLE_ConfigAox (RAIL_Handle_t railHandle, const RAIL_BLE_AoxConfig_t *aoxConfig)

Configure Angle of Arrival/Departure (AoX) functionality.

Parameters
[in]railHandle

A RAIL instance handle.

[in]aoxConfig

Configuration options for AoX

AoX is a method of radio localization which infers angle of arrival/departure of the signal based on different phases of the raw I/Q signal from different antennas by controlling external RF switch during the continuous tone extension (CTE). Connection based AoX packets are different than normal BLE packets in that they have 3 header bytes instead of 2 and they have CTE appended after the payload's CRC. 3rd byte or CTE info contains CTE length. Connectionless AoX packets have 2 header bytes and CTE info is part of the payload. Note that calling RAIL_GetRadioEntropy during AoX reception may break receiving packets.

Returns

  • RAIL_Status_t indicating success or failure of the call.


Definition at line 804 of file protocol/ble/rail_ble.h

RAIL_BLE_InitCte#

RAIL_Status_t RAIL_BLE_InitCte (RAIL_Handle_t railHandle)

Perform one time initialization of AoX registers.

Parameters
[in]railHandle

A RAIL instance handle.

This function must be called before RAIL_BLE_ConfigAox and before configuring the BLE PHY.

Returns

  • RAIL_Status_t indicating success or failure of the call.


Definition at line 814 of file protocol/ble/rail_ble.h

RAIL_BLE_ConfigAoxAntenna#

RAIL_Status_t RAIL_BLE_ConfigAoxAntenna (RAIL_Handle_t railHandle, RAIL_BLE_AoxAntennaConfig_t *antennaConfig)

Perform initialization of AoX antenna GPIO pins.

Parameters
[in]railHandle

A RAIL instance handle.

[in]antennaConfig

structure to hold the set of ports and pins to configure Antenna pins for AoX Antenna switching.

This function must be called before calls to RAIL_BLE_InitCte and RAIL_BLE_ConfigAox, and before configuring the BLE PHY, else a RAIL_STATUS_INVALID_CALL is returned.

If user configures more pins, i.e., antCount in RAIL_BLE_AoxAntennaConfig_t, than allowed RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then the API returns RAIL_STATUS_INVALID_PARAMETER.

If user configures lesser than or equal to number of pins allowed by RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then the requested number of pins are configured and RAIL_STATUS_NO_ERROR is returned.

If AoX antenna switching is inactive, non-AoX transmits and receives will occur on the first antenna specified by the antenna pattern or on the default antenna if no antenna pattern is provided.

Returns

  • RAIL_Status_t indicating success or failure of the call.


Definition at line 840 of file protocol/ble/rail_ble.h

Macro Definition Documentation#

RAIL_BLE_AOX_ANTENNA_PIN_COUNT#

#define RAIL_BLE_AOX_ANTENNA_PIN_COUNT
Value:
(6U)

The maximum number of GPIO pins used for AoX Antenna switching.

If the user configures more pins using RAIL_BLE_ConfigAoxAntenna than allowed RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then RAIL_STATUS_INVALID_PARAMETER status will be returned.

RAIL_STATUS_INVALID_CALL is returned if : RAIL_BLE_AOX_ANTENNA_PIN_COUNT is set to 0 or The user configures no pins.

The maximum value RAIL_BLE_AOX_ANTENNA_PIN_COUNT can take depends on number of Antenna route pins , a chip provides. For EFR32XG22, the maximum value of RAIL_BLE_AOX_ANTENNA_PIN_COUNT is 6. If the user configures fewer pins than RAIL_BLE_AOX_ANTENNA_PIN_COUNT, then only number of pins asked by user will be configured with RAIL_STATUS_NO_ERROR.


Definition at line 625 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_DO_SWITCH#

#define RAIL_BLE_AOX_OPTIONS_DO_SWITCH
Value:
(0U)

DeprecatedObsolete AOX option


Definition at line 645 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_TX_ENABLED#

#define RAIL_BLE_AOX_OPTIONS_TX_ENABLED
Value:
(0U)

DeprecatedObsolete AOX option


Definition at line 649 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_RX_ENABLED#

#define RAIL_BLE_AOX_OPTIONS_RX_ENABLED
Value:
(0U)

DeprecatedObsolete AOX option


Definition at line 653 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_LOCK_CTE_BUFFER_SHIFT#

#define RAIL_BLE_AOX_OPTIONS_LOCK_CTE_BUFFER_SHIFT
Value:
RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT

DeprecatedPlease use RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT instead.


Definition at line 657 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_DISABLED#

#define RAIL_BLE_AOX_OPTIONS_DISABLED
Value:
(0U)

Disable the AoX feature.


Definition at line 662 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE#

#define RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE
Value:
(1U << RAIL_BLE_AOX_OPTIONS_SAMPLE_MODE_SHIFT)

Sets one of the two AoX sampling/switching modes: 1 us or 2 us window.


Definition at line 666 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_CONNLESS#

#define RAIL_BLE_AOX_OPTIONS_CONNLESS
Value:
(1U << RAIL_BLE_AOX_OPTIONS_CONNLESS_SHIFT)

Enables connectionless AoX Rx packets.


Definition at line 670 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_CONN#

#define RAIL_BLE_AOX_OPTIONS_CONN
Value:
(1U << RAIL_BLE_AOX_OPTIONS_CONN_SHIFT)

Enables connection based AoX Rx packets.


Definition at line 674 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK#

#define RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK
Value:
(1U << RAIL_BLE_AOX_OPTIONS_DISABLE_BUFFER_LOCK_SHIFT)

Disables CTE buffer lock.


Definition at line 678 of file protocol/ble/rail_ble.h

RAIL_BLE_AOX_OPTIONS_ENABLED#

#define RAIL_BLE_AOX_OPTIONS_ENABLED
Value:
(RAIL_BLE_AOX_OPTIONS_CONN | RAIL_BLE_AOX_OPTIONS_CONNLESS)

Enables connection based or connectionless AoX Rx packets.


Definition at line 682 of file protocol/ble/rail_ble.h