Accelerator routines for Bluetooth Low Energy (BLE).

Data Structures

struct  RAIL_BLE_State_t
 State structure for BLE.

Enumerations

enum  RAIL_BLE_Coding_t {
  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.

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_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi (RAIL_Handle_t railHandle)
 Switch the Viterbi 1Mbps BLE PHY.
 
RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps (RAIL_Handle_t railHandle)
 Switch the legacy non-Viterbi 1Mbps BLE PHY.
 
RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi (RAIL_Handle_t railHandle)
 Switch the Viterbi 2Mbps BLE PHY.
 
RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps (RAIL_Handle_t railHandle)
 Switch the legacy non-Viterbi 2Mbps BLE PHY.
 
RAIL_Status_t RAIL_BLE_ConfigPhyCoded (RAIL_Handle_t railHandle, RAIL_BLE_Coding_t bleCoding)
 Switch to the BLE Coded PHY.
 
RAIL_Status_t RAIL_BLE_ConfigChannelRadioParams (RAIL_Handle_t railHandle, uint32_t crcInit, uint32_t accessAddress, uint16_t channel, bool disableWhitening)
 Helper function to change BLE radio parameters.

Detailed Description

Accelerator routines for Bluetooth Low Energy (BLE).

The APIs in this module help take care of configuring the radio for BLE operation and provide some additional helper routines necessary for normal BLE send/receive that aren't available directly in RAIL. All normal RAIL APIs should be used to setup the application; however, RAIL_ConfigChannels() and RAIL_ConfigRadio() should not be called to setup the PHY. Instead, the RAIL_BLE_Config* APIs should be used to setup the 1Mbps, 2Mbps, or Coded PHY configuration needed by the application. These APIs will configure the hardware and also configure the set of valid BLE channels.

To implement a standard BLE link layer you will also need to handle tight turnaround times and send packets at specific instants. This can all be managed through general RAIL functions like RAIL_ScheduleTx(), RAIL_ScheduleRx(), and RAIL_SetStateTiming(). See the full RAIL API for more useful functions.

A simple example of how to setup your application to be in BLE mode is shown below. Note that this will put the radio on the first advertising channel with the advertising Access Address. In any full featured BLE application you will need to use the RAIL_BLE_ConfigChannelRadioParams() function to change the sync word and other parameters as needed based on your connection.

// RAIL Handle set at init time
static RAIL_Handle_t railHandle = NULL;
// Put the radio into receive on the first BLE advertising channel
int bleAdvertiseEnable(void)
{
// Call the BLE initialization function to load the right radio config
RAIL_BLE_Init(railHandle);
// Always choose the Viterbi PHY configuration if available on your chip
// for performance reasons.
// Configure us for the first advertising channel (Physical: 0, Logical: 37)
// The CRC init value and Access Address come from the BLE specification.
0x555555,
0x8E89BED6,
37,
false);
// Start receiving on physical channel 0 (logical channel 37)
RAIL_StartRx(railHandle, 0, NULL);
}

Function Documentation

◆ RAIL_BLE_ConfigChannelRadioParams()

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

Helper function to change BLE radio parameters.

Parameters
[in]railHandleHandle for RAIL instance.
[in]crcInitThe value to use for CRC initialization.
[in]accessAddressThe access address to use for the connection.
[in]channelThe logical channel that you're changing to. This is used to initialize the whitener if you're using whitening.
[in]disableWhiteningThis can turn off the whitening engine and is useful for sending BLE test mode packets that don't have this turned on.
Returns
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 config.

◆ RAIL_BLE_ConfigPhy1Mbps()

RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps ( RAIL_Handle_t  railHandle)

Switch the legacy non-Viterbi 1Mbps BLE PHY.

Parameters
[in]railHandleHandle for RAIL instance.
Returns
Status code indicating success of the function call.

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

◆ RAIL_BLE_ConfigPhy1MbpsViterbi()

RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi ( RAIL_Handle_t  railHandle)

Switch the Viterbi 1Mbps BLE PHY.

Parameters
[in]railHandleHandle for RAIL instance.
Returns
Status code indicating success of the function call.

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

◆ RAIL_BLE_ConfigPhy2Mbps()

RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps ( RAIL_Handle_t  railHandle)

Switch the legacy non-Viterbi 2Mbps BLE PHY.

Parameters
[in]railHandleHandle for RAIL instance.
Returns
Status code indicating success of the function call.

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

Note
Not all chips support the 2Mbps PHY. Consult your part's reference manual to be sure that it does before trying this.

◆ RAIL_BLE_ConfigPhy2MbpsViterbi()

RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi ( RAIL_Handle_t  railHandle)

Switch the Viterbi 2Mbps BLE PHY.

Parameters
[in]railHandleHandle for RAIL instance.
Returns
Status code indicating success of the function call.

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

Note
Not all chips support the 2Mbps PHY. Consult your part's reference manual to be sure that it does before trying this.

◆ 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]railHandleHandle for RAIL instance.
[in]bleCodingThe RAIL_BLE_Coding_t to use
Returns
Status code indicating success of the function call.

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

Note
Not all chips support the BLE Coded PHY. Consult your part's reference manual to be sure that it does before trying this.

◆ RAIL_BLE_Deinit()

void RAIL_BLE_Deinit ( RAIL_Handle_t  railHandle)

Take RAIL out of BLE mode.

Parameters
[in]railHandleHandle 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 will 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.

◆ RAIL_BLE_Init()

void RAIL_BLE_Init ( RAIL_Handle_t  railHandle)

Configure RAIL to run in BLE mode.

Parameters
[in]railHandleHandle for RAIL instance. This function will change your radio and channel configuration and other parameters to match what is needed for BLE. If you need to switch back to a default RAIL mode then you must call RAIL_BLE_Deinit() first. This function will configure the protocol output on PTI to RAIL_PTI_PROTOCOL_BLE.

◆ RAIL_BLE_IsEnabled()

bool RAIL_BLE_IsEnabled ( RAIL_Handle_t  railHandle)

Determine whether BLE mode is enabled or not.

Parameters
[in]railHandleHandle 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().