Radio Configuration#

Routines for setting up and querying radio configuration information.

These routines allow for runtime flexibility in the radio configuration. Some of the parameters, however, are meant to be generated from the radio calculator in Simplicity Studio. The basic code to configure the radio from this calculator output looks like the example below.

// Associate a specific channel configuration with a particular RAIL instance and
// load the settings that correspond to the first usable channel.
RAIL_ConfigChannels(railHandle, channelConfigs[0]);

For more information about the types of parameters that can be changed in the other functions and how to use them, see their individual documentation.

Modules#

RAIL_FrameType_t

RAIL_AlternatePhy_t

RAIL_ChannelConfigEntry_t

RAIL_ChannelConfig_t

RAIL_ChannelMetadata_t

RAIL_StackInfoCommon_t

RAIL_ChannelConfigEntryAttr_t

Enumerations#

enum
RAIL_CH_TYPE_NORMAL
RAIL_CH_TYPE_CONC_BASE
RAIL_CH_TYPE_CONC_VIRTUAL
}

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

Typedefs#

typedef const uint32_t *

Pointer to a radio configuration array.

typedef void(*
RAIL_RadioConfigChangedCallback_t)(RAIL_Handle_t railHandle, const RAIL_ChannelConfigEntry_t *entry)

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

Functions#

RAIL_ConfigRadio(RAIL_Handle_t railHandle, RAIL_RadioConfig_t config)

Load a static radio configuration.

