APIs related to transmitting data packets.

Modules
Packet Transmit
APIs which initiate a packet transmission in RAIL.

Power Amplifier (PA)
APIs for interacting with one of the on chip PAs.

Data Structures
struct	RAIL_TxPacketDetails_t
	Detailed information requested about the packet that was just, or is currently being, transmitted.

struct	RAIL_ScheduleTxConfig_t
	A configuration structure for a scheduled transmit.

struct	RAIL_CsmaConfig_t
	A configuration structure for the CSMA transmit algorithm.

struct	RAIL_LbtConfig_t
	A configuration structure for the LBT transmit algorithm.

struct	RAIL_SyncWordConfig_t
	RAIL sync words and length configuration.

struct	RAIL_TxRepeatConfig_t
	A configuration structure for repeated transmits.

Macros
#define	RAIL_STOP_MODES_NONE (0U)
	Do not stop any radio operations.

#define	RAIL_STOP_MODE_ACTIVE (1U << RAIL_STOP_MODE_ACTIVE_SHIFT)
	Stop active radio operations only.

#define	RAIL_STOP_MODE_PENDING (1U << RAIL_STOP_MODE_PENDING_SHIFT)
	Stop pending radio operations.

#define	RAIL_STOP_MODES_ALL (0xFFU)
	Stop all radio operations.

#define	RAIL_TX_OPTIONS_NONE 0UL
	A value representing no options enabled.

#define	RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE
	All options disabled by default.

#define	RAIL_TX_OPTION_WAIT_FOR_ACK (1UL << RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT)
	An option to configure whether or not the TXing node will listen for an ACK.

#define	RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT)
	An option to remove CRC bytes from TX packets.

#define	RAIL_TX_OPTION_SYNC_WORD_ID (1UL << RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT)
	An option to select which sync word to send (0 or 1).

#define	RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT)
	An option to select antenna 0 for transmission.

#define	RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT)
	An option to select antenna 1 for transmission.

#define	RAIL_TX_OPTION_ALT_PREAMBLE_LEN (1UL << RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT)
	An option to dynamically set an alternate preamble length for the transmission.

#define	RAIL_TX_OPTION_CCA_PEAK_RSSI (1UL << RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT)
	An option to use peak rather than average RSSI energy detected during CSMA's RAIL_CsmaConfig_t::ccaDuration or LBT's RAIL_LbtConfig_t::lbtDuration to determine whether the channel is clear or busy.

#define	RAIL_TX_OPTION_CCA_ONLY (1UL << RAIL_TX_OPTION_CCA_ONLY_SHIFT)
	An option to only perform the CCA (CSMA/LBT) operation but not automatically transmit if the channel is clear.

#define	RAIL_TX_OPTION_RESEND (1UL << RAIL_TX_OPTION_RESEND_SHIFT)
	An option to resend packet at the beginning of the Transmit FIFO.

#define	RAIL_TX_OPTIONS_ALL 0xFFFFFFFFUL
	A value representing all possible options.

#define	RAIL_MAX_LBT_TRIES (15U)
	The maximum number of LBT/CSMA retries supported.

#define	RAIL_MAX_CSMA_EXPONENT (8U)
	The maximum power-of-2 exponent for CSMA backoffs.

#define	RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA
	RAIL_CsmaConfig_t initializer configuring CSMA per IEEE 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by ZigBee.

#define	RAIL_CSMA_CONFIG_SINGLE_CCA
	RAIL_CsmaConfig_t initializer configuring a single CCA prior to TX.

#define	RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1
	RAIL_LbtConfig_t initializer configuring LBT per ETSI 300 220-1 V2.4.1 for a typical Sub-GHz band.

#define	RAIL_TX_REPEAT_OPTIONS_NONE 0U
	A value representing no repeat options enabled.

#define	RAIL_TX_REPEAT_OPTIONS_DEFAULT RAIL_TX_REPEAT_OPTIONS_NONE
	All repeat options disabled by default.

