APIs for configuring and controlling an attached Energy Friendly Front End Module (EFF).

Data Structures
struct	RAIL_FemProtectionConfig_t
	Temperature protection configuration for the attached FEM.

struct	RAIL_EffConfig_t
	Configuration data for the attached EFF device.

Macros
#define	RAIL_TEMP_MEASURE_COUNT (13U)
	Number of temperature values provided by RAIL_GetTemperature() .

#define	RAIL_EFF_CONTROL_SIZE (52U)
	Number of bytes provided by RAIL_GetSetEffControl() .

#define	RAIL_EFF_SUPPORTS_TRANSMIT (x)
	A macro that checks for EFFxx devices that support high power transmit.

#define	RAIL_EFF_SUPPORTS_RECEIVE (x)
	A macro that checks for EFFxx devices that support receive.

Enumerations
enum	RAIL_EffDevice_t { RAIL_EFF_DEVICE_NONE = 0, RAIL_EFF_DEVICE_EFF01Z11 , RAIL_EFF_DEVICE_EFF01A12 , RAIL_EFF_DEVICE_COUNT }
	EFF part numbers.

enum	RAIL_EffLnaMode_t { RAIL_EFF_LNA_MODE_RURAL = (0x01U << 0), RAIL_EFF_LNA_MODE_URBAN = (0x01U << 1), RAIL_EFF_LNA_MODE_BYPASS = (0x01U << 2), RAIL_EFF_LNA_MODE_COUNT = (0x01U << 3) }
	EFF LNA Modes.

enum	RAIL_ClpcEnable_t { RAIL_EFF_CLPC_DISABLED = 0, RAIL_EFF_CLPC_MODE_CHANGE = 1, RAIL_EFF_CLPC_POWER_SLOW = 2, RAIL_EFF_CLPC_POWER_FAST = 3, RAIL_EFF_CLPC_POWER_BOTH = 4, RAIL_EFF_CLPC_POWER_SLOW_BELOW_MAX = 5, RAIL_EFF_CLPC_POWER_FAST_BELOW_MAX = 6, RAIL_EFF_CLPC_POWER_BOTH_BELOW_MAX = 7, RAIL_EFF_CLPC_COUNT = 8 }
	EFF Closed Loop Power Control (CLPC) Enable states.

Functions
RAIL_Status_t	RAIL_ConfigEff ( RAIL_Handle_t railHandle, const RAIL_EffConfig_t *config)
	Configure the attached EFF device.

RAIL_Status_t	RAIL_GetTemperature ( RAIL_Handle_t railHandle, int16_t tempBuffer[(13U)], bool reset)
	Get the different temperature measurements in Kelvin done by sequencer or host.

RAIL_Status_t	RAIL_SetFemProtectionConfig ( RAIL_Handle_t railHandle, const RAIL_FemProtectionConfig_t *newFemConfig)
	Set the FEM maximum power for continuous TX and the duty cycle for TX operations from RAIL_FemProtectionConfig_t .

RAIL_Status_t	RAIL_GetFemProtectionConfig ( RAIL_Handle_t railHandle, RAIL_FemProtectionConfig_t *femConfig)
	Get the FEM protection configuration.

RAIL_Status_t	RAIL_GetSetEffControl ( RAIL_Handle_t railHandle, uint16_t tempBuffer[(52U)/sizeof(uint16_t)], bool reset)
	Get the different EFF Control measurements.

RAIL_Status_t	RAIL_GetSetEffMode ( RAIL_Handle_t railHandle, uint8_t *newMode, bool changeMode)
	Copy the current FEM_DATA pin values into newMode.

RAIL_Status_t	RAIL_GetSetEffRuralUrbanMv ( RAIL_Handle_t railHandle, uint16_t *newTrip, bool changeTrip)
	Copy the current Rural to Urban trip voltage into newTrip.

RAIL_Status_t	RAIL_GetSetEffUrbanBypassMv ( RAIL_Handle_t railHandle, uint16_t *newTrip, bool changeTrip)
	Copy the current Urban to Bypass trip voltage into newTrip.

RAIL_Status_t	RAIL_GetSetEffUrbanDwellTimeMs ( RAIL_Handle_t railHandle, uint32_t *newDwellTime, bool changeDwellTime)
	Copy the current Urban dwell time into newDwellTime.

