RAIL_CLPC_MINIMUM_POWER#

#define RAIL_CLPC_MINIMUM_POWER

180

Minimum power for CLPC usage in deci-dBm.

Below this power CLPC will not activate. Recommend staying above 19 dBm for best performance. Signed unit, do not add U.

RAIL_EFF_TEMP_MEASURE_COUNT#

#define RAIL_EFF_TEMP_MEASURE_COUNT

(6U)

Number of temperature values provided for the EFF thermal protection.

RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT#

#define RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT

(2U)

Number of deprecated temperature values in EFF thermal protection.

RAIL_HFXO_TEMP_MEASURE_COUNT#

#define RAIL_HFXO_TEMP_MEASURE_COUNT

(1U)

Number of temperature values provided for HFXO metrics.

RAIL_TEMP_MEASURE_COUNT#

#define RAIL_TEMP_MEASURE_COUNT

Total number of temperature values provided by RAIL_GetTemperature().

RAIL_EFF_CONTROL_SIZE#

#define RAIL_EFF_CONTROL_SIZE

(52U)

Number of bytes provided by RAIL_GetSetEffClpcControl().

RAIL_GetVersion#

void RAIL_GetVersion (RAIL_Version_t * version, bool verbose)

Get the version information for the compiled RAIL library.

The version information contains a major version number, a minor version number, and a rev (revision) number.

RAIL_AddStateBuffer3#

RAIL_Status_t RAIL_AddStateBuffer3 (RAIL_Handle_t genericRailHandle)

Add a 3rd multiprotocol internal state buffer for use by RAIL_Init().

Returns

• Status code indicating success of the function call. An error is returned if the 3rd state buffer was previously added or this isn't the RAIL multiprotocol library.

RAIL_AddStateBuffer4#

RAIL_Status_t RAIL_AddStateBuffer4 (RAIL_Handle_t genericRailHandle)

Add a 4th multiprotocol internal state buffer for use by RAIL_Init().

Returns

• Status code indicating success of the function call. An error is returned if the 4th state buffer was previously added. or this isn't the RAIL multiprotocol library.

RAIL_UseDma#

RAIL_Status_t RAIL_UseDma (uint8_t channel)

Allocate a DMA channel for RAIL to work with.

Returns

• Status code indicating success of the function call.

To use this API, the application must initialize the DMA engine on the chip and allocate a DMA channel. This channel will be used periodically to copy memory more efficiently. Call this function before RAIL_Init to have the most benefit. If the application needs to take back control of the DMA channel that RAIL is using, this API may be called with a channel of RAIL_DMA_INVALID to tell RAIL to stop using DMA.

RAIL_Init#

RAIL_Handle_t RAIL_Init (RAIL_Config_t * railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

Returns

• Handle for initialized rail instance or NULL if an invalid value was passed in the railCfg.

Note

• Call this function only once per protocol. If called again, it will do nothing and return NULL.

RAIL_IsInitialized#

bool RAIL_IsInitialized (void )

Get RAIL initialization status.

Returns

• True if the radio has finished initializing and false otherwise.

RAIL APIs, e.g., RAIL_GetTime(), which work only if RAIL_Init() has been called, can use RAIL_IsInitialized() to determine whether RAIL has been initialized or not.

RAIL_GetRadioEntropy#

uint16_t RAIL_GetRadioEntropy (RAIL_Handle_t railHandle, uint8_t * buffer, uint16_t bytes)

Collect entropy from the radio if available.

Returns

• Returns the number of bytes of entropy collected. For chips that don't support entropy collection, the function returns 0. Values less than the requested amount may also be returned on platforms that use entropy pools to collect random data periodically.

Attempts to fill the provided buffer with the requested number of bytes of entropy. If the requested number of bytes can't be provided, as many bytes as possible will be filled and returned. For chips that do not support this function, 0 bytes are always returned. For information about the specific mechanism for gathering entropy, see documentation for the chip family.

RAIL_ConfigPti#

RAIL_Status_t RAIL_ConfigPti (RAIL_Handle_t railHandle, const RAIL_PtiConfig_t * ptiConfig)

Configure PTI pin locations, serial protocols, and baud rates.

Returns

• Status code indicating success of the function call.

This method must be called before RAIL_EnablePti() is called. Although a RAIL handle is included for potential future expansion of this function, it is currently not used. That is, there is only one PTI configuration that can be active on a chip, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch), and the configuration is not saved in the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

PTI should be configured only when the radio is off (idle).

Note

• On EFR32 platforms GPIO configuration must be unlocked (see GPIO->LOCK register) to configure or use PTI.

RAIL_GetPtiConfig#

RAIL_Status_t RAIL_GetPtiConfig (RAIL_Handle_t railHandle, RAIL_PtiConfig_t * ptiConfig)

Get the currently-active PTI configuration.

Returns

• RAIL status indicating success of the function call.

Although most combinations of configurations can be set, it is safest to call this method after configuration to confirm which values were actually set. As in RAIL_ConfigPti, railHandle is not used. This function always returns the single active PTI configuration regardless of the active protocol. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

RAIL_EnablePti#

RAIL_Status_t RAIL_EnablePti (RAIL_Handle_t railHandle, bool enable)

Enable Packet Trace Interface (PTI) output of packet data.

Returns

• RAIL status indicating success of the function call.

Similarly to having only one PTI configuration per chip, PTI can only be enabled or disabled for all protocols. It cannot be individually set to enabled and disabled per protocol (unless the application switches it when the protocol switches), and enable/disable is not saved as part of the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

PTI should be enabled or disabled only when the radio is off (idle).

Warnings

• On EFR32 platforms GPIO configuration must be unlocked (see GPIO->LOCK register) to configure or use PTI, otherwise a fault or assert might occur. If GPIO configuration locking is desired, PTI must be disabled beforehand either with this function or with RAIL_ConfigPti() using RAIL_PTI_MODE_DISABLED.

RAIL_SetPtiProtocol#

RAIL_Status_t RAIL_SetPtiProtocol (RAIL_Handle_t railHandle, RAIL_PtiProtocol_t protocol)

Set a protocol that RAIL outputs on PTI.

Returns

• Status code indicating success of the function call.

The protocol is output via PTI for each packet. Before any protocol is set, the default value is RAIL_PTI_PROTOCOL_CUSTOM. Use one of the enumeration values so that the Network Analyzer can decode the packet.

Note

• This function cannot be called unless the radio is currently in the RAIL_RF_STATE_IDLE or RAIL_RF_STATE_INACTIVE states. For this reason, call this function early on before starting radio operations and not changed later.

RAIL_GetPtiProtocol#

RAIL_PtiProtocol_t RAIL_GetPtiProtocol (RAIL_Handle_t railHandle)

Get the protocol that RAIL outputs on PTI.

Returns

• PTI protocol in use.

RAIL_ConfigAntenna#

RAIL_Status_t RAIL_ConfigAntenna (RAIL_Handle_t railHandle, const RAIL_AntennaConfig_t * config)

Configure antenna path and pin locations.

Warnings

• This API must be called before any TX or RX occurs. Otherwise, the antenna configurations for those functions will not take effect.

Returns

• Status code indicating success of the function call.

This function informs RAIL how to select each antenna, but not when. Antenna selection for receive is controlled by the RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA0 and RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA1 options (and the RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA_AUTO combination). Antenna selection for transmit is controlled by the RAIL_TxOptions_t::RAIL_TX_OPTION_ANTENNA0 and RAIL_TxOptions_t::RAIL_TX_OPTION_ANTENNA1 options.

Although a RAIL handle is included for potential future expansion of this function, it is currently not used. That is, only one antenna configuration can be active on a chip, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch), and the configuration is not saved in the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

RAIL_GetRfPath#