#define	RAIL_TX_REPEAT_OPTION_HOP (1U << RAIL_TX_REPEAT_OPTION_HOP_SHIFT)
	An option to configure whether or not to channel-hop before each repeated transmit.

#define	RAIL_TX_REPEAT_INFINITE_ITERATIONS (0xFFFFU)
	RAIL_TxRepeatConfig_t::iterations initializer configuring infinite repeated transmissions.

Enumerations
enum	RAIL_StopMode_t { RAIL_STOP_MODE_ACTIVE_SHIFT = 0, RAIL_STOP_MODE_PENDING_SHIFT = 1 }
	Stop radio operation options bit mask.

enum	RAIL_TxOptions_t { RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT = 0, RAIL_TX_OPTION_REMOVE_CRC_SHIFT , RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT , RAIL_TX_OPTION_ANTENNA0_SHIFT , RAIL_TX_OPTION_ANTENNA1_SHIFT , RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT , RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT , RAIL_TX_OPTION_CCA_ONLY_SHIFT , RAIL_TX_OPTION_RESEND_SHIFT , RAIL_TX_OPTIONS_COUNT }
	Transmit options, in reality a bitmask.

enum	RAIL_ScheduledTxDuringRx_t { RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX , RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX }
	Enumerates the possible outcomes of what will occur if a scheduled TX ends up firing during RX.

enum	RAIL_TxRepeatOptions_t { RAIL_TX_REPEAT_OPTION_HOP_SHIFT = 0 }
	Transmit repeat options, in reality a bitmask.

Functions
RAIL_Status_t	RAIL_StopTx ( RAIL_Handle_t railHandle, RAIL_StopMode_t mode)
	Stop an active or pending transmit.

RAIL_Status_t	RAIL_SetCcaThreshold ( RAIL_Handle_t railHandle, int8_t ccaThresholdDbm)
	Set the CCA threshold in dBm.

RAIL_Status_t	RAIL_GetTxPacketDetails ( RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)
	Get detailed information about the last packet transmitted.

RAIL_Status_t	RAIL_GetTxPacketDetailsAlt ( RAIL_Handle_t railHandle, bool isAck, RAIL_Time_t *pPacketTime)
	Get detailed information about the last packet transmitted.

RAIL_Status_t	RAIL_GetTxPacketDetailsAlt2 ( RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)
	Get detailed information about the last packet transmitted.

RAIL_Status_t	RAIL_GetTxTimePreambleStart ( RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)
	Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

RAIL_Status_t	RAIL_GetTxTimePreambleStartAlt ( RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)
	Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

RAIL_Status_t	RAIL_GetTxTimeSyncWordEnd ( RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)
	Adjust a RAIL TX timestamp to refer to the end of the sync word.

RAIL_Status_t	RAIL_GetTxTimeSyncWordEndAlt ( RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)
	Adjust a RAIL TX timestamp to refer to the end of the sync word.

RAIL_Status_t	RAIL_GetTxTimeFrameEnd ( RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)
	Adjust a RAIL TX timestamp to refer to the end of frame.

RAIL_Status_t	RAIL_GetTxTimeFrameEndAlt ( RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)
	Adjust a RAIL TX timestamp to refer to the end of frame.

void	RAIL_EnableTxHoldOff ( RAIL_Handle_t railHandle, bool enable)
	Prevent the radio from starting a transmit.

bool	RAIL_IsTxHoldOffEnabled ( RAIL_Handle_t railHandle)
	Check whether or not TX hold off is enabled.

RAIL_Status_t	RAIL_SetTxAltPreambleLength ( RAIL_Handle_t railHandle, uint16_t length)
	Set an alternate transmitter preamble length.

Detailed Description

APIs related to transmitting data packets.

Macro Definition Documentation

◆ RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA

#define RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA

Value:

         {                    \
        
          /* CSMA per 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by ZigBee     */
         
         \
        
          /* csmaMinBoExp */
         
         3,
         
          /* 2^3-1 for 0..7 backoffs on 1st try           */
         
         \
        
          /* csmaMaxBoExp */
         
         5,
         
          /* 2^5-1 for 0..31 backoffs on 3rd+ tries       */
         
         \
        
          /* csmaTries    */
         
         5,
         
          /* 5 tries overall (4 re-tries)                 */
         
         \
        
          /* ccaThreshold */
         
         -75,
         
          /* 10 dB above sensitivity                      */
         
         \
        
          /* ccaBackoff   */
         
         320,
         
          /* 20 symbols at 16 us/symbol                   */
         
         \
        
          /* ccaDuration  */
         
         128,
         
          /* 8 symbols at 16 us/symbol                    */
         
         \
        
          /* csmaTimeout  */
         
         0,
         
          /* No timeout                                   */
         
         \
        
         }

RAIL_CsmaConfig_t initializer configuring CSMA per IEEE 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by ZigBee.

Definition at line 2652 of file rail_types.h .

◆ RAIL_CSMA_CONFIG_SINGLE_CCA

#define RAIL_CSMA_CONFIG_SINGLE_CCA

Value:

         {                                          \
        
          /* Perform a single CCA after 'fixed' delay                             */
         
         \
        
          /* csmaMinBoExp */
         
         0,
         
          /* Used for fixed backoff                       */
         
         \
        
          /* csmaMaxBoExp */
         
         0,
         
          /* Used for fixed backoff                       */
         
         \
        
          /* csmaTries    */
         
         1,
         
          /* Single try                                   */
         
         \
        
          /* ccaThreshold */
         
         -75,
         
          /* Override if not desired choice               */
         
         \
        
          /* ccaBackoff   */
         
         0,
         
          /* No backoff (override with fixed value)       */
         
         \
        
          /* ccaDuration  */
         
         128,
         
          /* Override if not desired length               */
         
         \
        
          /* csmaTimeout  */
         
         0,
         
          /* no timeout                                   */
         
         \
        
         }

RAIL_CsmaConfig_t initializer configuring a single CCA prior to TX.

It can be used to as a basis for implementing other channel access schemes with custom backoff delays. Users can override ccaBackoff with a fixed delay on each use.

Definition at line 2670 of file rail_types.h .

◆ RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1

#define RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1

Value:

         {                                \
        
          /* LBT per ETSI 300 220-1 V2.4.1                                        */
         
         \
        
          /* LBT time = random backoff of 0-5 ms in .5 ms increments plus 5 ms fixed */
         
         \
        
          /* lbtMinBoRand */
         
         0,
         
          /*                                             */
         
         \
        
          /* lbtMaxBoRand */
         
         10,
         
          /*                                             */
         
         \
        
          /* lbtTries     */
         
          RAIL_MAX_LBT_TRIES
         
         ,
         
          /* the maximum supported         */
         
         \
        
          /* lbtThreshold */
         
         -87,
         
          /*                                             */
         
         \
        
          /* lbtBackoff   */
         
         500,
         
          /* 0.5 ms                                      */
         
         \
        
          /* lbtDuration  */
         
         5000,
         
          /* 5 ms                                        */
         
         \
        
          /* lbtTimeout   */
         
         0,
         
          /* No timeout (recommend user override)        */
         
         \
        
         }

RAIL_LbtConfig_t initializer configuring LBT per ETSI 300 220-1 V2.4.1 for a typical Sub-GHz band.

To be practical, users should override lbtTries and/or lbtTimeout so channel access failure will be reported in a reasonable time frame rather than the unbounded time frame ETSI defined.

Definition at line 2772 of file rail_types.h .

◆ RAIL_TX_OPTION_ALT_PREAMBLE_LEN

#define RAIL_TX_OPTION_ALT_PREAMBLE_LEN (1UL << RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT)

An option to dynamically set an alternate preamble length for the transmission.

If this option is not set, the pre-configured channel preamble length will be used.

Definition at line 2385 of file rail_types.h .

