The BLE specific header file for the RAIL library.

License#

Copyright 2020 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

Modules#

RAIL_BLE_State_t

RAIL_BLE_AoxConfig_t

RAIL_BLE_AoxAntennaPortPins_t

RAIL_BLE_AoxAntennaConfig_t

RAIL_BLE_TxChannelHoppingConfigEntry_t

RAIL_BLE_TxChannelHoppingConfig_t

RAIL_BLE_TxRepeatConfig_t

Macros#

#define

subPhyId indicating a 500kbps packet

#define

subPhyId indicating a 125kbps packet

#define

subPhyId value indicating a 1Mbps packet

#define

Invalid subPhyId value.

#define

subPhyId indicating the total count

#define
RAIL_BLE_EnableSignalIdentifier RAIL_BLE_EnableSignalDetection

Backward compatible name for the RAIL_BLE_EnableSignalDetection API.

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

Enumerations#

enum
RAIL_BLE_Coding_125kbps = 0
RAIL_BLE_Coding_125kbps_DSA = 1
RAIL_BLE_Coding_500kbps = 2
RAIL_BLE_Coding_500kbps_DSA = 3
}

The variant of the BLE Coded PHY.

enum
RAIL_BLE_1Mbps
RAIL_BLE_2Mbps
RAIL_BLE_Coded125kbps
RAIL_BLE_Coded500kbps
}

The variant of the BLE PHY.

enum
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE = 0
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS
}

Available Signal Identifier modes.

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.

Variables#

Default PHY to use for BLE 1M non-Viterbi.

Default PHY to use for BLE 2M non-Viterbi.

Default PHY to use for BLE 1M Viterbi.

Default PHY to use for BLE 2M Viterbi.

PHY to use for BLE 2M with AoX functionality.

Default PHY to use for BLE Coded 125kbps.

Default PHY to use for BLE Coded 500kbps.

Default PHY to use for BLE Simulscan.

Default 1Mbps Quuppa PHY.

Functions#

void
RAIL_BLE_Init(RAIL_Handle_t railHandle)

Configure RAIL to run in BLE mode.

void
RAIL_BLE_Deinit(RAIL_Handle_t railHandle)

Take RAIL out of BLE mode.

bool
RAIL_BLE_IsEnabled(RAIL_Handle_t railHandle)

Determine whether BLE mode is enabled or not.

RAIL_BLE_ConfigPhyQuuppa(RAIL_Handle_t railHandle)

Switch to the 1 Mbps Quuppa PHY.

RAIL_BLE_ConfigPhy1MbpsViterbi(RAIL_Handle_t railHandle)

Switch to the Viterbi 1 Mbps BLE PHY.

RAIL_BLE_ConfigPhy1Mbps(RAIL_Handle_t railHandle)

Switch to the legacy non-Viterbi 1 Mbps BLE PHY.

RAIL_BLE_ConfigPhy2MbpsViterbi(RAIL_Handle_t railHandle)

Switch to the Viterbi 2 Mbps BLE PHY.

RAIL_BLE_ConfigPhy2Mbps(RAIL_Handle_t railHandle)

Switch to the legacy non-Viterbi 2 Mbps BLE PHY.

RAIL_BLE_ConfigPhyCoded(RAIL_Handle_t railHandle, RAIL_BLE_Coding_t bleCoding)

Switch to the BLE Coded PHY.

RAIL_BLE_ConfigPhySimulscan(RAIL_Handle_t railHandle)

Switch to the Simulscan PHY.

RAIL_BLE_ConfigChannelRadioParams(RAIL_Handle_t railHandle, uint32_t crcInit, uint32_t accessAddress, uint16_t channel, bool disableWhitening)

Change BLE radio parameters.

RAIL_BLE_PhySwitchToRx(RAIL_Handle_t railHandle, RAIL_BLE_Phy_t phy, uint16_t railChannel, uint32_t startRxTime, uint32_t crcInit, uint32_t accessAddress, uint16_t logicalChannel, bool disableWhitening)

Change the current BLE PHY and go into receive.

RAIL_BLE_ConfigSignalIdentifier(RAIL_Handle_t railHandle, RAIL_BLE_SignalIdentifierMode_t signalIdentifierMode)

Configure and enable signal identifier for BLE signal detection.

RAIL_BLE_EnableSignalDetection(RAIL_Handle_t railHandle, bool enable)

Enable or disable signal identifier interrupt for BLE signal detection.

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.