RAIL_Status_t RAIL_GetRfPath (RAIL_Handle_t railHandle, RAIL_AntennaSel_t * rfPath)

Get the default RF path.

Returns

• A status code indicating success of the function call.

If multiple protocols are used, this function returns RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later, for example when RAIL_EVENT_CONFIG_SCHEDULED trigger.

RAIL_ConfigRadio#

RAIL_Status_t RAIL_ConfigRadio (RAIL_Handle_t railHandle, RAIL_RadioConfig_t config)

Load a static radio configuration.

Returns

• Status code indicating success of the function call.

The configuration passed into this function should be auto-generated and not manually created or edited. By default, do not call this function in RAIL 2.x and later unless instructed by Silicon Labs because it may bypass updating certain RAIL state. In RAIL 2.x and later, the RAIL_ConfigChannels function applies the default radio configuration automatically.

RAIL_SetFixedLength#

uint16_t RAIL_SetFixedLength (RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

Returns

• Length configured; The new frame length configured into the hardware for use. 0 if in infinite mode, or RAIL_SETFIXEDLENGTH_INVALID if the frame length has not yet been overridden by a valid value.

Sets the fixed-length configuration for transmit and receive. Be careful when using this function in receive and transmit as this function changes the default frame configuration and remains in force until it is called again with an input value of RAIL_SETFIXEDLENGTH_INVALID. This function will override any fixed or variable length settings from a radio configuration.

RAIL_ConfigChannels#

uint16_t RAIL_ConfigChannels (RAIL_Handle_t railHandle, const RAIL_ChannelConfig_t * config, RAIL_RadioConfigChangedCallback_t cb)

Configure the channels supported by this device.

Returns

• Returns the first available channel in the configuration.

When configuring channels on EFR32, the radio tuner is reconfigured based on the frequency and channel spacing in the channel configuration.

Note

• config can be NULL to simply register or unregister the cb callback function when using RAIL internal protocol-specific radio configuration APIs for BLE, IEEE 802.15.4, or Z-Wave, which lack callback specification. In this use case, 0 is returned.

RAIL_GetChannelMetadata#

RAIL_Status_t RAIL_GetChannelMetadata (RAIL_Handle_t railHandle, RAIL_ChannelMetadata_t * channelMetadata, uint16_t * length, uint16_t minChannel, uint16_t maxChannel)

Get verbose listing of channel metadata for the current channel configuration.

Returns

• Status of the call. RAIL_STATUS_INVALID_PARAMETER means that, based on the currently active radio configuration, there are more channels to write than there is space provided in the allocated channelMetadata. However, the channel metadata that was written is valid. RAIL_STATUS_INVALID_STATE indicates that the channel configuration has not been configured. RAIL_STATUS_NO_ERROR indicates complete success.

RAIL_IsValidChannel#

RAIL_Status_t RAIL_IsValidChannel (RAIL_Handle_t railHandle, uint16_t channel)

Check whether the channel exists in RAIL.

Returns

• Returns RAIL_STATUS_NO_ERROR if channel exists

Returns RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist in the channel configuration currently used or RAIL_STATUS_NO_ERROR if the channel is valid.

RAIL_PrepareChannel#

RAIL_Status_t RAIL_PrepareChannel (RAIL_Handle_t railHandle, uint16_t channel)

Cause radio settings associated with a particular channel to be applied to hardware.

Returns

• RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_PARAMETER if the given channel does not have an associated channel configuration entry.

This function walks the channelConfigEntry list and applies the configuration associated with the specified channel. This function manually changes channels without starting a TX or RX operation.

When successful, the radio is idled. When unsuccessful, the radio state will not be altered.

RAIL_GetChannel#

RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t * channel)

Return the current RAIL channel.

Returns

• RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or RAIL_STATUS_INVALID_PARAMETER if channel parameter is NULL.

This function returns the channel most recently specified in API calls that pass in a channel to tune to, namely RAIL_PrepareChannel, RAIL_StartTx, RAIL_StartScheduledTx, RAIL_StartCcaCsmaTx, RAIL_StartCcaLbtTx, RAIL_StartScheduledCcaCsmaTx, RAIL_StartScheduledCcaLbtTx, RAIL_StartRx, RAIL_ScheduleRx, RAIL_StartAverageRssi, RAIL_StartTxStream, RAIL_StartTxStreamAlt. It doesn't follow changes RAIL performs implicitly during channel hopping and mode switch.

RAIL_GetChannelAlt#

RAIL_Status_t RAIL_GetChannelAlt (RAIL_Handle_t railHandle, uint16_t * channel)

Return the current RAIL channel.

Returns

• RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or RAIL_STATUS_INVALID_PARAMETER if channel parameter is NULL.

This function returns the channel the radio is currently tuned to if the specified RAIL handle is active. It returns the channel it will be tuned to during the next protocol switch if the handle is inactive. The channel returned may be different than what RAIL_GetChannel returns when channel hopping or mode switch are involved.

RAIL_GetSymbolRate#