◆ RAIL_TX_OPTION_ANTENNA0

#define RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT)

An option to select antenna 0 for transmission.

If the antenna selection option is not set or if both antenna options are set, then the transmit will occur on either antenna depending on the last receive or transmit selection. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna() .

Note: These TX antenna options do not control the antenna used for Auto-ACK transmissions, which always occur on the same antenna used to receive the packet being acknowledged.

Definition at line 2367 of file rail_types.h .

◆ RAIL_TX_OPTION_ANTENNA1

#define RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT)

An option to select antenna 1 for transmission.

If the antenna selection option is not set or if both antenna options are set, then the transmit will occur on either antenna depending on the last receive or transmit selection. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna() .

Note: These TX antenna options do not control the antenna used for Auto-ACK transmissions, which always occur on the same antenna used to receive the packet being acknowledged.

Definition at line 2379 of file rail_types.h .

◆ RAIL_TX_OPTION_CCA_ONLY

#define RAIL_TX_OPTION_CCA_ONLY (1UL << RAIL_TX_OPTION_CCA_ONLY_SHIFT)

An option to only perform the CCA (CSMA/LBT) operation but not automatically transmit if the channel is clear.

Application can then use the RAIL_EVENT_TX_CHANNEL_CLEAR to initiate transmit manually, e.g., giving it the opportunity to adjust outgoing packet data before the packet goes out.

Note: Configured state transitions to Rx or Idle are suspended during this CSMA/LBT operation. If packet reception occurs, the radio will return to the state it was in just prior to the CSMA/LBT operation when that reception (including any AutoACK response) is complete.

Definition at line 2408 of file rail_types.h .

◆ RAIL_TX_OPTION_CCA_PEAK_RSSI

#define RAIL_TX_OPTION_CCA_PEAK_RSSI (1UL << RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT)

An option to use peak rather than average RSSI energy detected during CSMA's RAIL_CsmaConfig_t::ccaDuration or LBT's RAIL_LbtConfig_t::lbtDuration to determine whether the channel is clear or busy.

Note: This option does nothing on platforms like EFR32XG1 that lack support for capturing peak RSSI energy.

Definition at line 2394 of file rail_types.h .

◆ RAIL_TX_OPTION_REMOVE_CRC

#define RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT)

An option to remove CRC bytes from TX packets.

To receive packets when the sender has this option set true, set RAIL_RX_OPTION_IGNORE_CRC_ERRORS on the receive side.

Definition at line 2345 of file rail_types.h .

◆ RAIL_TX_OPTION_RESEND

#define RAIL_TX_OPTION_RESEND (1UL << RAIL_TX_OPTION_RESEND_SHIFT)

An option to resend packet at the beginning of the Transmit FIFO.

The packet to be resent must have been previously provided by RAIL_SetTxFifo() or RAIL_WriteTxFifo() passing true for the latter's reset parameter. It works by setting the transmit FIFO's read offset to the beginning of the FIFO while leaving its write offset intact. For this to work, RAIL_DataConfig_t::txMethod must be RAIL_DataMethod_t::PACKET_MODE (i.e., the packet can't exceed the Transmit FIFO's size), otherwise undefined behavior will result.

This option can also be used with RAIL_SetNextTxRepeat() to cause the repeated packet(s) to all be the same as the first.

Definition at line 2425 of file rail_types.h .

◆ RAIL_TX_OPTION_SYNC_WORD_ID

#define RAIL_TX_OPTION_SYNC_WORD_ID (1UL << RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT)

An option to select which sync word to send (0 or 1).

This does not set the actual sync words, it just picks which of the two will be sent with the outgoing packet. Setting to 0 will transmit on SYNC1. Setting to 1 will transmit on SYNC2.

Note: There are a few special radio configurations (e.g. BLE Viterbi) that do not support transmitting different sync words.

Definition at line 2355 of file rail_types.h .

◆ RAIL_TX_OPTION_WAIT_FOR_ACK