RAIL_BLE_SetNextTxRepeat(RAIL_Handle_t railHandle, const RAIL_BLE_TxRepeatConfig_t *repeatConfig)

Set up automatic repeated transmits after the next transmit.

RAIL_BLE_CalibrateIr(RAIL_Handle_t railHandle, uint32_t *imageRejection)

Calibrate image rejection for Bluetooth Low Energy.

Macro Definition Documentation#

RAIL_BLE_RX_SUBPHY_ID_500K#

#define RAIL_BLE_RX_SUBPHY_ID_500K
Value:
(0U)

subPhyId indicating a 500kbps packet


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

RAIL_BLE_RX_SUBPHY_ID_125K#

#define RAIL_BLE_RX_SUBPHY_ID_125K
Value:
(1U)

subPhyId indicating a 125kbps packet


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

RAIL_BLE_RX_SUBPHY_ID_1M#

#define RAIL_BLE_RX_SUBPHY_ID_1M
Value:
(2U)

subPhyId value indicating a 1Mbps packet


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

RAIL_BLE_RX_SUBPHY_ID_INVALID#

#define RAIL_BLE_RX_SUBPHY_ID_INVALID
Value:
(3U)

Invalid subPhyId value.


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

RAIL_BLE_RX_SUBPHY_COUNT#

#define RAIL_BLE_RX_SUBPHY_COUNT
Value:
(4U)

subPhyId indicating the total count


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

RAIL_BLE_EnableSignalIdentifier#

#define RAIL_BLE_EnableSignalIdentifier
Value:
RAIL_BLE_EnableSignalDetection

Backward compatible name for the RAIL_BLE_EnableSignalDetection API.


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

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 629 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 649 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 653 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 657 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 661 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 666 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 670 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 674 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 678 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 682 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 686 of file protocol/ble/rail_ble.h

Enumeration Documentation#

RAIL_BLE_Coding_t#

RAIL_BLE_Coding_t

The variant of the BLE Coded PHY.

Enumerator
RAIL_BLE_Coding_125kbps

Enables the 125 kbps variant of the BLE Coded PHY.

RAIL_BLE_Coding_125kbps_DSA

DeprecatedWill be removed in a future version of RAIL

RAIL_BLE_Coding_500kbps

Enables the 500 kbps variant of the BLE Coded PHY.

RAIL_BLE_Coding_500kbps_DSA

DeprecatedWill be removed in a future version of RAIL


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

RAIL_BLE_Phy_t#

RAIL_BLE_Phy_t

The variant of the BLE PHY.

Enumerator
RAIL_BLE_1Mbps

Use the standard BLE 1Mbps PHY.

RAIL_BLE_2Mbps

Use the high data rate BLE 2Mbps PHY.

RAIL_BLE_Coded125kbps

Enables the 125 kbps variant of the BLE Coded PHY.

RAIL_BLE_Coded500kbps

Enables the 500 kbps variant of the BLE Coded PHY.


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

RAIL_BLE_SignalIdentifierMode_t#

RAIL_BLE_SignalIdentifierMode_t

Available Signal Identifier modes.

Enumerator
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS
RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS

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

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 635 of file protocol/ble/rail_ble.h

Variable Documentation#

RAIL_BLE_Phy1Mbps#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy1Mbps

Default PHY to use for BLE 1M non-Viterbi.

Will be NULL if RAIL_BLE_SUPPORTS_1MBPS_NON_VITERBI is 0.


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

RAIL_BLE_Phy2Mbps#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy2Mbps

Default PHY to use for BLE 2M non-Viterbi.

Will be NULL if RAIL_BLE_SUPPORTS_2MBPS_NON_VITERBI is 0.


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

RAIL_BLE_Phy1MbpsViterbi#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy1MbpsViterbi

Default PHY to use for BLE 1M Viterbi.

Will be NULL if RAIL_BLE_SUPPORTS_1MBPS_VITERBI is 0.


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

RAIL_BLE_Phy2MbpsViterbi#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy2MbpsViterbi

Default PHY to use for BLE 2M Viterbi.

Will be NULL if RAIL_BLE_SUPPORTS_2MBPS_VITERBI is 0.


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

RAIL_BLE_Phy2MbpsAox#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy2MbpsAox

PHY to use for BLE 2M with AoX functionality.

Will be NULL if either RAIL_BLE_SUPPORTS_2MBPS_VITERBI or RAIL_BLE_SUPPORTS_AOX is 0.


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

