State Transitions#

RAIL_RadioState_t#

RAIL_RadioState_t

The state of the radio.

RAIL_RadioStateDetail_t#

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.

RAIL_IdleMode_t#

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.

RAIL_TransitionTime_t#

RAIL_TransitionTime_t

Suitable type for the supported transition time range.

Refer to platform-specific RAIL_MINIMUM_TRANSITION_US and RAIL_MAXIMUM_TRANSITION_US for the valid range of this type.

RAIL_SetRxTransitions#

RAIL_Status_t RAIL_SetRxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t * transitions)

Configure RAIL automatic state transitions after RX.

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_GetRxTransitions#

RAIL_Status_t RAIL_GetRxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t * transitions)

Get the current RAIL automatic state transitions after RX.

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_SetTxTransitions#

RAIL_Status_t RAIL_SetTxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t * transitions)

Configure RAIL automatic state transitions after TX.

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 only, not TX. For the ability to run repeated transmits, see RAIL_SetNextTxRepeat(). Calling this function will clear any repeated transmissions set up by RAIL_SetNextTxRepeat().

RAIL_GetTxTransitions#

RAIL_Status_t RAIL_GetTxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t * transitions)

Get the current RAIL automatic state transitions after TX.

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_SetNextTxRepeat#

RAIL_Status_t RAIL_SetNextTxRepeat (RAIL_Handle_t railHandle, const RAIL_TxRepeatConfig_t * repeatConfig)

Set up automatic repeated transmits after the next transmit.

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 PTI Packet Trace 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(), RAIL_StopTx(), or RAIL_SetTxTransitions() will clear the pending repeated transmits. The state will also be cleared by another call to this function. A DMP switch will clear this state only if the initial transmit triggering the repeated transmits has started.

One can change the repeated transmit configuration by re-calling this function with new parameters as long as that occurs prior to calling a Packet Transmit API. Passing a RAIL_TxRepeatConfig_t::iterations count of 0 will prevent the next transmit from repeating.

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 via a Packet Transmit API call or before processing the final transmit completion event of a prior transmit. This function will fail to (re)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

• 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_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.

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_SetStateTiming#

RAIL_Status_t RAIL_SetStateTiming (RAIL_Handle_t railHandle, RAIL_StateTiming_t * timings)

Configure RAIL automatic state transition timing.

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_Idle#

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

Place the radio into an idle state.

Returns

• RAIL_STATUS_NO_ERROR if the radio has idled by the time this function returns, or RAIL_STATUS_SUSPENDED if it is still in the process of idling.

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_GetRadioState#

RAIL_RadioState_t RAIL_GetRadioState (RAIL_Handle_t railHandle)

Get the current radio state.

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.

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_tRAIL_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_EnableCacheSynthCal#

RAIL_Status_t RAIL_EnableCacheSynthCal (RAIL_Handle_t railHandle, bool enable)

Enable/disable caching of synth calibration value.

Returns

• Status code indicating success of the function call.

Once enabled, the sequencer will start caching synth calibration values for channels and apply them instead of performing calibration on every state transition and channel change. This will increase the transition time for the first time calibration is performed. Subsequent state transitions will be faster. The cache size is 2. RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING internally uses this feature and there is no need to enable/disable it. This function returns RAIL_STATUS_INVALID_STATE if we try to disable it while RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is enabled.

Note

• This function will improve the minimum timings that can be achieved in RAIL_StateTiming_t::idleToRx, RAIL_StateTiming_t::idleToTx, RAIL_StateTiming_t::rxToTx, RAIL_StateTiming_t::txToRx and RAIL_StateTiming_t::txToTx. A call to RAIL_SetStateTiming() is needed to achieve lower transition times.

• On a protocol switch the cache is cleared, so it is not suitable for applications where a protocol switch happens frequently, like with Dynamic Multiprotocol.

RAIL_TRANSITION_TIME_KEEP#

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

RAIL_RF_STATE_DETAIL_INACTIVE#

#define RAIL_RF_STATE_DETAIL_INACTIVE

(0U)

Radio is inactive.

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.

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.

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.

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.

RAIL_RF_STATE_DETAIL_ACTIVE#

#define RAIL_RF_STATE_DETAIL_ACTIVE

(1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)

Radio is actively transmitting or receiving.

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.

RAIL_RF_STATE_DETAIL_LBT#

#define RAIL_RF_STATE_DETAIL_LBT

(1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)

LBT/CSMA operation is currently ongoing.

RAIL_RF_STATE_DETAIL_CORE_STATE_MASK#

#define RAIL_RF_STATE_DETAIL_CORE_STATE_MASK

Mask for core radio state bits.