uint16_t
RAIL_SetFixedLength(RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

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

Configure the channels supported by this device.

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.

RAIL_IsValidChannel(RAIL_Handle_t railHandle, uint16_t channel)

Check whether the channel exists in RAIL.

RAIL_PrepareChannel(RAIL_Handle_t railHandle, uint16_t channel)

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

RAIL_GetChannel(RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

RAIL_GetChannelAlt(RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

uint32_t
RAIL_GetSymbolRate(RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

uint32_t
RAIL_GetBitRate(RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

RAIL_SetPaCTune(RAIL_Handle_t railHandle, uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue)

Set the PA capacitor tune value for transmit and receive.

RAIL_GetSyncWords(RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t *syncWordConfig)

Get the sync words and their length.

RAIL_ConfigSyncWords(RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t *syncWordConfig)

Set the selected sync words and their length.

uint16_t
RAIL_GetWhiteningInitVal(RAIL_Handle_t railHandle)

Sets the whitening initialization value.

uint32_t
RAIL_GetCrcInitVal(RAIL_Handle_t railHandle)

Returns the CRC initialization value.

RAIL_SetWhiteningInitVal(RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

RAIL_SetCrcInitVal(RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

RAIL_ResetWhiteningInitVal(RAIL_Handle_t railHandle)

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

RAIL_ResetCrcInitVal(RAIL_Handle_t railHandle)

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

Macros#

#define

An invalid return value when calling RAIL_SetFixedLength().

#define

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

#define

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

Enumeration Documentation#

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.

Enumerator
RAIL_CH_TYPE_NORMAL

Not a concurrent PHY.

RAIL_CH_TYPE_CONC_BASE

Base concurrent PHY.

RAIL_CH_TYPE_CONC_VIRTUAL

Virtual concurrent PHY.


Definition at line 2028 of file common/rail_types.h

Typedef Documentation#

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.


Definition at line 1966 of file common/rail_types.h

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.

Parameters
[in]railHandle

A handle for RAIL instance.

[in]entry

The radio configuration entry being changed to.


Definition at line 2353 of file common/rail_types.h

Function Documentation#

RAIL_ConfigRadio#

RAIL_Status_t RAIL_ConfigRadio (RAIL_Handle_t railHandle, RAIL_RadioConfig_t config)

Load a static radio configuration.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to a 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.


Definition at line 559 of file common/rail.h

RAIL_SetFixedLength#

uint16_t RAIL_SetFixedLength (RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

Parameters
[in]railHandle

A RAIL instance handle.

[in]length

The expected fixed frame length. A value of 0 is infinite. A value of RAIL_SETFIXEDLENGTH_INVALID restores the frame's length back to the length specified by the default frame type configuration.

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.


Definition at line 580 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to the channel configuration for your device. This pointer will be cached in the library so it must exist for the runtime of the application. Typically, this should be what is stored in Flash by the configuration tool.

[in]cb

Function called whenever a radio configuration change occurs.

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.


Definition at line 601 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channelMetadata

Allocated array that will be populated with channel metadata.

[inout]length

Pointer to the length of the channelMetadata. This value will be updated to the number of channels written to the array.

[in]minChannel

Minimum channel number about which to collect data.

[in]maxChannel

Maximum channel number about which to collect data.

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.


Definition at line 623 of file common/rail.h

RAIL_IsValidChannel#

RAIL_Status_t RAIL_IsValidChannel (RAIL_Handle_t railHandle, uint16_t channel)

Check whether the channel exists in RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel number to check.

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.


Definition at line 640 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The channel to prepare for use.

Returns

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.


Definition at line 660 of file common/rail.h

RAIL_GetChannel#

RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t * channel)

Return the current RAIL channel.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channel

The channel for which RAIL is currently configured.

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.


Definition at line 680 of file common/rail.h

RAIL_GetChannelAlt#

RAIL_Status_t RAIL_GetChannelAlt (RAIL_Handle_t railHandle, uint16_t * channel)

Return the current RAIL channel.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channel

The channel for which RAIL is currently configured.

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.


Definition at line 697 of file common/rail.h

RAIL_GetSymbolRate#

uint32_t RAIL_GetSymbolRate (RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

Parameters
[in]railHandle

A RAIL instance handle.

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.


Definition at line 711 of file common/rail.h

RAIL_GetBitRate#

uint32_t RAIL_GetBitRate (RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

Parameters
[in]railHandle

A RAIL instance handle.

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.


Definition at line 739 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txPaCtuneValue

PA Ctune value for TX mode.

[in]rxPaCtuneValue

PA Ctune value for RX mode.

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.


Definition at line 769 of file common/rail.h

RAIL_GetSyncWords#

RAIL_Status_t RAIL_GetSyncWords (RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t * syncWordConfig)

Get the sync words and their length.

Parameters
[in]railHandle

A RAIL instance handle.

[out]syncWordConfig

An application-provided non-NULL pointer to store RAIL_SyncWordConfig_t sync word information.

Returns

  • Status code indicating success of the function call.


Definition at line 781 of file common/rail.h

RAIL_ConfigSyncWords#

RAIL_Status_t RAIL_ConfigSyncWords (RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t * syncWordConfig)

Set the selected sync words and their length.

Parameters
[in]railHandle

A RAIL instance handle.

[in]syncWordConfig

A non-NULL pointer to RAIL_SyncWordConfig_t specifying the sync words and their length. The desired length should be between 2 and 32 bits inclusive, however it is recommended to not change the length below what the PHY syncWord length is configured to be. Changing the syncWord length, especially to that which is lower than the default length, may result in a decrease in packet reception rate or may not work at all. Other values will result in RAIL_STATUS_INVALID_PARAMETER. The default syncWord continues to be valid.

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.


Definition at line 806 of file common/rail.h

RAIL_GetWhiteningInitVal#

uint16_t RAIL_GetWhiteningInitVal (RAIL_Handle_t railHandle)

Sets the whitening initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The whitening initialization value currently being used.


Definition at line 815 of file common/rail.h

RAIL_GetCrcInitVal#

uint32_t RAIL_GetCrcInitVal (RAIL_Handle_t railHandle)

Returns the CRC initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The CRC initialization value currently being used.


Definition at line 823 of file common/rail.h

RAIL_SetWhiteningInitVal#

RAIL_Status_t RAIL_SetWhiteningInitVal (RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]whiteInit

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


Definition at line 845 of file common/rail.h

RAIL_SetCrcInitVal#

RAIL_Status_t RAIL_SetCrcInitVal (RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]crcInit

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


Definition at line 867 of file common/rail.h

RAIL_ResetWhiteningInitVal#

RAIL_Status_t RAIL_ResetWhiteningInitVal (RAIL_Handle_t railHandle)

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

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Can use this function after using RAIL_SetWhiteningInitVal().


Definition at line 879 of file common/rail.h

RAIL_ResetCrcInitVal#

RAIL_Status_t RAIL_ResetCrcInitVal (RAIL_Handle_t railHandle)

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

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Can use this function after using RAIL_SetCrcInitVal().


Definition at line 890 of file common/rail.h

Macro Definition Documentation#

RAIL_SETFIXEDLENGTH_INVALID#

#define RAIL_SETFIXEDLENGTH_INVALID
Value:
(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.


Definition at line 2013 of file common/rail_types.h

RADIO_CONFIG_ENABLE_CONC_PHY#

#define RADIO_CONFIG_ENABLE_CONC_PHY
Value:
1

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

Needed for backwards compatibility.


Definition at line 2046 of file common/rail_types.h

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.


Definition at line 2053 of file common/rail_types.h