State Transitions

Modules

EFR32

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_RF_STATE_DETAIL_INACTIVE   (0U)
 Radio is inactive.
 
#define RAIL_RF_STATE_DETAIL_IDLE_STATE   (1U << RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT)
 Radio is in or headed to the idle state.
 
#define RAIL_RF_STATE_DETAIL_RX_STATE   (1U << RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT)
 Radio is in or headed to the receive state.
 
#define RAIL_RF_STATE_DETAIL_TX_STATE   (1U << RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT)
 Radio is in or headed to the transmit state.
 
#define RAIL_RF_STATE_DETAIL_TRANSITION   (1U << RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT)
 Radio is headed to the idle, receive, or transmit state.
 
#define RAIL_RF_STATE_DETAIL_ACTIVE   (1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)
 Radio is actively transmitting or receiving.
 
#define RAIL_RF_STATE_DETAIL_NO_FRAMES   (1U << RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT)
 Radio has frame detect disabled.
 
#define RAIL_RF_STATE_DETAIL_LBT   (1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)
 LBT/CSMA operation is currently ongoing.
 
#define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK
 Mask for core radio state bits.
 
#define RAIL_TRANSITION_TIME_KEEP   ((RAIL_TransitionTime_t) -1)
 A value to use in RAIL_StateTiming_t fields when calling RAIL_SetStateTiming() to keep that timing parameter at it current setting.

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_RadioStateDetail_t {
  RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT = 0u,
  RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT,
  RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT,
  RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT,
  RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT,
  RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT,
  RAIL_RF_STATE_DETAIL_LBT_SHIFT
}
 The detailed 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_SetNextTxRepeat (RAIL_Handle_t railHandle, const RAIL_TxRepeatConfig_t *repeatConfig)
 Set up automatic repeated transmits after the next transmit.
 
uint16_t RAIL_GetTxPacketsRemaining (RAIL_Handle_t railHandle)
 Get the number of transmits remaining in a repeat operation.
 
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.
 
RAIL_RadioStateDetail_t RAIL_GetRadioStateDetail (RAIL_Handle_t railHandle)
 Get the detailed current radio state.

Macro Definition Documentation

◆ RAIL_RF_STATE_DETAIL_ACTIVE

#define RAIL_RF_STATE_DETAIL_ACTIVE   (1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)

Radio is actively transmitting or receiving.

Definition at line 2138 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_CORE_STATE_MASK

#define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK
Value:
#define RAIL_RF_STATE_DETAIL_TX_STATE
Radio is in or headed to the transmit state.
Definition: rail_types.h:2134
#define RAIL_RF_STATE_DETAIL_RX_STATE
Radio is in or headed to the receive state.
Definition: rail_types.h:2132
#define RAIL_RF_STATE_DETAIL_IDLE_STATE
Radio is in or headed to the idle state.
Definition: rail_types.h:2130

Mask for core radio state bits.

Definition at line 2144 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_IDLE_STATE

#define RAIL_RF_STATE_DETAIL_IDLE_STATE   (1U << RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT)

Radio is in or headed to the idle state.

Definition at line 2130 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_INACTIVE

#define RAIL_RF_STATE_DETAIL_INACTIVE   (0U)

Radio is inactive.

Definition at line 2128 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_LBT

#define RAIL_RF_STATE_DETAIL_LBT   (1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)

LBT/CSMA operation is currently ongoing.

Definition at line 2142 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_NO_FRAMES

#define RAIL_RF_STATE_DETAIL_NO_FRAMES   (1U << RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT)

Radio has frame detect disabled.

Definition at line 2140 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_RX_STATE

#define RAIL_RF_STATE_DETAIL_RX_STATE   (1U << RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT)

Radio is in or headed to the receive state.

Definition at line 2132 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_TRANSITION

#define RAIL_RF_STATE_DETAIL_TRANSITION   (1U << RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT)

Radio is headed to the idle, receive, or transmit state.

Definition at line 2136 of file rail_types.h.

◆ RAIL_RF_STATE_DETAIL_TX_STATE

#define RAIL_RF_STATE_DETAIL_TX_STATE   (1U << RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT)

Radio is in or headed to the transmit state.

Definition at line 2134 of file rail_types.h.

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

