RAIL_Idle() takes a mode argument, with which you select one of the four available methods of idling the radio to use. Though the API documentation briefly describes each mode, it might be difficult to understand their differences without seeing examples and usecases. This document aims to help you more clearly understand each mode.
In most cases,
RAIL_IDLE is the recommended mode to use with this API.
RAIL_IDLE_ABORT is helpful when you want to also abort an ongoing ("active") tx or rx operation.
On the other hand,
RAIL_IDLE_FORCE_SHUTDOWN is not recommended for use, and
RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS should be handled with care.
RAIL_IDLE turns off the radio after the current operation is finished. It also cancels any transmit or receive scheduled in the future. Current operations that won't be aborted include:
RAIL_IDLE_ABORT works the same as
RAIL_IDLE, but it will also abort active operations. However,
RAIL_IDLE_ABORT will always wait for a stable state before turning off the radio, e.g. if the radio was preparing to enter rx mode and is waiting for the PLL to lock, RAIL will wait until the rx state is reached before idling the radio.
RAIL_IDLE_ABORT (which waits for a stable radio state),
RAIL_IDLE_FORCE_SHUTDOWN immediately forces the radio off. As this is an abrupt transition, it may corrupt data in the receive or transmit buffers. This buffer corruption can only be resolved by completely clearing the FIFO - which loses data, and can also consume additional time.
In our experience, it's almost always slower than
RAIL_IDLE_ABORT, so the costs typically outweigh the benefit of using
RAIL_IDLE_FORCE_SHUTDOWN (except when recommended by our support team for diagnostic purposes).
RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS works the same as
RAIL_IDLE_FORCE_SHUTDOWN, but it also clears any pending events. For more details on scenarios where this can be useful, see the article on RAIL interrupt safety.