RAIL_BLE_Phy125kbps#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy125kbps

Default PHY to use for BLE Coded 125kbps.

Will be NULL if RAIL_BLE_SUPPORTS_CODED_PHY is 0. This PHY can receive on both 125kbps and 500kbps BLE Coded, but will only transmit at 125kbps.


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

RAIL_BLE_Phy500kbps#

const RAIL_ChannelConfig_t* const RAIL_BLE_Phy500kbps

Default PHY to use for BLE Coded 500kbps.

Will be NULL if RAIL_BLE_SUPPORTS_CODED_PHY is 0. This PHY can receive on both 125kbps and 500kbps BLE Coded, but will only transmit at 125kbps.


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

RAIL_BLE_PhySimulscan#

const RAIL_ChannelConfig_t* const RAIL_BLE_PhySimulscan

Default PHY to use for BLE Simulscan.

Will be NULL if RAIL_BLE_SUPPORTS_SIMULSCAN_PHY is 0. This PHY can receive on 1Mbps as well as 125kbps and 500kbps BLE Coded, but will only transmit at 1Mbps.


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

RAIL_BLE_PhyQuuppa#

const RAIL_ChannelConfig_t* const RAIL_BLE_PhyQuuppa

Default 1Mbps Quuppa PHY.

Will be NULL if RAIL_BLE_SUPPORTS_QUUPPA is 0.


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

Function Documentation#

RAIL_BLE_Init#

void RAIL_BLE_Init (RAIL_Handle_t railHandle)

Configure RAIL to run in BLE mode.

Parameters
[in]railHandle

A handle for RAIL instance. This function changes your radio, channel configuration, and other parameters to match what is needed for BLE. To switch back to a default RAIL mode, call RAIL_BLE_Deinit() first. This function will configure the protocol output on PTI to RAIL_PTI_PROTOCOL_BLE.

Note

  • BLE may not be enabled while Auto-ACKing is enabled.


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

RAIL_BLE_Deinit#

void RAIL_BLE_Deinit (RAIL_Handle_t railHandle)

Take RAIL out of BLE mode.

Parameters
[in]railHandle

A handle for RAIL instance. This function will undo some of the configuration that happens when you call RAIL_BLE_Init(). After this you can safely run your normal radio initialization code to use a non-BLE configuration. This function does not change back your radio or channel configurations so you must do this by manually reinitializing. This also resets the protocol output on PTI to RAIL_PTI_PROTOCOL_CUSTOM.


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

RAIL_BLE_IsEnabled#

bool RAIL_BLE_IsEnabled (RAIL_Handle_t railHandle)

Determine whether BLE mode is enabled or not.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • True if BLE mode is enabled and false otherwise. This function returns the current status of RAIL's BLE mode. It is enabled by a call to RAIL_BLE_Init() and disabled by a call to RAIL_BLE_Deinit().


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

RAIL_BLE_ConfigPhyQuuppa#

RAIL_Status_t RAIL_BLE_ConfigPhyQuuppa (RAIL_Handle_t railHandle)

Switch to the 1 Mbps Quuppa PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • Status code indicating success of the function call.

You can use this function to switch to the Quuppa PHY.

Note

  • Not all chips support the 1Mbps Quuppa PHY. This API should return RAIL_STATUS_INVALID_CALL if unsupported by the hardware we're building for.


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

RAIL_BLE_ConfigPhy1MbpsViterbi#

RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi (RAIL_Handle_t railHandle)

Switch to the Viterbi 1 Mbps BLE PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the function call.

Use this function to switch back to the default BLE 1 Mbps PHY if you have switched to the 2 Mbps or another configuration. You may only call this function after initializing BLE and while the radio is idle.

Note

  • The EFR32XG1 family does not support BLE Viterbi PHYs. However, calls to this function from that family will be silently redirected to the legacy RAIL_BLE_ConfigPhy1Mbps().


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

RAIL_BLE_ConfigPhy1Mbps#

RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps (RAIL_Handle_t railHandle)

Switch to the legacy non-Viterbi 1 Mbps BLE PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the function call.

Use this function to switch back to the legacy BLE 1 Mbps PHY if you have switched to the 2 Mbps or another configuration. You may only call this function after initializing BLE and while the radio is idle.

Note

  • The EFR32XG2x family does not support BLE non-Viterbi PHYs.


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

