Diagnostic#

APIs for diagnostic and test chip modes.

Modules#

RAIL_DirectModeConfig_t

RAIL_VerifyConfig_t

Enumerations#

enum
RAIL_STREAM_CARRIER_WAVE = 0
RAIL_STREAM_PN9_STREAM = 1
RAIL_STREAM_10_STREAM = 2
RAIL_STREAM_CARRIER_WAVE_PHASENOISE = 3
RAIL_STREAM_RAMP_STREAM = 4
RAIL_STREAM_CARRIER_WAVE_SHIFTED = 5
RAIL_STREAM_MODES_COUNT
}

Possible stream output modes.

Typedefs#

typedef int16_t

Type that represents the number of Frequency Offset units.

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

A pointer to a verification callback function.

Functions#

RAIL_ConfigDirectMode(RAIL_Handle_t railHandle, const RAIL_DirectModeConfig_t *directModeConfig)

Configure direct mode for RAIL.

RAIL_EnableDirectMode(RAIL_Handle_t railHandle, bool enable)

Enable or disable direct mode for RAIL.

RAIL_EnableDirectModeAlt(RAIL_Handle_t railHandle, bool enableDirectTx, bool enableDirectRx)

Enable or disable direct mode for RAIL.

uint32_t
RAIL_GetRadioClockFreqHz(RAIL_Handle_t railHandle)

Get the radio subsystem clock frequency in Hz.

RAIL_SetTune(RAIL_Handle_t railHandle, uint32_t tune)

Set the crystal tuning.

uint32_t
RAIL_GetTune(RAIL_Handle_t railHandle)

Get the crystal tuning.

RAIL_SetTuneDelta(RAIL_Handle_t railHandle, int32_t delta)

Set the crystal tuning delta.

int32_t
RAIL_GetTuneDelta(RAIL_Handle_t railHandle)

Get the crystal tuning delta.

RAIL_GetRxFreqOffset(RAIL_Handle_t railHandle)

Get the frequency offset.

RAIL_SetFreqOffset(RAIL_Handle_t railHandle, RAIL_FrequencyOffset_t freqOffset)

Set the nominal radio frequency offset.

RAIL_StartTxStream(RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode)

Start transmitting a stream on a certain channel.

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.

RAIL_StopTxStream(RAIL_Handle_t railHandle)

Stop stream transmission and idle the radio.

RAIL_StopInfinitePreambleTx(RAIL_Handle_t railHandle)

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

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.

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

Verify radio memory contents.

Macros#

#define
RAIL_FREQUENCY_OFFSET_MAX ((RAIL_FrequencyOffset_t) 0x3FFF)

The maximum frequency offset value supported.

#define
RAIL_FREQUENCY_OFFSET_MIN ((RAIL_FrequencyOffset_t) -RAIL_FREQUENCY_OFFSET_MAX)

The minimum frequency offset value supported.

#define
RAIL_FREQUENCY_OFFSET_INVALID ((RAIL_FrequencyOffset_t) 0x8000)

Specify an invalid frequency offset value.

#define

This radio state verification duration indicates to RAIL that all memory contents should be verified by RAIL before returning to the application.

Enumeration Documentation#

RAIL_StreamMode_t#

RAIL_StreamMode_t

Possible stream output modes.

Enumerator
RAIL_STREAM_CARRIER_WAVE

An unmodulated carrier wave.

RAIL_STREAM_PN9_STREAM

PN9 byte sequence.

RAIL_STREAM_10_STREAM

101010 sequence.

RAIL_STREAM_CARRIER_WAVE_PHASENOISE

An unmodulated carrier wave with no change to PLL BW.

RAIL_STREAM_RAMP_STREAM

ramp sequence starting at a different offset for consecutive packets.

RAIL_STREAM_CARRIER_WAVE_SHIFTED

An unmodulated carrier wave not centered on DC but shifted roughly by channel_bandwidth/6 allowing an easy check of the residual DC.

RAIL_STREAM_MODES_COUNT