uint32_t RAIL_GetSymbolRate (RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

Returns

• The symbol rate in symbols per second or 0.

The symbol rate is the rate of symbol changes over the air. For non-DSSS PHYs, this is the same as the baudrate. For DSSS PHYs, it is the baudrate divided by the length of a chipping sequence. For more information, see the modem calculator documentation. If the rate cannot be calculated, this function returns 0.

RAIL_GetBitRate#

uint32_t RAIL_GetBitRate (RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

Returns

• The bit rate in bits per second or 0.

The bit rate is the effective over-the-air data rate. It does not account for extra spreading for forward error correction, and so on, but accounts for modulation schemes, DSSS, and other configurations. For more information, see the modem calculator documentation. If the rate cannot be calculated, this function returns 0.

RAIL_SetPaCTune#

RAIL_Status_t RAIL_SetPaCTune (RAIL_Handle_t railHandle, uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue)

Set the PA capacitor tune value for transmit and receive.

Returns

• Status code indicating success of the function call.

Tunes the impedance of the transmit and receive modes by changing the amount of capacitance at the PA output. Changes made to the TX Power configuration, e.g., calling RAIL_ConfigTxPower, will undo changes made to PA capacitor tune value for transmit and receive via RAIL_SetPaCTune.

RAIL_GetSyncWords#

RAIL_Status_t RAIL_GetSyncWords (RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t * syncWordConfig)

Get the sync words and their length.

Returns

• Status code indicating success of the function call.

RAIL_ConfigSyncWords#

RAIL_Status_t RAIL_ConfigSyncWords (RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t * syncWordConfig)

Set the selected sync words and their length.

Returns

• Status code indicating success of the function call. When the custom sync word(s) applied by this API are no longer needed, or to revert to default sync word, calling RAIL_ConfigChannels() will re-establish the sync words specified in the radio configuration.

This function will return RAIL_STATUS_INVALID_STATE if called when BLE has been enabled for this railHandle. When changing sync words in BLE mode, use RAIL_BLE_ConfigChannelRadioParams instead.

RAIL_GetWhiteningInitVal#

uint16_t RAIL_GetWhiteningInitVal (RAIL_Handle_t railHandle)

Sets the whitening initialization value.

Returns

• The whitening initialization value currently being used.

RAIL_GetCrcInitVal#

uint32_t RAIL_GetCrcInitVal (RAIL_Handle_t railHandle)

Returns the CRC initialization value.

Returns

• The CRC initialization value currently being used.

RAIL_SetWhiteningInitVal#

RAIL_Status_t RAIL_SetWhiteningInitVal (RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

Returns

• Status code indicating success of the function call.

Use this function to override the whitening initialization value defined by the current PHY's radio configuration. The new value will persist until this function is called again, RAIL_ResetWhiteningInitVal() is called, or the PHY is changed.

Note

• Overriding a PHY's whitening initialization value will break communication with peers unless they effect a similar change.

Warnings

• This API must not be used when either 802.15.4 or BLE modes are enabled.

RAIL_SetCrcInitVal#

RAIL_Status_t RAIL_SetCrcInitVal (RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

Returns

• Status code indicating success of the function call.

Use this function to override the CRC initialization value defined by the current PHY's radio configuration. The new value will persist until this function is called again, RAIL_ResetCrcInitVal() is called, or the PHY is changed.

Note

• Overriding a PHY's CRC initialization value will break communication with peers unless they effect a similar change.

Warnings

• This API must not be used when either 802.15.4 or BLE modes are enabled.

RAIL_ResetWhiteningInitVal#

RAIL_Status_t RAIL_ResetWhiteningInitVal (RAIL_Handle_t railHandle)

Restores the whitening initialization value to its initial setting from the Radio Configurator.

Returns

• Status code indicating success of the function call.

Can use this function after using RAIL_SetWhiteningInitVal().

RAIL_ResetCrcInitVal#

RAIL_Status_t RAIL_ResetCrcInitVal (RAIL_Handle_t railHandle)

Restores the CRC initialization value to its initial setting from the Radio Configurator.

Returns

• Status code indicating success of the function call.

Can use this function after using RAIL_SetCrcInitVal().

RAIL_GetTime#

RAIL_Time_t RAIL_GetTime (void )

Get the current RAIL time.

Returns

• Returns the RAIL timebase in microseconds. Note that this wraps after about 1.19 hours since it's stored in a 32 bit value.

Returns the current time in the RAIL timebase (microseconds). It can be used to compare with packet timestamps or to schedule transmits.

RAIL_SetTime#

RAIL_Status_t RAIL_SetTime (RAIL_Time_t time)

Set the current RAIL time.

Warnings

• Use this API only for testing purposes or in very limited circumstances during RAIL Timer Synchronization. Undefined behavior can result by calling it in multiprotocol or when the radio is not idle or timed events are active. Applications using RAIL_GetTime() may not be designed for discontinuous changes to the RAIL time base.

Returns

• Status code indicating the success of the function call.

Sets the current time in the RAIL timebase in microseconds.

RAIL_DelayUs#

RAIL_Status_t RAIL_DelayUs (RAIL_Time_t microseconds)

Blocking delay routine for a specified number of microseconds.

Returns

• Status code indicating success of the function call.

Use this RAIL API only for short blocking delays because it has less overhead than calling RAIL_GetTime() in a loop. Note

• Passing large delay values may give unpredictable results or trigger the Watchdog reset. Also, this function will start the clocks required for the RAIL timebase if they are not running, except between RAIL_Sleep() and RAIL_Wake() where the timer must remain stopped. Interrupts are not disabled during the delay, so the delay may be longer if an interrupt extends beyond the delay duration.

RAIL_SetTimer#

RAIL_Status_t RAIL_SetTimer (RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb)

Schedule a timer to expire using the RAIL timebase.

Returns

• RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_PARAMETER if the timer can't be scheduled.

Configures a timer to expire after a period in the RAIL timebase. This timer can be used to implement low-level protocol features.

Warnings

• Attempting to schedule the timer when it is still running from a previous request is bad practice, unless the cb callback is identical to that used in the previous request, in which case the timer is rescheduled to the new time. Note that if the original timer expires as it is being rescheduled, the callback may or may not occur. It is generally good practice to cancel a running timer before rescheduling it to minimize ambiguity.

RAIL_GetTimer#

RAIL_Time_t RAIL_GetTimer (RAIL_Handle_t railHandle)

Return the absolute time that the RAIL timer was configured to expire.

Returns

• The absolute time that this timer was set to expire.

Provides the absolute time regardless of the RAIL_TimeMode_t that was passed into RAIL_SetTimer. Note that the time might be in the past if the timer has already expired. The return value is undefined if the timer was never set.

RAIL_CancelTimer#

void RAIL_CancelTimer (RAIL_Handle_t railHandle)

Stop the currently scheduled RAIL timer.

RAIL_IsTimerExpired#

bool RAIL_IsTimerExpired (RAIL_Handle_t railHandle)

Check whether the RAIL timer has expired.

Returns

• True if the previously scheduled timer has expired and false otherwise.

Polling with this function is an alternative to the callback.

RAIL_IsTimerRunning#

bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)

Check whether the RAIL timer is currently running.

Returns

• Returns true if the timer is running and false if the timer has expired or was never set.

RAIL_ConfigMultiTimer#

bool RAIL_ConfigMultiTimer (bool enable)

Configure the RAIL software timer feature.

Returns

• True if the multitimer was successfully enabled/disabled, false otherwise.

Turning this on will add a software timer layer above the physical RAIL timer so that the user can have as many timers as desired. It is not necessary to call this function if the MultiTimer APIs are not used.

Note

• This function must be called before calling RAIL_SetMultiTimer. This function is a no-op on multiprotocol as this layer is already used under the hood. Do not call this function while the RAIL timer is running. Call RAIL_IsTimerRunning before enabling/disabling the multitimer. If the multitimer is not needed, do not call this function to allow the multitimer code to be dead stripped. If the multitimer is enabled for use, the multitimer and timer APIs can both be used. However, no timer can be in use while this function is being called.

RAIL_SetMultiTimer#

RAIL_Status_t RAIL_SetMultiTimer (RAIL_MultiTimer_t * tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void * cbArg)

Start a multitimer instance.

Note

• It is legal to start an already running timer. If this is done, the timer will first be stopped before the new configuration is applied. If expirationTime is 0, the callback is called immediately.

Returns

• RAIL_STATUS_NO_ERROR on success.RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.

RAIL_CancelMultiTimer#

bool RAIL_CancelMultiTimer (RAIL_MultiTimer_t * tmr)

Stop the currently scheduled RAIL multitimer.

Returns

• true if the timer was successfully canceled. false if the timer was not running.

Cancels the timer. If this function is called before the timer expires, the cb callback specified in the earlier RAIL_SetTimer() call will never be called.

RAIL_IsMultiTimerRunning#

bool RAIL_IsMultiTimerRunning (RAIL_MultiTimer_t * tmr)

Check if a given timer is running.

Returns

• true if the timer is running. false if the timer is not running.

RAIL_IsMultiTimerExpired#

bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t * tmr)

Check if a given timer has expired.

Returns

• true if the timer is expired. false if the timer is running.

RAIL_GetMultiTimer#

RAIL_Time_t RAIL_GetMultiTimer (RAIL_MultiTimer_t * tmr, RAIL_TimeMode_t timeMode)

Get time left before a given timer instance expires.

Returns

• Time left expressed in RAIL's time units. 0 if the soft timer is not running or has already expired.

RAILCb_ConfigSleepTimerSync#

void RAILCb_ConfigSleepTimerSync (RAIL_TimerSyncConfig_t * timerSyncConfig)

Configure RAIL timer synchronization.

This function is optional to implement.

This function is called during RAIL_ConfigSleep to allow an application to configure the PRS and RTCC channels used for timer sync to values other than their defaults. The default channels are populated in timerSyncConfig and can be overwritten by the application. If this function is not implemented by the application, a default implementation from within the RAIL library will be used that simply maintains the default channel values in timerSyncConfig.

If an unsupported channel is selected by the application, RAIL_ConfigSleep will return RAIL_STATUS_INVALID_PARAMETER.

void RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)
{
  timerSyncConfig->prsChannel = MY_TIMERSYNC_PRS_CHANNEL;
  timerSyncConfig->rtccChannel = MY_TIMERSYNC_RTCC_CHANNEL;
}

RAIL_ConfigSleep#

RAIL_Status_t RAIL_ConfigSleep (RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)

Initialize RAIL timer synchronization.

Returns

• Status code indicating success of the function call.

RAIL_ConfigSleepAlt#

RAIL_Status_t RAIL_ConfigSleepAlt (RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t * syncConfig)

Initialize RAIL timer synchronization.

The default structure used to enable timer synchronization across sleep is RAIL_TIMER_SYNC_DEFAULT.

Returns

• Status code indicating success of the function call.

RAIL_Sleep#

RAIL_Status_t RAIL_Sleep (uint16_t wakeupProcessTime, bool * deepSleepAllowed)

Stop the RAIL timer and prepare RAIL for sleep.

Returns

• Status code indicating success of the function call.

Warnings

• The active RAIL configuration must be idle to enable sleep.

Note

• This API must not be called if RAIL Power Manager is initialized.

RAIL_Wake#

RAIL_Status_t RAIL_Wake (RAIL_Time_t elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Returns

• Status code indicating success of the function call.

If the timer sync was enabled by RAIL_ConfigSleep, synchronize the RAIL timer using an alternate timer. Otherwise, add elapsedTime to the RAIL timer.

Note

• This API must not be called if RAIL Power Manager is initialized.

RAIL_InitPowerManager#

RAIL_Status_t RAIL_InitPowerManager (void )

Initialize RAIL Power Manager.

Returns

• Status code indicating success of the function call.

Note

• Call this function only when the application is built and initialized with Power Manager plugin. RAIL will perform timer synchronization, upon transitioning from EM2 or lower to EM1 or higher energy mode or vice-versa, in the Power Manager EM transition callback. Since EM transition callbacks are not called in a deterministic order, it is suggested to not call any RAIL time dependent APIs in an EM transition callback.

RAIL_DeinitPowerManager#

RAIL_Status_t RAIL_DeinitPowerManager (void )

Stop the RAIL Power Manager.

Returns

• Status code indicating success of the function call.

Note

• The active RAIL configuration must be idle to disable radio power manager and there should be no outstanding requirements by radio power manager.

RAIL_ConfigEvents#

RAIL_Status_t RAIL_ConfigEvents (RAIL_Handle_t railHandle, RAIL_Events_t mask, RAIL_Events_t events)

Configure radio events.

Returns

• Status code indicating success of the function call.

Sets up which radio interrupts generate a RAIL event. The full list of options is in RAIL_Events_t.

RAIL_ConfigData#

RAIL_Status_t RAIL_ConfigData (RAIL_Handle_t railHandle, const RAIL_DataConfig_t * dataConfig)

RAIL data management configuration.

Returns

• Status code indicating success of the function call.

This function configures how RAIL manages data. The application can configure RAIL to receive data in a packet-based or FIFO-based manner. RAIL_DataMethod_t::FIFO_MODE is necessary to receive packets larger than the radio's receive FIFO. It is also required for receive data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.

Generally with RAIL_DataMethod_t::FIFO_MODE, the application sets appropriate FIFO thresholds via RAIL_SetTxFifoThreshold() and RAIL_SetRxFifoThreshold() and then enables and handles the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event callback (to feed more packet data via RAIL_WriteTxFifo() before the FIFO underflows) and the RAIL_EVENT_RX_FIFO_ALMOST_FULL event callback (to consume packet data via RAIL_ReadRxFifo() before the receive FIFO overflows).

When configuring TX for RAIL_DataMethod_t::FIFO_MODE, this function resets the transmit FIFO. When configuring TX or RX for RAIL_DataMethod_t::PACKET_MODE, this function will reset the corresponding FIFO thresholds such that they won't trigger the RAIL_EVENT_RX_FIFO_ALMOST_FULL or RAIL_EVENT_TX_FIFO_ALMOST_EMPTY events.

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::FIFO_MODE, the radio won't drop packet data of aborted or CRC error packets, but will present it to the application to deal with accordingly. On completion of erroneous packets, the RAIL_Config_t::eventsCallback with RAIL_EVENT_RX_PACKET_ABORTED, RAIL_EVENT_RX_FRAME_ERROR, or RAIL_EVENT_RX_ADDRESS_FILTERED will tell the application it can drop any data it read via RAIL_ReadRxFifo() during reception. For CRC error packets when the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option is in effect, the application should check for that from the RAIL_RxPacketStatus_t obtained by calling RAIL_GetRxPacketInfo(). RAIL will automatically flush any remaining packet data after reporting one of these packet completion events or the application can explicitly flush it by calling RAIL_ReleaseRxPacket().

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::PACKET_MODE, the radio will roll back (drop) all packet data associated with aborted packets including those with CRC errors (unless configured to ignore CRC errors via the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option). The application will never have to deal with packet data from these packets. In either mode, the application can set RX options as needed.

When RAIL_DataConfig_t::rxSource is set to a value other than RX_PACKET_DATA and RAIL_Config_t::eventsCallbackRAIL_EVENT_RX_FIFO_OVERFLOW is enabled RX will be terminated if a RX FIFO overflow occurs. If RAIL_EVENT_RX_FIFO_OVERFLOW is not enabled, data will be discarded until the overflow condition is resolved. To continue capturing data RX must be restarted using RAIL_StartRx().

RAIL_WriteTxFifo#

uint16_t RAIL_WriteTxFifo (RAIL_Handle_t railHandle, const uint8_t * dataPtr, uint16_t writeLength, bool reset)

Write data to the transmit FIFO previously established by RAIL_SetTxFifo().

Returns

• The number of bytes written to the transmit FIFO.

This function reads data from the provided dataPtr and writes it to the transmit FIFO that was previously established by RAIL_SetTxFifo(). If the requested writeLength exceeds the current number of bytes open in the transmit FIFO, the function only writes until the transmit FIFO is full. The function returns the number of bytes written to the transmit FIFO or returns zero if railHandle is NULL or if the transmit FIFO is full.

Note

• The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the writeLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes, which the packet configuration causes to be sent automatically.

• This function does not create a critical section but, depending on the application, a critical section could be appropriate.

RAIL_SetTxFifo#

uint16_t RAIL_SetTxFifo (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data.

Returns

• Returns the FIFO size in bytes, 0 if an error occurs.

This function sets the memory location for the transmit FIFO. RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size, in that case 0 is returned. If the initLength parameter is larger than the returned size, the FIFO will be filled up to its size.

A user may write to the custom memory location directly before calling this function, or use RAIL_WriteTxFifo to write to the memory location after calling this function. Users must specify the initLength for previously-written memory to be set in the transmit FIFO.

This function reserves the block of RAM starting at addr with a length of the returned FIFO size, which is used internally as a circular buffer for the transmit FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via calls to RAIL_WriteTxFifo) until the next call to this function.

Note

• The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the initLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes which the packet configuration causes to be sent automatically.

RAIL_SetTxFifoAlt#

uint16_t RAIL_SetTxFifoAlt (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t startOffset, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data which can start at offset distance from the FIFO base address.

Returns

• Returns the FIFO size in bytes, 0 if an error occurs.

This function is similar to RAIL_SetTxFifo except a startOffset can be specified to indicate where the transmit packet data starts. This allows an application to place unaligned initial packet data within the aligned transmit FIFO (initLength > 0). Specifying a startOffset will not reduce the FIFO threshold or affect RAIL_GetTxFifoSpaceAvailable(). RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur. FIFO size handling is quite same as RAIL_SetTxFifo. Only difference is that if the initLength plus startOffset parameters are larger than the returned size, the FIFO will be filled up to its size from startOffset. Note that the startOffset is essentially forgotten after the next transmit – i.e. it applies onto to the next transmit operation, and is not re-established when the transmit FIFO is reset.

RAIL_SetRxFifo#

RAIL_Status_t RAIL_SetRxFifo (RAIL_Handle_t railHandle, uint8_t * addr, uint16_t * size)

Set the address of the receive FIFO, a circular buffer used for RX data.

Returns

• Status code indicating success of the function call.

This function sets the memory location for the receive FIFO. It must be called at least once before any receive operations occur.

Note

• After it is called, any prior receive FIFO is orphaned. To avoid orphaning the default internal 512-byte receive FIFO so it does not unnecessarily consume RAM resources in your application, implement RAILCb_SetupRxFifo() to call this function.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size.

This function reserves the block of RAM starting at addr with a length of size, which is used internally as a circular buffer for the receive FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via incoming packet data being written) until the next call to this function.

In multiprotocol, RAIL currently shares one receive FIFO across all protocols. This function will return RAIL_STATUS_INVALID_STATE if the requested RAIL_Handle_t is not active.

RAILCb_SetupRxFifo#

RAIL_Status_t RAILCb_SetupRxFifo (RAIL_Handle_t railHandle)

Set up the receive FIFO to use.

This function is optional to implement.

Returns

• Status code indicating success of the function call.

This function is called during the RAIL_Init process to set up the FIFO to use for received packets. If not implemented by the application, a default implementation from within the RAIL library will be used to initialize an internal default 512-byte receive FIFO.

If this function returns an error, the RAIL_Init process will fail.

During this function, the application should generally call RAIL_SetRxFifo. If that does not happen, the application needs to set up the receive FIFO via a call to RAIL_SetRxFifo before attempting to receive any packets. An example implementation may look like the following:

#define RX_FIFO_SIZE 1024
static uint8_t rxFifo[RX_FIFO_SIZE];

RAIL_Status_t RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)
{
  uint16_t rxFifoSize = RX_FIFO_SIZE;
  RAIL_Status_t status = RAIL_SetRxFifo(railHandle, &rxFifo[0], &rxFifoSize);
  if (rxFifoSize != RX_FIFO_SIZE) {
    // We set up an incorrect FIFO size
    return RAIL_STATUS_INVALID_PARAMETER;
  }
  if (status == RAIL_STATUS_INVALID_STATE) {
    // Allow failures due to multiprotocol
    return RAIL_STATUS_NO_ERROR;
  }
  return status;
}

RAIL_ReadRxFifo#

uint16_t RAIL_ReadRxFifo (RAIL_Handle_t railHandle, uint8_t * dataPtr, uint16_t readLength)

Read packet data from RAIL's internal receive FIFO.

Returns

• The number of packet bytes read from the receive FIFO.

This function reads packet data from the head of receive FIFO and writes it to the provided dataPtr. It does not permit reading more data than is available in the FIFO, nor does it permit reading more data than remains in the oldest unreleased packet.

Because this function does not have a critical section, use it only in one context or make sure function calls are protected to prevent buffer corruption.

Warnings

• This function is intended for use only with RAIL_DataMethod_t::FIFO_MODE and should never be called in RAIL_DataMethod_t::PACKET_MODE where it could lead to receive FIFO corruption.

Note

• When reading data from an arriving packet that is not yet complete, keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the receive FIFO could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid reading this info because it will corrupt the packet's details and possibly corrupt the receive FIFO.

RAIL_SetTxFifoThreshold#

uint16_t RAIL_SetTxFifoThreshold (RAIL_Handle_t railHandle, uint16_t txThreshold)

Configure the RAIL transmit FIFO almost empty threshold.

Returns

• Configured transmit FIFO threshold value.

This function configures the threshold for the transmit FIFO. When the number of bytes in the transmit FIFO falls below the configured threshold, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_TX_FIFO_ALMOST_EMPTY set. The txThreshold value should be smaller than or equal to the transmit FIFO size; higher values will be pegged to the FIFO size. A value of 0 or RAIL_FIFO_THRESHOLD_DISABLED will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.

RAIL_SetRxFifoThreshold#

uint16_t RAIL_SetRxFifoThreshold (RAIL_Handle_t railHandle, uint16_t rxThreshold)

Configure the RAIL receive FIFO almost full threshold.

Returns

• Configured receive FIFO threshold value.

This function configures the threshold for the receive FIFO. When the number of bytes of packet data in the receive FIFO exceeds the configured threshold, RAIL_Config_t::eventsCallback will keep firing with RAIL_EVENT_RX_FIFO_ALMOST_FULL set as long as the number of bytes in the receive FIFO exceeds the configured threshold value. The rxThreshold value should be smaller than the receive FIFO size; anything else, including a value of RAIL_FIFO_THRESHOLD_DISABLED, will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.

Note

• To avoid sticking in the event handler (even in idle state):

  1. Disable the event (via the config events API or the RAIL_FIFO_THRESHOLD_DISABLED parameter)

  2. Increase FIFO threshold

  3. Read the FIFO (that's not an option in RAIL_DataMethod_t::PACKET_MODE) in the event handler

RAIL_GetTxFifoThreshold#

uint16_t RAIL_GetTxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL transmit FIFO almost empty threshold value.

Returns

• Configured TX Threshold value.

Retrieves the configured TX threshold value.

RAIL_GetRxFifoThreshold#

uint16_t RAIL_GetRxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL receive FIFO almost full threshold value.

Returns

• Configured RX Threshold value.

Retrieves the configured RX threshold value.

RAIL_ResetFifo#

void RAIL_ResetFifo (RAIL_Handle_t railHandle, bool txFifo, bool rxFifo)

Reset the RAIL transmit and/or receive FIFOs.

This function can reset each FIFO independently. The application should not reset the receive FIFO while receiving a frame, nor should it reset the transmit FIFO while transmitting a frame.

RAIL_GetRxFifoBytesAvailable#

uint16_t RAIL_GetRxFifoBytesAvailable (RAIL_Handle_t railHandle)

Get the number of bytes used in the receive FIFO.

Only use this function in RX RAIL_DataMethod_t::FIFO_MODE. Apps should use RAIL_GetRxPacketInfo() instead.

Returns

• Number of bytes used in the receive FIFO.

This function indicates how much packet-related data exists in the receive FIFO that could be read.

Note

• The number of bytes returned may not just reflect the current packet's data but could also include raw appended info bytes added after successful packet reception and bytes from subsequently received packets. It is up to the app to never try to consume more than the packet's actual data when using the value returned here in a subsequent call to RAIL_ReadRxFifo(), otherwise the receive FIFO will be corrupted.

RAIL_GetTxFifoSpaceAvailable#

uint16_t RAIL_GetTxFifoSpaceAvailable (RAIL_Handle_t railHandle)

Get the number of bytes unused in the transmit FIFO.

Returns

• Number of bytes unused in the transmit FIFO.

This function indicates how much space is available in the transmit FIFO for writing additional packet data.

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

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#

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

Place the radio into an idle state.

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

RAIL_Status_t RAIL_ConfigTxPower (RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t * config)

Initialize TX power settings.

Returns

• RAIL_Status_t indicating success or an error.

These settings include the selection between the multiple TX amplifiers, voltage supplied to the TX power amplifier, and ramp times. This must be called before any transmit occurs or RAIL_SetTxPower is called. While this function should always be called during initialization, it can also be called any time if these settings need to change to adapt to a different application/protocol. This API also resets TX power to RAIL_TX_POWER_LEVEL_INVALID, so RAIL_SetTxPower must be called afterwards.

At times, certain combinations of configurations cannot be achieved. This API attempts to get as close as possible to the requested settings. The following "RAIL_Get..." API can be used to determine what values were set. A change in RAIL_TxPowerConfig_t::rampTime may affect the minimum timings that can be achieved in RAIL_StateTiming_t::idleToTx and RAIL_StateTiming_t::rxToTx. Call RAIL_SetStateTiming() again to check whether these times have changed.

RAIL_GetTxPowerConfig#

RAIL_Status_t RAIL_GetTxPowerConfig (RAIL_Handle_t railHandle, RAIL_TxPowerConfig_t * config)

Get the TX power settings currently used in the amplifier.

Returns

• RAIL status variable indicating whether or not the get was successful.

Note that this API does not return the current TX power, which is separately managed by the RAIL_GetTxPower / RAIL_SetTxPower APIs. Use this API to determine which values were set as a result of RAIL_ConfigTxPower.

RAIL_SetTxPower#

RAIL_Status_t RAIL_SetTxPower (RAIL_Handle_t railHandle, RAIL_TxPowerLevel_t powerLevel)

Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).

Returns

• RAIL_Status_t indicating success or an error.

To convert between decibels and the integer values that the registers take, call RAIL_ConvertDbmToRaw. A weak version of this function, which works well with our boards is provided. However, customers using a custom board need to characterize chip operation on that board and override the function to convert appropriately from the desired dB values to raw integer values.

Depending on the configuration used in RAIL_ConfigTxPower, not all power levels are achievable. This API will get as close as possible to the desired power without exceeding it, and calling RAIL_GetTxPower is the only way to know the exact value written.

Calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower) will return an error.