RAIL_BLE_ConfigPhy2MbpsViterbi#

RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi (RAIL_Handle_t railHandle)

Switch to the Viterbi 2 Mbps BLE PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the function call.

Use this function to switch back to the BLE 2 Mbps PHY from the default 1 Mbps option. You may only call this function after initializing BLE and while the radio is idle.

Note

  • The EFR32XG1 family does not support BLE Viterbi PHYs.


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

RAIL_BLE_ConfigPhy2Mbps#

RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps (RAIL_Handle_t railHandle)

Switch to the legacy non-Viterbi 2 Mbps BLE PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the function call.

Use this function to switch back to legacy BLE 2Mbps PHY from the default 1 Mbps option. You may only call this function after initializing BLE and while the radio is idle.

Note

  • The EFR32XG1 and EFR32XG2x families do not support BLE non-Viterbi 2 Mbps PHY.


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

RAIL_BLE_ConfigPhyCoded#

RAIL_Status_t RAIL_BLE_ConfigPhyCoded (RAIL_Handle_t railHandle, RAIL_BLE_Coding_t bleCoding)

Switch to the BLE Coded PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

[in]bleCoding

The RAIL_BLE_Coding_t to use

Returns

  • A status code indicating success of the function call.

Use this function to switch back to BLE Coded PHY from the default 1 Mbps option. You may only call this function after initializing BLE and while the radio is idle. When using a BLE Coded PHY, the RAIL_RxPacketDetails_t::subPhyId marks the coding of the received packet. A subPhyId of 0 marks a 500 kbps packet, and a subPhyId of 1 marks a 125 kbps packet.

Note

  • The EFR32XG1, EFR32XG12, and EFR32XG14 families do not support BLE Coded PHYs.


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

RAIL_BLE_ConfigPhySimulscan#

RAIL_Status_t RAIL_BLE_ConfigPhySimulscan (RAIL_Handle_t railHandle)

Switch to the Simulscan PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the function call.

Use this function to switch to the BLE Simulscan PHY. You may only call this function after initializing BLE and while the radio is idle. When using Simulscan PHY, the RAIL_RxPacketDetails_t::subPhyId marks the coding of the received packet. A subPhyId of 0 marks a 500 kbps packet, a subPhyId of 1 marks a 125 kbps packet, and a subPhyId of 2 marks a 1 Mbps packet.

Note


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

RAIL_BLE_ConfigChannelRadioParams#

RAIL_Status_t RAIL_BLE_ConfigChannelRadioParams (RAIL_Handle_t railHandle, uint32_t crcInit, uint32_t accessAddress, uint16_t channel, bool disableWhitening)

Change BLE radio parameters.

Parameters
[in]railHandle

A handle for RAIL instance.

[in]crcInit

The value to use for CRC initialization.

[in]accessAddress

The access address to use for the connection. The bits of this parameter are transmitted or received LSB first.

[in]channel

The logical channel that you're changing to, which initializes the whitener if used.

[in]disableWhitening

This can turn off the whitening engine and is useful for sending BLE test mode packets that don't have this turned on.

Returns

  • A status code indicating success of the function call.

This function can be used to switch radio parameters on every connection and/or channel change. It is BLE-aware and will set the access address, preamble, CRC initialization value, and whitening configuration without requiring you to load a new radio configuration. This function should not be called while the radio is active.


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

RAIL_BLE_PhySwitchToRx#

RAIL_Status_t RAIL_BLE_PhySwitchToRx (RAIL_Handle_t railHandle, RAIL_BLE_Phy_t phy, uint16_t railChannel, uint32_t startRxTime, uint32_t crcInit, uint32_t accessAddress, uint16_t logicalChannel, bool disableWhitening)

Change the current BLE PHY and go into receive.

Parameters
[in]railHandle

A handle for RAIL instance.

[in]phy

Indicates which PHY to receive on

[in]railChannel

Which channel of the given PHY to receive on

[in]startRxTime

When to enter RX

[in]crcInit

The value to use for CRC initialization.

[in]accessAddress

The access address to use for the connection. The bits of this parameter are transmitted or received LSB first.

[in]logicalChannel

The logical channel that you're changing to, which initializes the whitener if used.

[in]disableWhitening

This can turn off the whitening engine and is useful for sending BLE test mode packets that don't have this turned on.

Returns

  • A status code indicating success of the function call.

