BLE#
Accelerator routines for Bluetooth Low Energy (BLE).
The APIs in this module configure the radio for BLE operation and provide additional helper routines necessary for normal BLE send/receive that aren't available directly in RAIL. RAIL APIs should be used to set up the application. However, RAIL_ConfigChannels() and RAIL_ConfigRadio() should not be called to set up the PHY. Instead, RAIL_BLE_Config* APIs should be used to set up the 1 Mbps, 2 Mbps, or Coded PHY configurations 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, such as RAIL_StartScheduledTx(), RAIL_ScheduleRx(), and RAIL_SetStateTiming(). See RAIL APIs for more useful functions.
A simple example to set up the 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 initialization time.
static RAIL_Handle_t gRailHandle = NULL;
static void radioEventHandler(RAIL_Handle_t railHandle,
RAIL_Events_t events)
{
// ... handle RAIL events, e.g., receive and transmit completion
}
// Set the radio to receive on the first BLE advertising channel.
void bleAdvertiseEnable(void)
{
RAIL_Config_t railCfg = {
.eventsCallback = &radioEventHandler,
};
// Initializes the RAIL library and any internal state it requires.
gRailHandle = RAIL_Init(&railCfg, NULL);
// Calls the BLE initialization function to load the right radio configuration.
RAIL_BLE_Init(gRailHandle);
// Always choose the Viterbi PHY configuration if available on your chip
// for performance reasons.
RAIL_BLE_ConfigPhy1MbpsViterbi(gRailHandle);
// Configures us for the first advertising channel (Physical: 0, Logical: 37).
// The CRC init value and Access Address come from the BLE specification.
RAIL_BLE_ConfigChannelRadioParams(gRailHandle,
0x555555,
0x8E89BED6,
37,
false);
// Starts receiving on physical channel 0 (logical channel 37).
RAIL_StartRx(gRailHandle, 0, NULL);
}
Modules#
Enumerations#
The variant of the BLE Coded PHY.
The variant of the BLE PHY.
Available Signal Identifier modes.
Functions#
Configure RAIL to run in BLE mode.
Take RAIL out of BLE mode.
Determine whether BLE mode is enabled or not.
Switch to the 1 Mbps Quuppa PHY.
Switch to the Viterbi 1 Mbps BLE PHY.
Switch to the legacy non-Viterbi 1 Mbps BLE PHY.
Switch to the Viterbi 2 Mbps BLE PHY.
Switch to the legacy non-Viterbi 2 Mbps BLE PHY.
Switch to the BLE Coded PHY.
Switch to the Simulscan PHY.
Change BLE radio parameters.
Change the current BLE PHY and go into receive.
Configure and enable signal identifier for BLE signal detection.
Enable or disable signal identifier interrupt for BLE signal detection.
Macros#
RAIL_RxPacketDetails_t::subPhyId indicating a 500 kbps packet.
RAIL_RxPacketDetails_t::subPhyId indicating a 125 kbps packet.
RAIL_RxPacketDetails_t::subPhyId value indicating a 1 Mbps packet.
RAIL_RxPacketDetails_t::subPhyId invalid value.
The total count of BLE subPhyId's.
Backward compatible name for the RAIL_BLE_EnableSignalDetection API.
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. |
116 of file protocol/ble/rail_ble.hRAIL_BLE_Phy_t#
RAIL_BLE_Phy_t
The variant of the BLE PHY.
| Enumerator | |
|---|---|
| RAIL_BLE_1Mbps | Use the standard BLE 1 Mbps PHY. |
| RAIL_BLE_2Mbps | Use the high data rate BLE 2 Mbps 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. |
| RAIL_BLE_Simulscan | Use the BLE Simulscan PHY. |
| RAIL_BLE_CS1Mbps | Use the 1 Mbps variant of the BLE CS PHY. |
| RAIL_BLE_CS2Mbps | Use the 2 Mbps variant of the BLE CS PHY. |
| RAIL_BLE_AOX2Mbps | Use the BLE 2 Mbps AOX PHY. |
| RAIL_BLE_Quuppa1Mbps | Use the BLE 1 Mbps Quuppa PHY. |
139 of file protocol/ble/rail_ble.hRAIL_BLE_SignalIdentifierMode_t#
RAIL_BLE_SignalIdentifierMode_t
Available Signal Identifier modes.
| Enumerator | |
|---|---|
| RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE | Disable signal detection mode. |
| RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS | BLE 1 Mbps (GFSK) detection mode. |
| RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS | BLE 2 Mbps (GFSK) detection mode. |
275 of file protocol/ble/rail_ble.hFunction Documentation#
RAIL_BLE_Init#
RAIL_Status_t RAIL_BLE_Init (RAIL_Handle_t railHandle)
Configure RAIL to run in BLE mode.
| [in] | railHandle | A handle for RAIL instance. |
Returns
Status code indicating success of the function call.
This function changes your radio, channel configuration, and other parameters to match what is needed for BLE, initially establishing the BLE 1 Mbps PHY. 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.
325 of file protocol/ble/rail_ble.hRAIL_BLE_Deinit#
RAIL_Status_t RAIL_BLE_Deinit (RAIL_Handle_t railHandle)
Take RAIL out of BLE mode.
| [in] | railHandle | A handle for RAIL instance. |
Returns
Status code indicating success of the function call.
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.
340 of file protocol/ble/rail_ble.hRAIL_BLE_IsEnabled#
bool RAIL_BLE_IsEnabled (RAIL_Handle_t railHandle)
Determine whether BLE mode is enabled or not.
| [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().
351 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhyQuuppa#
RAIL_Status_t RAIL_BLE_ConfigPhyQuuppa (RAIL_Handle_t railHandle)
Switch to the 1 Mbps Quuppa PHY.
| [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 1 Mbps Quuppa PHY. This API should return RAIL_STATUS_INVALID_CALL if unsupported by the hardware we're building for.
364 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhy1MbpsViterbi#
RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi (RAIL_Handle_t railHandle)
Switch to the Viterbi 1 Mbps BLE PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
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.
376 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhy1Mbps#
RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps (RAIL_Handle_t railHandle)
Switch to the legacy non-Viterbi 1 Mbps BLE PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
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.
DeprecatedBLE non-Viterbi PHYs are no longer supported.
390 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhy2MbpsViterbi#
RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi (RAIL_Handle_t railHandle)
Switch to the Viterbi 2 Mbps BLE PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
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.
402 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhy2Mbps#
RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps (RAIL_Handle_t railHandle)
Switch to the legacy non-Viterbi 2 Mbps BLE PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
Status code indicating success of the function call.
Use this function to switch back to legacy 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.
DeprecatedBLE non-Viterbi PHYs are no longer supported.
416 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhyCoded#
RAIL_Status_t RAIL_BLE_ConfigPhyCoded (RAIL_Handle_t railHandle, RAIL_BLE_Coding_t bleCoding)
Switch to the BLE Coded PHY.
| [in] | railHandle | A handle for RAIL instance. |
| [in] | bleCoding | The RAIL_BLE_Coding_t to use |
Returns
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.
432 of file protocol/ble/rail_ble.hRAIL_BLE_ConfigPhySimulscan#
RAIL_Status_t RAIL_BLE_ConfigPhySimulscan (RAIL_Handle_t railHandle)
Switch to the Simulscan PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
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
: The Simulscan PHY is supported only on some parts. The preprocessor symbol RAIL_BLE_SUPPORTS_SIMULSCAN_PHY and the runtime function RAIL_BLE_SupportsSimulscanPhy() may be used to test for support of the Simulscan PHY.
453 of file protocol/ble/rail_ble.hRAIL_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.
| [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
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 be called after switching to a particular BLE phy (1 Mbps, 2 Mbps, etc.) and not while the radio is active.
505 of file protocol/ble/rail_ble.hRAIL_BLE_PhySwitchToRx#
RAIL_Status_t RAIL_BLE_PhySwitchToRx (RAIL_Handle_t railHandle, RAIL_BLE_Phy_t phy, uint16_t railChannel, RAIL_Time_t startRxTime, uint32_t crcInit, uint32_t accessAddress, uint16_t logicalChannel, bool disableWhitening)
Change the current BLE PHY and go into receive.
| [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 | Absolute near-future RAIL time 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
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.
536 of file protocol/ble/rail_ble.hRAIL_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.
| [in] | railHandle | A RAIL instance handle. |
| [in] | signalIdentifierMode | Mode of signal identifier operation. |
Returns
Status code indicating success of the function call.
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.
563 of file protocol/ble/rail_ble.hRAIL_BLE_EnableSignalDetection#
RAIL_Status_t RAIL_BLE_EnableSignalDetection (RAIL_Handle_t railHandle, bool enable)
Enable or disable signal identifier interrupt for BLE signal detection.
| [in] | railHandle | A RAIL instance handle. |
| [in] | enable | Signal detection is enabled if true, disabled if false. |
Returns
Status code indicating success of the function call.
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.
584 of file protocol/ble/rail_ble.hMacro Definition Documentation#
RAIL_BLE_RX_SUBPHY_ID_500K#
#define RAIL_BLE_RX_SUBPHY_ID_500KValue:
(0U)
RAIL_RxPacketDetails_t::subPhyId indicating a 500 kbps packet.
261 of file protocol/ble/rail_ble.hRAIL_BLE_RX_SUBPHY_ID_125K#
#define RAIL_BLE_RX_SUBPHY_ID_125KValue:
(1U)
RAIL_RxPacketDetails_t::subPhyId indicating a 125 kbps packet.
263 of file protocol/ble/rail_ble.hRAIL_BLE_RX_SUBPHY_ID_1M#
#define RAIL_BLE_RX_SUBPHY_ID_1MValue:
(2U)
RAIL_RxPacketDetails_t::subPhyId value indicating a 1 Mbps packet.
265 of file protocol/ble/rail_ble.hRAIL_BLE_RX_SUBPHY_ID_INVALID#
#define RAIL_BLE_RX_SUBPHY_ID_INVALIDValue:
(3U)
RAIL_RxPacketDetails_t::subPhyId invalid value.
267 of file protocol/ble/rail_ble.hRAIL_BLE_RX_SUBPHY_COUNT#
#define RAIL_BLE_RX_SUBPHY_COUNTValue:
(4U)
The total count of BLE subPhyId's.
Must be last.
269 of file protocol/ble/rail_ble.hRAIL_BLE_EnableSignalIdentifier#
#define RAIL_BLE_EnableSignalIdentifierValue:
RAIL_BLE_EnableSignalDetection
Backward compatible name for the RAIL_BLE_EnableSignalDetection API.
591 of file protocol/ble/rail_ble.h