BLE TX Channel Hopping
RAIL API > Protocol-specific > BLE

Data Structures

struct RAIL_BLE_TxChannelHoppingConfigEntry_t
Structure that represents one of the channels that is part of a RAIL_BLE_TxChannelHoppingConfig_t sequence of channels used in channel hopping.
struct RAIL_BLE_TxChannelHoppingConfig_t
Wrapper struct that will contain the sequence of RAIL_BLE_TxChannelHoppingConfigEntry_t that represents the channel sequence to use during TX Channel Hopping.
struct RAIL_BLE_TxRepeatConfig_t
A configuration structure for repeated transmits.

Functions

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.
// Configuration to send one additional packet
static RAIL_BLE_TxChannelHoppingConfigEntry_t entry[1];
static uint32_t buffer[BUFFER_SIZE];
static RAIL_BLE_TxRepeatConfig_t repeat = {
. iterations = 1,
.repeatOptions = RAIL_TX_REPEAT_OPTION_HOP ,
.delayOrHop.channelHopping = {
.buffer = buffer,
.bufferLength = BUFFER_SIZE,
.numberOfChannels = 1,
.entries = &entry[0],
},
};
// Send a normal packet on the current channel, then a packet on a new channel
int bleSendThenAdvertise(uint8_t *firstPacket, uint8_t *secondPacket)
{
// Load both packets into the FIFO
RAIL_WriteTxFifo (railHandle, firstPacket, FIRST_PACKET_LEN, true );
RAIL_WriteTxFifo (railHandle, secondPacket, SECOND_PACKET_LEN, false );
// Configure a 300 us turnaround between transmits
entry[0].delayMode = RAIL_CHANNEL_HOPPING_DELAY_MODE_STATIC;
entry[0]. delay = 300; // microseconds
// Use default advertising parameters
entry[0]. disableWhitening = false ;
entry[0]. crcInit = 0x00555555;
entry[0]. accessAddress = 0x8E89BED6;
// Transmit the repeated packet on the first advertising channel
entry[0]. phy = RAIL_BLE_1Mbps ;
entry[0]. railChannel = 0;
entry[0]. logicalChannel = 37;
// Configure repeated transmit in RAIL, then transmit, sending both packets
RAIL_BLE_SetNextTxRepeat (railHandle, &repeat);
RAIL_StartTx (railHandle, currentChannel, RAIL_TX_OPTIONS_DEFAULT , NULL);
}

Function Documentation

◆ 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
This feature/API is not supported on the EFR32XG1 family of chips. Use the compile time symbol RAIL_SUPPORTS_TX_TO_TX or the runtime call RAIL_SupportsTxToTx() to check whether the platform supports this feature.