This function is used to implement auxiliary packet reception, as defined in the BLE specification. The radio will be put into IDLE, the PHY and channel will be changed, and then receive will be entered at the start time given. The new receive will have a timeout of 30 us, which means that this function should only be called if the offset unit is 30 us.

This function is extremely time-sensitive, and may only be called within the interrupt context of a RAIL_EVENT_RX_PACKET_RECEIVED event.


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

RAIL_BLE_ConfigSignalIdentifier#

RAIL_Status_t RAIL_BLE_ConfigSignalIdentifier (RAIL_Handle_t railHandle, RAIL_BLE_SignalIdentifierMode_t signalIdentifierMode)

Configure and enable signal identifier for BLE signal detection.

Parameters
[in]railHandle

A RAIL instance handle.

[in]signalIdentifierMode

Mode of signal identifier operation.

This features allows detection of BLE signal on air based on the mode. This function must be called once before RAIL_BLE_EnableSignalDetection to configure and enable signal identifier.

To enable event for signal detection RAIL_ConfigEvents() must be called for enabling RAIL_EVENT_SIGNAL_DETECTED.

This function is only supported by chips where RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and RAIL_BLE_SupportsSignalIdentifier() are true.

Returns

  • Status code indicating success of the function call.


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

RAIL_BLE_EnableSignalDetection#

RAIL_Status_t RAIL_BLE_EnableSignalDetection (RAIL_Handle_t railHandle, bool enable)

Enable or disable signal identifier interrupt for BLE signal detection.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

Signal detection is enabled if true, disabled if false.

RAIL_BLE_ConfigSignalIdentifier must be called once before calling this function to configure and enable signal identifier. Once a signal is detected signal detection will be turned off and this function should be called to re-enable the signal detection without needing to call RAIL_BLE_ConfigSignalIdentifier if the signal identifier is already configured and enabled.

This function is only supported by chips where RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and RAIL_BLE_SupportsSignalIdentifier() are true.

Returns

  • Status code indicating success of the function call.


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

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 764 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 772 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 781 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 790 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. AoX is supported on EFR32XG12/13/14 only on legacy 1Mbps BLE PHY. 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 809 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 819 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 845 of file protocol/ble/rail_ble.h

RAIL_BLE_SetNextTxRepeat#

RAIL_Status_t RAIL_BLE_SetNextTxRepeat (RAIL_Handle_t railHandle, const RAIL_BLE_TxRepeatConfig_t * repeatConfig)

Set up automatic repeated transmits after the next transmit.

Parameters
[in]railHandle

A RAIL instance handle.

[in]repeatConfig

The configuration structure for repeated transmits.

Returns

  • Status code indicating a success of the function call.

Repeated transmits will occur after an application-initiated transmit caused by calling one of the Packet Transmit APIs. The repetition will only occur after the first application-initiated transmit after this function is called. Future repeated transmits must be requested by calling this function again.

Each repeated transmit that occurs will have full Packet Trace (PTI) information and will receive events such as RAIL_EVENT_TX_PACKET_SENT as normal.

If a TX error occurs during the repetition, the process will abort and the TX error transition from RAIL_SetTxTransitions will be used. If the repetition completes successfully, the TX success transition from RAIL_SetTxTransitions will be used.

Any call to RAIL_Idle or RAIL_StopTx will clear the pending repeated transmits. The state will also be cleared by another call to this function. To clear the repeated transmits before they've started without stopping other radio actions, call this function with a RAIL_BLE_TxRepeatConfig_t::iterations count of 0. A DMP switch will clear this state only if the initial transmit triggering the repeated transmits has started.

The application is responsible for populating the transmit data to be used by the repeated transmits via RAIL_SetTxFifo or RAIL_WriteTxFifo. Data will be transmitted from the TX FIFO. If the TX FIFO does not have sufficient data to transmit, a TX error and a RAIL_EVENT_TX_UNDERFLOW will occur. To avoid an underflow, the application should queue data to be transmitted as early as possible.

This function will fail to configure the repetition if a transmit of any kind is ongoing, including during the time between an initial transmit and the end of a previously-configured repetition.

Note


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

RAIL_BLE_CalibrateIr#

RAIL_Status_t RAIL_BLE_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)

Calibrate image rejection for Bluetooth Low Energy.

Parameters
[in]railHandle

A RAIL instance handle.

[out]imageRejection

The result of the image rejection calibration.

Returns

  • A status code indicating success of the function call.

Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.


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