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 (64U)
	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 automatic 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 FIFO.

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 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,
      
        // "error" param ignored
       
       .rxTransitions = {
       
        RAIL_RF_STATE_RX
       
       ,
       
        RAIL_RF_STATE_RX
       
       },
      
        // "error" param ignored
       
       .txTransitions = {
       
        RAIL_RF_STATE_RX
       
       , 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
       
       (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(true) and resume by calling 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 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() .

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.

RAIL_Status_t RAIL_ConfigAutoAck	(	RAIL_Handle_t	`railHandle,`
		const RAIL_AutoAckConfig_t *	`config`
	)

Configures and enables automatic 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 automatic 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, 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.

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.

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.

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.

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.

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.

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.

RAIL_Status_t RAIL_UseTxFifoForAutoAck ( RAIL_Handle_t railHandle )

Modifies the upcoming ACK to use the TX 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 TX FIFO as the data source for the upcoming ACK. The ACK modification to use the TX 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 TX FIFO must not be used for AutoACK when IEEE 802.15.4, Z-Wave, or BLE protocols are active.

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.

Auto-ACK RAIL API

Data Structures

Macros

Functions

Detailed Description

Function Documentation

Auto-ACK
RAIL API