Diagnostic#

RAIL_StreamMode_t#

RAIL_StreamMode_t

Possible stream output modes.

DeprecatedRAIL 2.x synonym of sl_rail_stream_mode_t.

sl_rail_stream_mode_t#

sl_rail_stream_mode_t

Possible stream output modes.

RAIL_FrequencyOffset_t#

RAIL_FrequencyOffset_t

Type that represents the number of Frequency Offset units.

It is used with RAIL_GetRxFreqOffset() and RAIL_SetFreqOffset().

The units are chip-specific. For EFR32 they are radio synthesizer resolution steps (synth ticks) and is limited to 15 bits. A value of RAIL_FREQUENCY_OFFSET_INVALID means that this value is invalid.

DeprecatedRAIL 2.x synonym of sl_rail_frequency_offset_t.

RAIL_VerifyCallbackPtr_t#

typedef bool(* RAIL_VerifyCallbackPtr_t) (uint32_t address, uint32_t expectedValue, uint32_t actualValue) )(uint32_t address, uint32_t expectedValue, uint32_t actualValue)

A pointer to a verification callback function.

This will be called by the radio state verification feature built into RAIL when a verified memory value is different from its reference value.

Returns

• true indicates a data value difference is acceptable. false indicates a data value difference in unacceptable.

Note

• This callback will be issued when an address' value is different from its reference value and either of the following conditions are met:

  1. The default radio configuration provided by the radio configurator is used for verification purposes (i.e., a custom radio configuration is not supplied as an input to RAIL_ConfigVerification()), and the radio configurator has flagged the address under question as being verifiable.

  2. A custom radio configuration is provided to the verification API (i.e., a custom radio configuration is supplied as an input to RAIL_ConfigVerification()). When providing a custom radio configuration for verification purposes, all addresses in that configuration will be verified, regardless of whether or not the addresses are flagged as verifiable.

DeprecatedThis RAIL 2.x type has been eliminated in RAIL 3. This functionality is no longer supported.

sl_rail_frequency_offset_t#

sl_rail_frequency_offset_t

Type that represents the number of Frequency Offset units.

It is used with sl_rail_get_rx_freq_offset() and sl_rail_set_freq_offset().

The units are chip-specific. For EFR32 they are radio synthesizer resolution steps (synth ticks) and is limited to 15 bits. A value of SL_RAIL_FREQUENCY_OFFSET_INVALID means that this value is invalid.

RAIL_ConfigDirectMode#

RAIL_Status_t RAIL_ConfigDirectMode (RAIL_Handle_t railHandle, const RAIL_DirectModeConfig_t * directModeConfig)

Configure direct mode for RAIL.

Returns

• RAIL_STATUS_NO_ERROR on success and an error code on failure.

This API configures direct mode and should be called before calling RAIL_EnableDirectMode(). If this function is not called, the following default RAIL_DirectModeConfig_t configuration will be used:

RAIL_DirectModeConfig_t defaultConfig = {
  .syncRx   = false,
  .syncTx   = false,
  .doutPort = SL_GPIO_PORT_A,
  .doutPin  = 5,
  .dinPort  = SL_GPIO_PORT_A,
  .dinPin   = 7,
  .dclkPort = SL_GPIO_PORT_A,
  .dclkPin  = 6,
};

Warnings

• This API is not safe to use in a multiprotocol app.

DeprecatedRAIL 2.x synonym of sl_rail_config_direct_mode().

RAIL_EnableDirectMode#

RAIL_Status_t RAIL_EnableDirectMode (RAIL_Handle_t railHandle, bool enable)

Enable or disable direct mode for RAIL.

Returns

• RAIL_STATUS_NO_ERROR on success and an error code on failure.

See RAIL_EnableDirectModeAlt() for more detailed function description.

Warnings

• New applications should consider using RAIL_EnableDirectModeAlt() for this functionality.

Note

• This feature is only available on certain devices. RAIL_SupportsDirectMode() can be used to check if a particular device supports this feature or not.

Warnings