RAIL_Status_t	RAIL_GetSetEffBypassDwellTimeMs ( RAIL_Handle_t railHandle, uint32_t *newDwellTime, bool changeDwellTime)
	Copy the current Bypass dwell time into newDwellTime.

RAIL_Status_t	RAIL_GetSetClpcSlowLoop ( RAIL_Handle_t railHandle, uint16_t newTarget, uint16_t newSlope, bool changeValues)
	Copy the current CLPC Slow Loop values into newTarget and newSlope.

RAIL_Status_t	RAIL_GetSetClpcFastLoop ( RAIL_Handle_t railHandle, uint16_t newTarget, uint16_t newSlope, bool changeValues)
	Copy the current CLPC Fast Loop values into newTarget and newSlope.

RAIL_Status_t	RAIL_GetSetClpcEnable ( RAIL_Handle_t railHandle, uint8_t *newClpcEnable, bool changeClpcEnable)
	Copy the current CLPC Enable in to newClpcEnable.

RAIL_Status_t	RAIL_GetSetEffTempThreshold ( RAIL_Handle_t railHandle, uint16_t *newThreshold, bool changeThreshold)
	Get and set the EFF temperature threshold.

RAIL_Status_t	RAIL_GetSetInternalTempThreshold ( RAIL_Handle_t railHandle, uint16_t *newThreshold, bool changeThreshold)
	Get and set the internal temperature threshold.

Detailed Description

APIs for configuring and controlling an attached Energy Friendly Front End Module (EFF).

The EFF is a high-performance, transmit/receive (T/R) front end module (FEM) for sub-GHz EFR32 devices. RAIL includes built-in functionality to transmit and receive via an attached EFF. This functionality optimizes RF performance while ensuring that the EFF stays within safe operating temperature limits.

Configuration and control of the EFF is performed by the Energy Friendly Front End Module (EFF) Utility .

Note: The EFF is only supported with EFR32XG25 devices.

Macro Definition Documentation

◆ RAIL_EFF_CONTROL_SIZE

#define RAIL_EFF_CONTROL_SIZE (52U)

Number of bytes provided by RAIL_GetSetEffControl() .

Definition at line 5664 of file rail.h .

◆ RAIL_EFF_SUPPORTS_RECEIVE

#define RAIL_EFF_SUPPORTS_RECEIVE ( x )

Value:

         ( ((x) ==
         
          RAIL_EFF_DEVICE_EFF01A12
         
         )    \
        
         || ((x) ==
         
          RAIL_EFF_DEVICE_EFF01Z11
         
         ) \
        
         )

A macro that checks for EFFxx devices that support receive.

Definition at line 4294 of file rail_types.h .

◆ RAIL_EFF_SUPPORTS_TRANSMIT

#define RAIL_EFF_SUPPORTS_TRANSMIT ( x )

Value:

( ((x) == RAIL_EFF_DEVICE_EFF01A12 ) \

)

RAIL_EFF_DEVICE_EFF01A12

EFF01A12.

Definition:


           rail_types.h:4281

A macro that checks for EFFxx devices that support high power transmit.

Definition at line 4288 of file rail_types.h .

◆ RAIL_TEMP_MEASURE_COUNT

#define RAIL_TEMP_MEASURE_COUNT (13U)

Number of temperature values provided by RAIL_GetTemperature() .

Definition at line 5620 of file rail.h .

Enumeration Type Documentation

◆ RAIL_ClpcEnable_t

enum RAIL_ClpcEnable_t

EFF Closed Loop Power Control (CLPC) Enable states.

The EFF CLPC Enable state is passed to RAIL_ConfigEff() as the RAIL_EffConfig_t::clpcEnable . The Energy Friendly Front End Module (EFF) Utility uses advanced power controls to tune EFF output to match Surface Acoustic Wave (SAW) filter losses and antenna performance.

