State Transitions

Data Structures

struct  RAIL_StateTransitions_t
 Used to specify radio states to transition to on success or failure.
 
struct  RAIL_StateTiming_t
 A timing configuration structure for the RAIL State Machine.

Enumerations

enum  RAIL_RadioState_t {
  RAIL_RF_STATE_INACTIVE = 0u,
  RAIL_RF_STATE_ACTIVE = (1u << 0),
  RAIL_RF_STATE_RX = (1u << 1),
  RAIL_RF_STATE_TX = (1u << 2),
  RAIL_RF_STATE_IDLE = (RAIL_RF_STATE_ACTIVE),
  RAIL_RF_STATE_RX_ACTIVE = (RAIL_RF_STATE_RX | RAIL_RF_STATE_ACTIVE),
  RAIL_RF_STATE_TX_ACTIVE = (RAIL_RF_STATE_TX | RAIL_RF_STATE_ACTIVE)
}
 The state of the radio.
 
enum  RAIL_IdleMode_t {
  RAIL_IDLE,
  RAIL_IDLE_ABORT,
  RAIL_IDLE_FORCE_SHUTDOWN,
  RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS
}
 An enumeration for the different types of supported idle modes.

Functions

RAIL_Status_t RAIL_SetRxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)
 Configure RAIL automatic state transitions after RX.
 
RAIL_Status_t RAIL_GetRxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)
 Get the current RAIL automatic state transitions after RX.
 
RAIL_Status_t RAIL_SetTxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)
 Configure RAIL automatic state transitions after TX.
 
RAIL_Status_t RAIL_GetTxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)
 Get the current RAIL automatic state transitions after TX.
 
RAIL_Status_t RAIL_SetStateTiming (RAIL_Handle_t railHandle, RAIL_StateTiming_t *timings)
 Configure RAIL automatic state transition timing.
 
void RAIL_Idle (RAIL_Handle_t railHandle, RAIL_IdleMode_t mode, bool wait)
 Place the radio into an idle state.
 
RAIL_RadioState_t RAIL_GetRadioState (RAIL_Handle_t railHandle)
 Get the current radio state.

Enumeration Type Documentation

◆ RAIL_IdleMode_t

An enumeration for the different types of supported idle modes.

These vary how quickly and destructively they put the radio into idle.

Enumerator
RAIL_IDLE 

Idle the radio by turning off receive and canceling any future scheduled receive or transmit operations.

It does not abort a receive or transmit in progress.

RAIL_IDLE_ABORT 

Idle the radio by turning off receive and any scheduled events.

It also aborts any receive, transmit, or scheduled events in progress.

RAIL_IDLE_FORCE_SHUTDOWN 

Force the radio into a shutdown mode as quickly as possible.

It aborts all current operations and cancels any pending scheduled operations. It may also corrupt receive or transmit buffers and end up clearing them.

RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS 

Similar to the RAIL_IDLE_FORCE_SHUTDOWN command, it quickly puts the radio into idle state.

Additionally, it clears any pending receive or transmit callbacks and clear both the receive and transmit storage.

Definition at line 1724 of file rail_types.h.

◆ RAIL_RadioState_t

The state of the radio.

Enumerator
RAIL_RF_STATE_INACTIVE 

Radio is inactive.

RAIL_RF_STATE_ACTIVE 

Radio is either idle or, in combination with the RX and TX states, receiving or transmitting a frame.

RAIL_RF_STATE_RX 

Radio is in receive.

RAIL_RF_STATE_TX 

Radio is in transmit.

RAIL_RF_STATE_IDLE 

Radio is idle.

RAIL_RF_STATE_RX_ACTIVE 

Radio is actively receiving a frame.

RAIL_RF_STATE_TX_ACTIVE 

Radio is actively transmitting a frame.

Definition at line 1657 of file rail_types.h.

Function Documentation

◆ RAIL_GetRadioState()

RAIL_RadioState_t RAIL_GetRadioState ( RAIL_Handle_t  railHandle)

Get the current radio state.

