Radio Configuration#

RAIL_ChannelConfigEntryType_t#

RAIL_ChannelConfigEntryType_t

Define if the channel support using concurrent PHY during channel hopping.

RAIL_RX_CHANNEL_HOPPING_MODE_CONC and RAIL_RX_CHANNEL_HOPPING_MODE_VT can only be used if the channel supports it.

RAIL_RadioConfig_t#

typedef const uint32_t* RAIL_RadioConfig_t

Pointer to a radio configuration array.

The radio configuration properly configures the radio for operation on a protocol. These configurations are very chip-specific should not be created or edited by hand.

RAIL_RadioConfigChangedCallback_t#

RAIL_RadioConfigChangedCallback_t )(RAIL_Handle_t railHandle, const RAIL_ChannelConfigEntry_t *entry)

A pointer to a function called whenever a radio configuration change occurs.

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

• 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

• 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_ConfigChannelsAlt#

RAIL_Status_t RAIL_ConfigChannelsAlt (RAIL_Handle_t railHandle, const RAIL_ChannelConfig_t * config, RAIL_RadioConfigChangedCallback_t cb)

Configure the channels supported by this device.

Returns

• Status code indicating success of the function call.

Note

• Unlike RAIL_ConfigChannels(), this function only caches the configuration and does not prepare any channel in the configuration. That action is deferred to the next call to a RAIL API where channel is passed as a parameter, namely RAIL_PrepareChannel(), RAIL_StartTx(), RAIL_StartScheduledTx(), RAIL_StartCcaCsmaTx(), RAIL_StartCcaLbtTx(), RAIL_StartScheduledCcaCsmaTx(), RAIL_StartScheduledCcaLbtTx(), RAIL_StartRx(), RAIL_ScheduleRx(), RAIL_StartAverageRssi(), RAIL_StartTxStream().

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

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 code indicating success of the function 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 the current RAIL channel configuration.

Returns

• RAIL_STATUS_NO_ERROR if channel exists or RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist.

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 current RAIL_ChannelConfig_t::configs list and applies the configuration associated with the specified channel if found. 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 most-recently requested 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 RAIL channel to which the radio is currently tuned.

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 to which the radio is currently tuned if the specified RAIL handle is active. It returns the channel to which it will be tuned 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.

Note

• This function does nothing on EFR32 Series 2 devices.

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

#define RAIL_SETFIXEDLENGTH_INVALID

(0xFFFFU)

An invalid return value when calling RAIL_SetFixedLength().

An invalid return value when calling RAIL_SetFixedLength() while the radio is not in fixed-length mode.

RADIO_CONFIG_ENABLE_CONC_PHY#

#define RADIO_CONFIG_ENABLE_CONC_PHY

1

Indicates this version of RAIL supports concurrent PHY information in radio configurator output.

Needed for backwards compatibility.

RADIO_CONFIG_ENABLE_STACK_INFO#

#define RADIO_CONFIG_ENABLE_STACK_INFO

Indicates this version of RAIL supports stack info feature in radio configurator output.

Needed for backwards compatibility.