RAIL_GetTxPower#

RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)

Return the current power setting of the PA.

Returns

• The chip-specific RAIL_TxPowerLevel_t value of the current transmit power.

This API returns the raw value that was set by RAIL_SetTxPower. A weak version of RAIL_ConvertRawToDbm that works with our boards to convert the raw values into actual output dBm values is provided. However, customers using a custom board need to re-characterize the relationship between raw and decibel values and rewrite the provided function.

Calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower) will return an error (RAIL_TX_POWER_LEVEL_INVALID).

RAIL_ConvertRawToDbm#

RAIL_TxPower_t RAIL_ConvertRawToDbm (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPowerLevel_t powerLevel)

Convert raw values written to registers to decibel value (in units of deci-dBm).

Returns

• raw amplifier values converted to units of deci-dBm.

A weak version of this function is provided that is tuned to provide accurate values for our boards. For a custom board, the relationship between what is written to the TX amplifier and the actual output power should be re-characterized and implemented in an overriding version of RAIL_ConvertRawToDbm. For minimum code size and best speed, use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.

RAIL_ConvertDbmToRaw#

RAIL_TxPowerLevel_t RAIL_ConvertDbmToRaw (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t power)

Convert the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.

Returns

• deci-dBm value converted to a raw integer value that can be used directly with RAIL_SetTxPower.