Parameters
[in]railHandleA RAIL instance handle.
Returns
An enumeration for the current radio state.

Returns the state of the radio as a bitmask containing: RAIL_RF_STATE_IDLE, RAIL_RF_STATE_RX, RAIL_RF_STATE_TX, and RAIL_RF_STATE_ACTIVE. RAIL_RF_STATE_IDLE, RAIL_RF_STATE_RX, and RAIL_RF_STATE_TX bits are mutually exclusive. The radio can transition through intermediate states, which are not reported but are instead considered part of the state most closely associated. For example, when the radio is warming up or shutting down the transmitter or receiver, this function returns RAIL_RF_STATE_TX or RAIL_RF_STATE_RX, respectively. When transitioning directly from RX to TX or vice-versa, this function returns the earlier state.

◆ RAIL_GetRxTransitions()

RAIL_Status_t RAIL_GetRxTransitions ( RAIL_Handle_t  railHandle,
RAIL_StateTransitions_t transitions 
)

Get the current RAIL automatic state transitions after RX.

Parameters
[in]railHandleA RAIL instance handle.
[out]transitionsThe state transitions that apply after receive.
Returns
Status code indicating a success of the function call.

Retrieves the current state transitions after RX and stores them in the transitions argument.

◆ RAIL_GetTxTransitions()

RAIL_Status_t RAIL_GetTxTransitions ( RAIL_Handle_t  railHandle,
RAIL_StateTransitions_t transitions 
)

Get the current RAIL automatic state transitions after TX.

Parameters
[in]railHandleA RAIL instance handle.
[out]transitionsThe state transitions that apply after transmission.
Returns
Status code indicating a success of the function call.

Retrieves the current state transitions after TX and stores them in the transitions argument.

◆ RAIL_Idle()

void RAIL_Idle ( RAIL_Handle_t  railHandle,
RAIL_IdleMode_t  mode,
bool  wait 
)

Place the radio into an idle state.

Parameters
[in]railHandleA RAIL instance handle.
[in]modeThe method for shutting down the radio.
[in]waitWhether this function should wait for the radio to reach idle before returning.
Returns
void.

This function is used to remove the radio from TX and RX states. How these states are left is defined by the mode parameter.

In multiprotocol, this API will also cause the radio to be yielded so that other tasks can be run. See Yielding the radio for more details.

◆ RAIL_SetRxTransitions()

RAIL_Status_t RAIL_SetRxTransitions ( RAIL_Handle_t  railHandle,
const RAIL_StateTransitions_t transitions 
)

Configure RAIL automatic state transitions after RX.

Parameters
[in]railHandleA RAIL instance handle.
[in]transitionsThe state transitions to apply after reception.
Returns
Status code indicating success of the function call.

This function fails if unsupported transitions are passed in or if the radio is currently in the RX state. Success can transition to TX, RX, or IDLE, while error can transition to RX or IDLE.

◆ RAIL_SetStateTiming()

RAIL_Status_t RAIL_SetStateTiming ( RAIL_Handle_t  railHandle,
RAIL_StateTiming_t timings 
)

Configure RAIL automatic state transition timing.

Parameters
[in]railHandleA RAIL instance handle.
[in,out]timingsThe timings used to configure the RAIL state machine. This structure is overwritten with the actual times that were set, if an input timing is invalid.
Returns
Status code indicating a success of the function call.

The timings given are close to the actual transition time. However, a still uncharacterized software overhead occurs. Also, timings are not always adhered to when using an automatic transition after an error, due to the cleanup required to recover from the error.

◆ RAIL_SetTxTransitions()

RAIL_Status_t RAIL_SetTxTransitions ( RAIL_Handle_t  railHandle,
const RAIL_StateTransitions_t transitions 
)

Configure RAIL automatic state transitions after TX.

Parameters
[in]railHandleA RAIL instance handle.
[in]transitionsThe state transitions to apply after transmission.
Returns
Status code indicating a success of the function call.

This function fails if unsupported transitions are passed in or if the radio is currently in the TX state. Success and error can each transition to RX or IDLE.