#define RAIL_TX_OPTION_WAIT_FOR_ACK (1UL << RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT)

An option to configure whether or not the TXing node will listen for an ACK.

If this is false, the isAck flag in RAIL_RxPacketDetails_t of a received packet will always be false.

Definition at line 2339 of file rail_types.h .

◆ RAIL_TX_OPTIONS_ALL

#define RAIL_TX_OPTIONS_ALL 0xFFFFFFFFUL

A value representing all possible options.

Definition at line 2428 of file rail_types.h .

◆ RAIL_TX_OPTIONS_DEFAULT

#define RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE

All options disabled by default.

This is the fastest TX option to apply.

Definition at line 2333 of file rail_types.h .

◆ RAIL_TX_OPTIONS_NONE

#define RAIL_TX_OPTIONS_NONE 0UL

A value representing no options enabled.

Definition at line 2331 of file rail_types.h .

◆ RAIL_TX_REPEAT_INFINITE_ITERATIONS

#define RAIL_TX_REPEAT_INFINITE_ITERATIONS (0xFFFFU)

RAIL_TxRepeatConfig_t::iterations initializer configuring infinite repeated transmissions.

Definition at line 4348 of file rail_types.h .

◆ RAIL_TX_REPEAT_OPTIONS_DEFAULT

#define RAIL_TX_REPEAT_OPTIONS_DEFAULT RAIL_TX_REPEAT_OPTIONS_NONE

All repeat options disabled by default.

Definition at line 4301 of file rail_types.h .

◆ RAIL_TX_REPEAT_OPTIONS_NONE

#define RAIL_TX_REPEAT_OPTIONS_NONE 0U

A value representing no repeat options enabled.

Definition at line 4299 of file rail_types.h .

Enumeration Type Documentation

◆ RAIL_ScheduledTxDuringRx_t

enum RAIL_ScheduledTxDuringRx_t

Enumerates the possible outcomes of what will occur if a scheduled TX ends up firing during RX.

Because RX and TX can't happen at the same time, it is up to the user how the TX should be handled. This enumeration is passed into RAIL_StartScheduledTx() as part of RAIL_ScheduleTxConfig_t .

Enumerator
RAIL_SCHEDULED_TX_DURING_RX_POSTPONE_TX	The scheduled TX will be postponed until RX completes and then sent.
RAIL_SCHEDULED_TX_DURING_RX_ABORT_TX	The scheduled TX will be aborted and a RAIL_EVENT_TX_BLOCKED event will fire.

Definition at line 2459 of file rail_types.h .

◆ RAIL_StopMode_t

enum RAIL_StopMode_t

Stop radio operation options bit mask.

Enumerator
RAIL_STOP_MODE_ACTIVE_SHIFT	Shift position of RAIL_STOP_MODE_ACTIVE bit.
RAIL_STOP_MODE_PENDING_SHIFT	Shift position of RAIL_STOP_MODE_PENDING bit.

Definition at line 2287 of file rail_types.h .

◆ RAIL_TxOptions_t

enum RAIL_TxOptions_t

Transmit options, in reality a bitmask.

Enumerator
RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT	Shift position of RAIL_TX_OPTION_WAIT_FOR_ACK bit.
RAIL_TX_OPTION_REMOVE_CRC_SHIFT	Shift position of RAIL_TX_OPTION_REMOVE_CRC bit.
RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT	Shift position of RAIL_TX_OPTION_SYNC_WORD_ID bit.
RAIL_TX_OPTION_ANTENNA0_SHIFT	Shift position of RAIL_TX_OPTION_ANTENNA0 bit.
RAIL_TX_OPTION_ANTENNA1_SHIFT	Shift position of RAIL_TX_OPTION_ANTENNA1 bit.
RAIL_TX_OPTION_ALT_PREAMBLE_LEN_SHIFT	Shift position of RAIL_TX_OPTION_ALT_PREAMBLE_LEN bit.
RAIL_TX_OPTION_CCA_PEAK_RSSI_SHIFT	Shift position of RAIL_TX_OPTION_CCA_PEAK_RSSI bit.
RAIL_TX_OPTION_CCA_ONLY_SHIFT	Shift position of RAIL_TX_OPTION_CCA_ONLY bit.
RAIL_TX_OPTION_RESEND_SHIFT	Shift position of RAIL_TX_OPTION_RESEND bit.
RAIL_TX_OPTIONS_COUNT	A count of the choices in this enumeration.

