Auto-ACK#

APIs for configuring auto-ACK functionality.

These APIs configure the radio for automatic 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.

// Go to RX after ACK operation.
RAIL_AutoAckConfig_t autoAckConfig = {
  .enable = true,
  .ackTimeout = 1000,
  .rxTransitions = {
     .success = RAIL_RF_STATE_RX,
     .error   = RAIL_RF_STATE_RX
  },
  .txTransitions = {
     .success = RAIL_RF_STATE_RX,
     .error   = RAIL_RF_STATE_RX,
  },
};

RAIL_Status_t status = RAIL_ConfigAutoAck(railHandle, &autoAckConfig);

uint8_t ackData[] = {0x05, 0x02, 0x10, 0x00};

RAIL_Status_t status = RAIL_WriteAutoAckFifo(railHandle,
                                             ackData,
                                             sizeof(ackData));

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-auto-ACK mode, auto-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 suspend automatic acknowledgment of a series of packets after transmit or receive call RAIL_PauseTxAutoAck() or RAIL_PauseRxAutoAck() respectively with the pause parameter set to true. When auto-ACKing is paused, after receiving or transmitting a packet (regardless of success), the radio transitions to the same state it would use while ACKing. To return to normal state transition logic outside of ACKing, call RAIL_ConfigAutoAck() with the RAIL_AutoAckConfig_t::enable field false and specify the desired transitions in the RAIL_AutoAckConfig_t::rxTransitions and RAIL_AutoAckConfig_t::txTransitions fields. To get out of a paused state and resume auto-ACKing, call RAIL_PauseTxAutoAck() and/or RAIL_PauseRxAutoAck() with the pause parameter set to 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 option.

When Antenna Control is used for multiple antennas, ACKs are transmitted on the antenna that was selected to receive the packet being acknowledged. When receiving an ACK, the RAIL_RxOptions_t antenna options are used just like for any other receive.

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().

Modules#

RAIL_AutoAckConfig_t

Functions#

RAIL_ConfigAutoAck(RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t *config)

Configure and enable automatic acknowledgment.

bool
RAIL_IsAutoAckEnabled(RAIL_Handle_t railHandle)

Return the enable status of the auto-ACK feature.

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

Load the auto-ACK buffer with ACK data.

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

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

RAIL_PauseRxAutoAck(RAIL_Handle_t railHandle, bool pause)

Pause/resume RX auto-ACK functionality.

bool
RAIL_IsRxAutoAckPaused(RAIL_Handle_t railHandle)

Return whether the RX auto-ACK is paused.

RAIL_PauseTxAutoAck(RAIL_Handle_t railHandle, bool pause)

Pause/resume TX auto-ACK functionality.

bool
RAIL_IsTxAutoAckPaused(RAIL_Handle_t railHandle)

Return whether the TX auto-ACK is paused.

RAIL_UseTxFifoForAutoAck(RAIL_Handle_t railHandle)

Modify the upcoming ACK to use the transmit FIFO.

RAIL_CancelAutoAck(RAIL_Handle_t railHandle)

Cancel the upcoming ACK.

bool
RAIL_IsAutoAckWaitingForAck(RAIL_Handle_t railHandle)

Return whether the radio is currently waiting for an ACK.

Macros#

#define

Acknowledgment packets cannot be longer than 64 bytes.

Function Documentation#

RAIL_ConfigAutoAck#

RAIL_Status_t RAIL_ConfigAutoAck (RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t *config)

Configure and enable automatic acknowledgment.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to an Auto-ACK configuration structure.

Returns

  • Status code indicating success of the function call.