• As this function relies on GPIO access and RAIL is meant to run in TrustZone non-secure world, it is not supported if GPIO is configured as secure peripheral and it will return RAIL_STATUS_INVALID_CALL.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_enable_direct_mode() with different parameters.

RAIL_EnableDirectModeAlt#

RAIL_Status_t RAIL_EnableDirectModeAlt (RAIL_Handle_t railHandle, bool enableDirectTx, bool enableDirectRx)

Enable or disable direct mode for RAIL.

Returns

• RAIL_STATUS_NO_ERROR on success or an error code on failure.

This API enables or disables the modem and GPIOs for direct mode operation. see RAIL_ConfigDirectMode() for information on selecting the correct hardware configuration. If direct mode is enabled, packets are output and input directly to the radio via GPIO and RAIL packet handling is ignored.

Note

• This feature is only available on certain chips. RAIL_SupportsDirectMode() can be used to check if a particular chip supports this feature or not.

Warnings

• This API is not safe to use in a multiprotocol app.

• As this function relies on GPIO access and RAIL is meant to run in TrustZone non-secure world, it is not supported if GPIO is configured as secure peripheral and it will return RAIL_STATUS_INVALID_CALL.

DeprecatedRAIL 2.x synonym of sl_rail_enable_direct_mode().

RAIL_GetRadioClockFreqHz#

uint32_t RAIL_GetRadioClockFreqHz (RAIL_Handle_t railHandle)

Get the radio subsystem clock frequency in Hz.

Returns

• Radio subsystem clock frequency in Hz.

DeprecatedRAIL 2.x synonym of sl_rail_get_radio_clock_freq_hz().

RAIL_SetTune#

RAIL_Status_t RAIL_SetTune (RAIL_Handle_t railHandle, uint32_t tune)

Set the crystal tuning.

Returns

• Status code indicating success of the function call.

Tunes the crystal that the radio depends on to change the location of the center frequency for transmitting and receiving. This function will only succeed if the radio is idle at the time of the call.

Note

• This function proportionally affects the entire chip's timing across all its peripherals, including radio tuning and channel spacing. It is recommended to call this function only when HFXO is not being used, as it can cause disturbance on the HFXO frequency. A separate function, RAIL_SetFreqOffset(), can be used to adjust just the radio tuner without disturbing channel spacing or other chip peripheral timing.

• This API sets CTUNEXIANA and internally CTUNEXOANA = CTUNEXIANA + delta where delta is set or changed by RAIL_SetTuneDelta(). The default delta may not be 0 on some devices.

DeprecatedRAIL 2.x synonym of sl_rail_set_tune().

RAIL_GetTune#

uint32_t RAIL_GetTune (RAIL_Handle_t railHandle)

Get the crystal tuning.

Returns

• A chip-dependent crystal capacitor bank tuning parameter.

Retrieves the current tuning value used by the crystal that the radio depends on. Note

• This is the CTUNEXIANA value.

DeprecatedRAIL 2.x synonym of sl_rail_get_tune().

RAIL_SetTuneDelta#

RAIL_Status_t RAIL_SetTuneDelta (RAIL_Handle_t railHandle, int32_t delta)

Set the crystal tuning delta.

Returns

• Status code indicating success of the function call.

Set the CTUNEXOANA delta for RAIL_SetTune() to use: CTUNEXOANA = CTUNEXIANA + delta (subject to field-size limitations). This function does not change CTUNE values; call RAIL_SetTune() to put a new delta into effect.

DeprecatedRAIL 2.x synonym of sl_rail_set_tune_delta().

RAIL_GetTuneDelta#

int32_t RAIL_GetTuneDelta (RAIL_Handle_t railHandle)

Get the crystal tuning delta.

Returns

• A chip-dependent crystal capacitor bank tuning delta.

Retrieves the current tuning delta used by RAIL_SetTune(). Note

• The default delta if RAIL_SetTuneDelta() has never been called is device-dependent and may not be 0.

DeprecatedRAIL 2.x synonym of sl_rail_get_tune_delta().

RAIL_GetRxFreqOffset#