A weak version of this function is provided that is tuned to provide accurate values for our boards. For a custom board, the relationship between what is written to the TX amplifier and the actual output power should be characterized and implemented in an overriding version of RAIL_ConvertDbmToRaw. For minimum code size and best speed use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.

Note

• This function is called from within the RAIL library for comparison between channel limitations and current power. It will throw an assert if you haven't called RAIL_InitTxPowerCurves which initializes the mappings between raw power levels and actual dBm powers. To avoid the assert, ensure that the maxPower of all channel configuration entries is RAIL_TX_POWER_MAX or above, or override this function to always return 255.

RAIL_VerifyTxPowerCurves#

void RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt * config)

Verify the TX Power Curves on modules.

This function only needs to be called when using a module and has no effect otherwise. Transmit will not work before this function is called.

RAIL_SetTxPowerDbm#

RAIL_Status_t RAIL_SetTxPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t power)

Set the TX power in terms of deci-dBm instead of raw power level.

Returns

• RAIL Status variable indicate whether setting the power was successful.

This is a utility function for user convenience. Normally, to set TX power in dBm, do the following:

RAIL_TxPower_t power = 100; // 100 deci-dBm, 10 dBm
RAIL_TxPowerConfig_t txPowerConfig;
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertDbmToRaw will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle,
                                                      txPowerConfig.mode,
                                                      power);