Configures the RAIL state machine 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() Indeed, when auto-ACKing is enabled, only one state transition can be defined (without notion of success or error). Thus if you are enabling auto-ACK (i.e., "config.enable" field is true) the "error" fields of config.rxTransitions and config.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). On the oppsite, if you are disabling auto-ACK (i.e., "config.enable" field is false), transitions are reconfigured using all fields of config.rxTransitions and config.txTransitions. 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(void)
{
  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.


Definition at line 4752 of file common/rail.h

RAIL_IsAutoAckEnabled#

bool RAIL_IsAutoAckEnabled (RAIL_Handle_t railHandle)

Return 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.


Definition at line 4761 of file common/rail.h

RAIL_WriteAutoAckFifo#

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

Load the auto-ACK buffer with ACK data.

Parameters
[in]railHandle

A RAIL instance handle.

[in]ackData

A pointer to ACK data to transmit. This may be NULL, in which case it's assumed the data has already been emplaced into the ACK buffer and RAIL just needs to be told how many bytes are there. Use RAIL_GetAutoAckFifo() to get the address of RAIL's auto-ACK buffer in RAM and its size.

[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. 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).


Definition at line 4782 of file common/rail.h

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 transmit buffer for direct access.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]ackBuffer

A pointer to a uint8_t pointer that will be updated to the RAM base address of the auto-ACK FIFO buffer.

[inout]ackBufferBytes

A pointer to a uint16_t that will be updated to the size of the auto-ACK FIFO buffer, in bytes, currently RAIL_AUTOACK_MAX_LENGTH.

Returns

  • Status code indicating success of the function call.

Applications can use this to more flexibly write auto-ACK 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.


Definition at line 4802 of file common/rail.h

RAIL_PauseRxAutoAck#

RAIL_Status_t RAIL_PauseRxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume RX auto-ACK functionality.

Parameters
[in]railHandle

A RAIL instance handle.

[in]pause

Pause or resume RX auto-ACKing.

Returns

  • Status code indicating success of the function call.

When RX auto-ACKing is paused, the radio transitions to RAIL_AutoAckConfig_t::rxTransitions's RAIL_StateTransitions_t::success 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.


Definition at line 4819 of file common/rail.h

RAIL_IsRxAutoAckPaused#

bool RAIL_IsRxAutoAckPaused (RAIL_Handle_t railHandle)

Return 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.


Definition at line 4828 of file common/rail.h

RAIL_PauseTxAutoAck#

RAIL_Status_t RAIL_PauseTxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume TX auto-ACK functionality.

Parameters
[in]railHandle

A RAIL instance handle.

[in]pause

Pause or resume TX auto-ACKing.

Returns

  • Status code indicating success of the function call.

When TX auto-ACKing is paused, the radio transitions to RAIL_AutoAckConfig_t::txTransitions's RAIL_StateTransitions_t::success 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.


Definition at line 4843 of file common/rail.h

RAIL_IsTxAutoAckPaused#

bool RAIL_IsTxAutoAckPaused (RAIL_Handle_t railHandle)

Return 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.


Definition at line 4851 of file common/rail.h

RAIL_UseTxFifoForAutoAck#

RAIL_Status_t RAIL_UseTxFifoForAutoAck (RAIL_Handle_t railHandle)

Modify the upcoming ACK to use the transmit FIFO.

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 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 auto-ACK when IEEE 802.15.4, Z-Wave, or BLE protocols are active.


Definition at line 4872 of file common/rail.h

RAIL_CancelAutoAck#

RAIL_Status_t RAIL_CancelAutoAck (RAIL_Handle_t railHandle)

Cancel 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.


Definition at line 4889 of file common/rail.h

RAIL_IsAutoAckWaitingForAck#

bool RAIL_IsAutoAckWaitingForAck (RAIL_Handle_t railHandle)

Return 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.


Definition at line 4901 of file common/rail.h

Macro Definition Documentation#

RAIL_AUTOACK_MAX_LENGTH#

#define RAIL_AUTOACK_MAX_LENGTH
Value:
(64U)

Acknowledgment packets cannot be longer than 64 bytes.


Definition at line 4435 of file common/rail_types.h