RAIL_FrequencyOffset_t RAIL_GetRxFreqOffset (RAIL_Handle_t railHandle)

Get the frequency offset.

Returns

• The measured frequency offset on a received packet. The units are described in the RAIL_FrequencyOffset_t documentation. If this returns RAIL_FREQUENCY_OFFSET_INVALID, it was called while the radio wasn't active and there is no way to get the frequency offset.

Retrieves the measured frequency offset used during the previous received packet, which includes the current radio frequency offset (see RAIL_SetFreqOffset()). If the chip has not been in RX, it returns the nominal radio frequency offset.

Note

• Changing to any non-idle radio state after reception can cause this value to be overwritten so it is safest to capture during packet reception.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_freq_offset().

RAIL_SetFreqOffset#

RAIL_Status_t RAIL_SetFreqOffset (RAIL_Handle_t railHandle, RAIL_FrequencyOffset_t freqOffset)

Set the nominal radio frequency offset.

Returns

• Status code indicating success of the function call.

This function is used to adjust the radio's tuning frequency slightly up or down. It might be used in conjunction with RAIL_GetRxFreqOffset() after receiving a packet from a peer to adjust the tuner to better match the peer's tuned frequency.

Note

• Unlike RAIL_SetTune(), which affects the entire chip's timing including radio tuning and channel spacing, this function only affects radio tuning without disturbing channel spacing or other chip peripheral timing.

DeprecatedRAIL 2.x synonym of sl_rail_set_freq_offset().

RAIL_StartTxStream#

RAIL_Status_t RAIL_StartTxStream (RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode)

Start transmitting a stream on a certain channel.

Returns

• Status code indicating success of the function call.

Begins streaming onto the given channel. The sources can either be an unmodulated carrier wave or an encoded stream of bits from a PN9 source. All ongoing radio operations will be stopped before transmission begins.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_start_tx_stream() with its additional parameter.

RAIL_StartTxStreamAlt#

RAIL_Status_t RAIL_StartTxStreamAlt (RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode, RAIL_TxOptions_t options)

Start transmitting a stream on a certain channel with the ability to select an antenna.

Returns

• Status code indicating success of the function call.

Begins streaming onto the given channel. The sources can either be an unmodulated carrier wave or an encoded stream of bits from a PN9 source. All ongoing radio operations will be stopped before transmission begins.

DeprecatedRAIL 2.x synonym of sl_rail_start_tx_stream().

RAIL_StopTxStream#

RAIL_Status_t RAIL_StopTxStream (RAIL_Handle_t railHandle)

Stop stream transmission and idle the radio.

Returns

• Status code indicating success of the function call.

Halts the transmission started by RAIL_StartTxStream().

DeprecatedRAIL 2.x synonym of sl_rail_stop_tx_stream().

RAIL_StopInfinitePreambleTx#

RAIL_Status_t RAIL_StopInfinitePreambleTx (RAIL_Handle_t railHandle)

Stop infinite preamble transmission started and start transmitting the rest of the packet.

Returns

• Status code indicating success of the function call: RAIL_STATUS_NO_ERROR if infinite preamble was stopped; RAIL_STATUS_INVALID_CALL if the radio isn't configured for infinite preamble; RAIL_STATUS_INVALID_STATE if the radio isn't transmitting.

This function is only useful for radio configurations that specify an infinite preamble. Call this API only after RAIL_EVENT_TX_STARTED has occurred and the radio is transmitting.

DeprecatedRAIL 2.x synonym of sl_rail_stop_infinite_preamble_tx().

RAIL_ConfigVerification#

RAIL_Status_t RAIL_ConfigVerification (RAIL_Handle_t railHandle, RAIL_VerifyConfig_t * configVerify, RAIL_RadioConfig_t radioConfig, RAIL_VerifyCallbackPtr_t cb)

Configure the verification of radio memory contents.

Returns

• RAIL_STATUS_NO_ERROR if setup of the verification feature successfully occurred. RAIL_STATUS_INVALID_PARAMETER is returned if the provided railHandle or configVerify structures are invalid.