◆ RAIL_RadioStateDetail_t

The detailed state of the radio.

The three radio state bits RAIL_RF_STATE_DETAIL_IDLE_STATE, RAIL_RF_STATE_DETAIL_RX_STATE, and RAIL_RF_STATE_DETAIL_TX_STATE comprise a set of mutually exclusive core radio states. Only one (or none) of these bits can be set at a time. Otherwise, the value is invalid.

The precise meaning of each of these three core bits, when set, depends on the value of the two bits RAIL_RF_STATE_DETAIL_TRANSITION and RAIL_RF_STATE_DETAIL_ACTIVE. When RAIL_RF_STATE_DETAIL_TRANSITION is set, the radio is transitioning into the core radio state corresponding to the set state bit. When it is clear, the radio is already in the core radio state that corresponds to the set state bit. When RAIL_RF_STATE_DETAIL_ACTIVE is set, the radio is actively transmitting or receiving. When it is clear, the radio is not actively transmitting or receiving. This bit will always be clear when RAIL_RF_STATE_DETAIL_IDLE_STATE is set, and will always be set when RAIL_RF_STATE_DETAIL_TX_STATE is set. Otherwise, the value is invalid.

The bit RAIL_RF_STATE_DETAIL_NO_FRAMES is set if the radio is currently operating with frame detection disabled, and clear otherwise. The bit RAIL_RF_STATE_DETAIL_LBT_SHIFT is set if an LBT/CSMA operation (e.g., performing CCA) is currently ongoing, and clear otherwise.

Enumerator
RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_IDLE_STATE bit.

RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_RX_STATE bit.

RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_TX_STATE bit.

RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_TRANSITION bit.

RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_ACTIVE bit.

RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_NO_FRAMES bit.

RAIL_RF_STATE_DETAIL_LBT_SHIFT 

Shift position of RAIL_RF_STATE_DETAIL_LBT bit.

Definition at line 2110 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.

Note
For a more detailed radio state, see RAIL_GetRadioStateDetail

◆ RAIL_GetRadioStateDetail()

RAIL_RadioStateDetail_t RAIL_GetRadioStateDetail ( RAIL_Handle_t  railHandle)

Get the detailed current radio state.

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

Returns the state of the radio as a bitmask. The three core radio states IDLE, RX, and TX are represented by mutually exclusive bits RAIL_RF_STATE_DETAIL_IDLE_STATE, RAIL_RF_STATE_DETAIL_RX_STATE, and RAIL_RF_STATE_DETAIL_TX_STATE respectively. If the radio is transitioning between these three states, the returned bitmask will have RAIL_RF_STATE_DETAIL_TRANSITION set along with a bit corresponding to the destination core radio state. If, while in the receive state, the radio is actively receiving a packet, RAIL_RF_STATE_DETAIL_ACTIVE will be set; otherwise, this bit will be clear. If frame detection is disabled, RAIL_RF_STATE_DETAIL_NO_FRAMES in the returned state bitmask will be set; otherwise, this bit will be clear. If the radio is performing an LBT/CSMA operation (e.g., a backoff period) RAIL_RF_STATE_DETAIL_LBT in the returned state bitmask will be set; otherwise, this bit will be clear.

For the most part, the more detailed radio states returned by this API correspond to radio states returned by RAIL_GetRadioState as follows:

RAIL_RadioStateDetail_t RAIL_RadioState_t RAIL_RF_STATE_DETAIL_INACTIVE RAIL_RF_STATE_INACTIVE RAIL_RF_STATE_DETAIL_IDLE_STATE | RAIL_STATE_DETAIL_TRANSITION If RX overflow or leaving RX unforced: RAIL_RF_STATE_RX Else if leaving TX unforced: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_IDLE RAIL_RF_STATE_DETAIL_IDLE_STATE RAIL_RF_STATE_IDLE RAIL_RF_STATE_DETAIL_IDLE_STATE | RAIL_STATE_DETAIL_LBT RAIL_RF_STATE_TX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_STATE_DETAIL_TRANSITION If leaving TX: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_TRANSITION | RAIL_RF_STATE_DETAIL_NO_FRAMES If leaving TX: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_NO_FRAMES RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_LBT RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_NO_FRAMES | RAIL_RF_STATE_DETAIL_LBT RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_ACTIVE RAIL_RF_STATE_RX_ACTIVE RAIL_RF_STATE_DETAIL_TX_STATE | RAIL_RF_STATE_TRANSITION If leaving RX: RAIL_RF_STATE_RX Else: RAIL_RF_STATE_TX RAIL_RF_STATE_DETAIL_TX_STATE | RAIL_RF_STATE_ACTIVE RAIL_RF_STATE_TX_ACTIVE