RAIL_SetTxPower(railHandle, powerLevel);

This function wraps all those calls in a single function with power passed in as a parameter.

RAIL_GetTxPowerDbm#

RAIL_TxPower_t RAIL_GetTxPowerDbm (RAIL_Handle_t railHandle)

Get the TX power in terms of deci-dBm instead of raw power level.

Returns

• The current output power in deci-dBm.

This is a utility function for user convenience. Normally, to get TX power in dBm, do the following:

RAIL_TxPowerLevel_t powerLevel = RAIL_GetTxPower(railHandle);
RAIL_TxPowerConfig_t txPowerConfig;
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertRawToDbm will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPower_t power = RAIL_ConvertRawToDbm(railHandle,
                                            txPowerConfig.mode,
                                            powerLevel);
return power;

This function wraps all those calls in a single function with power returned as the result.

RAIL_GetPowerSettingTable#

const RAIL_PaPowerSetting_t * RAIL_GetPowerSettingTable (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t * minPower, RAIL_TxPower_t * maxPower, RAIL_TxPowerLevel_t * step)

Get the TX PA power setting table and related values.

Returns

• Power setting table start address. When NULL is returned all out params above won't be set.

The number of entries in the table can be calculated based on the minPower, maxPower, and step parameters. For example, for minPower = 115 (11.5 dBm), maxPower = 300 (30 dBm), and step = 1, the number of entries in table would be 186

RAIL_SetPaPowerSetting#

RAIL_Status_t RAIL_SetPaPowerSetting (RAIL_Handle_t railHandle, RAIL_PaPowerSetting_t paPowerSetting, RAIL_TxPower_t minPowerDbm, RAIL_TxPower_t maxPowerDbm, RAIL_TxPower_t currentPowerDbm)

Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().

Returns

• RAIL Status variable indicate whether setting the PA power setting was successful.

RAIL_GetPaPowerSetting#

RAIL_PaPowerSetting_t RAIL_GetPaPowerSetting (RAIL_Handle_t railHandle)

Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.

Returns

• The current PA power setting.

RAIL_EnablePaAutoMode#

RAIL_Status_t RAIL_EnablePaAutoMode (RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

While PA Automode is enabled, the PA will be chosen and set automatically whenever RAIL_SetTxPowerDbm is called or whenever powers are coerced automatically, internally to the RAIL library during a channel change. While PA Auto Mode is enabled, users cannot call RAIL_ConfigTxPower or RAIL_SetTxPower. When entering auto mode, RAIL_SetTxPowerDbm must be called to specify the desired power. When leaving auto mode, RAIL_ConfigTxPower as well as one of RAIL_SetTxPower or RAIL_SetTxPowerDbm must be called to re-specify the desired PA and power level combination.

Note

• : Power conversion curves must be initialized before calling this function. That is, RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm most both be able to operate properly to ensure that PA Auto Mode functions correctly. See the PA Conversions plugin or AN1127 for more details.

Returns

• Status parameter indicating success of function call.

RAIL_IsPaAutoModeEnabled#

bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

Returns

• Indicator of whether Auto Mode is enabled (true) or not (false).

RAILCb_PaAutoModeDecision#

RAIL_Status_t RAILCb_PaAutoModeDecision (RAIL_Handle_t railHandle, RAIL_TxPower_t * power, RAIL_TxPowerMode_t * mode, const RAIL_ChannelConfigEntry_t * chCfgEntry)

Callback that decides which PA and power level should be used while in PA auto mode.

Returns

• Return status indicating result of function call. If this is anything except RAIL_STATUS_NO_ERROR, neither PA's nor their powers will be configured automatically.

Whatever values mode and powerLevel point to when this function return will be applied to the PA hardware and used for transmits. Note

• The mode and power level provided by this function depends on the RAIL_PaAutoModeConfig provided for the chip. The RAIL_PaAutoModeConfig definition for a chip should tend to all the bands supported by the chip and cover the full range of power to find a valid entry for requested power for a specific band.

RAIL_StartTx#

RAIL_Status_t RAIL_StartTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_SchedulerInfo_t * schedulerInfo)