DeprecatedThis RAIL 2.x function has been eliminated in RAIL 3. This functionality is no longer supported.

RAIL_Verify#

RAIL_Status_t RAIL_Verify (RAIL_VerifyConfig_t * configVerify, uint32_t durationUs, bool restart)

Verify radio memory contents.

Returns

• RAIL_STATUS_NO_ERROR if the contents of all applicable memory locations have been verified. RAIL_STATUS_SUSPENDED is returned if the provided test duration expired but the time was not sufficient to verify all memory contents. By calling RAIL_Verify() again, further verification will commence. RAIL_STATUS_INVALID_PARAMETER is returned if the provided verifyConfig structure pointer is not configured for use by the active RAIL handle. RAIL_STATUS_INVALID_STATE is returned if any of the verified memory contents are different from their reference values.

DeprecatedThis RAIL 2.x function has been eliminated in RAIL 3. This functionality is no longer supported.

sl_rail_config_direct_mode#

sl_rail_status_t sl_rail_config_direct_mode (sl_rail_handle_t rail_handle, const sl_rail_direct_mode_config_t * p_direct_mode_config)

Configure direct mode for RAIL.

Returns

• SL_RAIL_STATUS_NO_ERROR on success and an error code on failure.

This API configures direct mode and should be called before calling sl_rail_enable_direct_mode(). If this function is not called, the following default configuration will be used:

sl_rail_direct_mode_config_t default_config = {
  .sync_rx   = false,
  .sync_tx   = false,
  .dout_port = SL_GPIO_PORT_A,
  .dout_pin  = 5,
  .din_port  = SL_GPIO_PORT_A,
  .din_pin   = 7,
  .dclk_port = SL_GPIO_PORT_A,
  .dclk_pin  = 6,
};

Warnings

• This API is not safe to use in a multiprotocol app.

sl_rail_enable_direct_mode#

sl_rail_status_t sl_rail_enable_direct_mode (sl_rail_handle_t rail_handle, bool enable_direct_tx, bool enable_direct_rx)

Enable or disable direct mode for RAIL.

Returns

• SL_RAIL_STATUS_NO_ERROR on success or an error code on failure.

This API enables or disables the modem and GPIOs for direct mode operation. see sl_rail_config_direct_mode() for information on selecting the correct hardware configuration. If direct mode is enabled, packets are output and input directly to the radio via GPIO and RAIL packet handling is ignored.

Note

• This feature is only available on certain chips. sl_rail_supports_direct_mode() can be used to check if a particular chip supports this feature or not.

Warnings

• This API is not safe to use in a multiprotocol app.

• As this function relies on GPIO access and RAIL is meant to run in TrustZone non-secure world, it is not supported if GPIO is configured as secure peripheral and it will return SL_RAIL_STATUS_INVALID_CALL.

sl_rail_get_radio_clock_freq_hz#

uint32_t sl_rail_get_radio_clock_freq_hz (sl_rail_handle_t rail_handle)

Get the radio subsystem clock frequency in Hz.

Returns

• Radio subsystem clock frequency in Hz.

sl_rail_set_tune#

sl_rail_status_t sl_rail_set_tune (sl_rail_handle_t rail_handle, uint32_t tune)

Set the crystal tuning.

Returns

• Status code indicating success of the function call.

Tunes the crystal that the radio depends on to change the location of the center frequency for transmitting and receiving. This function will only succeed if the radio is idle at the time of the call.

Note

• This function proportionally affects the entire chip's timing across all its peripherals, including radio tuning and channel spacing. It is recommended to call this function only when HFXO is not being used, as it can cause disturbance on the HFXO frequency. A separate function, sl_rail_set_freq_offset(), can be used to adjust just the radio tuner without disturbing channel spacing or other chip peripheral timing.

• This API sets CTUNEXIANA and internally CTUNEXOANA = CTUNEXIANA + delta where delta is set or changed by sl_rail_set_tune_delta(). The default delta may not be 0 on some devices.

sl_rail_get_tune#

uint32_t sl_rail_get_tune (sl_rail_handle_t rail_handle)

