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;
static volatile bool calibrateRadio = false;
void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
// Omitting other event handlers
if (events & RAIL_EVENT_CAL_NEEDED) {
calibrateRadio = true;
}
}
void main(void)
{
// Initialize RAIL ...
// Application main loop
while (1) {
...
if (calibrateRadio) {
// Run all pending calibrations, and save the results
RAIL_Calibrate(railHandle, &calValues, RAIL_CAL_ALL_PENDING);
calibrateRadio = false;
}
...
}
}
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.
These APIs calibrate the radio. The RAIL library determines which calibrations are necessary. Calibrations can be enabled/disabled with the sl_rail_cal_mask_t parameter.
Some calibrations produce values that can be saved and reapplied to avoid repeating the calibration process.
Calibrations can either be run with sl_rail_calibrate(), or with the individual chip-specific calibration routines. An example for running code with sl_rail_calibrate() looks like the following:
static sl_rail_cal_values_t cal_values = SL_RAIL_CALVALUES_UNINIT;
static volatile bool calibrateRadio = false;
void rail_events_callback(sl_rail_handle_t rail_handle, sl_rail_events_t events)
{
// Omitting other event handlers
if (events & SL_RAIL_EVENT_CAL_NEEDED) {
calibrateRadio = true;
}
}
void main(void)
{
// Initialize RAIL ...
// Application main loop
while (1) {
...
if (calibrateRadio) {
// Run all pending calibrations, and save the results
sl_rail_calibrate(rail_handle, &cal_values, SL_RAIL_CAL_ALL_PENDING);
calibrateRadio = false;
}
...
}
}
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 sl_rail_ir_cal_values_t ir_cal_values = {
.rx_ir_cal_values = {
RX_IRCAL_VALUE_RF_PATH0,
RX_IRCAL_VALUE_RF_PATH1,
},
.tx_ir_cal_values = {
.dc_offset_iq = TX_IRCAL_DC_OFFSET_IQ,
.phi_epsilon = TX_IRCAL_PHI_EPSILON,
},
};
void rail_events_handler(sl_rail_handle_t rail_handle, sl_rail_events_t events)
{
// Omitting other event handlers
if (events & SL_RAIL_EVENT_CAL_NEEDED) {
sl_rail_cal_mask_t pending_cals = sl_rail_get_pending_cal(rail_handle);
// Disable the radio if we have to do an offline calibration
if (pending_cals & SL_RAIL_CAL_TEMP_VC0) {
(void) sl_rail_calibrate_temp(rail_handle);
}
if (pending_cals & SL_RAIL_CAL_ONETIME_IRCAL) {
(void) sl_rail_apply_ir_calibration(rail_handle, &ir_cal_values, SL_RAIL_ANTENNA_AUTO);
}
}
}
Modules#
Typedefs#
A calibration mask type.
RAIL_RxIrCalValues_t.
A calibration value structure.
A calibration mask type.
sl_rail_rx_ir_cal_values_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 given image rejection calibration values.
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.
Initialize RAIL calibration.
Start the calibration process.
Return the current set of pending calibrations.
Apply given image rejection calibration values.
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.
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.
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 sl_rail_rx_ir_cal_values_t values to uninitialized.
A define to set all sl_rail_tx_ir_cal_values_t values to uninitialized.
A define to set all sl_rail_ir_cal_values_t values to uninitialized.
A define allowing Rx calibration value access compatibility between non-OFDM and OFDM platforms.
A define to set all sl_rail_cal_values_t values to uninitialized.
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.
DeprecatedRAIL 2.x synonym of sl_rail_cal_mask_t.
RAIL_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.
DeprecatedRAIL 2.x synonym of sl_rail_rx_ir_cal_values_t.
RAIL_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.
DeprecatedRAIL 2.x synonym of sl_rail_ir_cal_values_t.
sl_rail_cal_mask_t#
sl_rail_cal_mask_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.
sl_rail_rx_ir_cal_values_t#
typedef uint32_t sl_rail_rx_ir_cal_values_t[2] [2]
sl_rail_rx_ir_cal_values_t
RX IR calibration values.
Platforms with fewer SL_RAIL_RF_PATHS than SL_RAIL_MAX_RF_PATHS will only respect and update SL_RAIL_RF_PATHS indices and ignore the rest.
sl_rail_cal_values_t#
sl_rail_cal_values_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 SL_RAIL_CAL_INVALID_VALUE to force the code to compute that calibration value.
Function Documentation#
RAIL_ConfigCal#
RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)
Initialize RAIL calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_CalMask_t | [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.
DeprecatedRAIL 2.x synonym of sl_rail_config_cal().
RAIL_Calibrate#
RAIL_Status_t RAIL_Calibrate (RAIL_Handle_t railHandle, RAIL_CalValues_t * calValues, RAIL_CalMask_t calForce)
Start the calibration process.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_CalValues_t * | [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. |
| RAIL_CalMask_t | [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).
Silicon Labs recommends calling this function from the application main loop.
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.
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.
DeprecatedRAIL 2.x synonym of sl_rail_calibrate().
RAIL_GetPendingCal#
RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)
Return the current set of pending calibrations.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [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.
DeprecatedRAIL 2.x synonym of sl_rail_get_pending_cal().
RAIL_ApplyIrCalibration#
RAIL_Status_t RAIL_ApplyIrCalibration (RAIL_Handle_t railHandle, uint32_t imageRejection)
Apply a given image rejection calibration value.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint32_t | [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.
DeprecatedThis previously-deprecated RAIL 2.x function has been replaced by sl_rail_apply_ir_calibration() with different parameters.
RAIL_ApplyIrCalibrationAlt#
RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Apply given image rejection calibration values.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IrCalValues_t * | [in] | imageRejection | A pointer to the image rejection values to apply. |
| RAIL_AntennaSel_t | [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.
DeprecatedRAIL 2.x synonym of sl_rail_apply_ir_calibration().
RAIL_CalibrateIr#
RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Run the image rejection calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint32_t * | [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. Silicon Labs recommends calling this function from the application main loop.
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.
DeprecatedThis previously-deprecated RAIL 2.x function has been replaced by sl_rail_calibrate_ir with different parameters.
RAIL_CalibrateIrAlt#
RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Run the image rejection calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_IrCalValues_t * | [out] | imageRejection | A pointer to the image rejection results. |
| RAIL_AntennaSel_t | [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. Silicon Labs recommends calling this function from the application main loop.
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.
DeprecatedRAIL 2.x synonym of sl_rail_calibrate_ir().
RAIL_CalibrateTemp#
RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)
Run the temperature calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [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.
Note
If RX channel hopping is enabled this function may trigger a channel hop, which can result in RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE occuring before it returns.
DeprecatedRAIL 2.x synonym of sl_rail_calibrate_temp().
RAIL_CalibrateHFXO#
RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t * crystalPPMError)
Performs HFXO compensation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| int8_t * | [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.
DeprecatedRAIL 2.x synonym of sl_rail_calibrate_hfxo().
RAIL_EnablePaCal#
void RAIL_EnablePaCal (bool enable)
Enable/disable the PA calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | [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 RAIL 2.x 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 not desired.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_enable_pa_cal() with additional sl_rail_handle_t parameter.
RAIL_BLE_CalibrateIr#
RAIL_Status_t RAIL_BLE_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Calibrate image rejection for Bluetooth Low Energy.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint32_t * | [out] | imageRejection | A pointer to where the result of the image rejection calibration will be stored. |
Returns
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.
DeprecatedRAIL 2.x synonym of sl_rail_ble_calibrate_ir().
RAIL_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint32_t * | [out] | imageRejection | A pointer to the result of the image rejection calibration. |
Returns
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.
DeprecatedRAIL 2.x synonym of sl_rail_ieee802154_calibrate_ir_2p4_ghz().
RAIL_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| uint32_t * | [out] | imageRejection | The result of the image rejection calibration. |
Returns
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.
DeprecatedUse sl_rail_calibrate_ir() instead.
sl_rail_config_cal#
sl_rail_status_t sl_rail_config_cal (sl_rail_handle_t rail_handle, sl_rail_cal_mask_t cal_enable_mask)
Initialize RAIL calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_cal_mask_t | [in] | cal_enable_mask | 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.
sl_rail_calibrate#
sl_rail_status_t sl_rail_calibrate (sl_rail_handle_t rail_handle, sl_rail_cal_values_t * p_cal_values, sl_rail_cal_mask_t cal_force_mask)
Start the calibration process.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_cal_values_t * | [inout] | p_cal_values | 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 SL_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. |
| sl_rail_cal_mask_t | [in] | cal_force_mask | A mask to force specific calibration(s) to execute. To run all pending calibrations, use the value SL_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 SL_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).
Silicon Labs recommends calling this function from the application main loop.
If multiple protocols are used, this function will make the given rail_handle 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 SL_RAIL_STATUS_INVALID_STATE, in which case the application must defer calibration until after the protocol switch is complete.
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.
sl_rail_get_pending_cal#
sl_rail_cal_mask_t sl_rail_get_pending_cal (sl_rail_handle_t rail_handle)
Return the current set of pending calibrations.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real 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 sl_rail_calibrate() API with the appropriate list of calibrations.
sl_rail_apply_ir_calibration#
sl_rail_status_t sl_rail_apply_ir_calibration (sl_rail_handle_t rail_handle, sl_rail_ir_cal_values_t * p_image_rejection, sl_rail_antenna_sel_t rf_path)
Apply given image rejection calibration values.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ir_cal_values_t * | [in] | p_image_rejection | A pointer to the image rejection values to apply. |
| sl_rail_antenna_sel_t | [in] | rf_path | 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 sl_rail_calibrate_ir() on the same physical device with the same radio configuration. The p_image_rejection values will also be stored to the sl_rail_channel_config_entry_t::p_attr, if possible.
Note
: To make sure the p_image_rejection value is stored/configured correctly, sl_rail_config_antenna() should be called before calling this API.
If multiple protocols are used, this function will return SL_RAIL_STATUS_INVALID_STATE if it is called and the given rail_handle is not active. In that case, the caller must attempt to re-call this function later.
sl_rail_calibrate_ir#
sl_rail_status_t sl_rail_calibrate_ir (sl_rail_handle_t rail_handle, sl_rail_ir_cal_values_t * p_image_rejection, sl_rail_antenna_sel_t rf_path)
Run the image rejection calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_ir_cal_values_t * | [out] | p_image_rejection | A pointer to the image rejection results. |
| sl_rail_antenna_sel_t | [in] | rf_path | 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 p_image_rejection parameter is not NULL, store the values at that location. The p_image_rejection values will also be stored to the sl_rail_channel_config_entry_t::p_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. Silicon Labs recommends calling this function from the application main loop.
Note
: To make sure the p_image_rejection values are stored/configured correctly, sl_rail_config_antenna() should be called before calling this API.
If multiple protocols are used, this function will return SL_RAIL_STATUS_INVALID_STATE if it is called and the given rail_handle is not active. In that case, the caller must attempt to re-call this function later.
sl_rail_calibrate_temp#
sl_rail_status_t sl_rail_calibrate_temp (sl_rail_handle_t rail_handle)
Run the temperature calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real 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 SL_RAIL_STATUS_INVALID_STATE if it is called and the given rail_handle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.
Note
If RX channel hopping is enabled this function may trigger a channel hop, which can result in SL_RAIL_EVENT_RX_CHANNEL_HOPPING_COMPLETE occuring before it returns.
sl_rail_calibrate_hfxo#
sl_rail_status_t sl_rail_calibrate_hfxo (sl_rail_handle_t rail_handle, int8_t * p_crystal_error_ppm)
Performs HFXO compensation.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| int8_t * | [out] | p_crystal_error_ppm | 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 SL_RAIL_EVENT_THERMISTOR_DONE occurs, after sl_rail_start_thermistor_measurement() 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.
sl_rail_enable_pa_cal#
void sl_rail_enable_pa_cal (sl_rail_handle_t rail_handle, bool enable)
Enable/disable the PA calibration.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| bool | [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 after reset.
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 RAIL 2.x 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 sl_rail_config_tx_power() if this feature is not desired.
sl_rail_ble_calibrate_ir#
sl_rail_status_t sl_rail_ble_calibrate_ir (sl_rail_handle_t rail_handle, uint32_t * p_image_rejection)
Calibrate image rejection for Bluetooth Low Energy.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint32_t * | [out] | p_image_rejection | A pointer to where the result of the image rejection calibration will be stored. |
Returns
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.
sl_rail_ieee802154_calibrate_ir_2p4_ghz#
sl_rail_status_t sl_rail_ieee802154_calibrate_ir_2p4_ghz (sl_rail_handle_t rail_handle, uint32_t * p_image_rejection)
Calibrate image rejection for IEEE 802.15.4 2.4 GHz.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| uint32_t * | [out] | p_image_rejection | A pointer to the result of the image rejection calibration. |
Returns
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.