State Transitions#
Modules#
Enumerations#
The state of the radio.
The detailed state of the radio.
An enumeration for the different types of supported idle modes.
Functions#
Configure RAIL automatic state transitions after RX.
Get the current RAIL automatic state transitions after RX.
Configure RAIL automatic state transitions after TX.
Get the current RAIL automatic state transitions after TX.
Set up automatic repeated transmits after the next transmit.
Get the number of transmits remaining in a repeat operation.
Configure RAIL automatic state transition timing.
Place the radio into an idle state.
Get the current radio state.
Get the detailed current radio state.
Enable/disable caching of synth calibration value.
Macros#
Radio is inactive.
Radio is in or headed to the idle state.
Radio is in or headed to the receive state.
Radio is in or headed to the transmit state.
Radio is headed to the idle, receive, or transmit state.
Radio is actively transmitting or receiving.
Radio has frame detect disabled.
LBT/CSMA operation is currently ongoing.
Mask for core radio state bits.
A value to use in RAIL_StateTiming_t fields when calling RAIL_SetStateTiming() to keep that timing parameter at it current setting.
Enumeration Documentation#
RAIL_RadioState_t#
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. |
2198
of file common/rail_types.h
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.
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. |
2264
of file common/rail_types.h
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.
Enumerator | |
---|---|
RAIL_IDLE | Idle the radio by turning off receive and canceling any future scheduled receive or transmit operations. |
RAIL_IDLE_ABORT | Idle the radio by turning off receive and any scheduled events. |
RAIL_IDLE_FORCE_SHUTDOWN | Force the radio into a shutdown mode by stopping whatever state is in progress. |
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. |
2307
of file common/rail_types.h
Function Documentation#
RAIL_SetRxTransitions#
RAIL_Status_t RAIL_SetRxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t * transitions)
Configure RAIL automatic state transitions after RX.
[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.
2194
of file common/rail.h
RAIL_GetRxTransitions#
RAIL_Status_t RAIL_GetRxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t * transitions)
Get the current RAIL automatic state transitions after RX.
[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.
2207
of file common/rail.h
RAIL_SetTxTransitions#
RAIL_Status_t RAIL_SetTxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t * transitions)
Configure RAIL automatic state transitions after TX.
[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.
2222
of file common/rail.h
RAIL_GetTxTransitions#
RAIL_Status_t RAIL_GetTxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t * transitions)
Get the current RAIL automatic state transitions after TX.
[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.
2235
of file common/rail.h
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.
[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.
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. 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
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.
2296
of file common/rail.h
RAIL_GetTxPacketsRemaining#
uint16_t RAIL_GetTxPacketsRemaining (RAIL_Handle_t railHandle)
Get the number of transmits remaining in a repeat operation.
[in] | railHandle | A RAIL instance handle. |
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.
2325
of file common/rail.h
RAIL_SetStateTiming#
RAIL_Status_t RAIL_SetStateTiming (RAIL_Handle_t railHandle, RAIL_StateTiming_t * timings)
Configure RAIL automatic state transition timing.
[in] | railHandle | A RAIL instance handle. |
[inout] | 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.
2341
of file common/rail.h
RAIL_Idle#
void RAIL_Idle (RAIL_Handle_t railHandle, RAIL_IdleMode_t mode, bool wait)
Place the radio into an idle state.
[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.
2358
of file common/rail.h
RAIL_GetRadioState#
RAIL_RadioState_t RAIL_GetRadioState (RAIL_Handle_t railHandle)
Get the current radio state.
[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
2382
of file common/rail.h
RAIL_GetRadioStateDetail#
RAIL_RadioStateDetail_t RAIL_GetRadioStateDetail (RAIL_Handle_t railHandle)
Get the detailed current radio state.
[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_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
2448
of file common/rail.h
RAIL_EnableCacheSynthCal#
RAIL_Status_t RAIL_EnableCacheSynthCal (RAIL_Handle_t railHandle, bool enable)
Enable/disable caching of synth calibration value.
[in] | railHandle | A RAIL instance handle. |
[in] | enable | A booloean to enable or disable caching of synth calibration. |
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.
2477
of file common/rail.h
Macro Definition Documentation#
RAIL_RF_STATE_DETAIL_INACTIVE#
#define RAIL_RF_STATE_DETAIL_INACTIVEValue:
(0U)
Radio is inactive.
2282
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_IDLE_STATE#
#define RAIL_RF_STATE_DETAIL_IDLE_STATEValue:
(1U << RAIL_RF_STATE_DETAIL_IDLE_STATE_SHIFT)
Radio is in or headed to the idle state.
2284
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_RX_STATE#
#define RAIL_RF_STATE_DETAIL_RX_STATEValue:
(1U << RAIL_RF_STATE_DETAIL_RX_STATE_SHIFT)
Radio is in or headed to the receive state.
2286
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_TX_STATE#
#define RAIL_RF_STATE_DETAIL_TX_STATEValue:
(1U << RAIL_RF_STATE_DETAIL_TX_STATE_SHIFT)
Radio is in or headed to the transmit state.
2288
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_TRANSITION#
#define RAIL_RF_STATE_DETAIL_TRANSITIONValue:
(1U << RAIL_RF_STATE_DETAIL_TRANSITION_SHIFT)
Radio is headed to the idle, receive, or transmit state.
2290
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_ACTIVE#
#define RAIL_RF_STATE_DETAIL_ACTIVEValue:
(1U << RAIL_RF_STATE_DETAIL_ACTIVE_SHIFT)
Radio is actively transmitting or receiving.
2292
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_NO_FRAMES#
#define RAIL_RF_STATE_DETAIL_NO_FRAMESValue:
(1U << RAIL_RF_STATE_DETAIL_NO_FRAMES_SHIFT)
Radio has frame detect disabled.
2294
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_LBT#
#define RAIL_RF_STATE_DETAIL_LBTValue:
(1U << RAIL_RF_STATE_DETAIL_LBT_SHIFT)
LBT/CSMA operation is currently ongoing.
2296
of file common/rail_types.h
RAIL_RF_STATE_DETAIL_CORE_STATE_MASK#
#define RAIL_RF_STATE_DETAIL_CORE_STATE_MASKValue:
Mask for core radio state bits.
2298
of file common/rail_types.h
RAIL_TRANSITION_TIME_KEEP#
#define RAIL_TRANSITION_TIME_KEEPValue:
((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.
4859
of file common/rail_types.h