A count of the choices in this enumeration.


Definition at line 5515 of file common/rail_types.h

Typedef Documentation#

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 (synthTicks) and is limited to 15 bits. A value of RAIL_FREQUENCY_OFFSET_INVALID means that this value is invalid.


Definition at line 5459 of file common/rail_types.h

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.

Parameters
[in]address

The address of the data in question.

[in]expectedValue

The expected value of the data in question.

[in]actualValue

The actual value of the data in question.

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.


Definition at line 5574 of file common/rail_types.h

Function Documentation#

RAIL_ConfigDirectMode#

RAIL_Status_t RAIL_ConfigDirectMode (RAIL_Handle_t railHandle, const RAIL_DirectModeConfig_t * directModeConfig)

Configure direct mode for RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

[in]directModeConfig

A pointer to a configuration structure to specify direct mode parameters. Default configuration will be used if NULL is passed.

Returns

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 = gpioPortA,
  .doutPin  = 5,
  .dinPort  = gpioPortA,
  .dinPin   = 7,
  .dclkPort = gpioPortA,
  .dclkPin  = 6,
};

Warnings

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


Definition at line 5819 of file common/rail.h

RAIL_EnableDirectMode#

RAIL_Status_t RAIL_EnableDirectMode (RAIL_Handle_t railHandle, bool enable)

Enable or disable direct mode for RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

Whether or not to enable direct mode for TX and RX.

Returns

See RAIL_EnableDirectModeAlt() for more detailed function description.

Warnings

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

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


Definition at line 5841 of file common/rail.h

RAIL_EnableDirectModeAlt#

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

Enable or disable direct mode for RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enableDirectTx

Enable direct mode for data being transmitted out of the radio.

[in]enableDirectRx

Enable direct mode for data being received from the radio.

Returns

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.


Definition at line 5866 of file common/rail.h

RAIL_GetRadioClockFreqHz#

uint32_t RAIL_GetRadioClockFreqHz (RAIL_Handle_t railHandle)

Get the radio subsystem clock frequency in Hz.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Radio subsystem clock frequency in Hz.


Definition at line 5876 of file common/rail.h

RAIL_SetTune#

RAIL_Status_t RAIL_SetTune (RAIL_Handle_t railHandle, uint32_t tune)

Set the crystal tuning.

Parameters
[in]railHandle

A RAIL instance handle.

[in]tune

A chip-dependent crystal capacitor bank tuning parameter.

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.


Definition at line 5900 of file common/rail.h

RAIL_GetTune#

uint32_t RAIL_GetTune (RAIL_Handle_t railHandle)

Get the crystal tuning.

Parameters
[in]railHandle

A RAIL instance handle.

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.


Definition at line 5912 of file common/rail.h

RAIL_SetTuneDelta#

RAIL_Status_t RAIL_SetTuneDelta (RAIL_Handle_t railHandle, int32_t delta)

Set the crystal tuning delta.

Parameters
[in]railHandle

A RAIL instance handle.

[in]delta

A chip-dependent crystal capacitor bank tuning delta.

Returns

  • Status code indicating success of the function call.

Set the CTUNEXOANA delta for RAIL_SetTune to use: CTUNEXOANA = CTUNEXIANA + delta. This function does not change CTUNE values; call RAIL_SetTune to put a new delta into effect.


Definition at line 5926 of file common/rail.h

RAIL_GetTuneDelta#

int32_t RAIL_GetTuneDelta (RAIL_Handle_t railHandle)

Get the crystal tuning delta.

Parameters
[in]railHandle

A RAIL instance handle.

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.


Definition at line 5938 of file common/rail.h

RAIL_GetRxFreqOffset#

RAIL_FrequencyOffset_t RAIL_GetRxFreqOffset (RAIL_Handle_t railHandle)

Get the frequency offset.

Parameters
[in]railHandle

A RAIL instance handle.

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.


Definition at line 5958 of file common/rail.h

RAIL_SetFreqOffset#

