Generating Conversion Data#

Piecewise Linear Curve Fits#

The following steps explain how to generate the piecewise fit curves for the following PAs:

  • EFR32xG1x: High-power 2.4 GHz and sub-GHz

  • EFR32xG21: All PAs

  • EFR32xG22: High-power 2.4 GHz

  • EFR32xG23: All PAs

  • EFR32xG24: High-power 2.4 GHz

The procedure uses the 2.4 GHz high-power PA on EFR32xG1x devices as an example, but the same procedure is applicable to all the aforementioned PAs. For the other PAs, which do not use the piecewise linear fit approach, see the Lookup Table Fits section below.

  1. In Simplicity Studio, generate a RAILtest application configured with the desired PA, PA power source, and PA ramp time. The configuration process depends on the Proprietary Flex SDK version. If you are using version 2.x with Simplicity Studio 4, use Hardware Configurator (see AN1115: Configuring Peripherals for 32-Bit Devices using Hardware Configurator for more detail). If you are using version 3.x with Simplicity Studio 5, use the Component Editor to modify the RAIL Utility, Power Amplifier component. Build the RAILtest application, and flash the resulting binary to the chip mounted to the PCB you are trying to characterize.

  2. Connect the RF output of the board (U.FL test connector, SMA connector, or similar, with antenna disconnected from the RF path) to the input of a spectrum analyzer. The spectrum analyzer should be in dBm peak detection mode to sense values between approximately -30 to 20 dBm and centered on the base frequency/channel for your PHY and channel combination. Make sure to account for any cable / adapter loss in your measurements.

  3. Connect to the RAILtest CLI and enter the command sweepTxPower. For more information on RAILtest functionality and the CLI interface, see Using RAILTest in the Simplicity Studio Flex SDK RAIL documents group (RailTestUserGuide.html).

  4. Your chip should begin a CW tone at power level 1. Record the power level and dBm power measured on the spectrum analyzer in a CSV file in the format <POWER_LEVEL>,<ACTUAL_DBM_OUTPUT> with one reading per line. Note that unlike the conversion functions RAIL_GetTxPowerDbm and RAIL_SetTxPowerDbm, which use deci-dBm values, values in these csv files should be specified in dBm. Sample files SubgigPowerMapping.csv and 2p4PowerMapping.csv are included in the SDK for reference, and can be found in the /platform/radio/rail_lib/chip/efr32/efr32xg1x/characterization folder of the SDK installation.

  5. Repeat step 4 for all power levels. Press Enter in the RAILtest CLI to progress to the next power level.

  6. From a terminal prompt, run the pa_customer_curve_fits.py script (in /platform/radio/rail_lib/tools), with the python pa_customer_curve_fits.py <CSV_FILE>. If you don’t already have them installed, you will need to install the numpy and pylab python libraries. Running the commands pip install numpy and pip install matplotlib will install those libraries in the appropriate directories on your machine to be accessible by python. The following figure shows an example of an intended result, after the pa_customer_curve_fits.py script has been run on the 2p4PowerMapping.csv file from a terminal prompt.

    Note: The script also provides extra parameters such as –maxPower/-m and –increment/-i to accommodate the maximum power from the csv and to divide the data in segments of needed "increment" dBm steps.

    pa_customer_curve_fits.py Script Resultspa_customer_curve_fits.py Script Results

  7. If using multiple PAs (other than the EFR32xG1x 2.4 GHz low-power PA), repeat steps 1-6 for the PA you did not characterize previously.

  8. Create a copy of the PA curve file (here and in subsequent steps, "PA curve file" refers to pa_curves_efr32xg1x.h or pa_curves_efr32xg2x.h in RAIL 2.8 and earlier versions, and sl_rail_util_pa_curves.h in RAIL 2.9 versions and later depending on the platform currently being characterized). Copy the terminal output from the python script under the appropriate macro. Note that there is one RAIL_PA_CURVES_… define for each combination of PA and PA power source available for your hardware. You do not need to copy data for a PA/PA power supply (…_VBAT_… or …_DCDC_…) combination that is not being used. Additionally, update the …_MIN_POWER and …_MAX_POWER macros to reflect the values you observed. The following figure shows an example of the copying process, where the values from the previous figure have been copied into the appropriate (Sub-GHz and 2.4 GHz, battery-powered) macros in a new CUSTOM_pa_curves_efr32xg1x.h file. Some of the …MIN_POWER and …_MAX_POWER macros have been updated.

    Terminal Output Copied into a Custom pa_curves_efr32xg1x.h FileTerminal Output Copied into a Custom pa_curves_efr32xg1x.h File

  9. Update the hardware config HAL_PA_CURVE_HEADER header to point to your new file. The following figures illustrates where to update the header.The interface depends on the tool used (Hardware Configurator in Proprietary Flex SDK 2.x, or Component Editor in Proprietary Flex SDK 3.x).

    Updating the Custom PA Curve Header File Name with Hardware ConfiguratorUpdating the Custom PA Curve Header File Name with Hardware Configurator

    Updating the Custom PA Curve Header File Name with Component EditorUpdating the Custom PA Curve Header File Name with Component Editor

  10. For customers using only one or two of the available PAs, Silicon Labs recommends removing references to these functions from pa_conversions_efr32.c and from the RAIL_DECLARE_TX_POWER macros in your new version of the PA curves file. Although not strictly necessarily, doing this can save substantial code size versus compiling in useless data for a PA that is never engaged.

