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.

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)
Configures RAIL automatic state transitions after RX.
RAIL_Status_t RAIL_SetTxTransitions ( RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)
Configures RAIL automatic state transitions after TX.
RAIL_Status_t RAIL_SetStateTiming ( RAIL_Handle_t railHandle, RAIL_StateTiming_t *timings)
Configures RAIL automatic state transition timing.
void RAIL_Idle ( RAIL_Handle_t railHandle, RAIL_IdleMode_t mode, bool wait)
Places the radio into an idle state.
RAIL_RadioState_t RAIL_GetRadioState ( RAIL_Handle_t railHandle)
Gets the current radio state.

Enumeration Type Documentation

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

Idles 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

Idles 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

Forces 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 1635 of file rail_types.h .

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 1568 of file rail_types.h .

Function Documentation

RAIL_RadioState_t RAIL_GetRadioState ( RAIL_Handle_t railHandle )

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

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

Places 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.
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_Status_t RAIL_SetRxTransitions ( RAIL_Handle_t railHandle,
const RAIL_StateTransitions_t * transitions
)

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

RAIL_Status_t RAIL_SetStateTiming ( RAIL_Handle_t railHandle,
RAIL_StateTiming_t * timings
)

Configures 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_Status_t RAIL_SetTxTransitions ( RAIL_Handle_t railHandle,
const RAIL_StateTransitions_t * transitions
)

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