Radio Configuration

Routines for setting up and querying radio configuration information.

Modules

EFR32
Types specific to the EFR32 for radio configuration.

Data Structures

struct  RAIL_FrameType_t
 Configures if there is a frame type in your frame and the lengths of each frame.
 
struct  RAIL_ChannelConfigEntry_t
 A channel configuration entry structure, which defines a channel range and parameters across which a corresponding radio configuration is valid.
 
struct  RAIL_ChannelConfig_t
 A channel configuration structure, which defines the channel meaning when a channel number is passed into a RAIL function, e.g., RAIL_StartTx() and RAIL_StartRx().
 
struct  RAIL_ChannelMetadata_t
 Container for individual channel metadata.
 
struct  RAIL_StackInfoCommon_t
 StackInfo fields common to all protocols.
 
struct  RAIL_ChannelConfigEntryAttr_t
 A channel configuration entry attribute structure.

Macros

#define RAIL_SETFIXEDLENGTH_INVALID   (0xFFFFU)
 An invalid return value when calling RAIL_SetFixedLength().
 
#define RADIO_CONFIG_ENABLE_CONC_PHY   1
 Indicates this version of RAIL supports concurrent PHY information in radio configurator output.
 
#define RADIO_CONFIG_ENABLE_STACK_INFO
 Indicates this version of RAIL supports stack info feature in radio configurator output.

Typedefs

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.

Enumerations

enum  RAIL_ChannelConfigEntryType_t {
  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.

Functions

RAIL_Status_t 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_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.
 
RAIL_Status_t RAIL_IsValidChannel (RAIL_Handle_t railHandle, uint16_t channel)
 Check whether the channel exists in RAIL.
 
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.
 
RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t *channel)
 Return the current RAIL channel.
 
RAIL_Status_t 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_Status_t RAIL_SetPaCTune (RAIL_Handle_t railHandle, uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue)
 Set the PA capacitor tune value for transmit and receive.
 
RAIL_Status_t RAIL_GetSyncWords (RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t *syncWordConfig)
 Get the sync words and their length.
 
RAIL_Status_t RAIL_ConfigSyncWords (RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t *syncWordConfig)
 Set the selected sync words and their length.

Detailed Description

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.

Macro Definition Documentation

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

Definition at line 1632 of file 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 1639 of file rail_types.h.

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

Definition at line 1599 of file rail_types.h.

Typedef Documentation

◆ RAIL_RadioConfigChangedCallback_t

RAIL_RadioConfigChangedCallback_t

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

Parameters
[in]railHandleA handle for RAIL instance.
[in]entryThe radio configuration entry being changed to.

Definition at line 1922 of file rail_types.h.

Enumeration Type Documentation

◆ 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 1614 of file rail_types.h.

Function Documentation

◆ 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]railHandleA RAIL instance handle.
[in]configA 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]cbFunction 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.

◆ RAIL_ConfigRadio()

RAIL_Status_t RAIL_ConfigRadio ( RAIL_Handle_t  railHandle,
RAIL_RadioConfig_t  config 
)

Load a static radio configuration.

Parameters
[in]railHandleA RAIL instance handle.
[in]configA 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.

◆ 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]railHandleA RAIL instance handle.
[in]syncWordConfigA 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. 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.

◆ RAIL_GetBitRate()

uint32_t RAIL_GetBitRate ( RAIL_Handle_t  railHandle)

Return the bit rate for the current PHY.

Parameters
[in]railHandleA 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.

◆ RAIL_GetChannel()

RAIL_Status_t RAIL_GetChannel ( RAIL_Handle_t  railHandle,
uint16_t *  channel 
)

Return the current RAIL channel.

Parameters
[in]railHandleA RAIL instance handle.
[out]channelThe 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.

◆ RAIL_GetChannelAlt()

RAIL_Status_t RAIL_GetChannelAlt ( RAIL_Handle_t  railHandle,
uint16_t *  channel 
)

Return the current RAIL channel.

Parameters
[in]railHandleA RAIL instance handle.
[out]channelThe 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.

◆ 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]railHandleA RAIL instance handle.
[out]channelMetadataAllocated array that will be populated with channel metadata.
[in,out]lengthPointer to the length of the channelMetadata. This value will be updated to the number of channels written to the array.
[in]minChannelMinimum channel number about which to collect data.
[in]maxChannelMaximum 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.

◆ RAIL_GetSymbolRate()

uint32_t RAIL_GetSymbolRate ( RAIL_Handle_t  railHandle)

Return the symbol rate for the current PHY.

Parameters
[in]railHandleA 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.

◆ RAIL_GetSyncWords()

RAIL_Status_t RAIL_GetSyncWords ( RAIL_Handle_t  railHandle,
RAIL_SyncWordConfig_t syncWordConfig 
)

Get the sync words and their length.

Parameters
[in]railHandleA RAIL instance handle.
[out]syncWordConfigAn application-provided non-NULL pointer to store RAIL_SyncWordConfig_t sync word information.
Returns
Status code indicating success of the function call.

◆ RAIL_IsValidChannel()

RAIL_Status_t RAIL_IsValidChannel ( RAIL_Handle_t  railHandle,
uint16_t  channel 
)

Check whether the channel exists in RAIL.

Parameters
[in]railHandleA RAIL instance handle.
[in]channelA 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.

◆ 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]railHandleA RAIL instance handle.
[in]channelThe channel to prepare for use.
Returns
RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_PARAMETER if the given channel does not have an associated channel configuration entry or RAIL_STATUS_INVALID_STATE if the specified railHandle is not the current RAIL handle in use. RAIL_STATUS_INVALID_STATE is only used in the multiprotocol version of RAIL.

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_SetFixedLength()

uint16_t RAIL_SetFixedLength ( RAIL_Handle_t  railHandle,
uint16_t  length 
)

Modify the currently configured fixed frame length in bytes.

Parameters
[in]railHandleA RAIL instance handle.
[in]lengthThe 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.

◆ 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]railHandleA RAIL instance handle.
[in]txPaCtuneValuePA Ctune value for TX mode.
[in]rxPaCtuneValuePA 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.