Lookup Table Fits#

This information applies to the following PAs:

  • EFR32xG1x: Low-power 2.4 GHz

  • EFR32xG22: Low power 2.4 GHz

  • EFR32xG24x01x: Low power 2.4 GHz

With only a few unique power levels, some PAs on some chip families use a simple lookup table to translate power levels to output powers, as opposed to a more code-size-intensive curve fit. Using the EFR32xG1x low-power PA as an example, follow steps 1-5 in the previous section, but for step 4, place the results directly into the RAIL_PA_CURVES_2P4_LP macro of the custom PA curves file. These values should be entered as deci-dBm (for example. enter -100 to indicate -10 dBm). A similar process can be followed for any other PAs using the lookup table approach. The following two figures contain an example of this process.

Running RAILtest’s sweepTxPower CommandRunning RAILtest’s sweepTxPower Command

Updating the deci-dBm Output Powers in the 2.4 GHz low-power PA Lookup TableUpdating the deci-dBm Output Powers in the 2.4 GHz low-power PA Lookup Table

dBm-to-powerSetting Mode#

A new mode has been added to the EFR32xG25 family that allows for a single PA to support the entire range of supported dBm levels for both the OFDM and SUBGIG (FSK) PAs. This is accomplished with a table in memory that contains a "powerSetting" for each supported dBm level. The table specifies the minimum and maximum dBm levels that are supported, as well as the step size between entries in the table. The default step size is 0.1 dBm. This allows for precise control over the output power of the PA, making it possible to achieve the desired level of performance across the entire range of supported dBm levels. Note that this new mode utilizes "powerSetting" instead of the traditional "power levels" for the output power of the PA. As a result, the capability to set a specific "raw" power level is no longer supported in this mode. Only the setting of dBm levels from the table is supported in this mode.

OFDM#

A powerSetting for OFDM is comprised of three primary components: the digital gain, the slice level, and the filter gain. The digital gain is specified by the VPA_OFDM_GAINDIG_MASK and VPA_OFDM_GAINDIG_SHIFT values, which define a mask and shift for extracting the digital gain from the powerSetting value. The slice level is specified by the VPA_OFDM_SLICE_MASK and VPA_OFDM_SLICE_SHIFT values, which define a mask and shift for extracting the slice level from the powerSetting value. Finally, the filter gain is specified by the VPA_OFDM_FILGAIN_MASK and VPA_OFDM_FILGAIN_SHIFT values, which define a mask and shift for extracting the filter gain from the powerSetting value. These three components work together to determine the overall power output of the PA for OFDM signals.

To ensure proper usage and optimal performance, it is important to adhere to the valid ranges for the digital gain, slice level, and filter gain. The valid range for the digital gain is 0 to 204 (the value is multiplied by 5 in RAIL, resulting in a range of 0 to 1020), the valid range for the slice level is 0 to 191, and the valid range for the filter gain is 0 to 3.

In addition to the valid ranges, the following are the recommended ranges: digital gain between 200 and 800, filter gain of 2.

#define VPA_OFDM_GAINDIG_MASK       (0xFFUL)
#define VPA_OFDM_GAINDIG_SHIFT      (0U)
#define VPA_OFDM_SLICE_MASK         (0xFF00UL)
#define VPA_OFDM_SLICE_SHIFT        (8U)
#define VPA_OFDM_FILGAIN_MASK       (0xFF0000UL)
#define VPA_OFDM_FILGAIN_SHIFT      (16U)

To generate a table using the pa_dbm_mapping_table_generator.py script (in platform/radio/rail_lib/tools), you will need a CSV file containing the necessary data for OFDM mode. The file should have a header row with column names for:

  • Digital gain

  • Slice level

  • Filter gain

Each subsequent row should contain data for a specific dBm level within the desired range. Each column's data should be separated by a comma, and you can add optional comments for each row using the "#" symbol. It is crucial to ensure that the CSV file is properly formatted, with the correct data in each column and the correct number of rows for the desired dBm range.

Format of the OFDM PA CSV File

TXTRIMPASLICE

GAINDIG

FILGAIN

#dBm

x

x

x

#-317

x

x

x

#-316

x

x

x

#-315

x

x

x

#-314

