The RCL enables the control of the TX output power associated with a radio operation. This is achieved by including a txPower field in the command struct of all commands that involve a TX operation.

The available TX power settings are defined in a TX power table (LRF_TxPowerTable) which is part of the radio setup.

In addition to the TX power table, the RCL also utilizes a TX power limitation table (LRF_TxPowerLimitTable) to specify maximum output power values based on frequency or channel. This table is sorted in ascending order of frequency and uses a bitmask to specify the regulatory domain (configurable via SysConfig) for which the output power limits apply.

The following regulatory domains are currently supported by the RCL:

Regulatory Domain	Description
RCL_REGULATORY_DOMAIN_NONE	No frequency-specific output power limitation
RCL_REGULATORY_DOMAIN_ETSI	European Telecommunications Standards Institute (Europe)
RCL_REGULATORY_DOMAIN_FCC	Federal Communications Commission (USA)
RCL_REGULATORY_DOMAIN_MIIT	Ministry of Information and Communications Technology (China)

Usage

For a normal use case, the following usage is recommended:

Set the 'Regulatory Domains' option of the RCL module in SysConfig. Multiple regulations can be selected.
Specify the desired dBm value in the txPower field. This must be done before submitting a command involving a TX operation.
- The RCL will apply the TX power table to determine the nearest entry that is equal to or below the requested power value (e.g., 7dBm might be rounded to 6dBm, and -5dBm might be rounded to -8dBm).
- The RCL will check the power limitation table to ensure the output power is within the regulatory domain and frequency or channel restrictions.
If no output power in the table satisfies the requested setting, an error is returned.
The recommended way to set TX output power is by using designated initializers, either setting .dBm and .fraction or .rawValue. However, if the application writes directly to the txPower field, it should ensure the value is within the available range.

Please note:

Special values (LRF_TxPower_Use_Min and LRF_TxPower_Use_Max) are available for selecting the maximum and minimum available output power.
No additional action is required by the application to apply the power limitation table. The RCL will automatically adjust the output power based on the regulatory domain and frequency or channel in use.
If needed, the regulatory domain can be modified at runtime.
The RCL will use the most restrictive regulatory domain when programming the output power value (i.e., the smallest value applicable) if multiple regulations are selected.

Examples

void runGenericTxWithTxPowerSet(void)
{
    ExampleRCL_GenericHdrDef hdrDef = FSK_hdrDef_DefaultRuntime();
    /* Set up Tx buffers considering 4 packets, packet length of 200 bytes, 2 header bytes and 3 padding bytes */
    RCL_Buffer_TxBuffer *txBuffers[NUM_PKT];
    uint32_t pktBuffer[NUM_PKT][RCL_TxBuffer_len_u32(NUM_PAD, HDR_LEN, PKT_LEN)];
    RCL_init();
    RCL_Handle h = RCL_open(&rclClient, &LRF_configGfsk500Kbps);
    for (int i = 0; i < NUM_PKT; i++)
    {
        txBuffers[i] = (RCL_Buffer_TxBuffer *)pktBuffer[i];
    }
    /* Declare command */
    RCL_CmdGenericTx cmd;
    cmd = RCL_CmdGenericTx_DefaultRuntime();
    /* Command configuration */
    cmd.common.scheduling = RCL_Schedule_AbsTime;
    cmd.common.runtime.callback = defaultCallback;
    cmd.common.runtime.rclCallbackMask = RCL_EventLastCmdDone;
    cmd.rfFrequency = FREQUENCY;
    cmd.syncWord = SYNCWORD;
    /* Set TX  output power */
    /* Set txPower.dBm and txPower.fraction, with rawValue set accordingly */
    cmd.txPower = (RCL_Command_TxPower) { .dBm = 7, .fraction = 0};
    /* OR, set txPower.rawValue, with dBm and fraction are set according to rawValue */
    cmd.txPower = (RCL_Command_TxPower) { .rawValue = 14};
    generatePackets(txBuffers, NUM_PKT, PKT_LEN, &hdrDef, EXAMPLE_HDR);
    for(int i = 0; i < NUM_PKT; i++)
    {
        RCL_TxBuffer_put(&cmd.txBuffers, txBuffers[i]);
    }
    /* Schedule first command considering a start delay of 600 us */
    uint32_t nextTime = RCL_Scheduler_getCurrentTime() + RCL_SCHEDULER_SYSTIM_US(600);
    for (int i = 0; i < NUM_PKT; i++)
    {
        cmd.common.status = RCL_CommandStatus_Idle;
        cmd.common.timing.absStartTime = nextTime;
        RCL_Command_submit(h, &cmd);
        /* Wait for command to conclude  */
        RCL_Command_pend(&cmd);
        /* Schedule next command considering the same start delay */
        nextTime = RCL_Scheduler_getCurrentTime() + RCL_SCHEDULER_SYSTIM_US(600);
    }
}

Alternative

The user can also set TX output power by assigning the value to an existing structure's member.

    /* Set txPower.dBm and txPower.fraction which combined form txPower.rawValue */
    cmd.txPower.dBm = 7;
    cmd.txPower.fraction = 0;
    /* OR, set txPower.rawValue which combines dBm and fraction */
    cmd.txPower.rawValue = 14;

Special settings

Special settings are another way to set the Tx output power, either to the maximum or the minimum available in the table

    /*  Use the lowest available value (min) in the table */
    cmd.txPower = LRF_TxPower_Use_Min;
     /* OR, use the highest available value (max) in the table */
    cmd.txPower = LRF_TxPower_Use_Max;

Advanced

This setting is intented for advanced users only and is not recommended

If the user set txPower to Raw, then value.rawValue and the temperature coefficient needs to be set.