Enumerator
RAIL_EFF_CLPC_DISABLED	CLPC actions are completely disabled. EFF will output but CLPC will not change modes, take power measurements or tune power output. Temperature measurements are taken.
RAIL_EFF_CLPC_MODE_CHANGE	CLPC actions are completely disabled. EFF will output, change modes, and take measurements, but not tune power output.
RAIL_EFF_CLPC_POWER_SLOW	CLPC actions allows Slow Loop. EFF will output, change modes, and take measurements, and tune power output based on slow loop.
RAIL_EFF_CLPC_POWER_FAST	CLPC actions allows Fast Loop. EFF will output, change modes, and take measurements, and tune power output based on fast loop.
RAIL_EFF_CLPC_POWER_BOTH	CLPC actions are completely enabled. EFF will output, change modes, take measurements, and tune power output based on slow and fast loops. Default state.
RAIL_EFF_CLPC_POWER_SLOW_BELOW_MAX	CLPC actions allows Slow Loop. EFF will output, change modes, and take measurements, but not tune power output because requested output power is less than max. Internal only state.
RAIL_EFF_CLPC_POWER_FAST_BELOW_MAX	CLPC actions allows Fast Loop. EFF will output, change modes, and take measurements, but not tune power output because requested output power is less than max. Internal only state.
RAIL_EFF_CLPC_POWER_BOTH_BELOW_MAX	CLPC actions are completely enabled. EFF will output, change modes, and take measurements, but not tune power output because requested output power is less than max. Internal only state.
RAIL_EFF_CLPC_COUNT	A count of the choices in this enumeration. Must be last

Definition at line 4323 of file rail_types.h .

◆ RAIL_EffDevice_t

enum RAIL_EffDevice_t

EFF part numbers.

The part number of the attached EFF device is passed to RAIL_ConfigEff() as RAIL_EffConfig_t::device . The Energy Friendly Front End Module (EFF) Utility configures and controls the EFF based on the capabilities of the attached EFF.

Enumerator
RAIL_EFF_DEVICE_NONE	No EFF device attached.
RAIL_EFF_DEVICE_EFF01Z11	EFF01Z11. LNA only, TX is bypass mode.
RAIL_EFF_DEVICE_EFF01A12	EFF01A12.
RAIL_EFF_DEVICE_COUNT	A count of the choices in this enumeration.

Definition at line 4278 of file rail_types.h .

◆ RAIL_EffLnaMode_t

enum RAIL_EffLnaMode_t

EFF LNA Modes.

The enabled EFF LNA modes are passed to RAIL_ConfigEff() as the RAIL_EffConfig_t::enabledLnaModes . The Energy Friendly Front End Module (EFF) Utility dynamically transitions between enabled LNA modes to maximize receive performance.

Enumerator
RAIL_EFF_LNA_MODE_RURAL	Rural LNA Mode.
RAIL_EFF_LNA_MODE_URBAN	Urban LNA Mode.
RAIL_EFF_LNA_MODE_BYPASS	Bypass LNA Mode.
RAIL_EFF_LNA_MODE_COUNT	A count of the choices in this enumeration.

Definition at line 4307 of file rail_types.h .

Function Documentation

◆ RAIL_ConfigEff()

RAIL_Status_t RAIL_ConfigEff	(	RAIL_Handle_t	`railHandle,`
		const RAIL_EffConfig_t *	`config`
	)

Configure the attached EFF device.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`config`	A pointer to a RAIL_EffConfig_t struct that contains configuration data for the EFF.

Returns: Status code indicating success of the function call.

◆ RAIL_GetFemProtectionConfig()

RAIL_Status_t RAIL_GetFemProtectionConfig	(	RAIL_Handle_t	`railHandle,`
		RAIL_FemProtectionConfig_t *	`femConfig`
	)

Get the FEM protection configuration.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[out]	`femConfig`	Current FEM protection configuration written to this pointer.

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetClpcEnable()

RAIL_Status_t RAIL_GetSetClpcEnable	(	RAIL_Handle_t	`railHandle,`
		uint8_t *	`newClpcEnable,`
		bool	`changeClpcEnable`
	)

Copy the current CLPC Enable in to newClpcEnable.

If changeClpcEnable is true, update current CLPC Enable with newClpcEnable first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newClpcEnable`	A pointer to a uint8_t that will contain the CLPC Enable
[in]	`changeClpcEnable`	If true, use newClpcEnable to update the current CLPC Enable

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetClpcFastLoop()

RAIL_Status_t RAIL_GetSetClpcFastLoop	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newTarget,`
		uint16_t *	`newSlope,`
		bool	`changeValues`
	)

Copy the current CLPC Fast Loop values into newTarget and newSlope.