Definition at line 2307 of file rail_types.h .

◆ RAIL_TxRepeatOptions_t

enum RAIL_TxRepeatOptions_t

Transmit repeat options, in reality a bitmask.

Enumerator
RAIL_TX_REPEAT_OPTION_HOP_SHIFT	Shift position of RAIL_TX_REPEAT_OPTION_HOP bit.

Definition at line 4293 of file rail_types.h .

Function Documentation

◆ RAIL_EnableTxHoldOff()

void RAIL_EnableTxHoldOff	(	RAIL_Handle_t	`railHandle,`
		bool	`enable`
	)

Prevent the radio from starting a transmit.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`enable`	Enable/Disable TX hold off.

Enable TX hold off to prevent the radio from starting any transmits. Disable TX hold off to allow the radio to transmit again. Attempting to transmit with the TX hold off enabled will result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.

Note: This function does not affect a transmit that has already started. To stop an already-started transmission, use RAIL_Idle() with RAIL_IDLE_ABORT .

◆ RAIL_GetTxPacketDetails()

RAIL_Status_t RAIL_GetTxPacketDetails	(	RAIL_Handle_t	`railHandle,`
		RAIL_TxPacketDetails_t *	`pPacketDetails`
	)

Get detailed information about the last packet transmitted.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in,out]	`pPacketDetails`	An application-provided pointer to store RAIL_TxPacketDetails_t corresponding to the transmit event. The isAck and timeSent fields totalPacketBytes and timePosition must be initialized prior to each call: isAck true to obtain details about the most recent ACK transmit, false to obtain details about the most recent app-initiated transmit. totalPacketBytes with the total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes sent over the air after the Preamble and Sync word(s), including CRC bytes. timePosition with a RAIL_PacketTimePosition_t value specifying the packet position to put in the timeSent field on return. This field will also be updated with the actual position corresponding to the timeSent value filled in.

Returns: RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

Note: Consider using RAIL_GetTxPacketDetailsAlt2 for smaller code size.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

◆ RAIL_GetTxPacketDetailsAlt()

RAIL_Status_t RAIL_GetTxPacketDetailsAlt	(	RAIL_Handle_t	`railHandle,`
		bool	`isAck,`
		RAIL_Time_t *	`pPacketTime`
	)

Get detailed information about the last packet transmitted.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`isAck`	True to obtain details about the most recent ACK transmit. False to obtain details about the most recent app-initiated transmit.
[out]	`pPacketTime`	An application-provided non-NULL pointer to store a RAIL_Time_t corresponding to the transmit event. This will be populated with a timestamp corresponding to an arbitrary location in the packet. Call RAIL_GetTxTimePreambleStart , RAIL_GetTxTimeSyncWordEnd , or RAIL_GetTxTimeFrameEnd to adjust the timestamp for different locations in the packet.

Returns: RAIL_STATUS_NO_ERROR if pPacketTime was filled in, or an appropriate error code otherwise.

Note: Consider using RAIL_GetTxPacketDetailsAlt2 to pass in a RAIL_PacketTimeStamp_t structure instead of a RAIL_Time_t structure, particularly when RAIL_PacketTimePosition_t information is needed or useful.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

◆ RAIL_GetTxPacketDetailsAlt2()

RAIL_Status_t RAIL_GetTxPacketDetailsAlt2	(	RAIL_Handle_t	`railHandle,`
		RAIL_TxPacketDetails_t *	`pPacketDetails`
	)

