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.

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

◆ RAIL_RF_STATE_DETAIL_CORE_STATE_MASK

#define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK

Value:

         (
         
          RAIL_RF_STATE_DETAIL_IDLE_STATE
         
         \
        
         |
         
          RAIL_RF_STATE_DETAIL_RX_STATE
         
         \
        
         |
         
          RAIL_RF_STATE_DETAIL_TX_STATE
         
         )

Mask for core radio state bits.

Definition at line 1926 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 1912 of file rail_types.h .

◆ RAIL_RF_STATE_DETAIL_INACTIVE

#define RAIL_RF_STATE_DETAIL_INACTIVE (0U)

Radio is inactive.

Definition at line 1910 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 1924 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 1922 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 1914 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 1918 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 1916 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 1935 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 1826 of file rail_types.h .

◆ RAIL_RadioStateDetail_t

enum 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 1892 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.

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] railHandle A 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]	`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_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]	`railHandle`	A RAIL instance handle.
[in]	`repeatConfig`	The 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.

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.

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

State Transitions RAIL API

Modules

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ RAIL_RF_STATE_DETAIL_ACTIVE

◆ RAIL_RF_STATE_DETAIL_CORE_STATE_MASK

◆ RAIL_RF_STATE_DETAIL_IDLE_STATE

◆ RAIL_RF_STATE_DETAIL_INACTIVE

◆ RAIL_RF_STATE_DETAIL_LBT

◆ RAIL_RF_STATE_DETAIL_NO_FRAMES

◆ RAIL_RF_STATE_DETAIL_RX_STATE

◆ RAIL_RF_STATE_DETAIL_TRANSITION

◆ RAIL_RF_STATE_DETAIL_TX_STATE

Enumeration Type Documentation

◆ RAIL_IdleMode_t

◆ RAIL_RadioState_t

◆ RAIL_RadioStateDetail_t

Function Documentation

◆ RAIL_GetRadioState()

◆ RAIL_GetRadioStateDetail()

◆ RAIL_GetRxTransitions()

◆ RAIL_GetTxTransitions()

◆ RAIL_Idle()

◆ RAIL_SetNextTxRepeat()

◆ RAIL_SetRxTransitions()

◆ RAIL_SetStateTiming()

◆ RAIL_SetTxTransitions()

State Transitions
RAIL API