External Thermistor#

APIs to measure temperature using an external thermistor.

This feature allows reading the temperature via an external thermistor on chips that support it. This will require connecting the necessary components and configuring the pins as required.

Modules#

RAIL_HFXOThermistorConfig_t

RAIL_HFXOCompensationConfig_t

Functions#

RAIL_Status_t

RAIL_StartThermistorMeasurement(RAIL_Handle_t railHandle)

Start a thermistor measurement.

RAIL_Status_t

RAIL_GetThermistorImpedance(RAIL_Handle_t railHandle, uint32_t *thermistorImpedance)

Get the thermistor impedance measurement and return RAIL_INVALID_THERMISTOR_VALUE if the thermistor is not properly configured or the thermistor measurement is not ready.

RAIL_Status_t

RAIL_ConvertThermistorImpedance(RAIL_Handle_t railHandle, uint32_t thermistorImpedance, int16_t *thermistorTemperatureC)

Convert the thermistor impedance into temperature, in Celsius.

RAIL_Status_t

RAIL_ComputeHFXOPPMError(RAIL_Handle_t railHandle, int16_t crystalTemperatureC, int8_t *crystalPPMError)

Compute the crystal PPM deviation from the thermistor temperature.

RAIL_Status_t

RAIL_ConfigHFXOThermistor(RAIL_Handle_t railHandle, const RAIL_HFXOThermistorConfig_t *pHfxoThermistorConfig)

Configure the GPIO for thermistor usage.

RAIL_Status_t

RAIL_ConfigHFXOCompensation(RAIL_Handle_t railHandle, const RAIL_HFXOCompensationConfig_t *pHfxoCompensationConfig)

Configure the temperature parameters for HFXO compensation.

RAIL_Status_t

RAIL_GetHFXOCompensationConfig(RAIL_Handle_t railHandle, RAIL_HFXOCompensationConfig_t *pHfxoCompensationConfig)

Get the temperature parameters for HFXO compensation.

RAIL_Status_t

RAIL_CompensateHFXO(RAIL_Handle_t railHandle, int8_t crystalPPMError)

Compute a frequency offset and compensate HFXO accordingly.

Macros#

#define

RAIL_INVALID_THERMISTOR_VALUE (0xFFFFFFFFU)

A sentinel value to indicate an invalid thermistor measurement value.

#define

RAIL_INVALID_PPM_VALUE (-128)

A sentinel value to indicate an invalid PPM calculation value.

Function Documentation#

RAIL_StartThermistorMeasurement#

RAIL_Status_t RAIL_StartThermistorMeasurement (RAIL_Handle_t railHandle)

Start a thermistor measurement.

Parameters

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

To get the thermistor impedance, call the function RAIL_GetThermistorImpedance. On platforms having RAIL_SUPPORTS_EXTERNAL_THERMISTOR, this function reconfigures GPIO_THMSW_EN_PIN located in GPIO_THMSW_EN_PORT. To locate this pin, refer to the data sheet or appropriate header files of the device. For proper operation, RAIL_Init must be called before using this function.

Note

This function is not designed for safe usage in multiprotocol applications.
When an EFF is attached, this function must not be called during transmit.

Returns

Status code indicating success of the function call. Returns RAIL_STATUS_INVALID_STATE if the thermistor is started while the radio is transmitting.

RAIL_GetThermistorImpedance#

RAIL_Status_t RAIL_GetThermistorImpedance (RAIL_Handle_t railHandle, uint32_t * thermistorImpedance)

Get the thermistor impedance measurement and return RAIL_INVALID_THERMISTOR_VALUE if the thermistor is not properly configured or the thermistor measurement is not ready.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint32_t *	[out]	thermistorImpedance	Current thermistor impedance measurement in Ohms.

Returns

Status code indicating success of the function call.

Note

This function is already called in RAIL_CalibrateHFXO(). It does not need to be manually called during the compensation sequence.

RAIL_ConvertThermistorImpedance#

RAIL_Status_t RAIL_ConvertThermistorImpedance (RAIL_Handle_t railHandle, uint32_t thermistorImpedance, int16_t * thermistorTemperatureC)

Convert the thermistor impedance into temperature, in Celsius.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
uint32_t	[in]	thermistorImpedance	Current thermistor impedance measurement in Ohms.
int16_t *	[out]	thermistorTemperatureC	Pointer to current thermistor temperature in eighth of Celsius degree