Get detailed information about the last packet transmitted.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in,out]	`pPacketDetails`	An application-provided pointer to store RAIL_TxPacketDetails_t corresponding to the transmit event. The isAck must be initialized prior to each call: isAck true to obtain details about the most recent ACK transmit, false to obtain details about the most recent app-initiated transmit. The timeSent field packetTime will be populated with a timestamp corresponding to a default location in the packet. The timeSent field timePosition will be populated with a RAIL_PacketTimePosition_t value specifying that default packet location. Call RAIL_GetTxTimePreambleStartAlt , RAIL_GetTxTimeSyncWordEndAlt , or RAIL_GetTxTimeFrameEndAlt to adjust the timestamp for different locations in the packet.

Returns: RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

◆ RAIL_GetTxTimeFrameEnd()

RAIL_Status_t RAIL_GetTxTimeFrameEnd	(	RAIL_Handle_t	`railHandle,`
		uint16_t	`totalPacketBytes,`
		RAIL_Time_t *	`pPacketTime`
	)

Adjust a RAIL TX timestamp to refer to the end of frame.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes.
[in,out]	`pPacketTime`	The time that was returned in a RAIL_Time_t from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that this packet finished on air. Must be non-NULL.

Returns: RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

◆ RAIL_GetTxTimeFrameEndAlt()

RAIL_Status_t RAIL_GetTxTimeFrameEndAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_TxPacketDetails_t *	`pPacketDetails`
	)

Adjust a RAIL TX timestamp to refer to the end of frame.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in,out]	`pPacketDetails`	The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that this packet finished on air. Must be non-NULL.

Returns: RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

◆ RAIL_GetTxTimePreambleStart()

RAIL_Status_t RAIL_GetTxTimePreambleStart	(	RAIL_Handle_t	`railHandle,`
		uint16_t	`totalPacketBytes,`
		RAIL_Time_t *	`pPacketTime`
	)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the transmitted packet for RAIL to use when adjusting the provided timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below).
[in,out]	`pPacketTime`	This points to the RAIL_Time_t returned from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. That time will be updated with the time that the preamble for this packet started on air. Must be non-NULL.

Returns: RAIL_STATUS_NO_ERROR if pPacketTime was successfully determined or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, totalPacketBytes must be RAIL_TX_STARTED_BYTES , and pPacketTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt() ).

◆ RAIL_GetTxTimePreambleStartAlt()

RAIL_Status_t RAIL_GetTxTimePreambleStartAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_TxPacketDetails_t *	`pPacketDetails`
	)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in,out]	`pPacketDetails`	The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that the preamble for this packet started on air.

Returns: RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, the timeSent field totalPacketBytes must be RAIL_TX_STARTED_BYTES , and the timeSent field packetTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt2() ).

◆ RAIL_GetTxTimeSyncWordEnd()

RAIL_Status_t RAIL_GetTxTimeSyncWordEnd	(	RAIL_Handle_t	`railHandle,`
		uint16_t	`totalPacketBytes,`
		RAIL_Time_t *	`pPacketTime`
	)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes.
[in,out]	`pPacketTime`	The time that was returned in a RAIL_Time_t from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

Returns: RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

◆ RAIL_GetTxTimeSyncWordEndAlt()

RAIL_Status_t RAIL_GetTxTimeSyncWordEndAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_TxPacketDetails_t *	`pPacketDetails`
	)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in,out]	`pPacketDetails`	The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

Returns: RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

◆ RAIL_IsTxHoldOffEnabled()

bool RAIL_IsTxHoldOffEnabled ( RAIL_Handle_t railHandle )

Check whether or not TX hold off is enabled.

Parameters

[in] railHandle A RAIL instance handle.

Returns: Returns true if TX hold off is enabled, false otherwise.

TX hold off can be enabled/disabled using RAIL_EnableTxHoldOff . Attempting to transmit with the TX hold off enabled will block the transmission and result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.

◆ RAIL_SetCcaThreshold()

