Calibration#
APIs for calibrating the radio.
IEEE802154 protocol-specific APIs for calibrating the radio.
Bluetooth protocol-specific APIs for calibrating the radio.
The EFR32 supports the Image Rejection (IR) calibration and a temperature-dependent calibration.
These APIs calibrate the radio. The RAIL library determines which calibrations are necessary. Calibrations can be enabled/disabled with the RAIL_CalMask_t parameter.
Some calibrations produce values that can be saved and reapplied to avoid repeating the calibration process.
Calibrations can either be run with RAIL_Calibrate, or with the individual chip-specific calibration routines. An example for running code with RAIL_Calibrate looks like the following:
static RAIL_CalValues_t calValues = RAIL_CALVALUES_UNINIT;
void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
// Omitting other event handlers
if (events & RAIL_EVENT_CAL_NEEDED) {
// Run all pending calibrations, and save the results
RAIL_Calibrate(railHandle, &calValues, RAIL_CAL_ALL_PENDING);
}
}
Alternatively, if the image rejection calibration for your radio can be determined ahead of time, such as by running the calibration on a separate firmware image on each chip, the following calibration process will result in smaller code.
static RAIL_IrCalValues_t irCalValues = {
.rxIrCalValues = {
RX_IRCAL_VALUE_RF_PATH0,
RX_IRCAL_VALUE_RF_PATH1,
},
.txIrCalValues = {
.dcOffsetIQ = TX_IRCAL_DC_OFFSET_IQ,
.phiEpsilon = TX_IRCAL_PHI_EPSILON,
},
};
void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events) {
// Omitting other event handlers
if (events & RAIL_EVENT_CAL_NEEDED) {
RAIL_CalMask_t pendingCals = RAIL_GetPendingCal(railHandle);
// Disable the radio if we have to do an offline calibration
if (pendingCals & RAIL_CAL_TEMP_VC0) {
(void) RAIL_CalibrateTemp(railHandle);
}
if (pendingCals & RAIL_CAL_ONETIME_IRCAL) {
(void) RAIL_ApplyIrCalibrationAlt(rail_handle, &ir_cal_values, RAIL_ANTENNA_AUTO);
}
}
}
The IR calibration can be computed once and stored off or computed each time at startup. Because it is PHY-specific and provides sensitivity improvements, it is highly recommended. The IR calibration should only be run when the radio is IDLE.
The temperature-dependent calibrations are used to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.
Modules#
Typedefs#
A calibration mask type.
RAIL_RxIrCalValues_t.
A calibration value structure.
Functions#
Initialize RAIL calibration.
Start the calibration process.
Return the current set of pending calibrations.
Apply a given image rejection calibration value.
Apply a given image rejection calibration value.
Run the image rejection calibration.
Run the image rejection calibration.
Run the temperature calibration.
Performs HFXO compensation.
Enable/disable the PA calibration.
Calibrate image rejection for Bluetooth Low Energy.
Calibrate image rejection for IEEE 802.15.4 2.4 GHz.
Calibrate image rejection for IEEE 802.15.4 915 MHz and 868 MHz.
Macros#
EFR32-specific temperature calibration bit.
EFR32-specific HFXO temperature check bit.
EFR32-specific HFXO compensation bit.
EFR32-specific IR calibration bit.
EFR32-specific Tx IR calibration bit.
A mask to run EFR32-specific IR calibrations.
A mask to run temperature-dependent calibrations.
A mask to run one-time calibrations.
A mask to run optional performance calibrations.
A mask for calibrations that require the radio to be off.
A mask to run all possible calibrations for this chip.
A mask to run all pending calibrations.
An invalid calibration value.
Indicates the maximum number of RF Paths supported across all platforms.
A define to set all RAIL_RxIrCalValues_t values to uninitialized.
A define to set all RAIL_TxIrCalValues_t values to uninitialized.
A define to set all RAIL_IrCalValues_t values to uninitialized.
A define allowing Rx calibration value access compatibility between non-OFDM and OFDM platforms.
A define to set all RAIL_CalValues_t values to uninitialized.
Use this value with either TX or RX values in RAIL_SetPaCTune to use whatever value is already set and do no update.
Typedef Documentation#
RAIL_CalMask_t#
RAIL_CalMask_t
A calibration mask type.
This type is a bitmask of different RAIL calibration values. The exact meaning of these bits depends on what a particular chip supports.
4599 of file common/rail_types.hRAIL_RxIrCalValues_t#
typedef uint32_t RAIL_RxIrCalValues_t[2] [2]
RAIL_RxIrCalValues_t.
RX IR calibration values.
Platforms with fewer RAIL_RF_PATHS than RAIL_MAX_RF_PATHS will only respect and update RAIL_RF_PATHS indices and ignore the rest.
4647 of file common/rail_types.hRAIL_CalValues_t#
RAIL_CalValues_t
A calibration value structure.
This structure contains the set of persistent calibration values for EFR32. You can set these beforehand and apply them at startup to save the time required to compute them. Any of these values may be set to RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.
4732 of file common/rail_types.hFunction Documentation#
RAIL_ConfigCal#
RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)
Initialize RAIL calibration.
| [in] | railHandle | A RAIL instance handle. |
| [in] | calEnable | A bitmask that indicates which calibrations to enable for a callback notification. The exact meaning of these bits is radio-specific. |
Returns
Status code indicating success of the function call.
Calibration initialization provides the calibration settings that correspond to the current radio configuration.
4978 of file common/rail.hRAIL_Calibrate#
RAIL_Status_t RAIL_Calibrate (RAIL_Handle_t railHandle, RAIL_CalValues_t * calValues, RAIL_CalMask_t calForce)
Start the calibration process.
| [in] | railHandle | A RAIL instance handle. |
| [inout] | calValues | A pointer to a structure of calibration values to apply. If a valid calibration structure is provided and the structure contains valid calibration values, those values will be applied to the hardware and the RAIL library will cache those values for use again later. If a valid calibration structure is provided and the structure contains a calibration value of RAIL_CAL_INVALID_VALUE for the desired calibration, the desired calibration will run, the calibration values structure will be updated with a valid calibration value, and the RAIL library will cache that value for use again later. If a NULL pointer is provided, the desired calibration will run and the RAIL library will cache that value for use again later. However, the valid calibration value will not be returned to the application. |
| [in] | calForce | A mask to force specific calibration(s) to execute. To run all pending calibrations, use the value RAIL_CAL_ALL_PENDING. Only the calibrations specified will run, even if not enabled during initialization. |
Returns
Status code indicating success of the function call.
If calibrations were performed previously and the application saves the calibration values (i.e., call this function with a calibration values structure containing calibration values of RAIL_CAL_INVALID_VALUE before a reset), the application can later bypass the time it would normally take to recalibrate hardware by reusing previous calibration values (i.e., call this function with a calibration values structure containing valid calibration values after a reset).
If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, to perform an IR calibration for the first time, it will return RAIL_STATUS_INVALID_STATE, in which case the application must defer calibration until after the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.
Note
Instead of this function, consider using the individual calibration-specific functions. Using the individual functions will allow for better dead-stripping if not all calibrations are run.
Some calibrations should only be executed when the radio is IDLE. See chip-specific documentation for more details.
5024 of file common/rail.hRAIL_GetPendingCal#
RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)
Return the current set of pending calibrations.
| [in] | railHandle | A RAIL instance handle. |
Returns
A mask of all pending calibrations that the user has been asked to perform.
This function returns a full set of pending calibrations. The only way to clear pending calibrations is to perform them using the RAIL_Calibrate() API with the appropriate list of calibrations.
5039 of file common/rail.hRAIL_ApplyIrCalibration#
RAIL_Status_t RAIL_ApplyIrCalibration (RAIL_Handle_t railHandle, uint32_t imageRejection)
Apply a given image rejection calibration value.
| [in] | railHandle | A RAIL instance handle. |
| [in] | imageRejection | The image rejection value to apply. |
Returns
Status code indicating success of the function call.
Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIr on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
DeprecatedPlease use RAIL_ApplyIrCalibrationAlt instead.
5059 of file common/rail.hRAIL_ApplyIrCalibrationAlt#
RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Apply a given image rejection calibration value.
| [in] | railHandle | A RAIL instance handle. |
| [in] | imageRejection | A pointer to the image rejection values to apply. |
| [in] | rfPath | RF path(s) to calibrate. |
Returns
Status code indicating success of the function call.
Take image rejection calibration values and apply them. These values should be determined from a previous run of RAIL_CalibrateIrAlt on the same physical device with the same radio configuration. The imageRejection values will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.
Note
: To make sure the imageRejection values are stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
5082 of file common/rail.hRAIL_CalibrateIr#
RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Run the image rejection calibration.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | The result of the image rejection calibration. |
Returns
Status code indicating success of the function call.
Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image.
If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, it will return RAIL_STATUS_INVALID_STATE. In this case, RAIL_ApplyIrCalibration may be called to apply a previously determined IR calibration value, or the app must defer calibration until the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.
DeprecatedPlease use RAIL_CalibrateIrAlt instead.
5111 of file common/rail.hRAIL_CalibrateIrAlt#
RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Run the image rejection calibration.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | A pointer to the image rejection results. |
| [in] | rfPath | RF path(s) to calibrate. |
Returns
Status code indicating success of the function call.
Run the image rejection calibration and apply the resulting values. If the imageRejection parameter is not NULL, store the values at that location. The imageRejection values will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image. Note
: To make sure the imageRejection values are stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
5136 of file common/rail.hRAIL_CalibrateTemp#
RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)
Run the temperature calibration.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Run the temperature calibration, which needs to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.
5160 of file common/rail.hRAIL_CalibrateHFXO#
RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t * crystalPPMError)
Performs HFXO compensation.
| [in] | railHandle | A RAIL instance handle. |
| [out] | crystalPPMError | A pointer for RAIL to store the current deviation that has been corrected, measured in PPM. May be NULL. |
Returns
Status code indicating the result of the function call.
Compute the PPM correction using the thermistor value available when RAIL_EVENT_THERMISTOR_DONE occurs, after RAIL_StartThermistorMeasurement() call. Then correct the RF frequency as well as TX and RX sampling.
This function calls the following RAIL functions in sequence saving having to call them individually:
Note
This function makes the radio idle.
5183 of file common/rail.hRAIL_EnablePaCal#
void RAIL_EnablePaCal (bool enable)
Enable/disable the PA calibration.
| [in] | enable | Enables/disables the PA calibration. |
Enabling will ensure that the PA power remains constant chip-to-chip. This feature is enabled by default on Series-2 platforms.
On EFR32xG21 and EFR32xG24 platforms, particularly the 20 dBm variants, it is recommended to keep this feature enabled in order to utilize the chip-specific calibrations designated for the chip.
The chip-specific define SL_RAIL_UTIL_PA_CALIBRATION_ENABLE in the Power Amplifier (PA) Utility plugin also enables/disables PA calibrations on initialization, which can override the default state of the feature.
Note
Call this function before RAIL_ConfigTxPower() if this feature is desired.
5204 of file common/rail.hRAIL_BLE_CalibrateIr#
RAIL_Status_t RAIL_BLE_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Calibrate image rejection for Bluetooth Low Energy.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | The result of the image rejection calibration. |
Returns
A status code indicating success of the function call.
Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.
1671 of file protocol/ble/rail_ble.hRAIL_IEEE802154_CalibrateIr2p4Ghz#
RAIL_Status_t RAIL_IEEE802154_CalibrateIr2p4Ghz (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Calibrate image rejection for IEEE 802.15.4 2.4 GHz.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | The result of the image rejection calibration. |
Returns
A status code indicating success of the function call.
Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.
1743 of file protocol/ieee802154/rail_ieee802154.hRAIL_IEEE802154_CalibrateIrSubGhz#
RAIL_Status_t RAIL_IEEE802154_CalibrateIrSubGhz (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Calibrate image rejection for IEEE 802.15.4 915 MHz and 868 MHz.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | The result of the image rejection calibration. |
Returns
A status code indicating success of the function call.
Some chips have protocol-specific image rejection calibrations programmed into their flash. This function will either get the value from flash and apply it, or run the image rejection algorithm to find the value.
DeprecatedPlease use RAIL_CalibrateIrAlt instead.
1759 of file protocol/ieee802154/rail_ieee802154.hMacro Definition Documentation#
RAIL_CAL_TEMP_VCO#
#define RAIL_CAL_TEMP_VCOValue:
(0x00000001U)
EFR32-specific temperature calibration bit.
4602 of file common/rail_types.hRAIL_CAL_TEMP_HFXO#
#define RAIL_CAL_TEMP_HFXOValue:
(0x00000002U)
EFR32-specific HFXO temperature check bit.
(Ignored if platform lacks RAIL_SUPPORTS_HFXO_COMPENSATION.)
4605 of file common/rail_types.hRAIL_CAL_COMPENSATE_HFXO#
#define RAIL_CAL_COMPENSATE_HFXOValue:
(0x00000004U)
EFR32-specific HFXO compensation bit.
(Ignored if platform lacks RAIL_SUPPORTS_HFXO_COMPENSATION.)
4608 of file common/rail_types.hRAIL_CAL_RX_IRCAL#
#define RAIL_CAL_RX_IRCALValue:
(0x00010000U)
EFR32-specific IR calibration bit.
4610 of file common/rail_types.hRAIL_CAL_OFDM_TX_IRCAL#
#define RAIL_CAL_OFDM_TX_IRCALValue:
(0x00100000U)
EFR32-specific Tx IR calibration bit.
(Ignored if platform lacks RAIL_SUPPORTS_OFDM_PA.)
4613 of file common/rail_types.hRAIL_CAL_ONETIME_IRCAL#
#define RAIL_CAL_ONETIME_IRCALValue:
(RAIL_CAL_RX_IRCAL | RAIL_CAL_OFDM_TX_IRCAL)
A mask to run EFR32-specific IR calibrations.
4616 of file common/rail_types.hRAIL_CAL_TEMP#
#define RAIL_CAL_TEMPValue:
(RAIL_CAL_TEMP_VCO | RAIL_CAL_TEMP_HFXO | RAIL_CAL_COMPENSATE_HFXO)
A mask to run temperature-dependent calibrations.
4618 of file common/rail_types.hRAIL_CAL_ONETIME#
#define RAIL_CAL_ONETIMEValue:
(RAIL_CAL_ONETIME_IRCAL)
A mask to run one-time calibrations.
4620 of file common/rail_types.hRAIL_CAL_PERF#
#define RAIL_CAL_PERFValue:
(0)
A mask to run optional performance calibrations.
4622 of file common/rail_types.hRAIL_CAL_OFFLINE#
#define RAIL_CAL_OFFLINEValue:
(RAIL_CAL_ONETIME_IRCAL)
A mask for calibrations that require the radio to be off.
4624 of file common/rail_types.hRAIL_CAL_ALL#
#define RAIL_CAL_ALLValue:
(RAIL_CAL_TEMP | RAIL_CAL_ONETIME)
A mask to run all possible calibrations for this chip.
4626 of file common/rail_types.hRAIL_CAL_ALL_PENDING#
#define RAIL_CAL_ALL_PENDINGValue:
(0x00000000U)
A mask to run all pending calibrations.
4628 of file common/rail_types.hRAIL_CAL_INVALID_VALUE#
#define RAIL_CAL_INVALID_VALUEValue:
(0xFFFFFFFFU)
An invalid calibration value.
4630 of file common/rail_types.hRAIL_MAX_RF_PATHS#
#define RAIL_MAX_RF_PATHSValue:
2
Indicates the maximum number of RF Paths supported across all platforms.
4637 of file common/rail_types.hRAIL_IRCALVALUES_RX_UNINIT#
#define RAIL_IRCALVALUES_RX_UNINITValue:
A define to set all RAIL_RxIrCalValues_t values to uninitialized.
This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.
4655 of file common/rail_types.hRAIL_IRCALVALUES_TX_UNINIT#
#define RAIL_IRCALVALUES_TX_UNINITValue:
A define to set all RAIL_TxIrCalValues_t values to uninitialized.
This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.
4684 of file common/rail_types.hRAIL_IRCALVALUES_UNINIT#
#define RAIL_IRCALVALUES_UNINITValue:
A define to set all RAIL_IrCalValues_t values to uninitialized.
This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.
4711 of file common/rail_types.hRAIL_IRCALVAL#
#define RAIL_IRCALVALValue:
(irCalStruct, rfPath)
A define allowing Rx calibration value access compatibility between non-OFDM and OFDM platforms.
4720 of file common/rail_types.hRAIL_CALVALUES_UNINIT#
#define RAIL_CALVALUES_UNINITValue:
RAIL_IRCALVALUES_UNINIT
A define to set all RAIL_CalValues_t values to uninitialized.
This define can be used when you have no data to pass to the calibration routines but wish to compute and save all possible calibrations.
4740 of file common/rail_types.hRAIL_PACTUNE_IGNORE#
#define RAIL_PACTUNE_IGNOREValue:
(255U)
Use this value with either TX or RX values in RAIL_SetPaCTune to use whatever value is already set and do no update.
This value is provided to provide consistency across EFR32 chips, but technically speaking, all PA capacitance tuning values are invalid on EFR32XG21 parts, as RAIL_SetPaCTune is not supported on those parts.
4748 of file common/rail_types.h