Auto ACK
APIs for configuring auto ACK functionality.
Data Structures |
|
struct | RAIL_AutoAckConfig_t |
Enables/disables the auto ACK algorithm, based on "enable".
|
Macros |
|
#define | RAIL_AUTOACK_MAX_LENGTH 64 |
Acknowledgment packets cannot be longer than 64 bytes.
|
Functions |
|
RAIL_Status_t | RAIL_ConfigAutoAck ( RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t *config) |
Configures and enables auto acknowledgment.
|
|
bool | RAIL_IsAutoAckEnabled ( RAIL_Handle_t railHandle) |
Returns the enable status of the auto ACK feature.
|
|
RAIL_Status_t | RAIL_WriteAutoAckFifo ( RAIL_Handle_t railHandle, const uint8_t *ackData, uint8_t ackDataLen) |
Loads the auto ACK buffer with ACK data.
|
|
void | RAIL_PauseRxAutoAck ( RAIL_Handle_t railHandle, bool pause) |
Pauses/resumes RX auto ACK functionality.
|
|
bool | RAIL_IsRxAutoAckPaused ( RAIL_Handle_t railHandle) |
Returns whether the RX auto ACK is paused.
|
|
void | RAIL_PauseTxAutoAck ( RAIL_Handle_t railHandle, bool pause) |
Pauses/resumes TX auto ACK functionality.
|
|
bool | RAIL_IsTxAutoAckPaused ( RAIL_Handle_t railHandle) |
Returns whether the TX auto ACK is paused.
|
|
RAIL_Status_t | RAIL_UseTxFifoForAutoAck ( RAIL_Handle_t railHandle) |
Modifies the upcoming ACK to use the TX Buffer.
|
|
RAIL_Status_t | RAIL_CancelAutoAck ( RAIL_Handle_t railHandle) |
Cancels the upcoming ACK.
|
|
bool | RAIL_IsAutoAckWaitingForAck ( RAIL_Handle_t railHandle) |
Returns whether the radio is currently waiting for an ACK.
|
Detailed Description
APIs for configuring auto ACK functionality.
These APIs are used to configure the radio for auto acknowledgment features. Auto ACK inherently changes how the underlying state machine behaves so users should not modify RAIL_SetRxTransitions() and RAIL_SetTxTransitions() while using auto ACK features.
The acknowledgment transmits based on the frame format configured via the Radio Configurator. For example, if the frame format is using a variable length scheme, the ACK will be sent according to that scheme. If a 10-byte packet is loaded into the ACK, but the variable length field of the ACK payload specifies a length of 5, only 5 bytes will transmit for the ACK. The converse is also true, if the frame length is configured to be a fixed 10-byte packet but only 5 bytes are loaded into the ACK buffer, a TX underflow occurs during the ACK transmit.
Unlike in non-ACK mode, ACK mode will always return to a single state after all ACK sequences complete, regardless of whether the ACK was successfully received/sent or not. See the documentation of RAIL_ConfigAutoAck for configuration information. To not auto acknowledge a series of packets after transmit or receive, call RAIL_PauseTxAutoAck(true) or RAIL_PauseRxAutoAck(true). When auto acking is paused, after receiving or transmitting (also regardless of success) a packet, the radio transitions to the same single state it always defaults to while acking. To return to normal state transition logic outside of acking, call RAIL_ConfigAutoAck with the "enable" field false and specify the desired transitions in the rxTransitions and txTransitions fields. To get out of a paused state and resume auto acking, call RAIL_PauseTxAutoAck(false) or RAIL_PauseRxAutoAck(false).
Applications can cancel the transmission of an ACK with RAIL_CancelAutoAck() . Conversely, applications can control if a transmit operation should wait for an ACK after transmitting by using the RAIL_TX_OPTION_WAIT_FOR_ACK bit.
If the ACK payload is dynamic, the application must call RAIL_WriteAutoAckFifo() with the appropriate ACK payload after the application processes the receive. RAIL can auto ACK from the normal transmit buffer if RAIL_UseTxFifoForAutoAck() is called before the radio transmits the ACK. Ensure the transmit buffer contains data loaded by RAIL_WriteTxFifo() .
Standard-based protocols that contain auto ACK functionality are normally configured in the protocol-specific configuration function. For example, RAIL_IEEE802154_Init() provides auto ACK configuration parameters in RAIL_IEEE802154_Config_t and should only be configured through that function. It is not advisable to call both RAIL_IEEE802154_Init() and RAIL_ConfigAutoAck() . However, ACK modification functions are still valid to use with protocol-specific ACKs. To cancel an IEEE 802.15.4 ACK transmit, use RAIL_CancelAutoAck() .
Function Documentation
RAIL_Status_t RAIL_CancelAutoAck | ( | RAIL_Handle_t |
railHandle
|
) |
Cancels the upcoming ACK.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- Status code indicating success of the function call. This call will fail if it is too late to modify the outgoing ACK.
This function allows the application to cancel the upcoming automatic acknowledgment.
This function only returns true if the following conditions are met:
- Radio has not already decided to transmit the ACK AND
- Radio is either looking for sync, receiving the packet after sync or in the Rx2Tx turnaround before the ACK is sent.
Referenced by
RAIL_CopyRxPacket()
.
RAIL_Status_t RAIL_ConfigAutoAck | ( | RAIL_Handle_t |
railHandle,
|
const RAIL_AutoAckConfig_t * |
config
|
||
) |
Configures and enables auto acknowledgment.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] config
Auto ACK configuration structure.
- Returns
- Status code indicating success of the function call.
Configures the RAIL state machine to for hardware-accelerated auto acknowledgment. ACK timing parameters are defined in the configuration structure.
While auto acking is enabled, do not call the following RAIL functions:
Note, that if you are enabling auto ACK (i.e., "enable" field is true) The "error" fields of rxTransitions and txTransitions are ignored. After all ACK sequences, (success or fail) the state machine will return the radio to the "success" state. If you need information about the actual success of the ACK sequence, use RAIL events such as RAIL_EVENT_TXACK_PACKET_SENT to make sure an ACK was sent, or RAIL_EVENT_RX_ACK_TIMEOUT to make sure that an ACK was received within the specified timeout.
To set a certain turnaround time (i.e., txToRx and rxToTx in RAIL_StateTiming_t ), make txToRx lower than desired to ensure you get to RX in time to receive the ACK. Silicon Labs recommends setting 10 us lower than desired:
As opposed to an explicit "Disable" API, set the "enable" field of the RAIL_AutoAckConfig_t to false. Then, auto ACK will be disabled and state transitions will be returned to the values set in RAIL_AutoAckConfig_t . When disabling, the "ackTimeout" field isn't used.
Referenced by
RAIL_CopyRxPacket()
.
bool RAIL_IsAutoAckEnabled | ( | RAIL_Handle_t |
railHandle
|
) |
Returns the enable status of the auto ACK feature.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- true if auto ACK is enabled, false if disabled.
Referenced by
RAIL_CopyRxPacket()
.
bool RAIL_IsAutoAckWaitingForAck | ( | RAIL_Handle_t |
railHandle
|
) |
Returns whether the radio is currently waiting for an ACK.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- True if radio is waiting for ACK, false if radio is not waiting for an ACK.
This function allows the application to query whether the radio is currently waiting for an ACK after a transmit operation.
Referenced by
RAIL_CopyRxPacket()
.
bool RAIL_IsRxAutoAckPaused | ( | RAIL_Handle_t |
railHandle
|
) |
Returns whether the RX auto ACK is paused.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- true if RX auto ACK is paused, false if not paused.
Referenced by
RAIL_CopyRxPacket()
.
bool RAIL_IsTxAutoAckPaused | ( | RAIL_Handle_t |
railHandle
|
) |
Returns whether the TX auto ACK is paused.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- true if TX auto ACK is paused, false if not paused.
Referenced by
RAIL_CopyRxPacket()
.
void RAIL_PauseRxAutoAck | ( | RAIL_Handle_t |
railHandle,
|
bool |
pause
|
||
) |
Pauses/resumes RX auto ACK functionality.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] pause
Pause or resume RX auto acking.
- Returns
- void.
When RX auto acking is paused, the radio transitions to default state after receiving a packet and does not transmit an ACK. When RX auto ACK is resumed, the radio resumes automatically acking every successfully received packet.
Referenced by
RAIL_CopyRxPacket()
.
void RAIL_PauseTxAutoAck | ( | RAIL_Handle_t |
railHandle,
|
bool |
pause
|
||
) |
Pauses/resumes TX auto ACK functionality.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] pause
Pause or resume TX auto acking.
- Returns
- void.
When TX auto acking is paused, the radio transitions to a default state after transmitting a packet and does not wait for an ACK. When TX auto ACK is resumed, the radio resumes automatically waiting for an ACK after a successful transmit.
Referenced by
RAIL_CopyRxPacket()
.
RAIL_Status_t RAIL_UseTxFifoForAutoAck | ( | RAIL_Handle_t |
railHandle
|
) |
Modifies the upcoming ACK to use the TX Buffer.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- Status code indicating success of the function call. The call will fail if it is too late to modify the outgoing ACK.
This function allows the application to use the normal TX buffer as the data source for the upcoming ACK. The ACK modification to use the TX buffer only applies to one ACK transmission.
This function only returns true if the following conditions are met:
- Radio has not already decided to use the ACK buffer AND
- Radio is either looking for sync, receiving the packet after sync, or in the Rx2Tx turnaround before the ACK is sent.
Referenced by
RAIL_CopyRxPacket()
.
RAIL_Status_t RAIL_WriteAutoAckFifo | ( | RAIL_Handle_t |
railHandle,
|
const uint8_t * |
ackData,
|
||
uint8_t |
ackDataLen
|
||
) |
Loads the auto ACK buffer with ACK data.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] ackData
A pointer to ACK data to transmit. [in] ackDataLen
The number of bytes in ACK data.
- Returns
- Status code indicating success of the function call.
If the ACK buffer is available for updates, load the ACK buffer with data.
Referenced by
RAIL_CopyRxPacket()
.