Start a transmit.

Returns

• Status code indicating success of the function call. If successfully initiated, transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

The transmit process will begin immediately or as soon as a packet being received has finished. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo().

Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StartScheduledTx#

RAIL_Status_t RAIL_StartScheduledTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t * config, const RAIL_SchedulerInfo_t * schedulerInfo)

Schedule sending a packet.

Returns

• Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

The transmit process will begin at the scheduled time. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). The time (in microseconds) and whether that time is absolute or relative is specified using the RAIL_ScheduleTxConfig_t structure. What to do if a scheduled transmit fires in the middle of receiving a packet is also specified in this structure.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and will abort any ongoing packet reception.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StartCcaCsmaTx#

RAIL_Status_t RAIL_StartCcaCsmaTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_CsmaConfig_t * csmaConfig, const RAIL_SchedulerInfo_t * schedulerInfo)

Start a transmit using CSMA.

Returns

• Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

Perform the Carrier Sense Multiple Access (CSMA) algorithm, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during CSMA backoff periods if receive is active throughout the CSMA process. This will happen either by starting the CSMA process while receive is already active, or if the csmaBackoff time in the RAIL_CsmaConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the csmaBackoff time is greater than the idleToRx time, receive will only be active during CSMA's clear channel assessments.

If the CSMA algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

Returns an error if a scheduled RX is still in progress.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StartCcaLbtTx#

RAIL_Status_t RAIL_StartCcaLbtTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_LbtConfig_t * lbtConfig, const RAIL_SchedulerInfo_t * schedulerInfo)

Start a transmit using LBT.

Returns

• Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

Performs the Listen Before Talk (LBT) algorithm, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during LBT backoff periods if receive is active throughout the LBT process. This will happen either by starting the LBT process while receive is already active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the lbtBackoff time is greater than the idleToRx time, receive will only be active during LBT's clear channel assessments.

If the LBT algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

Returns an error if a scheduled RX is still in progress.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StartScheduledCcaCsmaTx#

RAIL_Status_t RAIL_StartScheduledCcaCsmaTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t * scheduleTxConfig, const RAIL_CsmaConfig_t * csmaConfig, const RAIL_SchedulerInfo_t * schedulerInfo)

Schedule a transmit using CSMA.

Returns

• Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

Internally, the RAIL library needs a PRS channel for this feature. It will allocate an available PRS channel to use and hold onto that channel for future use. If no PRS channel is available, the function returns with RAIL_STATUS_INVALID_CALL.

Perform the Carrier Sense Multiple Access (CSMA) algorithm at the scheduled time, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during CSMA backoff periods if receive is active throughout the CSMA process. This will happen either by starting the CSMA process while receive is already active, or if the csmaBackoff time in the RAIL_CsmaConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the csmaBackoff time is greater than the idleToRx time, receive will only be active during CSMA's clear channel assessments.

If the CSMA algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StartScheduledCcaLbtTx#

RAIL_Status_t RAIL_StartScheduledCcaLbtTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t * scheduleTxConfig, const RAIL_LbtConfig_t * lbtConfig, const RAIL_SchedulerInfo_t * schedulerInfo)

Schedule a transmit using LBT.

Returns

• Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.

Internally, the RAIL library needs a PRS channel for this feature. It will allocate an available PRS channel to use and hold onto that channel for future use. If no PRS channel is available, the function returns with RAIL_STATUS_INVALID_CALL.

Performs the Listen Before Talk (LBT) algorithm at the scheduled time, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during LBT backoff periods if receive is active throughout the LBT process. This will happen either by starting the LBT process while receive is already active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the lbtBackoff time is greater than the idleToRx time, receive will only be active during LBT's clear channel assessments.

If the LBT algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.

RAIL_StopTx#

RAIL_Status_t RAIL_StopTx (RAIL_Handle_t railHandle, RAIL_StopMode_t mode)

Stop an active or pending transmit.

Returns

• RAIL_STATUS_NO_ERROR if the transmit was successfully stopped or RAIL_STATUS_INVALID_STATE if there is no transmit operation to stop.

Note

• When mode includes RAIL_STOP_MODE_ACTIVE, this can also stop an active auto-ACK transmit. When an active transmit is stopped, RAIL_EVENT_TX_ABORTED or RAIL_EVENT_TXACK_ABORTED should occur. When mode includes RAIL_STOP_MODE_PENDING this can also stop a RAIL_TX_OPTION_CCA_ONLY transmit operation. When a pending transmit is stopped, RAIL_EVENT_TX_BLOCKED should occur.

RAIL_SetCcaThreshold#

RAIL_Status_t RAIL_SetCcaThreshold (RAIL_Handle_t railHandle, int8_t ccaThresholdDbm)

Set the CCA threshold in dBm.

Returns

• Status code indicating success of the function call.

Unlike RAIL_StartCcaCsmaTx() or RAIL_StartCcaLbtTx(), which can cause a transmit, this function only modifies the CCA threshold. A possible use case for this function involves setting the CCA threshold to invalid RSSI of -128 which blocks transmission by preventing clear channel assessments from succeeding.

RAIL_GetTxPacketDetails#

RAIL_Status_t RAIL_GetTxPacketDetails (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t * pPacketDetails)

Get detailed information about the last packet transmitted.

Returns

• RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

Note

• Consider using RAIL_GetTxPacketDetailsAlt2 for smaller code size.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

RAIL_GetTxPacketDetailsAlt#

RAIL_Status_t RAIL_GetTxPacketDetailsAlt (RAIL_Handle_t railHandle, bool isAck, RAIL_Time_t * pPacketTime)

Get detailed information about the last packet transmitted.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was filled in, or an appropriate error code otherwise.

Note

• Consider using RAIL_GetTxPacketDetailsAlt2 to pass in a RAIL_PacketTimeStamp_t structure instead of a RAIL_Time_t structure, particularly when RAIL_PacketTimePosition_t information is needed or useful.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

RAIL_GetTxPacketDetailsAlt2#

RAIL_Status_t RAIL_GetTxPacketDetailsAlt2 (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t * pPacketDetails)

Get detailed information about the last packet transmitted.

Returns

• RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.

RAIL_GetTxTimePreambleStart#

RAIL_Status_t RAIL_GetTxTimePreambleStart (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully determined or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, totalPacketBytes must be RAIL_TX_STARTED_BYTES, and pPacketTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt()).

RAIL_GetTxTimePreambleStartAlt#

RAIL_Status_t RAIL_GetTxTimePreambleStartAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t * pPacketDetails)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, the timeSent field totalPacketBytes must be RAIL_TX_STARTED_BYTES, and the timeSent field packetTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt2()).

RAIL_GetTxTimeSyncWordEnd#

RAIL_Status_t RAIL_GetTxTimeSyncWordEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

RAIL_GetTxTimeSyncWordEndAlt#

RAIL_Status_t RAIL_GetTxTimeSyncWordEndAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t * pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

RAIL_GetTxTimeFrameEnd#

RAIL_Status_t RAIL_GetTxTimeFrameEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of frame.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

RAIL_GetTxTimeFrameEndAlt#

RAIL_Status_t RAIL_GetTxTimeFrameEndAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t * pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of frame.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

RAIL_EnableTxHoldOff#

void RAIL_EnableTxHoldOff (RAIL_Handle_t railHandle, bool enable)

Prevent the radio from starting a transmit.

Enable TX hold off to prevent the radio from starting any transmits. Disable TX hold off to allow the radio to transmit again. Attempting to transmit with the TX hold off enabled will result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.

Note