If changeTarget is true, update current CLPC Fast Loop Target and Slope first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newTarget`	A pointer to a uint16_t that will contain the CLPC Fast Loop Target
[in,out]	`newSlope`	A pointer to a uint16_t that will contain the CLPC Fast Loop Slope
[in]	`changeValues`	If true, use newTarget and newGain to update the CLPC Fast Loop values

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetClpcSlowLoop()

RAIL_Status_t RAIL_GetSetClpcSlowLoop	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newTarget,`
		uint16_t *	`newSlope,`
		bool	`changeValues`
	)

Copy the current CLPC Slow Loop values into newTarget and newSlope.

If changeTarget is true, update current CLPC Slow Loop Target and Slope first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newTarget`	A pointer to a uint16_t that will contain the CLPC Slow Loop Target
[in,out]	`newSlope`	A pointer to a uint16_t that will contain the CLPC Slow Loop Slope
[in]	`changeValues`	If true, use newTarget and newGain to update the CLPC SLow Loop values

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffBypassDwellTimeMs()

RAIL_Status_t RAIL_GetSetEffBypassDwellTimeMs	(	RAIL_Handle_t	`railHandle,`
		uint32_t *	`newDwellTime,`
		bool	`changeDwellTime`
	)

Copy the current Bypass dwell time into newDwellTime.

If changeDwellTime is true, update current Bypass dwell time with newDwellTime first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newDwellTime`	A pointer to a uint16_t that will contain the Bypass dwell dwell time, in milliseconds
[in]	`changeDwellTime`	If true, use newDwellTime to update current Bypass dwell time

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffControl()

RAIL_Status_t RAIL_GetSetEffControl	(	RAIL_Handle_t	`railHandle,`
		uint16_t	`tempBuffer[(52U)/sizeof(uint16_t)],`
		bool	`reset`
	)

Get the different EFF Control measurements.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[out]	`tempBuffer`	The address of the target array. tempBuffer array must be at least RAIL_EFF_CONTROL_SIZE bytes.
[in]	`reset`	Reset the EFF Control measurements.

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffMode()

RAIL_Status_t RAIL_GetSetEffMode	(	RAIL_Handle_t	`railHandle,`
		uint8_t *	`newMode,`
		bool	`changeMode`
	)

Copy the current FEM_DATA pin values into newMode.

If changeMode is true, update FEM_DATA pin values with newMode first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newMode`	A pointer to a uint8_t that will contain the FEM_DATA pin values
[in]	`changeMode`	If true, use newMode to update FEM_DATA pin values

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffRuralUrbanMv()

RAIL_Status_t RAIL_GetSetEffRuralUrbanMv	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newTrip,`
		bool	`changeTrip`
	)

Copy the current Rural to Urban trip voltage into newTrip.

If changeTrip is true, update current Rural to Urban trip voltage with newTrip first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newTrip`	A pointer to a uint16_t that will contain the Rural to Urban trip voltage, in millivolts
[in]	`changeTrip`	If true, use newTrip to update current Rural to Urban trip voltage

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffTempThreshold()

RAIL_Status_t RAIL_GetSetEffTempThreshold	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newThreshold,`
		bool	`changeThreshold`
	)

Get and set the EFF temperature threshold.

The EFR32 device periodically takes temperature measurements of the attached EFF device. If the EFF temperature ever exceeds the EFF temperature threshold, any active transmit operation is aborted and future transmit operations are blocked until the EFF temperature falls below the threshold.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newThreshold`	A pointer to a uint16_t that will contain the EFF temperature threshold, in Kelvin
[in]	`changeThreshold`	If true, use changeThreshold to update current EFF temperature threshold

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffUrbanBypassMv()

RAIL_Status_t RAIL_GetSetEffUrbanBypassMv	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newTrip,`
		bool	`changeTrip`
	)

Copy the current Urban to Bypass trip voltage into newTrip.

