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() 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);
 }

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, sl_rail_config_channels() should not be called to set up the PHY. Instead, sl_rail_ble_coding* 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 sl_rail_start_scheduled_tx(), sl_rail_start_scheduled_rx(), and sl_rail_set_state_timing(). 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 sl_rail_ble_config_channel_radio_params() function to change the sync word and other parameters as needed based on your connection.

// RAIL handle set at initialization time.
static sl_rail_handle_t g_rail_handle = SL_RAIL_EFR32_HANDLE;

#define BLE_RX_PACKET_QUEUE_ENTRIES 16
#define BLE_FIFO_BYTES 512 // Handle max-sized BLE packets, AoX

static sl_rail_packet_queue_t g_rx_packet_queue[BLE_RX_PACKET_QUEUE_ENTRIES];
static SL_RAIL_DECLARE_FIFO_BUFFER(g_rx_fifo_buffer, BLE_FIFO_BYTES);
static SL_RAIL_DECLARE_FIFO_BUFFER(g_tx_fifo_buffer, BLE_FIFO_BYTES);

static void radio_event_handler(sl_rail_handle_t rail_handle,
                                sl_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 ble_advertise_enable(void)
{
  sl_rail_config_t rail_config = {
    .events_callback         = &radio_event_handler,
    .rx_packet_queue_entries = BLE_RX_PACKET_QUEUE_ENTRIES,
    .rx_fifo_bytes           = sizeof(g_rx_fifo_buffer),
    .tx_fifo_bytes           = sizeof(g_tx_fifo_buffer),
    .tx_fifo_init_bytes      = 0,
    .rx_packet_queue         = g_rx_packet_queue,
    .rx_fifo_buffer          = g_rx_fifo_buffer,
    .tx_fifo_buffer          = g_tx_fifo_buffer,
  };
  sl_rail_status_t status;

  // Initializes the RAIL library and any internal state it requires.
  status = sl_rail_init(&g_rail_handle, &rail_config, NULL);
  assert(status == SL_RAIL_STATUS_NO_ERROR);

  // Calls the BLE initialization function to load the right radio configuration.
  status = sl_rail_ble_init(g_rail_handle);
  assert(status == SL_RAIL_STATUS_NO_ERROR);

  status = sl_rail_ble_config_phy_1_mbps(g_rail_handle);
  assert(status == SL_RAIL_STATUS_NO_ERROR);

  // Configures us for the first advertising channel (Physical: 0, Logical: 37).
  // The CRC init value and Access Address come from the BLE specification.
  sl_rail_ble_state_t ble_params = {
    .crc_init = 0x555555,
    .access_address = 0x0x8E89BED6,
    .logical_channel = 37,
    .disable_whitening = false,
  };
  status = sl_rail_ble_config_channel_radio_params(g_rail_handle, &ble_params);
  assert(status == SL_RAIL_STATUS_NO_ERROR);

  // Starts receiving on physical channel 0 (logical channel 37).
  status = sl_rail_start_rx(g_rail_handle, 0, NULL);
  assert(status == SL_RAIL_STATUS_NO_ERROR);
 }

Modules#

RAIL_BLE_State_t

sl_rail_ble_state_t

Angle of Arrival/Departure

BLE Radio Configurations

BLE TX Channel Hopping

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.

enum

RAIL_BLE_Phy_t {

RAIL_BLE_1Mbps = 0U

RAIL_BLE_2Mbps = 1U

RAIL_BLE_Coded125kbps = 2U

RAIL_BLE_Coded500kbps = 3U

RAIL_BLE_Simulscan = 4U

RAIL_BLE_AOX2mbps = 5U

RAIL_BLE_Quuppa1Mbps = 6U

RAIL_BLE_CS1Mbps = 7U

RAIL_BLE_CS2Mbps = 8U

}

The variant of the BLE PHY.

enum

RAIL_BLE_SignalIdentifierMode_t {

RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE = 0

RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1MBPS = 1

RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2MBPS = 2

}

Available Signal Identifier modes.

enum

sl_rail_ble_coding_t {

SL_RAIL_BLE_CODING_125_KBPS = 0u

SL_RAIL_BLE_CODING_500_KBPS = 2u

}

The variant of the BLE Coded PHY.

enum

sl_rail_ble_phy_t {

SL_RAIL_BLE_PHY_1_MBPS = 0u

SL_RAIL_BLE_PHY_2_MBPS = 1u

SL_RAIL_BLE_PHY_CODED_125_KBPS = 2u

SL_RAIL_BLE_PHY_CODED_500_KBPS = 3u

SL_RAIL_BLE_PHY_SIMULSCAN = 4u

SL_RAIL_BLE_PHY_AOX_2_MBPS = 5u

SL_RAIL_BLE_PHY_QUUPPA_1_MBPS = 6u

SL_RAIL_BLE_PHY_CS_1_MBPS = 7u

SL_RAIL_BLE_PHY_CS_2_MBPS = 8u

SL_RAIL_BLE_PHY_UNDEFINED = 0xFFu

}

The BLE PHY identifier (aka PTI radio configuration id).

enum

sl_rail_ble_signal_identifier_mode_t {

SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE = 0u

SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1_MBPS = 1u

SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2_MBPS = 2u

SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1_MBPS_WITH_AGC_RESET = 3u

SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2_MBPS_WITH_AGC_RESET = 4u

}

Available Signal Identifier modes.

Functions#

RAIL_Status_t

RAIL_BLE_Init(RAIL_Handle_t railHandle)

Configure RAIL to run in BLE mode.

RAIL_Status_t

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_ConfigPhyQuuppa(RAIL_Handle_t railHandle)

Switch to the 1 Mbps Quuppa PHY.

RAIL_Status_t

RAIL_BLE_ConfigPhy1MbpsViterbi(RAIL_Handle_t railHandle)

Switch to the Viterbi 1 Mbps BLE PHY.

RAIL_Status_t

RAIL_BLE_ConfigPhy1Mbps(RAIL_Handle_t railHandle)

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

RAIL_Status_t

RAIL_BLE_ConfigPhy2MbpsViterbi(RAIL_Handle_t railHandle)

Switch to the Viterbi 2 Mbps BLE PHY.

RAIL_Status_t

RAIL_BLE_ConfigPhy2Mbps(RAIL_Handle_t railHandle)

Switch to the legacy non-Viterbi 2 Mbps 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_ConfigPhySimulscan(RAIL_Handle_t railHandle)

Switch to the Simulscan PHY.

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.

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.

RAIL_Status_t

RAIL_BLE_ConfigSignalIdentifier(RAIL_Handle_t railHandle, RAIL_BLE_SignalIdentifierMode_t signalIdentifierMode)

Configure and enable signal identifier for BLE signal detection.

RAIL_Status_t

RAIL_BLE_EnableSignalDetection(RAIL_Handle_t railHandle, bool enable)

Enable or disable signal identifier interrupt for BLE signal detection.

sl_rail_status_t

sl_rail_ble_init(sl_rail_handle_t rail_handle)

Configure RAIL to run in BLE mode.

sl_rail_status_t

sl_rail_ble_deinit(sl_rail_handle_t rail_handle)

Take RAIL out of BLE mode.

bool

sl_rail_ble_is_enabled(sl_rail_handle_t rail_handle)

Determine whether BLE mode is enabled or not.

sl_rail_status_t

sl_rail_ble_config_channels(sl_rail_handle_t rail_handle, const sl_rail_channel_config_t *p_channel_config, sl_rail_ble_phy_t phy_id)

Load BLE channel config.

sl_rail_status_t

sl_rail_ble_config_phy_quuppa(sl_rail_handle_t rail_handle)

Switch to the 1 Mbps Quuppa PHY.

sl_rail_status_t

sl_rail_ble_config_phy_1_mbps(sl_rail_handle_t rail_handle)

Switch to the 1 Mbps BLE PHY.

sl_rail_status_t

sl_rail_ble_config_phy_2_mbps(sl_rail_handle_t rail_handle)

Switch to the 2 Mbps BLE PHY.

sl_rail_status_t

sl_rail_ble_config_phy_coded(sl_rail_handle_t rail_handle, sl_rail_ble_coding_t ble_coding)

Switch to the BLE Coded PHY.

sl_rail_status_t

sl_rail_ble_config_phy_simulscan(sl_rail_handle_t rail_handle)

Switch to the Simulscan PHY.

sl_rail_status_t

sl_rail_ble_config_channel_radio_params(sl_rail_handle_t rail_handle, const sl_rail_ble_state_t *p_params)

Change BLE radio parameters.

sl_rail_status_t

sl_rail_ble_phy_switch_to_rx(sl_rail_handle_t rail_handle, sl_rail_ble_phy_t phy, uint16_t rail_channel, sl_rail_time_t start_rx_time, const sl_rail_ble_state_t *p_params)

Change the current BLE PHY and go into receive.

sl_rail_status_t

sl_rail_ble_config_signal_identifier(sl_rail_handle_t rail_handle, sl_rail_ble_signal_identifier_mode_t signal_identifier_mode)

Configure and enable signal identifier for BLE signal detection.

sl_rail_status_t

sl_rail_ble_enable_signal_detection(sl_rail_handle_t rail_handle, bool enable)

Enable or disable signal identifier interrupt for BLE signal detection.

Macros#

#define

RAIL_BLE_RX_SUBPHY_ID_500K (0U)

RAIL_RxPacketDetails_t::subPhyId indicating a 500 kbps packet.

#define

RAIL_BLE_RX_SUBPHY_ID_125K (1U)

RAIL_RxPacketDetails_t::subPhyId indicating a 125 kbps packet.

#define

RAIL_BLE_RX_SUBPHY_ID_1M (2U)

RAIL_RxPacketDetails_t::subPhyId value indicating a 1 Mbps packet.

#define

RAIL_BLE_RX_SUBPHY_ID_INVALID (3U)

RAIL_RxPacketDetails_t::subPhyId invalid value.

#define

RAIL_BLE_RX_SUBPHY_COUNT (4U)

The total count of BLE subPhyId's.

#define

RAIL_BLE_EnableSignalIdentifier RAIL_BLE_EnableSignalDetection

Backward compatible name for the RAIL_BLE_EnableSignalDetection API.

#define

SL_RAIL_BLE_RX_SUBPHY_ID_500_KBPS (0U)

sl_rail_rx_packet_details_t::sub_phy_id indicating a 500 kbps packet.

#define

SL_RAIL_BLE_RX_SUBPHY_ID_125_KBPS (1U)

sl_rail_rx_packet_details_t::sub_phy_id indicating a 125 kbps packet.

#define

SL_RAIL_BLE_RX_SUBPHY_ID_1_MBPS (2U)

sl_rail_rx_packet_details_t::sub_phy_id value indicating a 1 Mbps packet.

#define

SL_RAIL_BLE_RX_SUBPHY_ID_INVALID (3U)

sl_rail_rx_packet_details_t::sub_phy_id invalid value.

#define

SL_RAIL_BLE_RX_SUBPHY_COUNT (4U)

The total count of BLE sub_phy_id's.

Enumeration Documentation#

RAIL_BLE_Coding_t#

RAIL_BLE_Coding_t

The variant of the BLE Coded PHY.

DeprecatedRAIL 2.x synonym of sl_rail_ble_coding_t.

Enumerator
RAIL_BLE_Coding_125kbps	Enables the 125 kbps variant of the BLE Coded PHY.
RAIL_BLE_Coding_125kbps_DSA	DeprecatedThis deprecated RAIL 2.x enum value has been eliminated in RAIL 3.
RAIL_BLE_Coding_500kbps	Enables the 500 kbps variant of the BLE Coded PHY.
RAIL_BLE_Coding_500kbps_DSA	DeprecatedThis deprecated RAIL 2.x enum value has been eliminated in RAIL 3.

RAIL_BLE_Phy_t#

RAIL_BLE_Phy_t

The variant of the BLE PHY.

DeprecatedRAIL 2.x synonym of sl_rail_ble_phy_t.

Enumerator
RAIL_BLE_1Mbps	BLE 1 Mbps PHY.
RAIL_BLE_2Mbps	BLE 2 Mbps PHY.
RAIL_BLE_Coded125kbps	BLE 125 kbps coded PHY.
RAIL_BLE_Coded500kbps	BLE 500 kbps coded PHY.
RAIL_BLE_Simulscan	BLE Simulscan PHY.
RAIL_BLE_AOX2mbps	BLE 2 Mbps PHY with AoX functionality.
RAIL_BLE_Quuppa1Mbps	BLE 1 Mbps Quuppa PHY.
RAIL_BLE_CS1Mbps	BLE 1 Mbps PHY with CS.
RAIL_BLE_CS2Mbps	BLE 2 Mbps PHY with CS.

RAIL_BLE_SignalIdentifierMode_t#

RAIL_BLE_SignalIdentifierMode_t

Available Signal Identifier modes.

DeprecatedRAIL 2.x synonym of sl_rail_ble_signal_identifier_mode_t.

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.

sl_rail_ble_coding_t#

sl_rail_ble_coding_t

The variant of the BLE Coded PHY.

Enumerator
SL_RAIL_BLE_CODING_125_KBPS	Enables the 125 kbps variant of the BLE Coded PHY.
SL_RAIL_BLE_CODING_500_KBPS	Enables the 500 kbps variant of the BLE Coded PHY.

sl_rail_ble_phy_t#

sl_rail_ble_phy_t

The BLE PHY identifier (aka PTI radio configuration id).

Enumerator
SL_RAIL_BLE_PHY_1_MBPS	BLE 1 Mbps PHY.
SL_RAIL_BLE_PHY_2_MBPS	BLE 2 Mbps PHY.
SL_RAIL_BLE_PHY_CODED_125_KBPS	BLE 125 kbps coded PHY.
SL_RAIL_BLE_PHY_CODED_500_KBPS	BLE 500 kbps coded PHY.
SL_RAIL_BLE_PHY_SIMULSCAN	BLE Simulscan PHY.
SL_RAIL_BLE_PHY_AOX_2_MBPS	BLE 2 Mbps PHY with AoX functionality.
SL_RAIL_BLE_PHY_QUUPPA_1_MBPS	BLE 1 Mbps Quuppa PHY.
SL_RAIL_BLE_PHY_CS_1_MBPS	BLE 1 Mbps PHY with CS.
SL_RAIL_BLE_PHY_CS_2_MBPS	BLE 2 Mbps PHY with CS.
SL_RAIL_BLE_PHY_UNDEFINED	BLE PHY undefined.

sl_rail_ble_signal_identifier_mode_t#

sl_rail_ble_signal_identifier_mode_t

Available Signal Identifier modes.

Enumerator
SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_DISABLE	Disable signal detection mode.
SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1_MBPS	BLE 1 Mbps (GFSK) detection mode with SI block reset on GPIO falling edge (via PRS).
SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2_MBPS	BLE 2 Mbps (GFSK) detection mode with SI block reset on GPIO falling edge (via PRS).
SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_1_MBPS_WITH_AGC_RESET	BLE 1 Mbps (GFSK) detection mode with SI block reset on AGC negative step.
SL_RAIL_BLE_SIGNAL_IDENTIFIER_MODE_2_MBPS_WITH_AGC_RESET	BLE 2 Mbps (GFSK) detection mod with SI block reset on AGC negative step.

Function Documentation#

RAIL_BLE_Init#

RAIL_Status_t RAIL_BLE_Init (RAIL_Handle_t railHandle)

Configure RAIL to run in BLE mode.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_init().

RAIL_BLE_Deinit#

RAIL_Status_t RAIL_BLE_Deinit (RAIL_Handle_t railHandle)

Take RAIL out of BLE mode.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_deinit().

RAIL_BLE_IsEnabled#

bool RAIL_BLE_IsEnabled (RAIL_Handle_t railHandle)

Determine whether BLE mode is enabled or not.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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().

DeprecatedRAIL 2.x synonym of sl_rail_ble_is_enabled().

RAIL_BLE_ConfigPhyQuuppa#

RAIL_Status_t RAIL_BLE_ConfigPhyQuuppa (RAIL_Handle_t railHandle)

Switch to the 1 Mbps Quuppa PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_phy_quuppa().

RAIL_BLE_ConfigPhy1MbpsViterbi#

RAIL_Status_t RAIL_BLE_ConfigPhy1MbpsViterbi (RAIL_Handle_t railHandle)

Switch to the Viterbi 1 Mbps BLE PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_phy_1_mbps().

RAIL_BLE_ConfigPhy1Mbps#

RAIL_Status_t RAIL_BLE_ConfigPhy1Mbps (RAIL_Handle_t railHandle)

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

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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. Use sl_rail_ble_config_phy_1_mbps() instead.

RAIL_BLE_ConfigPhy2MbpsViterbi#

RAIL_Status_t RAIL_BLE_ConfigPhy2MbpsViterbi (RAIL_Handle_t railHandle)

Switch to the Viterbi 2 Mbps BLE PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_phy_2_mbps().

RAIL_BLE_ConfigPhy2Mbps#

RAIL_Status_t RAIL_BLE_ConfigPhy2Mbps (RAIL_Handle_t railHandle)

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

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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. Use sl_rail_ble_config_phy_2_mbps() instead.

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A handle for RAIL instance.
RAIL_BLE_Coding_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_phy_coded().

RAIL_BLE_ConfigPhySimulscan#

RAIL_Status_t RAIL_BLE_ConfigPhySimulscan (RAIL_Handle_t railHandle)

Switch to the Simulscan PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_phy_simulscan().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A handle for RAIL instance.
uint32_t	[in]	crcInit	The value to use for CRC initialization.
uint32_t	[in]	accessAddress	The access address to use for the connection. The bits of this parameter are transmitted or received LSB first.
uint16_t	[in]	channel	The logical channel that you're changing to, which initializes the whitener if used.
bool	[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.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_ble_config_channel_radio_params() with different parameters.

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

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A handle for RAIL instance.
RAIL_BLE_Phy_t	[in]	phy	Indicates which PHY to receive on.
uint16_t	[in]	railChannel	Which channel of the given PHY to receive on.
RAIL_Time_t	[in]	startRxTime	Absolute near-future RAIL time to enter RX.
uint32_t	[in]	crcInit	The value to use for CRC initialization.
uint32_t	[in]	accessAddress	The access address to use for the connection. The bits of this parameter are transmitted or received LSB first.
uint16_t	[in]	logicalChannel	The logical channel that you're changing to, which initializes the whitener if used.
bool	[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.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_ble_phy_switch_to_rx() with different parameters.

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_BLE_SignalIdentifierMode_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_config_signal_identifier().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
bool	[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.

DeprecatedRAIL 2.x synonym of sl_rail_ble_enable_signal_detection().

sl_rail_ble_init#

sl_rail_status_t sl_rail_ble_init (sl_rail_handle_t rail_handle)

Configure RAIL to run in BLE mode.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

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 sl_rail_ble_deinit() first. This function will configure the protocol output on PTI to SL_RAIL_PTI_PROTOCOL_BLE.

Note

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

sl_rail_ble_deinit#

sl_rail_status_t sl_rail_ble_deinit (sl_rail_handle_t rail_handle)

Take RAIL out of BLE mode.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

Status code indicating success of the function call.

This function will undo some of the configuration that happens when you call sl_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 SL_RAIL_PTI_PROTOCOL_CUSTOM.

sl_rail_ble_is_enabled#

bool sl_rail_ble_is_enabled (sl_rail_handle_t rail_handle)

Determine whether BLE mode is enabled or not.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

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 sl_rail_ble_init() and disabled by a call to sl_rail_ble_deinit().

sl_rail_ble_config_channels#

sl_rail_status_t sl_rail_ble_config_channels (sl_rail_handle_t rail_handle, const sl_rail_channel_config_t * p_channel_config, sl_rail_ble_phy_t phy_id)

Load BLE channel config.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_channel_config_t *	[in]	p_channel_config	A pointer to the channel configuration structure.
sl_rail_ble_phy_t	[in]	phy_id	The PHY ID to configure.

Returns

Status code indicating success of the function call.

sl_rail_ble_config_phy_quuppa#

sl_rail_status_t sl_rail_ble_config_phy_quuppa (sl_rail_handle_t rail_handle)

Switch to the 1 Mbps Quuppa PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

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 SL_RAIL_STATUS_INVALID_CALL if unsupported by the hardware we're building for.

sl_rail_ble_config_phy_1_mbps#

sl_rail_status_t sl_rail_ble_config_phy_1_mbps (sl_rail_handle_t rail_handle)

Switch to the 1 Mbps BLE PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

Status code indicating success of the function call.

sl_rail_ble_config_phy_2_mbps#

sl_rail_status_t sl_rail_ble_config_phy_2_mbps (sl_rail_handle_t rail_handle)

Switch to the 2 Mbps BLE PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

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.

sl_rail_ble_config_phy_coded#

sl_rail_status_t sl_rail_ble_config_phy_coded (sl_rail_handle_t rail_handle, sl_rail_ble_coding_t ble_coding)

Switch to the BLE Coded PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_ble_coding_t	[in]	ble_coding	The sl_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 sl_rail_rx_packet_details_t::sub_phy_id marks the coding of the received packet. A sub_phy_id of 0 marks a 500 kbps packet, and a sub_phy_id of 1 marks a 125 kbps packet.

sl_rail_ble_config_phy_simulscan#

sl_rail_status_t sl_rail_ble_config_phy_simulscan (sl_rail_handle_t rail_handle)

Switch to the Simulscan PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

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 sl_rail_rx_packet_details_t::sub_phy_id marks the coding of the received packet. A sub_phy_id of 0 marks a 500 kbps packet, a sub_phy_id of 1 marks a 125 kbps packet, and a sub_phy_id of 2 marks a 1 Mbps packet.

Note

: The Simulscan PHY is supported only on some parts. The preprocessor symbol SL_RAIL_BLE_SUPPORTS_SIMULSCAN_PHY and the runtime function sl_rail_ble_supports_simulscan_phy() may be used to test for support of the Simulscan PHY.

sl_rail_ble_config_channel_radio_params#

sl_rail_status_t sl_rail_ble_config_channel_radio_params (sl_rail_handle_t rail_handle, const sl_rail_ble_state_t * p_params)

Change BLE radio parameters.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_ble_state_t *	[in]	p_params	A non-NULL pointer to a sl_rail_ble_state_t structure specifying the BLE radio state parameters to use.

Returns

Status code indicating success of the function call.

sl_rail_ble_phy_switch_to_rx#

sl_rail_status_t sl_rail_ble_phy_switch_to_rx (sl_rail_handle_t rail_handle, sl_rail_ble_phy_t phy, uint16_t rail_channel, sl_rail_time_t start_rx_time, const sl_rail_ble_state_t * p_params)

Change the current BLE PHY and go into receive.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_ble_phy_t	[in]	phy	Indicates which PHY to receive on.
uint16_t	[in]	rail_channel	Which channel of the given PHY to receive on.
sl_rail_time_t	[in]	start_rx_time	Absolute near-future RAIL time to enter RX.
const sl_rail_ble_state_t *	[in]	p_params	A non-NULL pointer to the parameters for this operation. sl_rail_ble_state_t::logical_channel should be the logical channel that you're changing to, which initializes the whitener if used.

Returns

Status code indicating success of the function call.

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

sl_rail_ble_config_signal_identifier#

sl_rail_status_t sl_rail_ble_config_signal_identifier (sl_rail_handle_t rail_handle, sl_rail_ble_signal_identifier_mode_t signal_identifier_mode)

Configure and enable signal identifier for BLE signal detection.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_ble_signal_identifier_mode_t	[in]	signal_identifier_mode	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 sl_rail_ble_enable_signal_detection to configure and enable signal identifier.

To enable event for signal detection sl_rail_config_events() must be called for enabling SL_RAIL_EVENT_SIGNAL_DETECTED.

This function is only supported by chips where SL_RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and sl_rail_ble_supports_signal_identifier() are true.

sl_rail_ble_enable_signal_detection#

sl_rail_status_t sl_rail_ble_enable_signal_detection (sl_rail_handle_t rail_handle, bool enable)

Enable or disable signal identifier interrupt for BLE signal detection.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
bool	[in]	enable	Signal detection is enabled if true, disabled if false.

Returns

Status code indicating success of the function call.

sl_rail_ble_config_signal_identifier() 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 sl_rail_ble_config_signal_identifier() if the signal identifier is already configured and enabled.

This function is only supported by chips where SL_RAIL_BLE_SUPPORTS_SIGNAL_IDENTIFIER and sl_rail_ble_supports_signal_identifier() are true.