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.

// Associate a specific channel configuration with a particular RAIL instance.
sl_rail_config_channels(rail_handle, channel_configs[0], NULL);
// If want RAIL 2.x behavior where the first channel is prepared by default
// then do:
sl_rail_prepare_channel(rail_handle,
                        sl_rail_get_first_channel(rail_handle,
                                                  channel_configs[0]));
// Otherwise channel preparation is deferred to the first API call that
// specifies a particular channel.

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

sl_rail_frame_type_t

sl_rail_alternate_phy_t

sl_rail_channel_config_group_t

sl_rail_channel_config_entry_t

sl_rail_channel_config_t

sl_rail_channel_metadata_t

sl_rail_stack_info_common_t

RAIL_ChannelConfigEntryAttr_t

sl_rail_channel_config_entry_attr_t

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.

enum

sl_rail_channel_config_entry_type_t {

SL_RAIL_CH_TYPE_NORMAL = 0

SL_RAIL_CH_TYPE_CONC_BASE = 1

SL_RAIL_CH_TYPE_CONC_VIRTUAL = 2

}

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

Typedefs#

typedef const uint32_t *

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

typedef const uint32_t *

sl_rail_radio_config_t

Pointer to a radio configuration array.

typedef uint32_t(*

sl_rail_packet_duration_t)(uint8_t bit_rate, uint16_t number_of_bytes)

A pointer to a function that processes packet duration on air.

typedef void(*

sl_rail_radio_config_changed_callback_t)(sl_rail_handle_t rail_handle, const sl_rail_channel_config_entry_t *p_entry)

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