• This function does not affect a transmit that has already started. To stop an already-started transmission, use RAIL_Idle() with RAIL_IDLE_ABORT.

RAIL_IsTxHoldOffEnabled#

bool RAIL_IsTxHoldOffEnabled (RAIL_Handle_t railHandle)

Check whether or not TX hold off is enabled.

Returns

• Returns true if TX hold off is enabled, false otherwise.

TX hold off can be enabled/disabled using RAIL_EnableTxHoldOff. Attempting to transmit with the TX hold off enabled will block the transmission and result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.

RAIL_SetTxAltPreambleLength#

RAIL_Status_t RAIL_SetTxAltPreambleLength (RAIL_Handle_t railHandle, uint16_t length)

Set an alternate transmitter preamble length.

Returns

• Status code indicating success of the function call.

To cause a transmission to use this alternate preamble length, specify RAIL_TX_OPTION_ALT_PREAMBLE_LEN in the txOptions parameter passed to the respective RAIL transmit API.

Note

• Attempting to set a preamble length of 0xFFFF bits will result in RAIL_STATUS_INVALID_PARAMETER.

RAIL_ConfigRxOptions#

RAIL_Status_t RAIL_ConfigRxOptions (RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)

Configure receive options.

Returns

• Status code indicating success of the function call.

Configure the radio receive flow based on the list of available options. Only the options indicated by the mask parameter will be affected. Pass RAIL_RX_OPTIONS_ALL to set all parameters. The previous settings may affect the current frame if a packet is received during this configuration.

Note

• : On chips where RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is true, enabling RAIL_RX_OPTION_CHANNEL_SWITCHING without configuring RX channel switching, via RAIL_IEEE802154_ConfigRxChannelSwitching, will return RAIL_STATUS_INVALID_PARAMETER for only this option. Any other RX options (except antenna selection) would still take effect.

RAIL_IncludeFrameTypeLength#

void RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

This function must be called before RAIL_ConfigChannels to allow configurations using a frame type based length setup. In RAIL 2.x, it is called by default in the RAILCb_ConfigFrameTypeLength API which can be overridden to save code space. In future versions, the user may be required to call this API explicitly.

RAILCb_ConfigFrameTypeLength#

void RAILCb_ConfigFrameTypeLength (RAIL_Handle_t railHandle, const RAIL_FrameType_t * frameType)

Handle frame type length.

This function is implemented in the radio configuration. Currently, the frame type passed in only handles packet length decoding. If NULL is passed into this function, it clears any currently configured frame type settings. This will either be implemented as an empty function in the radio configuration if it is not needed, to assist in dead code elimination.

RAIL_StartRx#

RAIL_Status_t RAIL_StartRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_SchedulerInfo_t * schedulerInfo)

Start the receiver on a specific channel.

Returns

• Status code indicating success of the function call.

This is a non-blocking function. Whenever a packet is received, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_RX_PACKET_RECEIVED set. If you call this while not idle but with a different channel, any ongoing receive or transmit operation will be aborted.

RAIL_ScheduleRx#

RAIL_Status_t RAIL_ScheduleRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_ScheduleRxConfig_t * cfg, const RAIL_SchedulerInfo_t * schedulerInfo)

Schedule a receive window for some future time.

Returns

• Status code indicating success of the function call.

This API immediately changes the channel and schedules receive to start at the specified time and end at the given end time. If you do not specify an end time, you may call this API later with an end time as long as you set the start time to disabled. You can also terminate the receive operation immediately using the RAIL_Idle() function. Note that relative end times are always relative to the start unless no start time is specified. If changing channels, the channel is changed immediately and will abort any ongoing packet transmission or reception.

Returns an error if a CSMA or LBT transmit is still in progress.

In multiprotocol, ensure that you properly yield the radio after this call. See Yielding the Radio for more details.

RAIL_GetRxPacketInfo#

RAIL_RxPacketHandle_t RAIL_GetRxPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketInfo_t * pPacketInfo)

Get basic information about a pending or received packet.

Returns

• The packet handle for the requested packet: if packetHandle was one of the sentinel values, returns the actual packet handle for that packet, otherwise returns packetHandle. It may return RAIL_RX_PACKET_HANDLE_INVALID to indicate an error.

This function can be used in any RX mode. It does not free up any internal resources. If used in RX RAIL_DataMethod_t::FIFO_MODE, the value in RAIL_RxPacketInfo_t::packetBytes will only return the data remaining in the FIFO. Any data read via earlier calls to RAIL_ReadRxFifo() is not included.

Note

• When getting information about an arriving packet that is not yet complete, (i.e., pPacketInfo->packetStatus == RAIL_RX_PACKET_RECEIVING), keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.

RAIL_GetRxIncomingPacketInfo#

void RAIL_GetRxIncomingPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t * pPacketInfo)

Get information about the live incoming packet (if any).

Differs from RAIL_GetRxPacketInfo() by only returning information about a packet actively being received, something which even the RAIL_RX_PACKET_HANDLE_NEWEST may not represent if there are completed but unprocessed packets in the receive FIFO.

This function can only be called from callback context, e.g., when handling RAIL_EVENT_RX_FILTER_PASSED or RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND. It must not be used with receive RAIL_DataMethod_t::FIFO_MODE if any portion of an incoming packet has already been extracted from the receive FIFO.

Note

• The incomplete data of an arriving packet is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.

RAIL_CopyRxPacket#

static void RAIL_CopyRxPacket (uint8_t * pDest, const RAIL_RxPacketInfo_t * pPacketInfo)

Copy a full packet to a user-specified contiguous buffer.

Note

• This is a convenience helper function, which is intended to be expedient. As a result, it does not check the validity of its arguments, so don't pass either as NULL, and don't pass a pDest pointer to a buffer that's too small for the packet's data.

• If only a portion of the packet is needed, use RAIL_PeekRxPacket() instead.

RAIL_GetRxPacketDetails#

RAIL_Status_t RAIL_GetRxPacketDetails (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Get detailed information about a received packet.

This function can be used in any RX mode; it does not free up any internal resources.

Returns

• RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

Note

• Certain details are always available, while others are only available if the RAIL_RxOptions_tRAIL_RX_OPTION_REMOVE_APPENDED_INFO option is not in effect and the received packet's RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set. See RAIL_RxPacketDetails_t for clarification.

• Consider using RAIL_GetRxPacketDetailsAlt for smaller code size.

RAIL_GetRxPacketDetailsAlt#

RAIL_Status_t RAIL_GetRxPacketDetailsAlt (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Get detailed information about a received packet.

This function can be used in any RX mode. It does not free up any internal resources.

Returns

• RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

This alternative API allows for smaller code size by deadstripping the timestamp adjustment algorithms which are not in use.

Note

• Certain details are always available, while others are only available if the RAIL_RxOptions_tRAIL_RX_OPTION_REMOVE_APPENDED_INFO option is not in effect and the received packet's RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set. See RAIL_RxPacketDetails_t for clarification.

RAIL_GetRxTimePreambleStart#

RAIL_Status_t RAIL_GetRxTimePreambleStart (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.

RAIL_GetRxTimePreambleStartAlt#

RAIL_Status_t RAIL_GetRxTimePreambleStartAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.

RAIL_GetRxTimeSyncWordEnd#

RAIL_Status_t RAIL_GetRxTimeSyncWordEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.

RAIL_GetRxTimeSyncWordEndAlt#

RAIL_Status_t RAIL_GetRxTimeSyncWordEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.

RAIL_GetRxTimeFrameEnd#

RAIL_Status_t RAIL_GetRxTimeFrameEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t * pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of frame.

Returns

• RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.

RAIL_GetRxTimeFrameEndAlt#

RAIL_Status_t RAIL_GetRxTimeFrameEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of frame.

Returns

• RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.