Transmit
APIs related to transmitting data packets.
Modules | |
Power Amplifier (PA) | |
APIs for interacting with one of the on chip PAs. |
Data Structures | |
struct | RAIL_TxPacketDetails_t |
Detailed information requested and about the packet that was just transmitted. | |
struct | RAIL_ScheduleTxConfig_t |
Configuration structure for a scheduled transmit. | |
struct | RAIL_CsmaConfig_t |
Configuration structure for the CSMA transmit algorithm. | |
struct | RAIL_LbtConfig_t |
Configuration structure for the LBT transmit algorithm. |
Macros | |
#define | RAIL_TX_OPTIONS_NONE 0UL |
Value representing no options enabled. | |
#define | RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE |
Default is all options disabled. | |
#define | RAIL_TX_OPTION_WAIT_FOR_ACK (1UL << RAIL_TX_OPTION_WAIT_FOR_ACK_SHIFT) |
Option to configure whether or not the TX'ing node will listen for an ACK. | |
#define | RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT) |
Option to remove crc bytes from tx packets. | |
#define | RAIL_TX_OPTION_SYNC_WORD_ID (1UL << RAIL_TX_OPTION_SYNC_WORD_ID_SHIFT) |
Option to select which sync word to send (0 or 1). | |
#define | RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT) |
Option to select antenna 0 for transmission. | |
#define | RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT) |
Option to select antenna 1 for transmission. | |
#define | RAIL_TX_OPTIONS_ALL 0xFFFFFFFFUL |
Value representing all possible options. | |
#define | RAIL_MAX_LBT_TRIES 15 |
The maximum number of LBT/CSMA retries supported. | |
#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. |
Enumerations | |
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 } |
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. |
Functions | |
RAIL_Status_t | RAIL_SetTxPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t power) |
Sets the TX power in terms of deci-dBm instead of raw power level. | |
RAIL_TxPower_t | RAIL_GetTxPowerDbm (RAIL_Handle_t railHandle) |
Gets the TX power in terms of deci-dBm instead of raw power level. | |
RAIL_Status_t | RAIL_StartTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_SchedulerInfo_t *schedulerInfo) |
Start a non-blocking transmit. | |
RAIL_Status_t | RAIL_StartScheduledTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *config, const RAIL_SchedulerInfo_t *schedulerInfo) |
Send a packet on a schedule, instead of immediately. | |
RAIL_Status_t | RAIL_StartCcaCsmaTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_CsmaConfig_t *csmaConfig, const RAIL_SchedulerInfo_t *schedulerInfo) |
Start a non-blocking Transmit using CSMA. | |
RAIL_Status_t | RAIL_StartCcaLbtTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_LbtConfig_t *lbtConfig, const RAIL_SchedulerInfo_t *schedulerInfo) |
Start a non-blocking Transmit using LBT. | |
RAIL_Status_t | RAIL_SetCcaThreshold (RAIL_Handle_t railHandle, int8_t ccaThresholdDbm) |
Sets the CCA threshold in dBm. | |
RAIL_Status_t | RAIL_GetTxPacketDetails (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails) |
Gets detailed information about the last packet transmitted. | |
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. |
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 |
RAIL_CsmaConfig_t initializer configuring CSMA per IEEE 802.15.4-2003 on 2.4 GHz OSPSK, commonly used by ZigBee.
Definition at line 1638
of file rail_types.h
.
◆ RAIL_CSMA_CONFIG_SINGLE_CCA
#define RAIL_CSMA_CONFIG_SINGLE_CCA |
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. User can override ccaBackoff with a fixed delay on each use.
Definition at line 1656
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 |
rail_types.h:1587
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 1720
of file rail_types.h
.
◆ RAIL_TX_OPTION_ANTENNA0
#define RAIL_TX_OPTION_ANTENNA0 (1UL << RAIL_TX_OPTION_ANTENNA0_SHIFT) |
Option to select antenna 0 for transmission.
If not antenna selection option is set or if both antenna options are set, then the TX will take place in either antenna depending on the last RX or TX configuration. This option is only valid on platforms that support antenna selection.
Definition at line 1507
of file rail_types.h
.
◆ RAIL_TX_OPTION_ANTENNA1
#define RAIL_TX_OPTION_ANTENNA1 (1UL << RAIL_TX_OPTION_ANTENNA1_SHIFT) |
Option to select antenna 1 for transmission.
If not antenna selection option is set or if both antenna options are set, then the TX will take place in either antenna depending on the last RX or TX configuration. This option is only valid on platforms that support antenna selection.
Definition at line 1515
of file rail_types.h
.
◆ RAIL_TX_OPTION_REMOVE_CRC
#define RAIL_TX_OPTION_REMOVE_CRC (1UL << RAIL_TX_OPTION_REMOVE_CRC_SHIFT) |
Option to remove crc bytes from tx packets.
If you want to be able to receive packets with this option set as true, you'll need to set the IGNORE_CRC_ERRORS option on the receive side.
Definition at line 1493
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) |
Option to select which sync word to send (0 or 1).
Note that this does not set the actual sync words, it just picks which of the two will be sent with the packet.
Definition at line 1499
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) |
Option to configure whether or not the TX'ing 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 1487
of file rail_types.h
.
◆ RAIL_TX_OPTIONS_DEFAULT
#define RAIL_TX_OPTIONS_DEFAULT RAIL_TX_OPTIONS_NONE |
Default is all options disabled.
Definition at line 1481
of file rail_types.h
.
◆ RAIL_TX_OPTIONS_NONE
#define RAIL_TX_OPTIONS_NONE 0UL |
Value representing no options enabled.
Definition at line 1479
of file rail_types.h
.
Enumeration Type Documentation
◆ 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.
Definition at line 1548
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. |
Definition at line 1465
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.
- Returns
- void.
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 |
||
) |
Gets 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.
This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.
◆ RAIL_GetTxPowerDbm()
RAIL_TxPower_t RAIL_GetTxPowerDbm | ( | RAIL_Handle_t | railHandle | ) |
Gets the TX power in terms of deci-dBm instead of raw power level.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- The current output power in deci-dBm
This is a utility function crafted for user convenience. Normally, to get TX power in dBm, the user would have to do the following:
This function wraps all those calls in a single function with power returned as the result.
◆ 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 |
||
) |
Sets 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 is to set the CCA threshold to invalid RSSI of -128 which blocks transmission by preventing clear channel assessments from succeeding.
◆ RAIL_SetTxPowerDbm()
RAIL_Status_t RAIL_SetTxPowerDbm | ( | RAIL_Handle_t | railHandle, |
RAIL_TxPower_t | power |
||
) |
Sets the TX power in terms of deci-dBm instead of raw power level.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] power
Desired deci-dBm power to be set.
- Returns
- RAIL Status variable indicate whether setting the power was successful.
This is a utility function crafted for user convenience. Normally, to set TX power in dBm, the user would have to do the following:
This function wraps all those calls in a single function with power passed in as a parameter.
◆ RAIL_StartCcaCsmaTx()
RAIL_Status_t RAIL_StartCcaCsmaTx | ( | RAIL_Handle_t | railHandle, |
uint16_t | channel, |
||
RAIL_TxOptions_t | options, |
||
const RAIL_CsmaConfig_t * | csmaConfig, |
||
const RAIL_SchedulerInfo_t * | schedulerInfo |
||
) |
Start a non-blocking Transmit using CSMA.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] channel
Define the channel to transmit on. [in] options
TX options to be applied to this transmit only. [in] csmaConfig
A pointer to the RAIL_CsmaConfig_t structure describing the CSMA parameters to use for this transmit. [in] schedulerInfo
Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.
- Returns
- Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
First performs the Carrier Sense Multiple Access (CSMA) algorithm and if the channel is deemed clear (RSSI below the specified threshold) it will commence transmission of the payload previously loaded via RAIL_WriteTxFifo(). Packets can be received during CSMA backoff periods if receive is active throughout the CSMA process. This will happen either by starting the CSMA process while receive is already active, or if the csmaBackoff time in the RAIL_CsmaConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the csmaBackoff time is greater than the idleToRx time, then receive will only be active during CSMA's clear channel assessments.
If the CSMA algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the TX FIFO remain intact, untouched.
Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.
In multiprotocol you must ensure that you properly yield the radio after this operation completes. See Yielding the radio for more details.
◆ RAIL_StartCcaLbtTx()
RAIL_Status_t RAIL_StartCcaLbtTx | ( | RAIL_Handle_t | railHandle, |
uint16_t | channel, |
||
RAIL_TxOptions_t | options, |
||
const RAIL_LbtConfig_t * | lbtConfig, |
||
const RAIL_SchedulerInfo_t * | schedulerInfo |
||
) |
Start a non-blocking Transmit using LBT.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] channel
Define the channel to transmit on. [in] options
TX options to be applied to this transmit only. [in] lbtConfig
A pointer to the RAIL_LbtConfig_t structure describing the LBT parameters to use for this transmit. [in] schedulerInfo
Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.
- Returns
- Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
First performs the Listen Before Talk (LBT) algorithm and if the channel is deemed clear (RSSI below the specified threshold) it will commence transmission of the payload previously loaded via RAIL_WriteTxFifo(). Packets can be received during LBT backoff periods if receive is active throughout the LBT process. This will happen either by starting the LBT process while receive is already active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the lbtBackoff time is greater than the idleToRx time, then receive will only be active during LBT's clear channel assessments.
If the LBT algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the TX FIFO remain intact, untouched.
Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.
In multiprotocol you must ensure that you properly yield the radio after this operation completes. See Yielding the radio for more details.
◆ RAIL_StartScheduledTx()
RAIL_Status_t RAIL_StartScheduledTx | ( | RAIL_Handle_t | railHandle, |
uint16_t | channel, |
||
RAIL_TxOptions_t | options, |
||
const RAIL_ScheduleTxConfig_t * | config, |
||
const RAIL_SchedulerInfo_t * | schedulerInfo |
||
) |
Send a packet on a schedule, instead of immediately.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] channel
Define the channel to transmit on. [in] options
TX options to be applied to this transmit only. [in] config
A pointer to the RAIL_ScheduleTxConfig_t structure containing when the transmit should occur. [in] schedulerInfo
Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.
- Returns
- Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
Will begin transmission of the payload previously loaded via RAIL_WriteTxFifo() at the scheduled time. The time (in microseconds) as well as whether that time is absolute or relative, is specified using the RAIL_ScheduleTxConfig_t structure. Also specified in this structure is what to do if a scheduled transmit fires in the midst of receiving a packet.
Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.
In multiprotocol you must ensure that you properly yield the radio after this operation completes. See Yielding the radio for more details.
◆ RAIL_StartTx()
RAIL_Status_t RAIL_StartTx | ( | RAIL_Handle_t | railHandle, |
uint16_t | channel, |
||
RAIL_TxOptions_t | options, |
||
const RAIL_SchedulerInfo_t * | schedulerInfo |
||
) |
Start a non-blocking transmit.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] channel
Define the channel to transmit on. [in] options
TX options to be applied to this transmit only. [in] schedulerInfo
Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.
- Returns
- Status code indicating success of the function call. If successfully initiated, transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
Will begin transmission of the payload previously loaded via RAIL_WriteTxFifo() immediately, or right after a packet currently being received is completed.
Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.
In multiprotocol you must ensure that you properly yield the radio after this operation completes. See Yielding the radio for more details.