◆ 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_GetTxPacketsRemaining()

uint16_t RAIL_GetTxPacketsRemaining ( RAIL_Handle_t  railHandle)

Get the number of transmits remaining in a repeat operation.

Must only be called from within event callback context when handling one of the RAIL_EVENTS_TX_COMPLETION events.

Parameters
[in]railHandleA RAIL instance handle.
Returns
transmits remaining as described below.

If the TX completion event is RAIL_EVENT_TX_PACKET_SENT the returned value indicates how many more such events are expected before the repeat transmit operation is done. Due to interrupt latency and timing, this may be an overcount if greater than 0 but is guaranteed to be accurate when 0.

If the TX completion event is an error, the returned value indicates the number of requested transmits that were not performed. For RAIL_EVENT_TX_ABORTED and RAIL_EVENT_TX_UNDERFLOW the count does not include the failing transmit itself. For the other errors where a transmit never started or was blocked, the count would include the failing transmit, which may be one higher than the configured RAIL_TxRepeatConfig_t::iterations if it was the original transmit that was blocked.

If an infinite repeat was configured, this will return RAIL_TX_REPEAT_INFINITE_ITERATIONS.

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

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

RAIL_Status_t RAIL_SetNextTxRepeat ( RAIL_Handle_t  railHandle,
const RAIL_TxRepeatConfig_t repeatConfig 
)

Set up automatic repeated transmits after the next transmit.

Parameters
[in]railHandleA RAIL instance handle.
[in]repeatConfigThe configuration structure for repeated transmits.
Returns
Status code indicating a success of the function call.

Repeated transmits will occur after an application-initiated transmit caused by calling one of the Packet Transmit APIs. The repetition will only occur after the first application-initiated transmit after this function is called. Future repeated transmits must be requested by calling this function again.

Each repeated transmit that occurs will have full Packet Trace (PTI) information, and will receive events such as RAIL_EVENT_TX_PACKET_SENT as normal.

If a TX error occurs during the repetition, the process will abort and the TX error transition from RAIL_SetTxTransitions will be used. If the repetition completes successfully, then the TX success transition from RAIL_SetTxTransitions will be used.

Use RAIL_GetTxPacketsRemaining() if need to know how many transmit completion events are expected before the repeating sequence is done, or how many were not performed due to a transmit error.

Any call to RAIL_Idle or RAIL_StopTx will clear the pending repeated transmits. The state will also be cleared by another call to this function. To clear the repeated transmits before they've started without stopping other radio actions, call this function with a RAIL_TxRepeatConfig_t::iterations count of 0. A DMP switch will clear this state only if the initial transmit triggering the repeated transmits has started.

The application is responsible for populating the transmit data to be used by the repeated transmits via RAIL_SetTxFifo or RAIL_WriteTxFifo. Data will be transmitted from the Transmit FIFO. If the Transmit FIFO does not have sufficient data to transmit, a TX error will be caused and a RAIL_EVENT_TX_UNDERFLOW will occur. In order to avoid an underflow, the application should queue data to be transmitted as early as possible. Consider using RAIL_TX_OPTION_RESEND if the same packet data is to be repeated: then the Transmit FIFO only needs to be set/written once.

Do not call this function after starting a transmit operation or before processing the final transmit completion event of a prior transmit. This function will fail to configure the repetition if a transmit of any kind is ongoing, including during the time between an initial transmit and the end of a previously-configured repetition.

Note
This feature/API is not supported on the EFR32XG1 family of chips. Use the compile time symbol RAIL_SUPPORTS_TX_TO_TX or the runtime call RAIL_SupportsTxToTx() to check whether the platform supports this feature.

◆ 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. 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]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. For the ability to run repeated transmits, see RAIL_SetNextTxRepeat.