BLE TX Channel Hopping#

// 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
void 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);
}

// Configuration to send one additional packet
static sl_rail_ble_tx_channel_hopping_config_entry_t entry[1];
static uint32_t buffer[BUFFER_WORDS];
static sl_rail_ble_tx_repeat_config_t tx_repeat_config = {
  .iterations = 1,
  .repeat_options = SL_RAIL_TX_REPEAT_OPTION_HOP,
  .delay_or_hop.channel_hopping = {
    .p_buffer = buffer,
    .buffer_words = BUFFER_WORDS,
    .number_of_channels = 1,
    .entries = &entry[0],
  },
};

// Send a normal packet on the current channel, then a packet on a new channel
void ble_send_then_advertise(uint8_t *p_first_packet,
                             uint8_t first_packet_bytes,
                             uint8_t *p_second_packet,
                             uint8_t second_packet_bytes)
{
  // Load both packets into the FIFO
  sl_rail_write_tx_fifo(rail_handle, p_first_packet, first_packet_bytes, true);
  sl_rail_write_tx_fifo(rail_handle, p_second_packet, second_packet_bytes, false);

  // Configure a 300 us turnaround between transmits
  entry[0].delay_mode = SL_RAIL_CHANNEL_HOPPING_DELAY_MODE_STATIC;
  entry[0].delay = 300; // microseconds

  // Use default advertising parameters
  entry[0].disable_whitening = false;
  entry[0].crc_init = 0x00555555;
  entry[0].access_address = 0x8E89BED6;

  // Transmit the repeated packet on the first advertising channel
  entry[0].phy = sl_rail_ble_1_mbps;
  entry[0].rail_channel = 0;
  entry[0].logical_channel = 37;

 // Configure repeated transmit in RAIL, then transmit, sending both packets
 sl_rail_ble_set_next_tx_repeat(rail_handle, &tx_repeat_config);
 sl_rail_start_tx(rail_handle, current_channel, SL_RAIL_TX_OPTIONS_DEFAULT, NULL);
}

Modules#

RAIL_BLE_TxChannelHoppingConfigEntry_t

RAIL_BLE_TxChannelHoppingConfig_t

RAIL_BLE_TxRepeatConfig_t

sl_rail_ble_tx_channel_hopping_config_entry_t

sl_rail_ble_tx_channel_hopping_config_t

sl_rail_ble_tx_repeat_config_t

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.

sl_rail_status_t

sl_rail_ble_set_next_tx_repeat(sl_rail_handle_t rail_handle, const sl_rail_ble_tx_repeat_config_t *p_repeat_config)

Set up automatic repeated transmits after the next transmit.

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
const RAIL_BLE_TxRepeatConfig_t *	[in]	repeatConfig	A non-NULL pointer to 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 PTI Packet Trace 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(), RAIL_StopTx(), or RAIL_SetTxTransitions() 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

Use the compile time symbol RAIL_SUPPORTS_TX_TO_TX or the runtime call RAIL_SupportsTxToTx() to check whether the platform supports this feature.

DeprecatedRAIL 2.x synonym of sl_rail_ble_set_next_tx_repeat().

sl_rail_ble_set_next_tx_repeat#

sl_rail_status_t sl_rail_ble_set_next_tx_repeat (sl_rail_handle_t rail_handle, const sl_rail_ble_tx_repeat_config_t * p_repeat_config)

Set up automatic repeated transmits after the next transmit.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_ble_tx_repeat_config_t *	[in]	p_repeat_config	A non-NULL pointer to the configuration structure for repeated transmits.

Returns

Status code indicating a success of the function call.

Each repeated transmit that occurs will have full PTI Packet Trace information and will receive events such as SL_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 sl_rail_set_tx_transitions() will be used. If the repetition completes successfully, the TX success transition from sl_rail_set_tx_transitions() will be used.

Any call to sl_rail_idle(), sl_rail_stop_tx(), or sl_rail_set_tx_transitions() 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 sl_rail_ble_tx_repeat_config_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 sl_rail_set_tx_fifo() or sl_rail_write_tx_fifo(). Data will be transmitted from the TX FIFO. If the TX FIFO does not have sufficient data to transmit, a TX error and a SL_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

Use the compile time symbol SL_RAIL_SUPPORTS_TX_TO_TX or the runtime call sl_rail_supports_tx_to_tx() to check whether the platform supports this feature.