Get the crystal tuning.

Returns

• A chip-dependent crystal capacitor bank tuning parameter.

Retrieves the current tuning value used by the crystal that the radio depends on. Note

• This is the CTUNEXIANA value.

sl_rail_set_tune_delta#

sl_rail_status_t sl_rail_set_tune_delta (sl_rail_handle_t rail_handle, int32_t delta)

Set the crystal tuning delta.

Returns

• Status code indicating success of the function call.

Set the CTUNEXOANA delta for sl_rail_set_tune() to use: CTUNEXOANA = CTUNEXIANA + delta (subject to field-size limitations). This function does not change CTUNE values; call sl_rail_set_tune() to put a new delta into effect.

sl_rail_get_tune_delta#

int32_t sl_rail_get_tune_delta (sl_rail_handle_t rail_handle)

Get the crystal tuning delta.

Returns

• A chip-dependent crystal capacitor bank tuning delta.

Retrieves the current tuning delta used by sl_rail_set_tune(). Note

• The default delta if sl_rail_set_tune_delta() has never been called is device-dependent and may not be 0.

sl_rail_get_rx_freq_offset#

sl_rail_frequency_offset_t sl_rail_get_rx_freq_offset (sl_rail_handle_t rail_handle)

Get the frequency offset.

Returns

• The measured frequency offset on a received packet. The units are described in the sl_rail_frequency_offset_t documentation. If this returns SL_RAIL_FREQUENCY_OFFSET_INVALID, it was called while the radio wasn't active and there is no way to get the frequency offset.

Retrieves the measured frequency offset used during the previous received packet, which includes the current radio frequency offset (see sl_rail_set_freq_offset()). If the chip has not been in RX, it returns the nominal radio frequency offset.

Note

• Changing to any non-idle radio state after reception can cause this value to be overwritten so it is safest to capture during packet reception.

sl_rail_set_freq_offset#

sl_rail_status_t sl_rail_set_freq_offset (sl_rail_handle_t rail_handle, sl_rail_frequency_offset_t freq_offset)

Set the nominal radio frequency offset.

Returns

• Status code indicating success of the function call.

This function is used to adjust the radio's tuning frequency slightly up or down. It might be used in conjunction with sl_rail_get_rx_freq_offset() after receiving a packet from a peer to adjust the tuner to better match the peer's tuned frequency.

Note

• Unlike sl_rail_set_tune(), which affects the entire chip's timing including radio tuning and channel spacing, this function only affects radio tuning without disturbing channel spacing or other chip peripheral timing.

sl_rail_start_tx_stream#

sl_rail_status_t sl_rail_start_tx_stream (sl_rail_handle_t rail_handle, uint16_t channel, sl_rail_stream_mode_t mode, sl_rail_tx_options_t tx_options)

Start transmitting a stream on a certain channel with the ability to select an antenna.

Returns

• Status code indicating success of the function call.

Begins streaming onto the given channel. The sources can either be an unmodulated carrier wave or an encoded stream of bits from a PN9 source. All ongoing radio operations will be stopped before transmission begins.

sl_rail_stop_tx_stream#

sl_rail_status_t sl_rail_stop_tx_stream (sl_rail_handle_t rail_handle)

Stop stream transmission and idle the radio.

Returns

• Status code indicating success of the function call.

Halts the transmission started by sl_rail_start_tx_stream().

sl_rail_stop_infinite_preamble_tx#

sl_rail_status_t sl_rail_stop_infinite_preamble_tx (sl_rail_handle_t rail_handle)

Stop infinite preamble transmission started and start transmitting the rest of the packet.

Returns

• Status code indicating success of the function call: SL_RAIL_STATUS_NO_ERROR if infinite preamble was stopped; SL_RAIL_STATUS_INVALID_CALL if the radio isn't configured for infinite preamble; SL_RAIL_STATUS_INVALID_STATE if the radio isn't transmitting.

This function is only useful for radio configurations that specify an infinite preamble. Call this API only after SL_RAIL_EVENT_TX_STARTED has occurred and the radio is transmitting.