Auto-ACK#

RAIL_ConfigAutoAck#

RAIL_Status_t RAIL_ConfigAutoAck (RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t * config)

Configure and enable automatic acknowledgment.

Returns

• Status code indicating success of the function call.

Configures the RAIL state machine to for hardware-accelerated automatic acknowledgment. ACK timing parameters are defined in the configuration structure.

While auto-ACKing is enabled, do not call the following RAIL functions:

• RAIL_SetRxTransitions()

• RAIL_SetTxTransitions()

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, which can be either RAIL_RF_STATE_RX or RAIL_RF_STATE_IDLE (returning to RAIL_RF_STATE_TX is not supported). 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:

void setAutoAckStateTimings()
{
  RAIL_StateTiming_t timings;

  // User is already in auto-ACK and wants a turnaround of 192 us.
  timings.rxToTx = 192;
  timings.txToRx = 192 - 10;

  // Set other fields of timings...
  timings.idleToRx = 100;
  timings.idleToTx = 100;
  timings.rxSearchTimeout = 0;
  timings.txToRxSearchTimeout = 0;

  RAIL_SetStateTiming(railHandle, &timings);
}

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.

Note

• Auto-ACKing may not be enabled while RX Channel Hopping is enabled, or when BLE is enabled.

RAIL_IsAutoAckEnabled#

bool RAIL_IsAutoAckEnabled (RAIL_Handle_t railHandle)

Return the enable status of the auto-ACK feature.

Returns

• true if auto-ACK is enabled, false if disabled.

RAIL_WriteAutoAckFifo#

RAIL_Status_t RAIL_WriteAutoAckFifo (RAIL_Handle_t railHandle, const uint8_t * ackData, uint8_t ackDataLen)

Load the auto-ACK buffer with 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. If it is not available, RAIL_STATUS_INVALID_STATE is returned. If ackDataLen exceeds RAIL_AUTOACK_MAX_LENGTH then RAIL_STATUS_INVALID_PARAMETER will be returned and nothing is written to the ACK buffer (unless ackData is NULL in which case this indicates the application has already likely corrupted RAM).

RAIL_GetAutoAckFifo#

RAIL_Status_t RAIL_GetAutoAckFifo (RAIL_Handle_t railHandle, uint8_t ** ackBuffer, uint16_t * ackBufferBytes)

Get the address and size of the auto-ACK buffer for direct access.

Returns

• Status code indicating success of the function call.

Applications can use this to more flexibly write AutoAck data into the buffer directly and in pieces, passing NULL ackData parameter to RAIL_WriteAutoAckFifo() or RAIL_IEEE802154_WriteEnhAck() to inform RAIL of its final length.

RAIL_PauseRxAutoAck#

void RAIL_PauseRxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume RX auto-ACK functionality.

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.

RAIL_IsRxAutoAckPaused#

bool RAIL_IsRxAutoAckPaused (RAIL_Handle_t railHandle)

Return whether the RX auto-ACK is paused.

Returns

• true if RX auto-ACK is paused, false if not paused.

RAIL_PauseTxAutoAck#

void RAIL_PauseTxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume TX auto-ACK functionality.

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.

RAIL_IsTxAutoAckPaused#

bool RAIL_IsTxAutoAckPaused (RAIL_Handle_t railHandle)

Return whether the TX auto-ACK is paused.

Returns

• true if TX auto-ACK is paused, false if not paused.

RAIL_UseTxFifoForAutoAck#

RAIL_Status_t RAIL_UseTxFifoForAutoAck (RAIL_Handle_t railHandle)

Modify the upcoming ACK to use the Transmit FIFO.

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 Transmit FIFO as the data source for the upcoming ACK. The ACK modification to use the Transmit FIFO 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.

Note

• The Transmit FIFO must not be used for AutoACK when IEEE 802.15.4, Z-Wave, or BLE protocols are active.

RAIL_CancelAutoAck#

RAIL_Status_t RAIL_CancelAutoAck (RAIL_Handle_t railHandle)

Cancel the upcoming ACK.

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.

RAIL_IsAutoAckWaitingForAck#

bool RAIL_IsAutoAckWaitingForAck (RAIL_Handle_t railHandle)

Return whether the radio is currently waiting for an ACK.

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.

RAIL_AUTOACK_MAX_LENGTH#

#define RAIL_AUTOACK_MAX_LENGTH

(64U)

Acknowledgment packets cannot be longer than 64 bytes.