Returns

Status code indicating success of the function call.

A version of this function is provided in the Thermistor Utility plugin for Silicon Labs radio boards. For custom boards this function can be modified and re-implemented as needed.

The variable railHandle is only used to indicate to the user from where the function was called, so it is okay to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Note

This plugin is mandatory on EFR32xG25 platform.

RAIL_ComputeHFXOPPMError#

RAIL_Status_t RAIL_ComputeHFXOPPMError (RAIL_Handle_t railHandle, int16_t crystalTemperatureC, int8_t * crystalPPMError)

Compute the crystal PPM deviation from the thermistor temperature.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
int16_t	[in]	crystalTemperatureC	Current crystal temperature.
int8_t *	[out]	crystalPPMError	Pointer to current ppm error.

Returns

Status code indicating success of the function call.

This function is provided in the rail_util_thermistor plugin to get accurate values from our boards thermistor. For a custom board, this function could be modified and re-implemented for other needs. The variable railHandle is only used to indicate to the user from where the function was called, so it is okay to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Note

This plugin is mandatory on EFR32xG25 platform.

RAIL_ConfigHFXOThermistor#

RAIL_Status_t RAIL_ConfigHFXOThermistor (RAIL_Handle_t railHandle, const RAIL_HFXOThermistorConfig_t * pHfxoThermistorConfig)

Configure the GPIO for thermistor usage.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	N/A	railHandle	A RAIL instance handle.
const RAIL_HFXOThermistorConfig_t *	[in]	pHfxoThermistorConfig	The thermistor configuration pointing to the GPIO port and pin to access.

Returns

Status code indicating the result of the function call.

Note

The port and pin that must be passed in RAIL_HFXOThermistorConfig_t are GPIO_THMSW_EN_PORT and GPIO_THMSW_EN_PIN respectively.

RAIL_ConfigHFXOCompensation#

RAIL_Status_t RAIL_ConfigHFXOCompensation (RAIL_Handle_t railHandle, const RAIL_HFXOCompensationConfig_t * pHfxoCompensationConfig)

Configure the temperature parameters for HFXO compensation.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	N/A	railHandle	A RAIL instance handle.
const RAIL_HFXOCompensationConfig_t *	[in]	pHfxoCompensationConfig	HFXO compensation parameters pointing to the temperature variations used to trigger a compensation.

Returns

Status code indicating the result of the function call.

Note

This function must be called after RAIL_ConfigHFXOThermistor to succeed.

In RAIL_HFXOCompensationConfig_t, deltaNominal and deltaCritical define the temperature variation triggering a new compensation. The field zoneTemperatureC defines the temperature separating the nominal case (below) from the critical one (above).

When enabled and either deltaNominal or deltaCritical are exceeded, RAIL raises event RAIL_EVENT_CAL_NEEDED with RAIL_CAL_TEMP_HFXO bit set. The API RAIL_StartThermistorMeasurement() must be called afterwards. The latter will raise RAIL_EVENT_THERMISTOR_DONE with calibration bit RAIL_CAL_COMPENSATE_HFXO set and RAIL_CalibrateHFXO() must follow.

Note

Set deltaNominal and deltaCritical to 0 to perform compensation after each transmit.

RAIL_GetHFXOCompensationConfig#

RAIL_Status_t RAIL_GetHFXOCompensationConfig (RAIL_Handle_t railHandle, RAIL_HFXOCompensationConfig_t * pHfxoCompensationConfig)

Get the temperature parameters for HFXO compensation.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	N/A	railHandle	A RAIL instance handle.
RAIL_HFXOCompensationConfig_t *	N/A	pHfxoCompensationConfig	HFXO compensation parameters pointing to the temperature variations used to trigger a compensation.

Returns

Status code indicating the result of the function call.

RAIL_CompensateHFXO#

RAIL_Status_t RAIL_CompensateHFXO (RAIL_Handle_t railHandle, int8_t crystalPPMError)

Compute a frequency offset and compensate HFXO accordingly.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	N/A	railHandle	A RAIL instance handle.
int8_t	N/A	crystalPPMError	The current ppm error. Positive values indicate the HFXO frequency is too high; negative values indicate it's too low.

Returns

Status code indicating success of the function call.

Note

This function only works for platforms having RAIL_SUPPORTS_EXTERNAL_THERMISTOR alongside RAIL_SUPPORTS_HFXO_COMPENSATION.