RAIL_Status_t RAIL_SetFreqOffset (RAIL_Handle_t railHandle, RAIL_FrequencyOffset_t freqOffset)

Set the nominal radio frequency offset.

Parameters
[in]railHandle

A RAIL instance handle.

[in]freqOffset

RAIL_FrequencyOffset_t parameter (signed, 2's complement).

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.


Definition at line 5978 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel on which to emit a stream.

[in]mode

Choose the stream mode (PN9, and so on).

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.


Definition at line 5993 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel on which to emit a stream.

[in]mode

Choose the stream mode (PN9, and so on).

[in]options

Choose the TX Antenna option. Takes only RAIL_TX_OPTION_ANTENNA0, RAIL_TX_OPTION_ANTENNA1, RAIL_TX_OPTIONS_DEFAULT or RAIL_TX_OPTIONS_NONE from the RAIL_TxOptions_t. If some other value is used then, transmission is possible on any 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.


Definition at line 6015 of file common/rail.h

RAIL_StopTxStream#

RAIL_Status_t RAIL_StopTxStream (RAIL_Handle_t railHandle)

Stop stream transmission and idle the radio.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Halts the transmission started by RAIL_StartTxStream().


Definition at line 6028 of file common/rail.h

RAIL_StopInfinitePreambleTx#

RAIL_Status_t RAIL_StopInfinitePreambleTx (RAIL_Handle_t railHandle)

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

Parameters
[in]railHandle

A RAIL instance handle.

Returns

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.


Definition at line 6045 of file common/rail.h

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.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]configVerify

A pointer to a configuration structure made available to RAIL to perform radio state verification. This structure must be allocated in application global read-write memory. RAIL may modify fields within or referenced by this structure during its operation.

[in]radioConfig

A radioConfig (pointer) that is to be used as a white list for verifying memory contents.

[in]cb

A callback that notifies the application of a mismatch in expected vs actual memory contents. A NULL parameter may be passed in if a callback is not needed by the application.

Returns


Definition at line 6065 of file common/rail.h

RAIL_Verify#

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

Verify radio memory contents.

Parameters
[inout]configVerify

A pointer to the configuration structure previously established by RAIL_ConfigVerification().

[in]durationUs

The duration (in microseconds) for how long memory verification should occur before returning to the application. A value of RAIL_VERIFY_DURATION_MAX indicates that all memory contents should be verified before returning to the application.

[in]restart

This flag only has meaning if a previous call of this function returned RAIL_STATUS_SUSPENDED. By restarting (true), the verification process starts over from the beginning, or by resuming where verification left off after being suspended (false), verification can proceed towards completion.

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.


Definition at line 6095 of file common/rail.h

Macro Definition Documentation#

RAIL_FREQUENCY_OFFSET_MAX#

#define RAIL_FREQUENCY_OFFSET_MAX
Value:
((RAIL_FrequencyOffset_t) 0x3FFF)

The maximum frequency offset value supported.


Definition at line 5464 of file common/rail_types.h

RAIL_FREQUENCY_OFFSET_MIN#

#define RAIL_FREQUENCY_OFFSET_MIN
Value:
((RAIL_FrequencyOffset_t) -RAIL_FREQUENCY_OFFSET_MAX)

The minimum frequency offset value supported.


Definition at line 5469 of file common/rail_types.h

RAIL_FREQUENCY_OFFSET_INVALID#

#define RAIL_FREQUENCY_OFFSET_INVALID
Value:
((RAIL_FrequencyOffset_t) 0x8000)

Specify an invalid frequency offset value.

This will be returned if you call RAIL_GetRxFreqOffset() at an invalid time.


Definition at line 5475 of file common/rail_types.h

RAIL_VERIFY_DURATION_MAX#

#define RAIL_VERIFY_DURATION_MAX
Value:
0xFFFFFFFFUL

This radio state verification duration indicates to RAIL that all memory contents should be verified by RAIL before returning to the application.


Definition at line 5549 of file common/rail_types.h