If changeTrip is true, update current Urban to Bypass trip voltage with newTrip first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newTrip`	A pointer to a uint16_t that will contain the Urban to Bypass trip voltage, in millivolts
[in]	`changeTrip`	If true, use newTrip to update current Urban to Bypass trip voltage

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetEffUrbanDwellTimeMs()

RAIL_Status_t RAIL_GetSetEffUrbanDwellTimeMs	(	RAIL_Handle_t	`railHandle,`
		uint32_t *	`newDwellTime,`
		bool	`changeDwellTime`
	)

Copy the current Urban dwell time into newDwellTime.

If changeDwellTime is true, update current Urban dwell time with newDwellTime first.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newDwellTime`	A pointer to a uint16_t that will contain the Urban dwell dwell time, in milliseconds
[in]	`changeDwellTime`	If true, use newDwellTime to update current Urban dwell time

Returns: Status code indicating success of the function call.

◆ RAIL_GetSetInternalTempThreshold()

RAIL_Status_t RAIL_GetSetInternalTempThreshold	(	RAIL_Handle_t	`railHandle,`
		uint16_t *	`newThreshold,`
		bool	`changeThreshold`
	)

Get and set the internal temperature threshold.

The EFR32 device periodically takes measurements of its internal temperature when attached to an EFF device. If the internal temperature ever exceeds the internal temperature threshold, any active transmit operation is aborted and future transmit operations are blocked until the internal temperature falls below the threshold.

Parameters

[in]	`railHandle`	A RAIL instance handle
[in,out]	`newThreshold`	A pointer to a uint16_t that will contain the internal temperature threshold, in Kelvin
[in]	`changeThreshold`	If true, use changeThreshold to update current internal temperature threshold

Returns: Status code indicating success of the function call.

◆ RAIL_GetTemperature()

RAIL_Status_t RAIL_GetTemperature	(	RAIL_Handle_t	`railHandle,`
		int16_t	`tempBuffer[(13U)],`
		bool	`reset`
	)

Get the different temperature measurements in Kelvin done by sequencer or host.

Values that are not populated yet or incorrect are set to 0.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[out]	`tempBuffer`	The address of the array that will contain temperatures. tempBuffer array must be at least RAIL_TEMP_MEASURE_COUNT int16_t.
[in]	`reset`	Reset the EFF temperature values.

Returns: Status code indicating success of the function call.

◆ RAIL_SetFemProtectionConfig()

RAIL_Status_t RAIL_SetFemProtectionConfig	(	RAIL_Handle_t	`railHandle,`
		const RAIL_FemProtectionConfig_t *	`newFemConfig`
	)

Set the FEM maximum power for continuous TX and the duty cycle for TX operations from RAIL_FemProtectionConfig_t .

Default continuous TX power is defined at 200 deci-dBm and can be set to a maximum of 300 deci-dBm. Default duty cycle is defined at 50 percent and can be set to a maximum of 100 percent.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`newFemConfig`	Pointer to the new limits to use for the FEM protection configuration

Returns: Status code indicating success of the function call.

Note: Setting the power for continuous TX and the duty cycle from RAIL_FemProtectionConfig_t to 0 will apply their default value. For an ambient temperature above 70 degrees Celsius, it is recommended to use the default configuration.

Energy Friendly Front End Module (EFF) RAIL API

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RAIL_EFF_CONTROL_SIZE

◆ RAIL_EFF_SUPPORTS_RECEIVE

◆ RAIL_EFF_SUPPORTS_TRANSMIT

◆ RAIL_TEMP_MEASURE_COUNT

Enumeration Type Documentation

◆ RAIL_ClpcEnable_t

◆ RAIL_EffDevice_t

◆ RAIL_EffLnaMode_t

Function Documentation

◆ RAIL_ConfigEff()

◆ RAIL_GetFemProtectionConfig()

◆ RAIL_GetSetClpcEnable()

◆ RAIL_GetSetClpcFastLoop()

◆ RAIL_GetSetClpcSlowLoop()

◆ RAIL_GetSetEffBypassDwellTimeMs()

◆ RAIL_GetSetEffControl()

◆ RAIL_GetSetEffMode()

◆ RAIL_GetSetEffRuralUrbanMv()

◆ RAIL_GetSetEffTempThreshold()

◆ RAIL_GetSetEffUrbanBypassMv()

◆ RAIL_GetSetEffUrbanDwellTimeMs()

◆ RAIL_GetSetInternalTempThreshold()

◆ RAIL_GetTemperature()

◆ RAIL_SetFemProtectionConfig()

Energy Friendly Front End Module (EFF)
RAIL API