This table shows an example of how the CSV file should be formatted for generating a table for OFDM mode. The first row is the header row, which specifies the column names. Each subsequent row contains data on the power settings for a specific dBm level, as well as an optional comment indicating the corresponding dBm value. The data for each column is separated by a comma. It is important to include a row for every dBm level within the desired range, with the appropriate power setting values for each level. Please be aware that the "dBm" column in the table is preceded by a "#" symbol, which indicates that it is a comment and will be ignored by the script.

SUBGIG (FSK)#

A powerSetting for SUBGIG (FSK) mode is comprised of four primary components: the fine current setting, the coarse current setting, the slice level, and the stripe setting. The fine current setting is specified by the VPA_SUBGIG_CURRENTFINE_MASK and VPA_SUBGIG_CURRENTFINE_SHIFT values, which define a mask and shift for extracting the fine current setting from the powerSetting value. The coarse current setting is specified by the VPA_SUBGIG_CURRENTCOARSE_MASK and VPA_SUBGIG_CURRENTCOARSE_SHIFT values, which define a mask and shift for extracting the coarse current setting from the powerSetting value. The slice level is specified by the VPA_SUBGIG_SLICE_MASK and VPA_SUBGIG_SLICE_SHIFT values, which define a mask and shift for extracting the slice level from the powerSetting value. Finally, the stripe setting is specified by the VPA_SUBGIG_STRIPE_MASK and VPA_SUBGIG_STRIPE_SHIFT values, which define a mask and shift for extracting the stripe setting from the powerSetting value. These four components work together to determine the overall power output of the PA for SUBGIG (FSK) signals.

The valid range for the fine current setting is 0 to 8, the valid range for the coarse current setting is 0 to 31, the valid range for the slice level is 0 to 2, and the valid range for the stripe setting is 0 to 31.

In addition to the valid ranges, the following are the recommended ranges: current fine of 4, and slice level between 1 and 2.

#define VPA_SUBGIG_CURRENTFINE_MASK       (0xFF000000UL)
#define VPA_SUBGIG_CURRENTFINE_SHIFT      (24U)
#define VPA_SUBGIG_CURRENTCOARSE_MASK     (0xFF0000UL)
#define VPA_SUBGIG_CURRENTCOARSE_SHIFT    (16U)
#define VPA_SUBGIG_SLICE_MASK             (0xFF00UL)
#define VPA_SUBGIG_SLICE_SHIFT            (8U)
#define VPA_SUBGIG_STRIPE_MASK            (0xFFUL)
#define VPA_SUBGIG_STRIPE_SHIFT           (0U)

To generate a table using the pa_dbm_mapping_table_generator.py script (in platform/radio/rail_lib/tools), you will need a CSV file containing the necessary data for SUBGIG (FSK) mode. The file should have a header row with column names for:

  • Coarse current setting

  • Fine current setting

  • Slice level

  • Stripe setting

Each subsequent row should contain data for a specific dBm level within the desired range. Each column's data should be separated by a comma, and you can add optional comments for each row using the "#" symbol. It is crucial to ensure that the CSV file is properly formatted, with the correct data in each column and the correct number of rows for the desired dBm range.

Format of the SUBGIG (FSK) PA CSV File

COARSE

FINE

SLICE

STRIPE

#dBm

x

x

x

x

#-317

x

x

x

x

#-316

x

x

x

x

#-315

x

x

x

x

#-314

This table shows an example of how the CSV file should be formatted for generating a table for SUBGIG (FSK) mode. The first row is the header row, which specifies the column names. Each subsequent row contains data on the power settings for a specific dBm level, as well as an optional comment indicating the corresponding dBm value. The data for each column is separated by a comma. It is important to include a row for every dBm level within the desired range, with the appropriate power setting values for each level. Please be aware that the "dBm" column in the table is preceded by a "#" symbol, which indicates that it is a comment and will be ignored by the script.

Generating the Table#

The script pa_dbm_mapping_table_generator.py is located in the platform/radio/rail_lib/tools directory. It takes data from the CSV file specified with the File argument and generates a list of power setting values based on the -min or --minPower and -max or --maxPower arguments. To understand the CSV format for each respective mode, refer to the OFDM and SUBGIG sections above. Note that a -t or --type argument is also required, with a default value of OFDM, to specify the type of curve.

It also accepts command-line arguments for:

  • An optional flag -f or --fem to indicate whether the table is for a front-end module (FEM) with a default value of False.

  • An optional argument -o or --output to specify the output file for the generated code.

The script has a default increment value for the dBm levels, which you can customize as needed. Additionally, the script generates C code for defining the table, including:

  • The number of values

  • The step size between dBm levels

  • The minimum and maximum dBm levels

  • The actual power setting values

Finally, the script outputs the generated C code to stdout. To use the generated table, the user should replace the applicable contents of the plugin/pa-conversions/efr32xg25/ files with the output of the script.