Functions#

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_ConfigChannelsAlt(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 the current RAIL channel configuration.

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 most-recently requested RAIL channel.

RAIL_Status_t

RAIL_GetChannelAlt(RAIL_Handle_t railHandle, uint16_t *channel)

Return the RAIL channel to which the radio is currently tuned.

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.

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_Status_t

RAIL_SetWhiteningInitVal(RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

RAIL_Status_t

RAIL_SetCrcInitVal(RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

RAIL_Status_t

RAIL_ResetWhiteningInitVal(RAIL_Handle_t railHandle)

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

RAIL_Status_t

RAIL_ResetCrcInitVal(RAIL_Handle_t railHandle)

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

uint16_t

sl_rail_get_first_channel(sl_rail_handle_t rail_handle, const sl_rail_channel_config_t *p_config)

Returns the first channel in the given configuration.

uint16_t

sl_rail_set_fixed_length(sl_rail_handle_t rail_handle, uint16_t bytes)

Modify the currently configured fixed frame length in bytes.

sl_rail_status_t

sl_rail_config_channels(sl_rail_handle_t rail_handle, const sl_rail_channel_config_t *p_config, sl_rail_radio_config_changed_callback_t config_changed_callback)

Configure the channels supported by this device.

sl_rail_status_t

sl_rail_get_channel_metadata(sl_rail_handle_t rail_handle, sl_rail_channel_metadata_t *p_channel_metadata, uint16_t *p_number_of_entries, uint16_t min_channel, uint16_t max_channel)

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

sl_rail_status_t

sl_rail_is_valid_channel(sl_rail_handle_t rail_handle, uint16_t channel)

Check whether the channel exists in the current RAIL channel configuration.

sl_rail_status_t

sl_rail_prepare_channel(sl_rail_handle_t rail_handle, uint16_t channel)

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

sl_rail_status_t

sl_rail_get_channel(sl_rail_handle_t rail_handle, uint16_t *p_channel)

Return the most-recently requested RAIL channel.

sl_rail_status_t

sl_rail_get_tuned_channel(sl_rail_handle_t rail_handle, uint16_t *p_channel)

Return the RAIL channel to which the radio is currently tuned.

uint32_t

sl_rail_get_symbol_rate(sl_rail_handle_t rail_handle)

Return the symbol rate for the current PHY.

uint32_t

sl_rail_get_bit_rate(sl_rail_handle_t rail_handle)

Return the bit rate for the current PHY.

sl_rail_status_t

sl_rail_get_sync_words(sl_rail_handle_t rail_handle, sl_rail_sync_word_config_t *p_sync_word_config)

Get the sync words and their length.

sl_rail_status_t

sl_rail_config_sync_words(sl_rail_handle_t rail_handle, const sl_rail_sync_word_config_t *p_sync_word_config)

Set the selected sync words and their length.

uint16_t

sl_rail_get_whitening_init_val(sl_rail_handle_t rail_handle)

Sets the whitening initialization value.

uint32_t

sl_rail_get_crc_init_val(sl_rail_handle_t rail_handle)

Returns the CRC initialization value.

sl_rail_status_t

sl_rail_set_whitening_init_val(sl_rail_handle_t rail_handle, uint16_t white_init)

Sets the whitening initialization value.

sl_rail_status_t

sl_rail_set_crc_init_val(sl_rail_handle_t rail_handle, uint32_t crc_init)

Sets the CRC initialization value.

sl_rail_status_t

sl_rail_reset_whitening_init_val(sl_rail_handle_t rail_handle)

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

sl_rail_status_t

sl_rail_reset_crc_init_val(sl_rail_handle_t rail_handle)

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

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.

#define

SL_RAIL_SET_FIXED_LENGTH_INVALID (0xFFFFU)

An invalid return value when calling sl_rail_set_fixed_length().

#define

SL_RAIL_RADIO_CONFIG_ENABLE_CONC_PHY 1

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

#define

SL_RAIL_RADIO_CONFIG_ENABLE_STACK_INFO

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

#define

SL_RAIL_CHANNEL_INVALID (0xFFFFU)

A value representing an invalid channel, used for APIs that return or output a channel when none can be identified.

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.

DeprecatedRAIL 2.x synonym of sl_rail_channel_config_entry_type_t.

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.

sl_rail_channel_config_entry_type_t#

sl_rail_channel_config_entry_type_t

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

SL_RAIL_RX_CHANNEL_HOPPING_MODE_CONC and SL_RAIL_RX_CHANNEL_HOPPING_MODE_VT can only be used if the channel supports it.

Enumerator
SL_RAIL_CH_TYPE_NORMAL	Not a concurrent PHY.
SL_RAIL_CH_TYPE_CONC_BASE	Base concurrent PHY.
SL_RAIL_CH_TYPE_CONC_VIRTUAL	Virtual concurrent PHY.

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.

DeprecatedRAIL 2.x synonym of sl_rail_radio_config_t.

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

Type	Direction	Argument Name	Description
	[in]	railHandle	The corresponding RAIL instance handle.
	[in]	entry	A pointer to the radio configuration entry being changed to.

DeprecatedRAIL 2.x synonym of sl_rail_radio_config_changed_callback_t().

sl_rail_radio_config_t#

typedef const uint32_t* sl_rail_radio_config_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.

sl_rail_packet_duration_t#

sl_rail_packet_duration_t )(uint8_t bit_rate, uint16_t number_of_bytes)

A pointer to a function that processes packet duration on air.

sl_rail_radio_config_changed_callback_t#

sl_rail_radio_config_changed_callback_t )(sl_rail_handle_t rail_handle, const sl_rail_channel_config_entry_t *p_entry)

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

Parameters

Type	Direction	Argument Name	Description
	[in]	rail_handle	The corresponding real RAIL instance handle.
	[in]	p_entry	A pointer to the radio configuration entry being changed to.

Function Documentation#

RAIL_SetFixedLength#

uint16_t RAIL_SetFixedLength (RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t	[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

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.

DeprecatedRAIL 2.x synonym of sl_rail_set_fixed_length().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
const RAIL_ChannelConfig_t *	[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.
RAIL_RadioConfigChangedCallback_t	[in]	cb	A pointer to a function called whenever a radio configuration change occurs. May be NULL if do not need a callback.

Returns

The first available channel in the configuration, or SL_RAIL_CHANNEL_INVALID if an error occurs during configuration.

When configuring channels on EFR32, the radio tuner is reconfigured based on the frequency and channel spacing in the channel configuration and the first channel in the configuration is implicitly prepared as if RAIL_PrepareChannel() were called.

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.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_config_channels() which does not implicitly prepare any channel in the configuration. Use sl_rail_get_first_channel() and sl_rail_prepare_channel() to achieve equivalent functionality.

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.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
const RAIL_ChannelConfig_t *	[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.
RAIL_RadioConfigChangedCallback_t	[in]	cb	A pointer to a function called whenever a radio configuration change occurs. May be NULL if do not need a callback.

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.

DeprecatedRAIL 2.x synonym of sl_rail_config_channels().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_ChannelMetadata_t *	[out]	channelMetadata	A pointer to an app-allocated array that will be populated with channel metadata.
uint16_t *	[inout]	length	A pointer to the number of entries available in the channelMetadata array. This value will be updated to the number of channels written to the array, not to exceed the length number passed in.
uint16_t	[in]	minChannel	Minimum channel number about which to collect data.
uint16_t	[in]	maxChannel	Maximum channel number about which to collect data.

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.

DeprecatedRAIL 2.x synonym of sl_rail_get_channel_metadata().

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.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t	[in]	channel	A channel number to check.

Returns

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

DeprecatedRAIL 2.x synonym of sl_rail_is_valid_channel().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t	[in]	channel	The 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.

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.

DeprecatedRAIL 2.x synonym of sl_rail_prepare_channel().

RAIL_GetChannel#

RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t * channel)

Return the most-recently requested RAIL channel.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t *	[out]	channel	A pointer to the channel for which RAIL was most-recently 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.

DeprecatedRAIL 2.x synonym of sl_rail_get_channel().

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.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t *	[out]	channel	A pointer to the currently-tuned 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 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.

DeprecatedRAIL 2.x synonym of sl_rail_get_tuned_channel().

RAIL_GetSymbolRate#

uint32_t RAIL_GetSymbolRate (RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_get_symbol_rate().

RAIL_GetBitRate#

uint32_t RAIL_GetBitRate (RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_get_bit_rate().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint8_t	[in]	txPaCtuneValue	PA Ctune value for TX mode.
uint8_t	[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.

Note

This function does nothing on EFR32 Series 2 devices.

DeprecatedThis RAIL 2.x function has been eliminated in RAIL 3; it only applied to devices no longer supported.

RAIL_GetSyncWords#

RAIL_Status_t RAIL_GetSyncWords (RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t * syncWordConfig)

Get the sync words and their length.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_SyncWordConfig_t *	[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.

DeprecatedRAIL 2.x synonym of sl_rail_get_sync_words().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
const RAIL_SyncWordConfig_t *	[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 sync word length is configured to be. Changing the sync word 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 sync word 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.

Note

If multiple protocols share the same radio configuration, the user should not set custom sync words in any of those protocols as these sync words could leak into the other protocol sharing the same radio configuration.

DeprecatedRAIL 2.x synonym of sl_rail_config_sync_words().

RAIL_GetWhiteningInitVal#

uint16_t RAIL_GetWhiteningInitVal (RAIL_Handle_t railHandle)

Sets the whitening initialization value.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.

Returns

The whitening initialization value currently being used.

DeprecatedRAIL 2.x synonym of sl_rail_get_whitening_init_val().

RAIL_GetCrcInitVal#

uint32_t RAIL_GetCrcInitVal (RAIL_Handle_t railHandle)

Returns the CRC initialization value.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.

Returns

The CRC initialization value currently being used.

DeprecatedRAIL 2.x synonym of sl_rail_get_crc_init_val().

RAIL_SetWhiteningInitVal#

RAIL_Status_t RAIL_SetWhiteningInitVal (RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint16_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_set_whitening_init_val().

RAIL_SetCrcInitVal#

RAIL_Status_t RAIL_SetCrcInitVal (RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint32_t	[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.

DeprecatedRAIL 2.x synonym of sl_rail_set_crc_init_val().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.

Returns

Status code indicating success of the function call.

Can use this function after using RAIL_SetWhiteningInitVal().

DeprecatedRAIL 2.x synonym of sl_rail_reset_whitening_init_val().

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.

Returns

Status code indicating success of the function call.

Can use this function after using RAIL_SetCrcInitVal().

DeprecatedRAIL 2.x synonym of sl_rail_reset_crc_init_val().

sl_rail_get_first_channel#

uint16_t sl_rail_get_first_channel (sl_rail_handle_t rail_handle, const sl_rail_channel_config_t * p_config)

Returns the first channel in the given configuration.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_channel_config_t *	[in]	p_config	A pointer to the channel configuration to use. If NULL, the protocol's currently-configured channel configuration is used.

Returns

Returns the first available channel in the configuration.

sl_rail_set_fixed_length#

uint16_t sl_rail_set_fixed_length (sl_rail_handle_t rail_handle, uint16_t bytes)

Modify the currently configured fixed frame length in bytes.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t	[in]	bytes	The expected fixed frame length in bytes. A value of 0 is infinite. A value of SL_RAIL_SET_FIXED_LENGTH_INVALID restores the frame's length back to that specified by the default frame type configuration.

Returns

The new frame length in bytes configured into the hardware for use: 0 if in infinite mode, or SL_RAIL_SET_FIXED_LENGTH_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 SL_RAIL_SET_FIXED_LENGTH_INVALID. This function will override any fixed or variable length settings from a radio configuration.

sl_rail_config_channels#

sl_rail_status_t sl_rail_config_channels (sl_rail_handle_t rail_handle, const sl_rail_channel_config_t * p_config, sl_rail_radio_config_changed_callback_t config_changed_callback)

Configure the channels supported by this device.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_channel_config_t *	[in]	p_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.
sl_rail_radio_config_changed_callback_t	[in]	config_changed_callback	A pointer to a function called whenever a radio configuration change occurs. May be NULL if do not need a callback.

Returns

Status code indicating success of the function call.

Note

Unlike RAIL 2.x 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 sl_rail_prepare_channel(), sl_rail_start_tx(), sl_rail_start_scheduled_tx(), sl_rail_start_cca_csma_tx(), sl_rail_start_cca_lbt_tx(), sl_rail_start_scheduled_cca_csma_tx(), sl_rail_start_scheduled_cca_lbt_tx(), sl_rail_start_rx(), sl_rail_start_scheduled_rx(), sl_rail_start_average_rssi(), sl_rail_start_tx_stream().
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.

sl_rail_get_channel_metadata#

sl_rail_status_t sl_rail_get_channel_metadata (sl_rail_handle_t rail_handle, sl_rail_channel_metadata_t * p_channel_metadata, uint16_t * p_number_of_entries, uint16_t min_channel, uint16_t max_channel)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_channel_metadata_t *	[out]	p_channel_metadata	A pointer to an app-allocated array that will be populated with channel metadata.
uint16_t *	[inout]	p_number_of_entries	A pointer to the number of entries available in the p_channel_metadata array. This value will be updated to the number of channels written to the array, not to exceed the length number passed in.
uint16_t	[in]	min_channel	Minimum channel number about which to collect data.
uint16_t	[in]	max_channel	Maximum channel number about which to collect data.

Returns

Status code indicating success of the function call. SL_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 p_channel_metadata. However, the channel metadata that was written is valid. SL_RAIL_STATUS_INVALID_STATE indicates that the channel configuration has not been configured. SL_RAIL_STATUS_NO_ERROR indicates complete success.

sl_rail_is_valid_channel#

sl_rail_status_t sl_rail_is_valid_channel (sl_rail_handle_t rail_handle, uint16_t channel)

Check whether the channel exists in the current RAIL channel configuration.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t	[in]	channel	A channel number to check.

Returns

SL_RAIL_STATUS_NO_ERROR if channel exists or SL_RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist.

sl_rail_prepare_channel#

sl_rail_status_t sl_rail_prepare_channel (sl_rail_handle_t rail_handle, uint16_t channel)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t	[in]	channel	The channel to prepare for use.

Returns

SL_RAIL_STATUS_NO_ERROR on success or SL_RAIL_STATUS_INVALID_PARAMETER if the given channel does not have an associated channel configuration entry.

This function walks the current sl_rail_channel_config_t::p_entries 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.

sl_rail_get_channel#

sl_rail_status_t sl_rail_get_channel (sl_rail_handle_t rail_handle, uint16_t * p_channel)

Return the most-recently requested RAIL channel.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t *	[out]	p_channel	A pointer to the channel for which RAIL was most-recently configured.

Returns

SL_RAIL_STATUS_NO_ERROR on success or SL_RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or SL_RAIL_STATUS_INVALID_PARAMETER if p_channel is NULL.

This function returns the channel most recently specified in API calls that pass in a channel to tune to, namely sl_rail_prepare_channel(), sl_rail_start_tx(), sl_rail_start_scheduled_tx(), sl_rail_start_cca_csma_tx(), sl_rail_start_cca_lbt_tx(), sl_rail_start_scheduled_cca_csma_tx(), sl_rail_start_scheduled_cca_lbt_tx(), sl_rail_start_rx(), sl_rail_start_scheduled_rx(), sl_rail_start_average_rssi(), sl_rail_start_tx_stream(). It doesn't follow changes RAIL performs implicitly during channel hopping and mode switch.

sl_rail_get_tuned_channel#

sl_rail_status_t sl_rail_get_tuned_channel (sl_rail_handle_t rail_handle, uint16_t * p_channel)

Return the RAIL channel to which the radio is currently tuned.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t *	[out]	p_channel	A pointer to the currently-tuned channel.

Returns

SL_RAIL_STATUS_NO_ERROR on success or SL_RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or SL_RAIL_STATUS_INVALID_PARAMETER if p_channel 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 sl_rail_get_channel() returns when channel hopping or mode switch are involved.

sl_rail_get_symbol_rate#

uint32_t sl_rail_get_symbol_rate (sl_rail_handle_t rail_handle)

Return the symbol rate for the current PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

The symbol rate in symbols per second or 0.

sl_rail_get_bit_rate#

uint32_t sl_rail_get_bit_rate (sl_rail_handle_t rail_handle)

Return the bit rate for the current PHY.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

The bit rate in bits per second or 0.

sl_rail_get_sync_words#

sl_rail_status_t sl_rail_get_sync_words (sl_rail_handle_t rail_handle, sl_rail_sync_word_config_t * p_sync_word_config)

Get the sync words and their length.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_sync_word_config_t *	[out]	p_sync_word_config	An application-provided non-NULL pointer to store sl_rail_sync_word_config_t sync word information.

Returns

Status code indicating success of the function call.

sl_rail_config_sync_words#

sl_rail_status_t sl_rail_config_sync_words (sl_rail_handle_t rail_handle, const sl_rail_sync_word_config_t * p_sync_word_config)

Set the selected sync words and their length.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
const sl_rail_sync_word_config_t *	[in]	p_sync_word_config	A non-NULL pointer to sl_rail_sync_word_config_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 sync word length is configured to be. Changing the sync word 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 SL_RAIL_STATUS_INVALID_PARAMETER. The default sync word 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 sl_rail_config_channels() will re-establish the sync words specified in the radio configuration.

This function will return SL_RAIL_STATUS_INVALID_STATE if called when BLE has been enabled for this rail_handle. When changing sync words in BLE mode, use sl_rail_ble_config_channel_radio_params() instead.

Note

If multiple protocols share the same radio configuration, the user should not set custom sync words in any of those protocols as these sync words could leak into the other protocol sharing the same radio configuration.

sl_rail_get_whitening_init_val#

uint16_t sl_rail_get_whitening_init_val (sl_rail_handle_t rail_handle)

Sets the whitening initialization value.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

The whitening initialization value currently being used.

sl_rail_get_crc_init_val#

uint32_t sl_rail_get_crc_init_val (sl_rail_handle_t rail_handle)

Returns the CRC initialization value.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

The CRC initialization value currently being used.

sl_rail_set_whitening_init_val#

sl_rail_status_t sl_rail_set_whitening_init_val (sl_rail_handle_t rail_handle, uint16_t white_init)

Sets the whitening initialization value.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint16_t	[in]	white_init	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, sl_rail_reset_whitening_init_val() 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.

sl_rail_set_crc_init_val#

sl_rail_status_t sl_rail_set_crc_init_val (sl_rail_handle_t rail_handle, uint32_t crc_init)

Sets the CRC initialization value.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint32_t	[in]	crc_init	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, sl_rail_reset_crc_init_val() 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.

sl_rail_reset_whitening_init_val#

sl_rail_status_t sl_rail_reset_whitening_init_val (sl_rail_handle_t rail_handle)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

Status code indicating success of the function call.

Can use this function after using sl_rail_set_whitening_init_val().

sl_rail_reset_crc_init_val#

sl_rail_status_t sl_rail_reset_crc_init_val (sl_rail_handle_t rail_handle)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

Status code indicating success of the function call.

Can use this function after using sl_rail_set_crc_init_val().