RAIL_Status_t RAIL_SetCcaThreshold	(	RAIL_Handle_t	`railHandle,`
		int8_t	`ccaThresholdDbm`
	)

Set the CCA threshold in dBm.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`ccaThresholdDbm`	The CCA threshold in dBm.

Returns: Status code indicating success of the function call.

Unlike RAIL_StartCcaCsmaTx() or RAIL_StartCcaLbtTx() , which can cause a transmit, this function only modifies the CCA threshold. A possible use case for this function involves setting the CCA threshold to invalid RSSI of -128 which blocks transmission by preventing clear channel assessments from succeeding.

◆ RAIL_SetTxAltPreambleLength()

RAIL_Status_t RAIL_SetTxAltPreambleLength	(	RAIL_Handle_t	`railHandle,`
		uint16_t	`length`
	)

Set an alternate transmitter preamble length.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`length`	The desired preamble length, in bits.

Returns: Status code indicating success of the function call.

Note: Attempting to set a preamble length of 0xFFFF bits will result in RAIL_STATUS_INVALID_PARAMETER .

◆ RAIL_StopTx()

RAIL_Status_t RAIL_StopTx	(	RAIL_Handle_t	`railHandle,`
		RAIL_StopMode_t	`mode`
	)

Stop an active or pending transmit.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`mode`	Configure the types of transmits to stop.

Returns: RAIL_STATUS_NO_ERROR if the transmit was successfully canceled. Returns RAIL_STATUS_INVALID_STATE if the requested transmit mode cannot be stopped.

Note: This function will stop an auto-ACK in active transmit.

Transmit RAIL API

Modules

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RAIL_CSMA_CONFIG_802_15_4_2003_2p4_GHz_OQPSK_CSMA

◆ RAIL_CSMA_CONFIG_SINGLE_CCA

◆ RAIL_LBT_CONFIG_ETSI_EN_300_220_1_V2_4_1

◆ RAIL_TX_OPTION_ALT_PREAMBLE_LEN

◆ RAIL_TX_OPTION_ANTENNA0

◆ RAIL_TX_OPTION_ANTENNA1

◆ RAIL_TX_OPTION_CCA_ONLY

◆ RAIL_TX_OPTION_CCA_PEAK_RSSI

◆ RAIL_TX_OPTION_REMOVE_CRC

◆ RAIL_TX_OPTION_RESEND

◆ RAIL_TX_OPTION_SYNC_WORD_ID

◆ RAIL_TX_OPTION_WAIT_FOR_ACK

◆ RAIL_TX_OPTIONS_ALL

◆ RAIL_TX_OPTIONS_DEFAULT

◆ RAIL_TX_OPTIONS_NONE

◆ RAIL_TX_REPEAT_INFINITE_ITERATIONS

◆ RAIL_TX_REPEAT_OPTIONS_DEFAULT

◆ RAIL_TX_REPEAT_OPTIONS_NONE

Enumeration Type Documentation

◆ RAIL_ScheduledTxDuringRx_t

◆ RAIL_StopMode_t

◆ RAIL_TxOptions_t

◆ RAIL_TxRepeatOptions_t

Function Documentation

◆ RAIL_EnableTxHoldOff()

◆ RAIL_GetTxPacketDetails()

◆ RAIL_GetTxPacketDetailsAlt()

◆ RAIL_GetTxPacketDetailsAlt2()

◆ RAIL_GetTxTimeFrameEnd()

◆ RAIL_GetTxTimeFrameEndAlt()

◆ RAIL_GetTxTimePreambleStart()

◆ RAIL_GetTxTimePreambleStartAlt()

◆ RAIL_GetTxTimeSyncWordEnd()

◆ RAIL_GetTxTimeSyncWordEndAlt()

◆ RAIL_IsTxHoldOffEnabled()

◆ RAIL_SetCcaThreshold()

◆ RAIL_SetTxAltPreambleLength()

◆ RAIL_StopTx()

Transmit
RAIL API