State Transitions
RAIL API

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.

Macros

#define RAIL_MINIMUM_TRANSITION_US (100U)
The minimum value for a consistent RAIL transition.
#define RAIL_MAXIMUM_TRANSITION_US (13000U)
The maximum value for a consistent RAIL transition.

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.

Macro Definition Documentation

◆ RAIL_MINIMUM_TRANSITION_US

#define RAIL_MINIMUM_TRANSITION_US   (100U)

The minimum value for a consistent RAIL transition.

Note
Transitions may need to be slower than this when using longer RAIL_TxPowerConfig_t::rampTime values

Definition at line 1746 of file rail_types.h .

Enumeration Type Documentation

◆ RAIL_IdleMode_t

enum 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 by stopping whatever state is in progress.

This is a more destructive shutdown than RAIL_IDLE or RAIL_IDLE_ABORT and can be useful in certain situations when directed by the support team or for debugging. Note that this method may corrupt receive and transmit buffers so it requires a more thorough cleanup and any held packets will be lost.

RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS

Similar to the RAIL_IDLE_FORCE_SHUTDOWN command, however, it will also clear any pending RAIL events related to receive and transmit.

Definition at line 1790 of file rail_types.h .

◆ RAIL_RadioState_t

enum 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 1700 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] railHandle A 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] railHandle A RAIL instance handle.
[out] transitions The 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] railHandle A RAIL instance handle.
[out] transitions The 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] railHandle A RAIL instance handle.
[in] mode The method for shutting down the radio.
[in] wait Whether this function should wait for the radio to reach idle before returning.

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] railHandle A RAIL instance handle.
[in] transitions The 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. The timings of state transitions from the RX state are not guaranteed when packets are longer than 16 seconds on-air.

◆ RAIL_SetStateTiming()

RAIL_Status_t RAIL_SetStateTiming ( RAIL_Handle_t railHandle,
RAIL_StateTiming_t * timings
)

Configure RAIL automatic state transition timing.

Parameters
[in] railHandle A RAIL instance handle.
[in,out] timings The 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] railHandle A RAIL instance handle.
[in] transitions The 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.