RF.h File Reference

Detailed Description

Radio Frequency (RF) Core Driver for the CC13XX and CC26XX device family.

---

To use the RF driver, ensure that the correct driver library for your device is linked in and include this header file as follows:

#include <ti/drivers/rf/RF.h>

---

Overview

The RF driver provides access to the radio core on the CC13xx/CC26xx device family. It offers a high-level interface for command execution and to the radio timer (RAT). The RF driver ensures the lowest possible power consumption by providing automatic power management that is fully transparent for the application.

Note

This document describes the features and usage of the RF driver API. For a detailed explanation of the RF core, please refer to the Technical Reference Manual or the Proprietary RF User Guide.

Key features are:

• Synchronous execution of direct and immediate radio commands
• Synchronous and asynchronous execution of radio operation commands
• Various event hooks to interact with RF commands and the RF driver
• Automatic power management
• Preemptive scheduler for RF operations of different RF driver instances
• Convenient Access to the radio timer (RAT)
• Programming the TX power level

Setup and configuration

The RF driver can be configured at 4 different places:

1. In the build configuration by choosing either the single-client or multi-client driver version.
2. At compile-time by setting hardware and software interrupt priorities in the board support file.
3. During run-time initialization by setting RF_Params when calling RF_open().
4. At run-time via RF_control().

Build configuration

The RF driver comes in two versions: single-client and multi-client. The single-client version allows only one driver instance to access the RF core at a time. The multi-client driver version allows concurrent access to the RF core with different RF settings. The multi-client driver has a slightly larger footprint and is not needed for many proprietary applications. The driver version can be selected in the build configuration by linking either against a RFCC26XX_singleMode or RFCC26XX_multiMode pre-built library. When using the single-client driver, RF_SINGLEMODE has to be defined globally in the build configuration. The multi-client driver is the default configuration in the SimpleLink SDKs.

Board configuration

The RF driver handles RF core hardware interrupts and uses software interrupts for its internal state machine. For managing the interrupt priorities, it expects the existence of a global RFCC26XX_HWAttrsV2 object. This is usually defined in the board support file, for example CC1310_LAUNCHXL.c, but when developing on custom boards, it might be kept anywhere in the application. By default, the priorities are set to the lowest possible value:

const RFCC26XX_HWAttrsV2 RFCC26XX_hwAttrs = {
    .hwiPriority        = INT_PRI_LEVEL7,  // Lowest HWI priority:  INT_PRI_LEVEL7
                                           // Highest HWI priority: INT_PRI_LEVEL1

    .swiPriority        = 0,               // Lowest SWI priority:  0
                                           // Highest SWI priority: Swi.numPriorities - 1

    .xoscHfAlwaysNeeded = true             // Power driver always starts XOSC-HF:       true
                                           // RF driver will request XOSC-HF if needed: false
};

Initialization

When initiating an RF driver instance, the function RF_open() accepts a pointer to a RF_Params object which might set several driver parameters. In addition, it expects an RF_Mode object and a setup command which is usually generated by SmartRF Studio:

RF_Params rfParams;
RF_Params_init(&rfParams);
rfParams.nInactivityTimeout = 2000;

RF_Handle rfHandle = RF_open(&rfObject, &RF_prop,
        (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);

The function RF_open() returns a driver handle that is used for accessing the correct driver instance. Please note that the first RF operation command before an RX or TX operation command must be a CMD_FS to set the synthesizer frequency. The RF driver caches both, the pointer to the setup command and the physical CMD_FS for automatic power management.

Run-time configuration

While a driver instance is opened, it can be re-configured with the function RF_control(). Various configuration parameters RF_CTRL are available. Example:

uint32_t timeoutUs = 2000;
RF_control(rfHandle, RF_CTRL_SET_INACTIVITY_TIMEOUT, &timeoutUs);

---

Command execution

The RF core supports 3 different kinds of commands:

1. Direct commands
2. Immediate commands
3. Radio operation commands

Direct and immediate commands are dispatched via RF_runDirectCmd() and RF_runImmediateCmd() respectively. These functions block until the command has completed and return a status code of the type RF_Stat when done.

#include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>

RF_Stat status = RF_runDirectCmd(rfHandle, CMD_ABORT);
assert(status == RF_StatCmdDoneSuccess);

Radio operation commands are potentially long-running commands and support different triggers as well as conditional execution. Only one command can be executed at a time, but the RF driver provides an internal queue that stores commands until the RF core is free. Two interfaces are provided for radio operation commands:

1. Asynchronous: RF_postCmd() and RF_pendCmd()
2. Synchronous: RF_runCmd()

The asynchronous function RF_postCmd() posts a radio operation into the driver's internal command queue and returns a command handle of the type RF_CmdHandle which is an index in the command queue. The command is dispatched as soon as the RF core has completed any previous radio operation command.

#include <ti/devices/${DEVICE_FAMILY}/driverlib/rf_common_cmd.h>

RF_Callback callback = NULL;
RF_EventMask subscribedEvents = 0;
RF_CmdHandle rxCommandHandle = RF_postCmd(rfHandle, (RF_Op*)&RF_cmdRx,
        RF_PriorityNormal, callback, subscribedEvents);

assert(rxCommandHandle != RF_ALLOC_ERROR); // The command queue is full.

Command execution happens in background. The calling task may proceed with other work or execute direct and immediate commands to interact with the posted radio operation. But beware that the posted command might not have started, yet. By calling the function RF_pendCmd() and subscribing events of the type RF_EventMask, it is possible to re-synchronize to a posted command:

// RF_EventRxEntryDone must have been subscribed in RF_postCmd().
RF_EventMask events = RF_pendCmd(rfHandle, rxCommandHandle,
        RF_EventRxEntryDone);

// Program proceeds after RF_EventRxEntryDone or after a termination event.

The function RF_runCmd() is a combination of both, RF_postCmd() and RF_pendCmd() and allows synchronous execution.

A pending or already running command might be aborted at any time by calling the function RF_cancelCmd() or RF_flushCmd(). These functions take command handles as parameters, but can also just abort anything in the RF driver's queue:

uint8_t abortGraceful = 1;

// Abort a single command
RF_cancelCmd(rfHandle, rxCommandHandle, abortGraceful);

// Abort anything
RF_flushCmd(rfHandle, RF_CMDHANDLE_FLUSH_ALL, abortGraceful);

When aborting a command, the return value of RF_runCmd() or RF_pendCmd() will contain the termination reason in form of event flags. If the command is in the RF driver queue, but has not yet start, the RF_EventCmdCancelled event is raised.

---

Event callbacks

The RF core generates multiple interrupts during command execution. The RF driver maps these interrupts 1:1 to callback events of the type RF_EventMask. Hence, it is unnecessary to implement own interrupt handlers. Callback events are divided into 3 groups:

• Command-specific events, documented for each radio operation command. An example is the RF_EventRxEntryDone for the CMD_PROP_RX.
• Generic events, defined for all radio operations and originating on the RF core. These are for instance RF_EventCmdDone and RF_EventLastCmdDone. Both events indicate the termination of one or more RF operations.
• Generic events, defined for all radio operations and originating in the RF driver, for instance RF_EventCmdCancelled.

See also

RF_Core_Events, RF_Driver_Events.

How callback events are subscribed was shown in the previous section. The following snippet shows a typical event handler callback for a proprietary RX operation:

void rxCallback(RF_Handle handle, RF_CmdHandle command, RF_EventMask events)
{
    if (events & RF_EventRxEntryDone)
    {
        Semaphore_post(rxPacketSemaphore);
    }
    if (events & RF_EventLastCmdDone)
    {
        // ...
    }
}

In addition, the RF driver can generate error and power-up events that do not relate directly to the execution of a radio command. Such events can be subscribed by specifying the callback function pointers RF_Params::pErrCb and RF_Params::pPowerCb.

All callback functions run in software interrupt (SWI) context. Therefore, only a minimum amount of code should be executed. When using absolute timed commands with tight timing constraints, then it is recommended to set the RF driver SWIs to a high priority. See Setup and configuration for more details.

---

Power management

The RF core is a hardware peripheral and can be switched on and off. The RF driver handles that automatically and provides the following power optimization features:

• Lazy power-up and radio setup caching
• Power-down on inactivity
• Deferred dispatching of commands with absolute timing

Lazy power-up and radio setup caching

The RF core optimizes the power consumption by enabling the RF core as late as possible. For instance does RF_open() not power up the RF core immediately. Instead, it waits until the first radio operation command is dispatched by RF_postCmd() or RF_runCmd().

The function RF_open() takes a radio setup command as parameter and expects a CMD_FS command to follow. The pointer to the radio setup command and the whole CMD_FS command are cached internally in the RF driver. They will be used for every proceeding power-up procedure. Whenever the client re-runs a setup command or a CMD_FS command, the driver updates its internal cache with the new settings.

By default, the RF driver measures the time that it needs for the power-up procedure and uses that as an estimate for the next power cycle. On the CC13x0/CC26x0 devices, power-up takes usually 1.6 ms. Automatic measurement can be suppressed by specifying a custom power-up time with RF_Params::nPowerUpDuration. In addition, the client might set RF_Params::nPowerUpDurationMargin to cover any uncertainty when doing automatic measurements. This is necessary in applications with a high hardware interrupt load which can delay the RF driver's internal state machine execution.

Power-down on inactivity

Whenever a radio operation completes and there is no other radio operation in the queue, the RF core might be powered down. There are two options in the RF driver:

• Automatic power-down by setting the parameter RF_Params::nInactivityTimeout. The RF core will then start a timer after the last command in the queue has completed. The default timeout is "forever" and this feature is disabled.
• Manual power-down by calling RF_yield(). The client should do this whenever it knows that no further radio operation will be executed for a couple of milliseconds.

During the power-down procedure the RF driver stops the radio timer and saves a synchronization timestamp for the next power-up. This keeps the radio timer virtually in sync with the RTC even though it is not running all the time. The synchronization is done in hardware.

Deferred dispatching of commands with absolute timing

When dispatching a radio operation command with an absolute start trigger that is ahead in the future, the RF driver defers the execution and powers the RF core down until the command is due. It does that only, when:

1. cmd.startTrigger.triggerType is set to TRIG_ABSTIME
2. The difference between RF_getCurrentTime() and cmd.startTime is at not more than 3/4 of a full RAT cycle. Otherwise the driver assumes that cmd.startTime is in the past.
3. There is enough time to run a full power cycle before cmd.startTime is due. That includes:
   • the power-down time (fixed value, 1 ms) if the RF core is already powered up,
   • the measured power-up duration or the value specified by RF_Params::nPowerUpDuration,
   • the power-up safety margin RF_Params::nPowerUpDurationMargin (the default is 282 microseconds).

If one of the conditions are not fulfilled, the RF core is kept up and running and the command is dispatched immediately. This ensures, that the command will execute on-time and not miss the configured start trigger.

---

Preemptive scheduling of RF commands in multi-client applications

Schedule BLE and proprietary radio commands.

RF_Object rfObject_ble;
RF_Object rfObject_prop;

RF_Handle rfHandle_ble, rfHandle_prop;
RF_Params rfParams_ble, rfParams_prop;
RF_ScheduleCmdParams schParams_ble, schParams_prop;

RF_Mode rfMode_ble =
{
  .rfMode      = RF_MODE_MULTIPLE,  // rfMode for dual mode
  .cpePatchFxn = &rf_patch_cpe_ble,
  .mcePatchFxn = 0,
  .rfePatchFxn = &rf_patch_rfe_ble,
};

RF_Mode rfMode_prop =
{
  .rfMode      = RF_MODE_MULTIPLE,  // rfMode for dual mode
  .cpePatchFxn = &rf_patch_cpe_genfsk,
  .mcePatchFxn = 0,
  .rfePatchFxn = 0,
};

// Init RF and specify non-default parameters
RF_Params_init(&rfParams_ble);
rfParams_ble.nInactivityTimeout = 200;     // 200us

RF_Params_init(&rfParams_prop);
rfParams_prop.nInactivityTimeout = 200;    // 200us

// Configure RF schedule command parameters directly.
schParams_ble.priority    = RF_PriorityNormal;
schParams_ble.endTime     = 0;
schParams_ble.allowDelay  = RF_AllowDelayAny;

// Alternatively, use the helper function to configure the default behavior
RF_ScheduleCmdParams_init(&schParams_prop);

// Open BLE and proprietary RF handles
rfHandle_ble  = RF_open(rfObj_ble,  &rfMode_ble,  (RF_RadioSetup*)&RF_cmdRadioSetup,        &rfParams_ble);
rfHandle_prop = RF_open(rfObj_prop, &rfMode_prop, (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams_prop);

// Run a proprietary Fs command
RF_runCmd(rfHandle_pro, (RF_Op*)&RF_cmdFs, RF_PriorityNormal, NULL, NULL);

// Schedule a proprietary RX command
RF_scheduleCmd(rfHandle_pro, (RF_Op*)&RF_cmdPropRx, &schParams_prop, &prop_callback, RF_EventRxOk);

// Schedule a BLE advertiser command
RF_scheduleCmd(rfHandle_ble, (RF_Op*)&RF_cmdBleAdv, &schParams_ble, &ble_callback,
             (RF_EventLastCmdDone | RF_EventRxEntryDone | RF_EventTxEntryDone));

Get dual mode schedule map including timing and priority information for access requests and commands.

RF_ScheduleMap rfSheduleMap;
RF_InfoVal     rfGetInfoVal;

// Get schedule map
rfGetInfoVal.pScheduleMap = &rfScheduleMap;
RF_getInfo(NULL, RF_GET_SCHEDULE_MAP, &rfGetInfoVal);

// RF_scheduleMap includes the following information:
// (RF_NUM_SCHEDULE_ACCESS_ENTRIES (default = 2)) entries of access request information
// (RF_NUM_SCHEDULE_COMMAND_ENTRIES (default = 8)) entries of radio command information
// Each entry has the type of RF_ScheduleMapElement.

---

Accessing the Radio Timer (RAT)

The Radio Timer on the RF core is an independent 32 bit timer running at a tick rate of 4 ticks per microsecond. It is only physically active while the RF core is on. But because the RF driver resynchronizes the RAT to the RTC on every power-up, it appears to the application as the timer is always running. The RAT accuracy depends on the system HF clock while the RF core is active and on the LF clock while the RF core is powered down.

The current RAT time stamp can be obtained by RF_getCurrentTime():

uint32_t now = RF_getCurrentTime();

The RAT has 8 independent channels that can be set up in capture and compare mode by RF_ratCapture() and RF_ratCompare() respectively. Three of these channels are accessible by the RF driver. Each channel may be connected to physical hardware signals for input and output or may trigger a callback function.

In order to allocate a RAT channel and trigger a callback function at a certain time stamp, use RF_ratCompare():

RF_Handle rfDriver;
RF_RatConfigCompare config;
RF_RatConfigCompare_init(&config);
config.callback = &onRatTriggered;
config.channel = RF_RatChannelAny;
config.timeout = RF_getCurrentTime() + RF_convertMsToRatTicks(1701);

RF_RatHandle ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
assert(ratHandle != RF_ALLOC_ERROR);

void onRatTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
{
    if (e & RF_EventError)
    {
        // RF driver failed to trigger the callback on time.
    }
    printf("RAT has triggered at %u.", compareCaptureTime);

    // Trigger precisely with the same period again
    config.timeout = compareCaptureTime + RF_convertMsToRatTicks(1701);
    ratHandle = RF_ratCompare(rfDriver, &config, nullptr);
    assert(ratHandle != RF_ALLOC_ERROR);
}

The RAT may be used to capture a time stamp on an edge of a physical pin. This can be achieved with RF_ratCapture().

#include <ti/drivers/pin/PINCC26XX.h>
// Map IO 26 to RFC_GPI0
PINCC26XX_setMux(pinHandle, IOID_26, PINCC26XX_MUX_RFC_GPI0);

RF_Handle rfDriver;
RF_RatConfigCapture config;
RF_RatConfigCapture_init(&config);
config.callback = &onSignalTriggered;
config.channel = RF_RatChannelAny;
config.source = RF_RatCaptureSourceRfcGpi0;
config.captureMode = RF_RatCaptureModeRising;
config.repeat = RF_RatCaptureRepeat;

RF_RatHandle ratHandle = RF_ratCapture(rfDriver, &config, nullptr);
assert(ratHandle != RF_ALLOC_ERROR);

void onSignalTriggered(RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
{
    if (e & RF_EventError)
    {
        // An internal error has occurred
    }
    printf("Rising edge detected on IO 26 at %u.", compareCaptureTime);
}

In both cases, the RAT may generate an output signal when being triggered. The signal can be routed to a physical IO pin:

// Generate a pulse on an internal RAT output signal
RF_RatConfigOutput output;
RF_RatConfigOutput_init(&output);
output.mode = RF_RatOutputModePulse;
output.select = RF_RatOutputSelectRatGpo3;
RF_ratCompare(...);

// Map RatGpo3 to one of four intermediate doorbell signals.
// This has to be done in the override list in order to take permanent effect.
// The override list can be found in the RF settings .c file exported from
// SmartRF Studio.
// Attention: This will change the default mapping of the PA and LNA signal as well.
#include <ti/devices/[DEVICE_FAMILY]/inc/hw_rfc_dbell.h>
static uint32_t pOverrides[] =
{
    HW_REG_OVERRIDE(0x1110, RFC_DBELL_SYSGPOCTL_GPOCTL2_RATGPO3),
    // ...
}

// Finally, route the intermediate doorbell signal to a physical pin.
#include <ti/drivers/pin/PINCC26XX.h>
PINCC26XX_setMux(pinHandle, IOID_17, PINCC26XX_MUX_RFC_GPO2);

---

Programming the TX power level

The application can program a TX power level for each RF client with the function RF_setTxPower(). The new value takes immediate effect if the RF core is up and running. Otherwise, it is stored in the RF driver client configuration.

TX power may be stored in a lookup table in ascending order. This table is usually generated and exported from SmartRF Studio together with the rest of the PHY configuration. A typical power table my look as follows:

RF_TxPowerTable_Entry txPowerTable[] = {
    { .power = 11,  .value = { 0x1233, RF_TxPowerTable_DefaultPA }},
    { .power = 13,  .value = { 0x1234, RF_TxPowerTable_DefaultPA }},
    // ...
    RF_TxPowerTable_TERMINATION_ENTRY
};

Note

Some devices offer a high-power PA in addition to the default PA. A client must not mix configuration values in the same power table and must not hop from a default PA configuration to a high-power PA configuration unless it can guarantee that the RF setup command is re-executed in between.

Given this power table format, the application may program a new power level in multiple ways. It can use convenience functions to search a certain power level in the power table or may access the table index-based:

// Set a certain power level. Search a matching level.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, 17));

// Set a certain power level with a known level.
RF_setTxPower(h, txPowerTable[3].value);

// Set a certain power without using a human readable level.
RF_setTxPower(h, value);

// Set maximum power. Search the value.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MAX_DBM));

// Set minimum power without searching.
RF_setTxPower(h, txPowerTable[0].value);

// Set minimum power. Search the value.
RF_setTxPower(h, RF_TxPowerTable_findValue(txPowerTable, RF_TxPowerTable_MIN_DBM));

// Set maximum power without searching.
int32_t lastIndex = sizeof(txPowerTable) / sizeof(RF_TxPowerTable_Entry) - 2;
RF_setTxPower(h, txPowerTable[lastIndex].value);

The current configured power level for a client can be retrieved by RF_getTxPower().

// Get the current configured power level.
int8_t power = RF_TxPowerTable_findPowerLevel(txPowerTable, RF_getTxPower(h));

---

Convenience features

The RF driver simplifies often needed tasks and provides additional functions. For instance, it can read the RSSI while the RF core is in RX mode using the function :tidrivers_api:RF_getRssi:

int8_t rssi = RF_getRssi(rfHandle);
assert (rssi != RF_GET_RSSI_ERROR_VAL); // Could not read the RSSI

---

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/utils/List.h>
#include <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(driverlib/rf_common_cmd.h)>
#include <DeviceFamily_constructPath(driverlib/rf_prop_cmd.h)>
#include <DeviceFamily_constructPath(driverlib/rf_ble_cmd.h)>

Include dependency graph for RF.h:

Go to the source code of this file.

Data Structures
struct	RF_TxPowerTable_Value
	PA configuration value for a certain power level. More...
struct	RF_TxPowerTable_Entry
	TX power configuration entry in a TX power table. More...
struct	RF_Mode
	Specifies a RF core firmware configuration. More...
union	RF_RadioSetup
	A unified type for radio setup commands of different PHYs. More...
union	RF_InfoVal
	Stores output parameters for RF_getInfo(). More...
struct	RF_ScheduleMapElement
	RF schedule map entry structure. More...
struct	RF_ScheduleMap
	RF schedule map structure. More...
struct	RF_Params
	RF driver configuration parameters. More...
struct	RF_Cmd_s
struct	RFCC26XX_HWAttrsV2
	RF Hardware attributes. More...
struct	RFCC26XX_SchedulerPolicy
	RF scheduler policy. More...
struct	RF_ScheduleCmdParams
struct	RF_AccessParams
	RF request access parameter struct. More...
struct	RF_RatConfigCapture
	RF_ratCapture parameter structure. More...
struct	RF_RatConfigCompare
	RF_ratCompare parameter structure. More...
struct	RF_RatConfigOutput
	RAT related IO parameter structure. More...

Macros
RF Core Events
Events originating on the RF core and caused during command execution. They are aliases for the corresponding interrupt flags. RF Core Events are command-specific and are explained in the Technical Reference Manual. See also RF_postCmd(), RF_pendCmd(), RF_runCmd()
#define	RF_EventCmdDone   (1 << 0)
	A radio operation command in a chain finished. More...
#define	RF_EventLastCmdDone   (1 << 1)
	A stand-alone radio operation command or the last radio operation command in a chain finished. More...
#define	RF_EventFGCmdDone   (1 << 2)
	A IEEE-mode radio operation command in a chain finished. More...
#define	RF_EventLastFGCmdDone   (1 << 3)
	A stand-alone IEEE-mode radio operation command or the last command in a chain finished. More...
#define	RF_EventTxDone   (1 << 4)
	Packet transmitted. More...
#define	RF_EventTXAck   (1 << 5)
	ACK packet transmitted. More...
#define	RF_EventTxCtrl   (1 << 6)
	Control packet transmitted. More...
#define	RF_EventTxCtrlAck   (1 << 7)
	Acknowledgement received on a transmitted control packet. More...
#define	RF_EventTxCtrlAckAck   (1 << 8)
	Acknowledgement received on a transmitted control packet, and acknowledgement transmitted for that packet. More...
#define	RF_EventTxRetrans   (1 << 9)
	Packet retransmitted. More...
#define	RF_EventTxEntryDone   (1 << 10)
	Tx queue data entry state changed to Finished. More...
#define	RF_EventTxBufferChange   (1 << 11)
	A buffer change is complete. More...
#define	RF_EventPaChanged   (1 << 14)
	The PA was reconfigured on the fly. More...
#define	RF_EventRxOk   (1 << 16)
	Packet received with CRC OK, payload, and not to be ignored. More...
#define	RF_EventRxNOk   (1 << 17)
	Packet received with CRC error. More...
#define	RF_EventRxIgnored   (1 << 18)
	Packet received with CRC OK, but to be ignored. More...
#define	RF_EventRxEmpty   (1 << 19)
	Packet received with CRC OK, not to be ignored, no payload. More...
#define	RF_EventRxCtrl   (1 << 20)
	Control packet received with CRC OK, not to be ignored. More...
#define	RF_EventRxCtrlAck   (1 << 21)
	Control packet received with CRC OK, not to be ignored, then ACK sent. More...
#define	RF_EventRxBufFull   (1 << 22)
	Packet received that did not fit in the Rx queue. More...
#define	RF_EventRxEntryDone   (1 << 23)
	Rx queue data entry changing state to Finished. More...
#define	RF_EventDataWritten   (1 << 24)
	Data written to partial read Rx buffer. More...
#define	RF_EventNDataWritten   (1 << 25)
	Specified number of bytes written to partial read Rx buffer. More...
#define	RF_EventRxAborted   (1 << 26)
	Packet reception stopped before packet was done. More...
#define	RF_EventRxCollisionDetected   (1 << 27)
	A collision was indicated during packet reception. More...
#define	RF_EventModulesUnlocked   (1 << 29)
	As part of the boot process, the CM0 has opened access to RF core modules and memories. More...
#define	RF_EventInternalError   (uint32_t)(1 << 31)
	Internal error observed. More...
#define	RF_EventMdmSoft   0x0000002000000000
	Synchronization word detected (MDMSOFT interrupt flag) More...
RF Driver Events
Event flags generated by the RF Driver.
#define	RF_EventCmdCancelled   0x1000000000000000
	Command canceled before it was started. More...
#define	RF_EventCmdAborted   0x2000000000000000
	Abrupt command termination caused by RF_cancelCmd() or RF_flushCmd(). More...
#define	RF_EventCmdStopped   0x4000000000000000
	Graceful command termination caused by RF_cancelCmd() or RF_flushCmd(). More...
#define	RF_EventRatCh   0x0800000000000000
	A user-programmable RAT channel triggered an event. More...
#define	RF_EventPowerUp   0x0400000000000000
	RF power up event. More...
#define	RF_EventError   0x0200000000000000
	Event flag used for error callback functions to indicate an error. See RF_Params::pErrCb. More...
#define	RF_EventCmdPreempted   0x0100000000000000
	Command preempted by another command with higher priority. Applies only to multi-client applications. More...
Control codes for driver configuration
Control codes are used in RF_control().
#define	RF_CTRL_SET_INACTIVITY_TIMEOUT   0
	Control code used by RF_control to set inactivity timeout. More...
#define	RF_CTRL_UPDATE_SETUP_CMD   1
	Control code used by RF_control to update setup command. More...
#define	RF_CTRL_SET_POWERUP_DURATION_MARGIN   2
	Control code used by RF_control to set powerup duration margin. More...
#define	RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN   3
	Control code used by RF_control to set the phy switching margin. More...
#define	RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL   4
	Control code used by RF_control to set max error tolerance for RAT/RTC. More...
#define	RF_CTRL_SET_POWER_MGMT   5
	Control code used by RF_control to set power management. More...
#define	RF_CTRL_SET_HWI_PRIORITY   6
	Control code used by RF_control to set the hardware interrupt priority level of the RF driver. More...
#define	RF_CTRL_SET_SWI_PRIORITY   7
	Control code used by RF_control to set the software interrupt priority level of the RF driver. More...
#define	RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK   8
	Control code used by RF_control to mask the available RAT channels manually. More...
TX Power Table defines
#define	RF_TxPowerTable_MIN_DBM   -128
#define	RF_TxPowerTable_MAX_DBM   126
#define	RF_TxPowerTable_INVALID_DBM   127
#define	RF_TxPowerTable_INVALID_VALUE   0x3fffff
#define	RF_TxPowerTable_TERMINATION_ENTRY   { .power = RF_TxPowerTable_INVALID_DBM, .value = { .rawValue = RF_TxPowerTable_INVALID_VALUE, .paType = RF_TxPowerTable_DefaultPA } }
#define	RF_TxPowerTable_DEFAULT_PA_ENTRY(bias, gain, boost, coefficient)   { .rawValue = ((bias) << 0) | ((gain) << 6) | ((boost) << 8) | ((coefficient) << 9), .paType = RF_TxPowerTable_DefaultPA }
#define	RF_TxPowerTable_HIGH_PA_ENTRY(bias, ibboost, boost, coefficient, ldotrim)   { .rawValue = ((bias) << 0) | ((ibboost) << 6) | ((boost) << 8) | ((coefficient) << 9) | ((ldotrim) << 16), .paType = RF_TxPowerTable_HighPA }
Other defines
#define	RF_GET_RSSI_ERROR_VAL   (-128)
	Error return value for RF_getRssi() More...
#define	RF_CMDHANDLE_FLUSH_ALL   (-1)
	RF command handle to flush all RF commands. More...
#define	RF_ALLOC_ERROR   (-2)
	RF command or RAT channel allocation error. More...
#define	RF_SCHEDULE_CMD_ERROR   (-3)
	RF command schedule error. More...
#define	RF_ERROR_RAT_PROG   (-255)
	A rat channel could not be programmed. More...
#define	RF_ERROR_INVALID_RFMODE   (-256)
	Invalid RF_Mode. Used in error callback. More...
#define	RF_ERROR_CMDFS_SYNTH_PROG   (-257)
	Synthesizer error with CMD_FS. Used in error callback. If this error occurred in error callback, user needs to resend CMD_FS to recover. See the device's errata for more details. More...
#define	RF_NUM_SCHEDULE_ACCESS_ENTRIES   2
	Number of access request entries. More...
#define	RF_NUM_SCHEDULE_COMMAND_ENTRIES   8
	Number of scheduled command entries. More...
#define	RF_NUM_SCHEDULE_MAP_ENTRIES   (RF_NUM_SCHEDULE_ACCESS_ENTRIES + RF_NUM_SCHEDULE_COMMAND_ENTRIES)
	Number of schedule map entries. This is the sum of access request and scheduled command entries. More...
#define	RF_SCH_MAP_CURRENT_CMD_OFFSET   RF_NUM_SCHEDULE_ACCESS_ENTRIES
	Offset of the current command entry in the schedule map. More...
#define	RF_SCH_MAP_PENDING_CMD_OFFSET   (RF_SCH_MAP_CURRENT_CMD_OFFSET + 2)
	Offset of the first pending command entry in the schedule map. More...
#define	RF_ABORT_PREEMPTION   (1<<2)
	Used with RF_cancelCmd() to provoke subscription to RadioFreeCallback. More...
#define	RF_ABORT_GRACEFULLY   (1<<0)
	Used with RF_cancelCmd() for graceful command termination. More...
#define	RF_SCH_CMD_EXECUTION_TIME_UNKNOWN   0
	For unknown execution time for RF scheduler. More...
#define	RF_RAT_ANY_CHANNEL   (-1)
	To be used within the channel configuration structure. Allocate any of the available channels. More...
#define	RF_RAT_TICKS_PER_US   4
	Radio timer (RAT) ticks per microsecond. More...
#define	RF_LODIVIDER_MASK   0x7F
	Mask to be used to determine the effective value of the setup command's loDivider field. More...
#define	RF_convertUsToRatTicks(microseconds)   ((microseconds) * (RF_RAT_TICKS_PER_US))
	Converts a duration given in microseconds into radio timer (RAT) ticks. More...
#define	RF_convertMsToRatTicks(milliseconds)   ((milliseconds) * 1000 * (RF_RAT_TICKS_PER_US))
	Converts a duration given in milliseconds into radio timer (RAT) ticks. More...
#define	RF_convertRatTicksToUs(ticks)   ((ticks) / (RF_RAT_TICKS_PER_US))
	Converts a duration given in radio timer (RAT) ticks into microseconds. More...
#define	RF_convertRatTicksToMs(ticks)   ((ticks) / (1000 * (RF_RAT_TICKS_PER_US)))
	Converts a duration given in radio timer (RAT) ticks into milliseconds. More...

Typedefs
typedef rfc_radioOp_t	RF_Op
	Base type for all radio operation commands. More...
typedef uint64_t	RF_EventMask
	Data type for events during command execution. More...
typedef uint32_t	RF_ClientEventMask
	Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask. More...
typedef uint32_t	RF_GlobalEventMask
	Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask. More...
typedef int16_t	RF_CmdHandle
	Command handle that is returned by RF_postCmd(). More...
typedef RF_Object *	RF_Handle
	A handle that is returned by to RF_open(). More...
typedef int8_t	RF_RatHandle
	RAT handle that is returned by RF_ratCompare() or RF_ratCapture(). More...
typedef void(*	RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e)
	Handles events related to RF command execution. More...
typedef void(*	RF_RatCallback) (RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)
	Handles events related to the Radio Timer (RAT). More...
typedef void(*	RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg)
	Handles events related to a driver instance. More...
typedef void(*	RF_GlobalCallback) (RF_Handle h, RF_GlobalEvent event, void *arg)
	Handles global events as part of PHY configuration. More...
typedef struct RF_Cmd_s	RF_Cmd
typedef RF_ScheduleStatus(*	RF_SubmitHook) (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
	Handles the queue sorting algorithm when a new command is submitted to the driver from any of the active clients. More...
typedef RF_Conflict(*	RF_ConflictHook) (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
	Defines the conflict resolution in runtime. More...

Enumerations
enum	RF_TxPowerTable_PAType { RF_TxPowerTable_DefaultPA = 0, RF_TxPowerTable_HighPA = 1 }
	Selects a power amplifier path in a TX power value. More...
enum	RF_Priority { RF_PriorityHighest = 2, RF_PriorityHigh = 1, RF_PriorityNormal = 0 }
	Scheduling priority of RF operation commands. More...
enum	RF_Stat {   RF_StatBusyError, RF_StatRadioInactiveError, RF_StatCmdDoneError, RF_StatInvalidParamsError,   RF_StatCmdEnded, RF_StatError = 0x80, RF_StatCmdDoneSuccess, RF_StatCmdSch,   RF_StatSuccess }
	Status codes for various RF driver functions. More...
enum	RF_ClientEvent { RF_ClientEventPowerUpFinished = (1 << 0), RF_ClientEventRadioFree = (1 << 1), RF_ClientEventSwitchClientEntered = (1 << 2) }
	Client-related RF driver events. More...
enum	RF_GlobalEvent { RF_GlobalEventRadioSetup = (1 << 0), RF_GlobalEventRadioPowerDown = (1 << 1) }
	Global RF driver events. More...
enum	RF_InfoType {   RF_GET_CURR_CMD, RF_GET_AVAIL_RAT_CH, RF_GET_RADIO_STATE, RF_GET_SCHEDULE_MAP,   RF_GET_CLIENT_LIST, RF_GET_CLIENT_SWITCHING_TIME }
	Selects the entry of interest in RF_getInfo(). More...
enum	RF_Conflict { RF_ConflictNone = 0, RF_ConflictReject = 1, RF_ConflictAbort = 2 }
	Controls the behavior of the state machine of the RF driver when a conflict is identified run-time between the commands waiting on the pend queue and the commands being actively executed by the radio. More...
enum	RF_ScheduleStatus {   RF_ScheduleStatusError = -3, RF_ScheduleStatusNone = 0, RF_ScheduleStatusTop = 1, RF_ScheduleStatusMiddle = 2,   RF_ScheduleStatusTail = 4, RF_ScheduleStatusPreempt = 8 }
	Describes the location within the pend queue where the new command was inserted by the scheduler. More...
enum	RF_AllowDelay { RF_AllowDelayNone = 0, RF_AllowDelayAny = UINT32_MAX }
	Controls the behavior of the RF_scheduleCmd() API. More...
enum	RF_RatSelectChannel { RF_RatChannelAny = -1, RF_RatChannel0 = 0, RF_RatChannel1 = 1, RF_RatChannel2 = 2 }
	Select the preferred RAT channel through the configuration of RF_ratCompare() or RF_ratCapture(). More...
enum	RF_RatCaptureSource { RF_RatCaptureSourceRtcUpdate = 20, RF_RatCaptureSourceEventGeneric = 21, RF_RatCaptureSourceRfcGpi0 = 22, RF_RatCaptureSourceRfcGpi1 = 23 }
	Selects the source signal for RF_ratCapture(). More...
enum	RF_RatCaptureMode { RF_RatCaptureModeRising = 0, RF_RatCaptureModeFalling = 1, RF_RatCaptureModeBoth = 2 }
	Selects the mode of RF_ratCapture(). More...
enum	RF_RatCaptureRepetition { RF_RatCaptureSingle = 0, RF_RatCaptureRepeat = 1 }
	Selects the repetition of RF_ratCapture(). More...
enum	RF_RatOutputMode {   RF_RatOutputModePulse = 0, RF_RatOutputModeSet = 1, RF_RatOutputModeClear = 2, RF_RatOutputModeToggle = 3,   RF_RatOutputModeAlwaysZero = 4, RF_RatOutputModeAlwaysOne = 5 }
	Selects the mode of the RAT_GPO[x] for RF_ratCompare() or RF_ratCapture(). More...
enum	RF_RatOutputSelect {   RF_RatOutputSelectRatGpo1 = 1, RF_RatOutputSelectRatGpo2 = 2, RF_RatOutputSelectRatGpo3 = 3, RF_RatOutputSelectRatGpo4 = 4,   RF_RatOutputSelectRatGpo5 = 5, RF_RatOutputSelectRatGpo6 = 6, RF_RatOutputSelectRatGpo7 = 7 }
	Selects GPO to be used with RF_ratCompare() or RF_ratCapture(). More...

Functions
RF_Handle	RF_open (RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pRadioSetup, RF_Params *params)
	Creates a a new client instance of the RF driver. More...
void	RF_close (RF_Handle h)
	Close client connection to RF driver. More...
uint32_t	RF_getCurrentTime (void)
	Return current radio timer value. More...
RF_CmdHandle	RF_postCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
	Appends RF operation commands to the driver's command queue and returns a command handle. More...
RF_ScheduleStatus	RF_defaultSubmitPolicy (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
	Sorts and adds commands to the RF driver internal command queue. More...
RF_Conflict	RF_defaultConflictPolicy (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)
	Makes a final decision when a conflict in run-time is identified. More...
void	RF_ScheduleCmdParams_init (RF_ScheduleCmdParams *pSchParams)
	Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API. More...
RF_CmdHandle	RF_scheduleCmd (RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
	Schedule an RF operation (chain) to the command queue. More...
RF_EventMask	RF_pendCmd (RF_Handle h, RF_CmdHandle ch, RF_EventMask bmEvent)
	Synchronizes the calling task to an RF operation command ch and returns accumulated event flags. More...
RF_EventMask	RF_runCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent)
	Runs synchronously an RF operation command or a chain of commands and returns the termination reason. More...
RF_EventMask	RF_runScheduleCmd (RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent)
	Runs synchronously a (chain of) RF operation(s) for dual or single-mode. More...
RF_Stat	RF_cancelCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
	Abort/stop/cancel single command in command queue. More...
RF_Stat	RF_flushCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode)
	Abort/stop/cancel command and any subsequent commands in command queue. More...
RF_Stat	RF_runImmediateCmd (RF_Handle h, uint32_t *pCmdStruct)
	Send any Immediate command. More...
RF_Stat	RF_runDirectCmd (RF_Handle h, uint32_t cmd)
	Send any Direct command. More...
void	RF_yield (RF_Handle h)
	Signal that radio client is not going to issue more commands in a while. More...
void	RF_Params_init (RF_Params *params)
	Function to initialize the RF_Params struct to its defaults. More...
RF_Stat	RF_getInfo (RF_Handle h, RF_InfoType type, RF_InfoVal *pValue)
	Get value for some RF driver parameters. More...
int8_t	RF_getRssi (RF_Handle h)
	Get RSSI value. More...
RF_Op *	RF_getCmdOp (RF_Handle h, RF_CmdHandle cmdHnd)
	Get command structure pointer. More...
void	RF_RatConfigCompare_init (RF_RatConfigCompare *channelConfig)
	Initialize the configuration structure to be used to set up a RAT compare event. More...
void	RF_RatConfigCapture_init (RF_RatConfigCapture *channelConfig)
	Initialize the configuration structure to be used to set up a RAT capture event. More...
void	RF_RatConfigOutput_init (RF_RatConfigOutput *ioConfig)
	Initialize the configuration structure to be used to set up a RAT IO. More...
RF_RatHandle	RF_ratCompare (RF_Handle rfHandle, RF_RatConfigCompare *channelConfig, RF_RatConfigOutput *ioConfig)
	Setup a Radio Timer (RAT) channel in compare mode. More...
RF_RatHandle	RF_ratCapture (RF_Handle rfHandle, RF_RatConfigCapture *channelConfig, RF_RatConfigOutput *ioConfig)
	Setup a Radio Timer (RAT) channel in capture mode. More...
RF_Stat	RF_ratDisableChannel (RF_Handle rfHandle, RF_RatHandle ratHandle)
	Disable a RAT channel. More...
RF_Stat	RF_control (RF_Handle h, int8_t ctrl, void *args)
	Set RF control parameters. More...
RF_Stat	RF_requestAccess (RF_Handle h, RF_AccessParams *pParams)
	Request radio access. More...
RF_TxPowerTable_Value	RF_getTxPower (RF_Handle h)
	Returns the currently configured transmit power configuration. More...
RF_Stat	RF_setTxPower (RF_Handle h, RF_TxPowerTable_Value value)
	Updates the transmit power configuration of the RF core. More...
int8_t	RF_TxPowerTable_findPowerLevel (RF_TxPowerTable_Entry table[], RF_TxPowerTable_Value value)
	Retrieves a power level in dBm for a given power configuration value. More...
RF_TxPowerTable_Value	RF_TxPowerTable_findValue (RF_TxPowerTable_Entry table[], int8_t powerLevel)
	Retrieves a power configuration value for a given power level in dBm. More...

Macro Definition Documentation

RF_EventCmdDone

#define RF_EventCmdDone   (1 << 0)

A radio operation command in a chain finished.

RF_EventLastCmdDone

#define RF_EventLastCmdDone   (1 << 1)

A stand-alone radio operation command or the last radio operation command in a chain finished.

RF_EventFGCmdDone

#define RF_EventFGCmdDone   (1 << 2)

A IEEE-mode radio operation command in a chain finished.

RF_EventLastFGCmdDone

#define RF_EventLastFGCmdDone   (1 << 3)

A stand-alone IEEE-mode radio operation command or the last command in a chain finished.

RF_EventTxDone

#define RF_EventTxDone   (1 << 4)

Packet transmitted.

RF_EventTXAck

#define RF_EventTXAck   (1 << 5)

ACK packet transmitted.

RF_EventTxCtrl

#define RF_EventTxCtrl   (1 << 6)

Control packet transmitted.

RF_EventTxCtrlAck

#define RF_EventTxCtrlAck   (1 << 7)

Acknowledgement received on a transmitted control packet.

RF_EventTxCtrlAckAck

#define RF_EventTxCtrlAckAck   (1 << 8)

Acknowledgement received on a transmitted control packet, and acknowledgement transmitted for that packet.

RF_EventTxRetrans

#define RF_EventTxRetrans   (1 << 9)

Packet retransmitted.

RF_EventTxEntryDone

#define RF_EventTxEntryDone   (1 << 10)

Tx queue data entry state changed to Finished.

RF_EventTxBufferChange

#define RF_EventTxBufferChange   (1 << 11)

A buffer change is complete.

RF_EventPaChanged

#define RF_EventPaChanged   (1 << 14)

The PA was reconfigured on the fly.

RF_EventRxOk

#define RF_EventRxOk   (1 << 16)

Packet received with CRC OK, payload, and not to be ignored.

RF_EventRxNOk

#define RF_EventRxNOk   (1 << 17)

Packet received with CRC error.

RF_EventRxIgnored

#define RF_EventRxIgnored   (1 << 18)

Packet received with CRC OK, but to be ignored.

RF_EventRxEmpty

#define RF_EventRxEmpty   (1 << 19)

Packet received with CRC OK, not to be ignored, no payload.

RF_EventRxCtrl

#define RF_EventRxCtrl   (1 << 20)

Control packet received with CRC OK, not to be ignored.

RF_EventRxCtrlAck

#define RF_EventRxCtrlAck   (1 << 21)

Control packet received with CRC OK, not to be ignored, then ACK sent.

RF_EventRxBufFull

#define RF_EventRxBufFull   (1 << 22)

Packet received that did not fit in the Rx queue.

RF_EventRxEntryDone

#define RF_EventRxEntryDone   (1 << 23)

Rx queue data entry changing state to Finished.

RF_EventDataWritten

#define RF_EventDataWritten   (1 << 24)

Data written to partial read Rx buffer.

RF_EventNDataWritten

#define RF_EventNDataWritten   (1 << 25)

Specified number of bytes written to partial read Rx buffer.

RF_EventRxAborted

#define RF_EventRxAborted   (1 << 26)

Packet reception stopped before packet was done.

RF_EventRxCollisionDetected

#define RF_EventRxCollisionDetected   (1 << 27)

A collision was indicated during packet reception.

RF_EventModulesUnlocked

#define RF_EventModulesUnlocked   (1 << 29)

As part of the boot process, the CM0 has opened access to RF core modules and memories.

RF_EventInternalError

#define RF_EventInternalError   (uint32_t)(1 << 31)

Internal error observed.

RF_EventMdmSoft

#define RF_EventMdmSoft   0x0000002000000000

Synchronization word detected (MDMSOFT interrupt flag)

RF_EventCmdCancelled

#define RF_EventCmdCancelled   0x1000000000000000

Command canceled before it was started.

RF_EventCmdAborted

#define RF_EventCmdAborted   0x2000000000000000

Abrupt command termination caused by RF_cancelCmd() or RF_flushCmd().

RF_EventCmdStopped

#define RF_EventCmdStopped   0x4000000000000000

Graceful command termination caused by RF_cancelCmd() or RF_flushCmd().

RF_EventRatCh

#define RF_EventRatCh   0x0800000000000000

A user-programmable RAT channel triggered an event.

RF_EventPowerUp

#define RF_EventPowerUp   0x0400000000000000

RF power up event.

Deprecated:

This event is deprecated. Use RF_ClientEventPowerUpFinished instead.

RF_EventError

#define RF_EventError   0x0200000000000000

Event flag used for error callback functions to indicate an error. See RF_Params::pErrCb.

RF_EventCmdPreempted

#define RF_EventCmdPreempted   0x0100000000000000

Command preempted by another command with higher priority. Applies only to multi-client applications.

RF_CTRL_SET_INACTIVITY_TIMEOUT

#define RF_CTRL_SET_INACTIVITY_TIMEOUT   0

Control code used by RF_control to set inactivity timeout.

Setting this control allows RF to power down the radio upon completion of a radio command after a specified timeout period (in us) With this control code arg is a pointer to the timeout variable and returns RF_StatSuccess.

RF_CTRL_UPDATE_SETUP_CMD

#define RF_CTRL_UPDATE_SETUP_CMD   1

Control code used by RF_control to update setup command.

Setting this control notifies RF that the setup command is to be updated, so that RF will take proper actions when executing the next setup command. Note the updated setup command will take effect in the next power up cycle when RF executes the setup command. Prior to updating the setup command, user should make sure all pending commands have completed.

RF_CTRL_SET_POWERUP_DURATION_MARGIN

#define RF_CTRL_SET_POWERUP_DURATION_MARGIN   2

Control code used by RF_control to set powerup duration margin.

Setting this control updates the powerup duration margin. Default is RF_DEFAULT_POWER_UP_MARGIN.

RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN

#define RF_CTRL_SET_PHYSWITCHING_DURATION_MARGIN   3

Control code used by RF_control to set the phy switching margin.

Setting this control updates the phy switching duration margin, which is used to calculate when run-time conflicts shall be evaluated in case of colliding radio operations issued from two different clients. Default is RF_DEFAULT_PHY_SWITCHING_MARGIN.

RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL

#define RF_CTRL_SET_RAT_RTC_ERR_TOL_VAL   4

Control code used by RF_control to set max error tolerance for RAT/RTC.

Setting this control updates the error tol for how frequently the CMD_RAT_SYNC_STOP is sent. Default is RF_DEFAULT_RAT_RTC_ERR_TOL_IN_US (5 us) Client is recommeneded to change this setting before sending any commands.

RF_CTRL_SET_POWER_MGMT

#define RF_CTRL_SET_POWER_MGMT   5

Control code used by RF_control to set power management.

Setting this control configures RF driver to enable or disable power management. By default power management is enabled. If disabled, once RF core wakes up, RF driver will not go to standby and will not power down RF core. To configure power management, use this control to pass a parameter value of 0 to disable power management, and pass a parameter value of 1 to re-enable power management. This control is valid for dual-mode code only. Setting this control when using single-mode code has no effect (power management always enabled).

RF_CTRL_SET_HWI_PRIORITY

#define RF_CTRL_SET_HWI_PRIORITY   6

Control code used by RF_control to set the hardware interrupt priority level of the RF driver.

This control code sets the hardware interrupt priority level that is used by the RF driver. Valid values are INT_PRI_LEVEL1 (highest) until INT_PRI_LEVEL7 (lowest). The default interrupt priority is set in the board support file. The default value is -1 which means "lowest possible priority".

When using the TI-RTOS kernel, INT_PRI_LEVEL0 is reserved for zero-latency interrupts and must not be used.

Execute this control code only while the RF core is powered down and the RF driver command queue is empty. This is usually the case after calling RF_open(). Changing the interrupt priority level while the RF driver is active will result in RF_StatBusyError being returned.

Example:

#include DeviceFamily_constructPath(driverlib/interrupt.h)

int32_t hwiPriority = INT_PRI_LEVEL5;
RF_control(rfHandle, RF_CTRL_SET_HWI_PRIORITY, &hwiPriority);

RF_CTRL_SET_SWI_PRIORITY

#define RF_CTRL_SET_SWI_PRIORITY   7

Control code used by RF_control to set the software interrupt priority level of the RF driver.

This control code sets the software interrupt priority level that is used by the RF driver. Valid values are integers starting at 0 (lowest) until Swi_numPriorities - 1 (highest). The default interrupt priority is set in the board support file. The default value is 0 which means means "lowest possible priority".

Execute this control code only while the RF core is powered down and the RF driver command queue is empty. This is usually the case after calling RF_open(). Changing the interrupt priority level while the RF driver is active will result in RF_StatBusyError being returned.

Example:

#include <ti/sysbios/knl/Swi.h>

// Set highest possible priority
uint32_t swiPriority = ~0;
RF_control(rfHandle, RF_CTRL_SET_SWI_PRIORITY, &swiPriority);

RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK

#define RF_CTRL_SET_AVAILABLE_RAT_CHANNELS_MASK   8

Control code used by RF_control to mask the available RAT channels manually.

This control code can be used to manually disallow/allow access to certain RAT channels from the RAT APIs. A typical use case is when a RAT channel is programmed through chained radio operations, and hence is used outside the scope of the RF driver. By disallowing access to this channel one can prevent collision between the automatic channel allocation through RF_ratCompare()/RF_ratCapture() and the direct configuration through RF_postCmd().

RF_TxPowerTable_MIN_DBM

#define RF_TxPowerTable_MIN_DBM   -128

Refers to the the minimum available power in dBm when accessing a power table.

See also

RF_TxPowerTable_findValue()

RF_TxPowerTable_MAX_DBM

#define RF_TxPowerTable_MAX_DBM   126

Refers to the the maximum available power in dBm when accessing a power table.

See also

RF_TxPowerTable_findValue()

RF_TxPowerTable_INVALID_DBM

#define RF_TxPowerTable_INVALID_DBM   127

Refers to an invalid power level in a TX power table.

See also

RF_TxPowerTable_findPowerLevel()

RF_TxPowerTable_INVALID_VALUE

#define RF_TxPowerTable_INVALID_VALUE   0x3fffff

Refers to an invalid power value in a TX power table.

This is the raw value part of a TX power configuration. In order to check whether a given power configuration is valid, do:

RF_TxPowerTable_Value value = ...;
if (value.rawValue == RF_TxPowerTable_INVALID_VALUE) {
    // error, value not valid
}

A TX power table is always terminated by an invalid power configuration.

See also

RF_getTxPower(), RF_TxPowerTable_findValue

RF_TxPowerTable_TERMINATION_ENTRY

#define RF_TxPowerTable_TERMINATION_ENTRY   { .power = RF_TxPowerTable_INVALID_DBM, .value = { .rawValue = RF_TxPowerTable_INVALID_VALUE, .paType = RF_TxPowerTable_DefaultPA } }

Marks the last entry in a TX power table.

In order to use RF_TxPowerTable_findValue() and RF_TxPowerTable_findPowerLevel(), every power table must be terminated by a RF_TxPowerTable_TERMINATION_ENTRY:

RF_TxPowerTable_Entry txPowerTable[] =
{
    { 20,  RF_TxPowerTable_HIGH_PA_ENTRY(1, 2, 3) },
    // ... ,
    RF_TxPowerTable_TERMINATION_ENTRY
};

RF_TxPowerTable_DEFAULT_PA_ENTRY

#define RF_TxPowerTable_DEFAULT_PA_ENTRY	(		bias,
			gain,
			boost,
			coefficient
	)		{ .rawValue = ((bias) << 0) | ((gain) << 6) | ((boost) << 8) | ((coefficient) << 9), .paType = RF_TxPowerTable_DefaultPA }

Creates a TX power table entry for the default PA.

The values for bias, gain, boost and coefficient are usually measured by Texas Instruments for a specific front-end configuration. They can then be obtained from SmartRFStudio.

RF_TxPowerTable_HIGH_PA_ENTRY

#define RF_TxPowerTable_HIGH_PA_ENTRY	(		bias,
			ibboost,
			boost,
			coefficient,
			ldotrim
	)		{ .rawValue = ((bias) << 0) | ((ibboost) << 6) | ((boost) << 8) | ((coefficient) << 9) | ((ldotrim) << 16), .paType = RF_TxPowerTable_HighPA }

Creates a TX power table entry for the High-power PA.

The values for bias, ibboost, boost, coefficient and ldoTrim are usually measured by Texas Instruments for a specific front-end configuration. They can then be obtained from SmartRFStudio.

RF_GET_RSSI_ERROR_VAL

#define RF_GET_RSSI_ERROR_VAL   (-128)

Error return value for RF_getRssi()

RF_CMDHANDLE_FLUSH_ALL

#define RF_CMDHANDLE_FLUSH_ALL   (-1)

RF command handle to flush all RF commands.

RF_ALLOC_ERROR

#define RF_ALLOC_ERROR   (-2)

RF command or RAT channel allocation error.

RF_SCHEDULE_CMD_ERROR

#define RF_SCHEDULE_CMD_ERROR   (-3)

RF command schedule error.

RF_ERROR_RAT_PROG

#define RF_ERROR_RAT_PROG   (-255)

A rat channel could not be programmed.

RF_ERROR_INVALID_RFMODE

#define RF_ERROR_INVALID_RFMODE   (-256)

Invalid RF_Mode. Used in error callback.

RF_ERROR_CMDFS_SYNTH_PROG

#define RF_ERROR_CMDFS_SYNTH_PROG   (-257)

Synthesizer error with CMD_FS. Used in error callback. If this error occurred in error callback, user needs to resend CMD_FS to recover. See the device's errata for more details.

RF_NUM_SCHEDULE_ACCESS_ENTRIES

#define RF_NUM_SCHEDULE_ACCESS_ENTRIES   2

Number of access request entries.

RF_NUM_SCHEDULE_COMMAND_ENTRIES

#define RF_NUM_SCHEDULE_COMMAND_ENTRIES   8

Number of scheduled command entries.

RF_NUM_SCHEDULE_MAP_ENTRIES

#define RF_NUM_SCHEDULE_MAP_ENTRIES   (RF_NUM_SCHEDULE_ACCESS_ENTRIES + RF_NUM_SCHEDULE_COMMAND_ENTRIES)

Number of schedule map entries. This is the sum of access request and scheduled command entries.

RF_SCH_MAP_CURRENT_CMD_OFFSET

#define RF_SCH_MAP_CURRENT_CMD_OFFSET   RF_NUM_SCHEDULE_ACCESS_ENTRIES

Offset of the current command entry in the schedule map.

RF_SCH_MAP_PENDING_CMD_OFFSET

#define RF_SCH_MAP_PENDING_CMD_OFFSET   (RF_SCH_MAP_CURRENT_CMD_OFFSET + 2)

Offset of the first pending command entry in the schedule map.

RF_ABORT_PREEMPTION

#define RF_ABORT_PREEMPTION   (1<<2)

Used with RF_cancelCmd() to provoke subscription to RadioFreeCallback.

RF_ABORT_GRACEFULLY

#define RF_ABORT_GRACEFULLY   (1<<0)

Used with RF_cancelCmd() for graceful command termination.

RF_SCH_CMD_EXECUTION_TIME_UNKNOWN

#define RF_SCH_CMD_EXECUTION_TIME_UNKNOWN   0

For unknown execution time for RF scheduler.

RF_RAT_ANY_CHANNEL

#define RF_RAT_ANY_CHANNEL   (-1)

To be used within the channel configuration structure. Allocate any of the available channels.

RF_RAT_TICKS_PER_US

#define RF_RAT_TICKS_PER_US   4

Radio timer (RAT) ticks per microsecond.

RF_LODIVIDER_MASK

#define RF_LODIVIDER_MASK   0x7F

Mask to be used to determine the effective value of the setup command's loDivider field.

RF_convertUsToRatTicks

#define RF_convertUsToRatTicks

(

microseconds

)

((microseconds) * (RF_RAT_TICKS_PER_US))

Converts a duration given in microseconds into radio timer (RAT) ticks.

RF_convertMsToRatTicks

#define RF_convertMsToRatTicks

(

milliseconds

)

((milliseconds) * 1000 * (RF_RAT_TICKS_PER_US))

Converts a duration given in milliseconds into radio timer (RAT) ticks.

RF_convertRatTicksToUs

#define RF_convertRatTicksToUs

(

ticks

)

((ticks) / (RF_RAT_TICKS_PER_US))

Converts a duration given in radio timer (RAT) ticks into microseconds.

RF_convertRatTicksToMs

#define RF_convertRatTicksToMs

(

ticks

)

((ticks) / (1000 * (RF_RAT_TICKS_PER_US)))

Converts a duration given in radio timer (RAT) ticks into milliseconds.

Typedef Documentation

RF_Op

typedef rfc_radioOp_t RF_Op

Base type for all radio operation commands.

All radio operation commands share a common part. That includes the command id, a status field, chaining properties and a start trigger. Whenever an RF operation command is used with the RF driver, it needs to be casted to an RF_Op.

More information about RF operation commands can be found in the Proprietary RF User's Guide.

See also

RF_runCmd(), RF_postCmd(), RF_pendCmd()

RF_EventMask

typedef uint64_t RF_EventMask

Data type for events during command execution.

Possible event flags are listed in RF_Core_Events and RF_Driver_Events.

RF_ClientEventMask

typedef uint32_t RF_ClientEventMask

Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask.

RF_GlobalEventMask

typedef uint32_t RF_GlobalEventMask

Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask.

RF_CmdHandle

typedef int16_t RF_CmdHandle

Command handle that is returned by RF_postCmd().

A command handle is an integer number greater equals zero and identifies a command container in the RF driver's internal command queue. A client can dispatch a command with RF_postCmd() and use the command handle later on to make the RF driver interact with the command.

A negative value has either a special meaning or indicates an error.

See also

RF_pendCmd(), RF_flushCmd(), RF_cancelCmd(), RF_ALLOC_ERROR, RF_CMDHANDLE_FLUSH_ALL

RF_Handle

typedef RF_Object* RF_Handle

A handle that is returned by to RF_open().

RF_Handle is used for further RF client interaction with the RF driver. An invalid handle has the value NULL.

RF_RatHandle

typedef int8_t RF_RatHandle

RAT handle that is returned by RF_ratCompare() or RF_ratCapture().

An RF_RatHandle is an integer number with value greater than or equal to zero and identifies a Radio Timer Channel in the RF driver's internal RAT module. A client can interact with the RAT module through the RF_ratCompare(), RF_ratCapture() or RF_ratDisableChannel() APIs.

A negative value indicates an error. A typical example when RF_ratCompare() returns with RF_ALLOC_ERROR.

RF_Callback

typedef void(* RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e)

Handles events related to RF command execution.

RF command callbacks notify the application of any events happening during RF command execution. Events may either refer to RF core interrupts (RF_Core_Events) or may be generated by the RF driver (RF_Driver_Events).

RF command callbacks are set up as parameter to RF_postCmd() or RF_runCmd() and provide:

• the relevant driver client handle h which was returned by RF_open(),
• the relevant radio operation command handle ch,
• an event mask e containing the occurred events.

RF command callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrsV2 in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().

The RF_Callback function type is also used for signaling power events and errors. These are set in RF_Params::pPowerCb and RF_Params::pErrCb respectively. In case of a power event, ch can be ignored and e has RF_EventPowerUp set. In case of an error callback, ch contains an error code instead of a command handle and e has the RF_EventError flag set.

Note

Error and power callbacks will be replaced by RF_ClientCallback in future releases.

RF_RatCallback

typedef void(* RF_RatCallback) (RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime)

Handles events related to the Radio Timer (RAT).

The RF driver provides an interface to the Radio Timer through RF_ratCompare(), RF_ratCapture() and RF_ratDisableChannel() APIs. Each API call receives an optional input argument of the type RF_RatCallback. When a timer event occurs (compare, capture or error events), the registered callback is invoked.

The RF_RatCallback provides the following argument:

• the relevant driver client handle h which was returned by RF_open(),
• the relevant rat timer handle rh which the event is caused by,
• an event mask e containing the occurred event (RF_EventRatCh or RF_EventError)
• the captured value or the compare time compareCaptureTime read from the Radio Timer channel.

RF_ClientCallback

typedef void(* RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg)

Handles events related to a driver instance.

The RF driver produces additional events that are not directly related to the execution of a certain command, but happen during general RF driver operations. This includes power-up events, client switching events and others.

A client callback provides the following arguments:

• the relevant driver client handle h which was returned by RF_open(),
• an event identifier event,
• an optional argument arg depending on the event.

RF client callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrsV2 in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().

RF_GlobalCallback

typedef void(* RF_GlobalCallback) (RF_Handle h, RF_GlobalEvent event, void *arg)

Handles global events as part of PHY configuration.

The RF driver serves additional global, client independent events by invoking the RF_GlobalCallback function registered through RFCC26XX_HWAttrsV2::globalCallback in the board file. The function can subscribe to particular events through the RFCC26XX_HWAttrsV2::globalEventMask, and receives the following arguments:

• the relevant driver client handle h which was returned by RF_open(),
• an event identifier event,
• an optional argument arg depending on the event.

If multiple events happen at the same time, the callback is always invoked separately for each event. Depending on the event, the callback might be invoked in SWI or HWI context.

RF_Cmd

typedef struct RF_Cmd_s RF_Cmd

RF_SubmitHook

typedef RF_ScheduleStatus(* RF_SubmitHook) (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)

Handles the queue sorting algorithm when a new command is submitted to the driver from any of the active clients.

The function is invoked within the RF_scheduleCmd API.

The default algorithm is subscribed through the RFCC26XX_SchedulerPolicy::submitHook and implemented in the RF driver. The arguments are:

• pCmdNew points to the command to be submitted.
• pCmdBg is the running background command.
• pCmdFg is the running foreground command.
• pPendQueue points to the head structure of pend queue.
• pDoneQueue points to the head structure of done queue.

In case the radio APIs do not distinguish between background and foreground contexts, the active operation will be returned within the pCmdBg pointer. If there are no commands being executed, both the pCmdBg and pCmdFg pointers are returned as NULL.

RF_ConflictHook

typedef RF_Conflict(* RF_ConflictHook) (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue)

Defines the conflict resolution in runtime.

The function is invoked if a conflict is identified before the start-time of the next radio command in the pending queue. The return value of type RF_Conflict determines the policy to be followed by the RF driver.

The arguments are:

• pCmdBg is the running background command.
• pCmdFg is the running foreground command.
• pPendQueue points to the head structure of pend queue.
• pDoneQueue points to the head structure of done queue.

Enumeration Type Documentation

RF_TxPowerTable_PAType

enum RF_TxPowerTable_PAType

Selects a power amplifier path in a TX power value.

RF_TxPowerTable_PAType selects one of the available power amplifiers on the RF core. It is usually included in a RF_TxPowerTable_Value.

Enumerator
RF_TxPowerTable_DefaultPA	Default PA.
RF_TxPowerTable_HighPA	High-power PA.

RF_Priority

enum RF_Priority

Scheduling priority of RF operation commands.

When multiple RF driver instances are used at the same time, commands from different clients may overlap. If an RF operation with a higher priority than the currently running operation is scheduled by RF_scheduleCmd(), then the running operation is interrupted.

In single-client applications, RF_PriorityNormal should be used.

Enumerator
RF_PriorityHighest	Highest priority. Only use this for urgent commands.
RF_PriorityHigh	High priority. Use this for time-critical commands in synchronous protocols.
RF_PriorityNormal	Default priority. Use this in single-client applications.

RF_Stat

enum RF_Stat

Status codes for various RF driver functions.

RF_Stat is reported as return value for RF driver functions which execute direct and immediate commands. Such commands are executed by RF_runDirectCmd() and RF_runImmediateCmd() in the first place, but also by some convenience functions like RF_cancelCmd(), RF_flushCmd(), RF_getInfo() and others.

Enumerator
RF_StatBusyError	Command not executed because RF driver is busy.
RF_StatRadioInactiveError	Command not executed because RF core is powered down.
RF_StatCmdDoneError	Command finished with an error.
RF_StatInvalidParamsError	Function was called with an invalid parameter.
RF_StatCmdEnded	Cmd is found in the pool but was already ended.
RF_StatError	General error specifier.
RF_StatCmdDoneSuccess	Command finished with success.
RF_StatCmdSch	Command successfully scheduled for execution.
RF_StatSuccess	Function finished with success.

RF_ClientEvent

enum RF_ClientEvent

Client-related RF driver events.

Events originating in the RF driver but not directly related to a specific radio command, are called client events. Clients may subscribe to these events by specifying a callback function RF_Params::pClientEventCb. Events are activated by specifying a bitmask RF_Params::nClientEventMask. The callback is called separately for every event providing an optional argument.

void onClientEvent(RF_Handle h, RF_ClientEvent event, void* arg)
{
    switch (event)
    {
    case RF_ClientEventPowerUpFinished:
        // Set output port
        break;
    default:
        // Unsubscribed events must not be issued.
        assert(false);
    }
}

RF_Params params;
params.pClientEventCb = &onClientEvent;
params.nClientEventMask = RF_ClientEventPowerUpFinished;
RF_open(...);

Enumerator
RF_ClientEventPowerUpFinished	The RF core has been powered up the radio setup has been finished.
RF_ClientEventRadioFree	Radio becomes free after a command has been preempted by a high-priority command of another client. This event is only triggered on a client that has been preempted. Clients may use this event to retry running their low-priority RF operation.
RF_ClientEventSwitchClientEntered	Signals the client that the RF driver is about to switch over from another client.

RF_GlobalEvent

enum RF_GlobalEvent

Global RF driver events.

The RF driver provides an interface through the global RFCC26XX_hwAttrs struct to register a global, client independent callback. This callback is typically used to control board related configurations such as antenna switches.

void globalCallback(RF_Handle h, RF_GlobalEvent event, void* arg)
{
    switch (event)
    {
    case RF_GlobalEventRadioSetup:
    {
        RF_RadioSetup* setupCommand = (RF_RadioSetup*)arg;
        // Select antenna path
        if (setupCommand->common.commandNo == CMD_PROP_RADIO_DIV_SETUP) {
            // Sub-1 GHz ...
        } else {
            // 2.4 GHz ...
        }
    }
        break;

    case RF_GlobalEventRadioPowerDown:
        // Disable antenna switch
        break;

    default:
        // Unsubscribed events must not be issued.
        assert(false);
    }
}

See also

RF_GlobalCallback

Enumerator
RF_GlobalEventRadioSetup	The RF core is being reconfigured through a setup command. The arg argument is a pointer to the setup command. HWI context.
RF_GlobalEventRadioPowerDown	The RF core is being powered down. The arg argument is empty. SWI context.

RF_InfoType

enum RF_InfoType

Selects the entry of interest in RF_getInfo().

Enumerator
RF_GET_CURR_CMD	Retrieve a command handle of the current command.
RF_GET_AVAIL_RAT_CH	Create a bitmask showing available RAT channels.
RF_GET_RADIO_STATE	Show the current RF core power state. 0: Radio OFF, 1: Radio ON.
RF_GET_SCHEDULE_MAP	Provide a timetable of all scheduled commands.
RF_GET_CLIENT_LIST	Provide the client list.
RF_GET_CLIENT_SWITCHING_TIME	Provide the client to client switching times.

RF_Conflict

enum RF_Conflict

Controls the behavior of the state machine of the RF driver when a conflict is identified run-time between the commands waiting on the pend queue and the commands being actively executed by the radio.

Enumerator
RF_ConflictNone
RF_ConflictReject
RF_ConflictAbort

RF_ScheduleStatus

enum RF_ScheduleStatus

Describes the location within the pend queue where the new command was inserted by the scheduler.

Enumerator
RF_ScheduleStatusError
RF_ScheduleStatusNone
RF_ScheduleStatusTop
RF_ScheduleStatusMiddle
RF_ScheduleStatusTail
RF_ScheduleStatusPreempt

RF_AllowDelay

enum RF_AllowDelay

Controls the behavior of the RF_scheduleCmd() API.

Enumerator
RF_AllowDelayNone
RF_AllowDelayAny

RF_RatSelectChannel

enum RF_RatSelectChannel

Select the preferred RAT channel through the configuration of RF_ratCompare() or RF_ratCapture().

If RF_RatChannelAny is provided within the channel configuration (default), the API will allocate the first available channel. Otherwise, it tries to allocate the requested channel, and if it is not available, returns with RF_ALLOC_ERROR.

Enumerator
RF_RatChannelAny	Chose the first available channel.
RF_RatChannel0	Use RAT user channel 0.
RF_RatChannel1	Use RAT user channel 1.
RF_RatChannel2	Use RAT user channel 2.

RF_RatCaptureSource

enum RF_RatCaptureSource

Selects the source signal for RF_ratCapture().

The source of a capture event can be selected through the source field of the RF_RatConfigCapture configuration structure.

Enumerator
RF_RatCaptureSourceRtcUpdate	Selects the RTC update signal source.
RF_RatCaptureSourceEventGeneric	Selects the Generic event of Event Fabric as source.
RF_RatCaptureSourceRfcGpi0	Selects the RFC_GPI[0] as source. This can be used i.e. to capture events on a GPIO. This requires that the GPIO is connected to RFC_GPO[0] from the GPIO driver.
RF_RatCaptureSourceRfcGpi1	Selects the RFC_GPO[1] as source. This can be used i.e. to capture events on a GPIO. This requires that the GPIO is connected to RFC_GPO[1] from the GPIO driver.

RF_RatCaptureMode

enum RF_RatCaptureMode

Selects the mode of RF_ratCapture().

The trigger mode of a capture event can be selected through the mode field of RF_RatConfigCapture configuration structure.

Enumerator
RF_RatCaptureModeRising	Rising edge of the selected source will trigger a capture event.
RF_RatCaptureModeFalling	Falling edge of the selected source will trigger a capture event.
RF_RatCaptureModeBoth	Both rising and falling edges of the selected source will generate capture events.

RF_RatCaptureRepetition

enum RF_RatCaptureRepetition

Selects the repetition of RF_ratCapture().

The configuration of a capture channel also defines whether the channel should be freed or automatically rearmed after a capture event occurred. In the latter case, the user needs to free the channel manually through the RF_ratDisableChannel() API.

Enumerator
RF_RatCaptureSingle	Free the channel after the first capture event.
RF_RatCaptureRepeat	Rearm the channel after each capture events.

RF_RatOutputMode

enum RF_RatOutputMode

Selects the mode of the RAT_GPO[x] for RF_ratCompare() or RF_ratCapture().

In case of compare mode, the channel can generate an output signal of the selected mode on the configured RAT_GPO[x] interface, and can be interconnected with other subsystems through the RFC_GPO[x] or Event Fabric. An example use case is to generate a pulse on a GPIO.

In case of capture mode, the channel can also generate an output signal of the selected mode on the configured RAT_GPO[x] interface. Note that the configuration of this output event is independent of the source signal of the capture event. An example use case is to generate a pulse on a GPIO on each raising edge of another GPIO source.

Enumerator
RF_RatOutputModePulse	Generates a one-clock period width pulse.
RF_RatOutputModeSet	Sets the output high on a RAT event.
RF_RatOutputModeClear	Sets the output low on a RAT event.
RF_RatOutputModeToggle	Inverts the polarity of the output.
RF_RatOutputModeAlwaysZero	Sets the output low independently of any RAT events.
RF_RatOutputModeAlwaysOne	Sets the output high independently of any RAT events.

RF_RatOutputSelect

enum RF_RatOutputSelect

Selects GPO to be used with RF_ratCompare() or RF_ratCapture().

RAT_GPO[0] - Reserved by the RF core. User shall not modify the configuration, but can observe the signal through any of RFC_GPO[0:3]. RAT_GPO[1] - Reserved by the RF core only if sync word detection is enabled. Otherwise can be used through RFC_GPO[0:3]. RAT_GPO[2:3] - Available and can be used through any of the RFC_GPO[0:3]. RAT_GPO[4:7] - Available and can be used through the Event fabric.

Enumerator
RF_RatOutputSelectRatGpo1	Configure RAT_CHANNEL[x] to interface with RAT_GPO[1].
RF_RatOutputSelectRatGpo2	Configure RAT_CHANNEL[x] to interface with RAT_GPO[2].
RF_RatOutputSelectRatGpo3	Configure RAT_CHANNEL[x] to interface with RAT_GPO[3].
RF_RatOutputSelectRatGpo4	Configure RAT_CHANNEL[x] to interface with RAT_GPO[4].
RF_RatOutputSelectRatGpo5	Configure RAT_CHANNEL[x] to interface with RAT_GPO[5].
RF_RatOutputSelectRatGpo6	Configure RAT_CHANNEL[x] to interface with RAT_GPO[6].
RF_RatOutputSelectRatGpo7	Configure RAT_CHANNEL[x] to interface with RAT_GPO[7].

Function Documentation

RF_open()

RF_Handle RF_open	(	RF_Object *	pObj,
		RF_Mode *	pRfMode,
		RF_RadioSetup *	pRadioSetup,
		RF_Params *	params
	)

Creates a a new client instance of the RF driver.

This function initializes an RF driver client instance using pObj as storage. It does not power up the RF core. Once the client starts the first RF operation command later in the application, the RF core is powered up and set into a PHY mode specified by pRfMode. The chosen PHY is then configured by a radio setup command pRadioSetup. Whenever the RF core is powered up, the RF driver re-executes the radio setup command pRadioSetup. Additional driver behavior may be set by an optional params.

// Define parameters
RF_Params rfParams;
rfParams.nInactivityTimeout = 4;
RF_Params_init(&rfParams);
rfParams.nInactivityTimeout = 1701; // microseconds

RF_Handle rfHandle = RF_open(&rfObject, &RF_prop, (RF_RadioSetup*)&RF_cmdPropRadioDivSetup, &rfParams);

Note

Calling context : Task

Parameters

pObj	Pointer to a RF_Object that will hold the state for this RF client. The object must be in persistent and writable memory.
pRfMode	Pointer to a RF_Mode struct holding PHY information
pRadioSetup	Pointer to the radio setup command used for this client. This is re-executed by the RF Driver on each power-up.
params	Pointer to an RF_Params object with the desired driver configuration. A NULL pointer results in the default configuration being loaded.

Returns

A handle for further RF driver calls on success. Otherwise NULL.

RF_close()

void RF_close

(

RF_Handle

h

)

Close client connection to RF driver.

Allows a RF client (high-level driver or application) to close its connection to the RF driver.

Note

Calling context : Task

Parameters

h	Handle previously returned by RF_open()

RF_getCurrentTime()

uint32_t RF_getCurrentTime

(

void

)

Return current radio timer value.

If the radio is powered returns the current radio timer value, if not returns a conservative estimate of the current radio timer value

Note

Calling context : Task/SWI/HWI

Returns

Current radio timer value

RF_postCmd()

RF_CmdHandle RF_postCmd	(	RF_Handle	h,
		RF_Op *	pOp,
		RF_Priority	ePri,
		RF_Callback	pCb,
		RF_EventMask	bmEvent
	)

Appends RF operation commands to the driver's command queue and returns a command handle.

The RF operation pOp may either represent a single operation or may be the first operation in a chain. If the command queue is empty, the pCmd is dispatched immediately. If there are other operations pending, then pCmd is processed after all other commands have been finished. The RF operation command must be compatible to the RF_Mode selected by RF_open(), e.g. proprietary commands can only be used when the RF core is configured for proprietary mode.

The returned command handle is an identifier that can be used to control command execution later on, for instance with RF_pendCmd() or RF_cancelCmd(). It is a 16 Bit signed integer value, incremented on every new command. If the RF driver runs out of command containers, RF_ALLOC_ERROR is returned.

The priority ePri is only relevant in multi-client applications where commands of distinct clients may interrupt each other. Only commands started by RF_scheduleCmd() can preempt running commands. RF_postCmd() or RF_runCmd() do never interrupt a running command. In single-client applications, ePri is ignored and should be set to RF_PriorityNormal.

A callback function pCb might be specified to get notified about events during command execution. Events are subscribed by the bit mask bmEvent. Valid event flags are specified in RF_Core_Events and RF_Driver_Events. If no callback is set, RF_pendCmd() can be used to synchronize the current task to command execution. For this it is necessary to subscribe all relevant events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed.

The following limitations apply to the execution of command chains:

• If TRIG_ABSTIME is used as a start trigger for the first command, TRIG_REL_FIRST_START can not be used for any other command. This is because the RF driver may insert a frequency-select command (CMD_FS) at the front of the chain when it performs an automatic power-up.
• Having more than one CMD_FS in a chain may lead to unexpected behavior. If a chain contains a CMD_FS and the command can be reached by iterating over the pNextOp field, then RF driver will always update the cached CMD_FS with the new settings. On the next automatic power-up, the RF driver will use the updated frequency.

Note

Calling context : Task/SWI

See also

RF_pendCmd(), RF_runCmd(), RF_scheduleCmd(), RF_RF_cancelCmd(), RF_flushCmd(), RF_getCmdOp()

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_postCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns

A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

RF_defaultSubmitPolicy()

RF_ScheduleStatus RF_defaultSubmitPolicy	(	RF_Cmd *	pCmdNew,
		RF_Cmd *	pCmdBg,
		RF_Cmd *	pCmdFg,
		List_List *	pPendQueue,
		List_List *	pDoneQueue
	)

Sorts and adds commands to the RF driver internal command queue.

Parameters

pCmdNew	Pointer to the command to be submitted.
pCmdBg	Running background command.
pCmdFg	Running foreground command.
pPendQueue	Pointer to the head structure of pend queue.
pDoneQueue	Pointer to the head structure of done queue..

Returns

RF_defaultSubmitPolicy identifies the success or failure of queuing.

RF_defaultConflictPolicy()

RF_Conflict RF_defaultConflictPolicy	(	RF_Cmd *	pCmdBg,
		RF_Cmd *	pCmdFg,
		List_List *	pPendQueue,
		List_List *	pDoneQueue
	)

Makes a final decision when a conflict in run-time is identified.

Parameters

pCmdBg	Running background command.
pCmdFg	Running foreground command.
pPendQueue	Pointer to the head structure of pend queue.
pDoneQueue	Pointer to the head structure of done queue..

Returns

RF_defaultSubmitPolicy identifies the success or failure of queuing.

RF_ScheduleCmdParams_init()

void RF_ScheduleCmdParams_init

(

RF_ScheduleCmdParams *

pSchParams

)

Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API.

Note

Calling context : Task/SWI/HWI

Parameters

pSchParams

Pointer to the configuration structure.

Returns

none

RF_scheduleCmd()

RF_CmdHandle RF_scheduleCmd	(	RF_Handle	h,
		RF_Op *	pOp,
		RF_ScheduleCmdParams *	pSchParams,
		RF_Callback	pCb,
		RF_EventMask	bmEvent
	)

Schedule an RF operation (chain) to the command queue.

Schedule an RF_Op to the RF command queue of the client with handle h.
The command can be the first in a chain of RF operations or a standalone RF operation. If a chain of operations are posted they are treated atomically, i.e. either all or none of the chained operations are run.
All operations must be posted in strictly increasing chronological order. Function returns immediately.

Limitations apply to the operations posted:

• The operation must be in the set supported in the chosen radio mode when RF_open() was called
• Only a subset of radio operations are supported
• Only some of the trigger modes are supported with potential power saving (TRIG_NOW, TRIG_ABSTIME)

Note

Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writable memory
pSchParams	Pointer to the schedule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_scheduleCmd() fails no callback is made
bmEvent	Bitmask of events that will trigger the callback.

Returns

A handle to the RF command. Return value of RF_ALLOC_ERROR indicates error.

RF_pendCmd()

RF_EventMask RF_pendCmd	(	RF_Handle	h,
		RF_CmdHandle	ch,
		RF_EventMask	bmEvent
	)

Synchronizes the calling task to an RF operation command ch and returns accumulated event flags.

After having dispatched an RF operation represented by ch with RF_postCmd(), the command is running in parallel on the RF core. Thus, it might be desirable to synchronize the calling task to the execution of the command. With RF_pendCmd(), the application can block until one of the events specified in bmEvent occurs or until the command finishes. The function consumes and returns all accumulated event flags that occurred during execution if they have been previously subscribed by RF_postCmd(). Possible events are specified in RF_Core_Events and RF_Driver_Events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed and can not be masked.

RF_pendCmd() may be called multiple times for the same command.

If RF_pendCmd() is called for a command handle representing a finished command, then only the RF_EventLastCmdDone flag is returned, regardless of how the command finished.

If the command has also a callback set, the callback is executed before RF_pendCmd() returns.

Example:

// Dispatch a command to the RF driver's command queue
RF_CmdHandle ch = RF_postCmd(driver, (RF_Op*)&CMD_PROP_RX, RF_PriorityNormal, NULL, RF_EventRxEntryDone);
assert(ch != RF_ALLOC_ERROR);

bool finished = false;
while (finished == false)
{
    // Synchronize to events during command execution.
    uint32_t events = RF_pendCmd(driver, ch, RF_EventRxEntryDone);
    // Check events that happen during execution
    if (events & RF_EventRxEntryDone)
    {
        // Process packet
    }
    if (events & (RF_EventLastCmdDone | RF_EventCmdStopped | RF_EventCmdAborted | RF_EventCmdCancelled))
    {
        finished = true;
    }
    // ...
}

Note

Calling context : Task

Parameters

h	Driver handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
bmEvent	Bitmask of events that make RF_pendCmd() return. Termination events are always implicitly subscribed.

Returns

Event flags accumulated during command execution.

See also

RF_postCmd()

RF_runCmd()

RF_EventMask RF_runCmd	(	RF_Handle	h,
		RF_Op *	pOp,
		RF_Priority	ePri,
		RF_Callback	pCb,
		RF_EventMask	bmEvent
	)

Runs synchronously an RF operation command or a chain of commands and returns the termination reason.

This function appends an RF operation command or a chain of commands to the RF driver's command queue and then waits for it to complete. A command is completed if one of the termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occurred.

This function is a combination of RF_postCmd() and RF_pendCmd(). All options and limitations for RF_postCmd() apply here as well.

An application should always ensure that the command completed in the expected way and with an expected status code.

Note

Calling context : Task

Parameters

h	Driver handle previously returned by RF_open()
pOp	Pointer to the RF operation command.
ePri	Priority of this RF command (used for arbitration in multi-client systems)
pCb	Callback function called during command execution and upon completion. If RF_runCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback or that can be pended on.

Returns

The relevant termination event.

See also

RF_postCmd(), RF_pendCmd(), RF_cancelCmd(), RF_flushCmd()

RF_runScheduleCmd()

RF_EventMask RF_runScheduleCmd	(	RF_Handle	h,
		RF_Op *	pOp,
		RF_ScheduleCmdParams *	pSchParams,
		RF_Callback	pCb,
		RF_EventMask	bmEvent
	)

Runs synchronously a (chain of) RF operation(s) for dual or single-mode.

Allows a (chain of) operation(s) to be scheduled to the command queue and then waits for it to complete.
A command is completed if one of the RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occurred.

Note

Calling context : Task

Only one call to RF_pendCmd() or RF_runScheduleCmd() can be made at a time for each client

Parameters

h	Handle previously returned by RF_open()
pOp	Pointer to the RF_Op. Must normally be in persistent and writable memory
pSchParams	Pointer to the schedule command parameter structure
pCb	Callback function called upon command completion (and some other events). If RF_runScheduleCmd() fails, no callback is made.
bmEvent	Bitmask of events that will trigger the callback.

Returns

The relevant command completed event.

RF_cancelCmd()

RF_Stat RF_cancelCmd	(	RF_Handle	h,
		RF_CmdHandle	ch,
		uint8_t	mode
	)

Abort/stop/cancel single command in command queue.

If command is running, aborts/stops it and posts callback for the aborted/stopped command.
If command has not yet run, cancels it it and posts callback for the canceled command.
If command has already run or been aborted/stopped/canceled, has no effect.
If RF_cancelCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note

Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns

RF_Stat indicates if command was successfully completed

RF_flushCmd()

RF_Stat RF_flushCmd	(	RF_Handle	h,
		RF_CmdHandle	ch,
		uint8_t	mode
	)

Abort/stop/cancel command and any subsequent commands in command queue.

If command is running, aborts/stops it and then cancels all later commands in queue.
If command has not yet run, cancels it and all later commands in queue.
If command has already run or been aborted/stopped/canceled, has no effect.
The callbacks for all canceled commands are issued in chronological order.
If RF_flushCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.

Note

Calling context : Task/SWI

Parameters

h	Handle previously returned by RF_open()
ch	Command handle previously returned by RF_postCmd().
mode	1: Stop gracefully, 0: abort abruptly

Returns

RF_Stat indicates if command was successfully completed

RF_runImmediateCmd()

RF_Stat RF_runImmediateCmd	(	RF_Handle	h,
		uint32_t *	pCmdStruct
	)

Send any Immediate command.

Immediate Command is send to RDBELL, if radio is active and the RF_Handle points to the current client.
In other appropriate RF_Stat values are returned.

Note

Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
pCmdStruct	Pointer to the immediate command structure

Returns

RF_Stat indicates if command was successfully completed

RF_runDirectCmd()

RF_Stat RF_runDirectCmd	(	RF_Handle	h,
		uint32_t	cmd
	)

Send any Direct command.

Direct Command value is send to RDBELL immediately, if radio is active and the RF_Handle point to the current client.
In other appropriate RF_Stat values are returned.

Note

Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
cmd	Direct command value.

Returns

RF_Stat indicates if command was successfully completed.

RF_yield()

void RF_yield

(

RF_Handle

h

)

Signal that radio client is not going to issue more commands in a while.

Hint to RF driver that, irrespective of inactivity timeout, no new further commands will be issued for a while and thus the radio can be powered down at the earliest convenience. In case the RF_yield() is called within a callback, the callback will need to finish and return before the power down sequence is initiated. Posting new commands to the queue will cancel any pending RF_yield() request.

Note

Calling context : Task

Parameters

h	Handle previously returned by RF_open()

RF_Params_init()

void RF_Params_init

(

RF_Params *

params

)

Function to initialize the RF_Params struct to its defaults.

Parameters

params

An pointer to RF_Params structure for initialization

Defaults values are: nInactivityTimeout = BIOS_WAIT_FOREVER nPowerUpDuration = RF_DEFAULT_POWER_UP_TIME

RF_getInfo()

RF_Stat RF_getInfo	(	RF_Handle	h,
		RF_InfoType	type,
		RF_InfoVal *	pValue
	)

Get value for some RF driver parameters.

Note

Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
type	Request value parameter defined by RF_InfoType
pValue	Pointer to return parameter values specified by RF_InfoVal

Returns

RF_Stat indicates if command was successfully completed

RF_getRssi()

int8_t RF_getRssi

(

RF_Handle

h

)

Get RSSI value.

Note

Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()

Returns

RSSI value. Return value of RF_GET_RSSI_ERROR_VAL indicates error case.

RF_getCmdOp()

RF_Op* RF_getCmdOp	(	RF_Handle	h,
		RF_CmdHandle	cmdHnd
	)

Get command structure pointer.

Note

Calling context : Task/SWI/HWI

Parameters

h	Handle previously returned by RF_open()
cmdHnd	Command handle returned by RF_postCmd()

Returns

Pointer to the command structure.

RF_RatConfigCompare_init()

void RF_RatConfigCompare_init

(

RF_RatConfigCompare *

channelConfig

)

Initialize the configuration structure to be used to set up a RAT compare event.

Note

Calling context : Task/SWI/HWI

Parameters

channelConfig

Pointer to the compare configuration structure.

Returns

none

RF_RatConfigCapture_init()

void RF_RatConfigCapture_init

(

RF_RatConfigCapture *

channelConfig

)

Initialize the configuration structure to be used to set up a RAT capture event.

Note

Calling context : Task/SWI/HWI

Parameters

channelConfig

Pointer to the capture configuration structure.

Returns

none

RF_RatConfigOutput_init()

void RF_RatConfigOutput_init

(

RF_RatConfigOutput *

ioConfig

)

Initialize the configuration structure to be used to set up a RAT IO.

Note

Calling context : Task/SWI/HWI

Parameters

ioConfig

Pointer to the IO configuration structure.

Returns

none

RF_ratCompare()

RF_RatHandle RF_ratCompare	(	RF_Handle	rfHandle,
		RF_RatConfigCompare *	channelConfig,
		RF_RatConfigOutput *	ioConfig
	)

Setup a Radio Timer (RAT) channel in compare mode.

The RF_ratCompare() API sets up one of the three available RAT channels in compare mode. When the compare event happens at the given compare time, the registered callback is invoked.

The RF driver handles power management. If the provided compare time is far into the future (and there is no other constraint set i.e. due to radio command execution), the RF core will be powered OFF and the device will enter the lowest possible power state. The RF core will be automatically powered ON just before the registered compare event. The callback function is served upon expiration of the allocated channel. The function is invoked with event type RF_EventRatCh and runs in SWI context.

The API generates a "one-shot" compare event. Since the channel is automatically freed before the callback is served, the same channel can be reallocated from the callback itself through a new API call.

In case there were no available channels at the time of API call, the function returns with RF_ALLOC_ERROR and no callback is invoked.

In case a runtime error occurs after the API successfully allocated a channel, the registered callback is invoked with event type RF_EventError. A typical example is when the provided compare time is in the past and rejected by the RF core itself.

The events issued by the RAT timer can be output from the timer module through the RAT_GPO interface, and can be interconnected with other parts of the system through the RFC_GPO or the Event Fabric. The mapping between the allocated RAT channel and the selected RAT_GPO can be controlled through the optional ioConfig argument of RF_ratCompare(). The possible RAT_GPO[x] are defined in RF_RatOutputSelect.

Note

Calling context : Task/SWI

Parameters

rfHandle	Handle previously returned by RF_open().
channelConfig	Pointer to configuration structure needed to set up a channel in compare mode.
ioConfig	Pointer to a configuration structure to set up the RAT_GPOs for the allocated channel (optional).

Returns

Allocated RAT channel. If allocation fails, RF_ALLOC_ERROR is returned.

See also

RF_RatConfigCompare_init(), RF_RatConfigOutput_init(), RF_ratDisableChannel(), RF_ratCapture()

RF_ratCapture()

RF_RatHandle RF_ratCapture	(	RF_Handle	rfHandle,
		RF_RatConfigCapture *	channelConfig,
		RF_RatConfigOutput *	ioConfig
	)

Setup a Radio Timer (RAT) channel in capture mode.

The RF_ratCapture() API sets up one of the three available RAT channels in capture mode. The registered callback is invoked on the capture event.

The RF driver handles power management. If the RF core is OFF when the RF_ratCapture() is called, it will be powered ON immediately and the RAT channel will be configured to capture mode. As long as at least one of the three RAT channels are in capture mode, the RF core will be kept ON. The callback function is served upon a capture event occurs. The function is invoked with event type RF_EventRatCh and runs in SWI context.

In case the channel is configured into single capture mode, the channel is automatically freed before the callback is called. In repeated capture mode, the channel remains allocated and automatically rearmed.

In case there were no available channels at the time of API call, the function returns with RF_ALLOC_ERROR and no callback is invoked.

In case a runtime error occurs after the API successfully allocated a channel, the registered callback is invoked with event type RF_EventError. A typical example is when the provided compare time is in the past and rejected by the RF core itself.

The events issued by the RAT timer can be output from the timer module through the RAT_GPO interface, and can be interconnected with other parts of the system through the RFC_GPO or the Event Fabric. The mapping between the allocated RAT channel and the selected RAT_GPO can be controlled through the optional ioConfig argument of RF_ratCapture(). The possible RAT_GPO[x] are defined in RF_RatOutputSelect. Note that this configuration is independent of the source signal of the capture event.

Note

Calling context : Task/SWI

Parameters

rfHandle	Handle previously returned by RF_open().
channelConfig	Pointer to configuration structure needed to set up a channel in compare mode.
ioConfig	Pointer to a configuration structure to set up the RAT_GPO for the allocated channel (optional).

Returns

Allocated RAT channel. If allocation fails, RF_ALLOC_ERROR is returned.

See also

RF_RatConfigCapture_init(), RF_RatConfigOutput_init() , RF_ratDisableChannel(), RF_ratCompare()

RF_ratDisableChannel()

RF_Stat RF_ratDisableChannel	(	RF_Handle	rfHandle,
		RF_RatHandle	ratHandle
	)

Disable a RAT channel.

The RF_RatHandle returned by the RF_ratCompare() or RF_ratCapture() APIs can be used for further interaction with the Radio Timer. Passing the handle to RF_ratDisableChannel() will abort a compare/capture event, and the provided channel is deallocated. No callback is invoked. This API can be called both if the RF core is ON or OFF. After the channel is freed, the next radio event will be rescheduled. A typical use case if a channel is configured in repeated capture mode, and the application decides to abort this operation.

Note

Calling context : Task/SWI

Parameters

rfHandle	Handle previously returned by RF_open().
ratHandle	RF_RatHandle returned by RF_ratCompare() or RF_ratCapture().

Returns

RF_Stat indicates if command was successfully completed.

See also

RF_ratCompare(), RF_ratCapture()

RF_control()

RF_Stat RF_control	(	RF_Handle	h,
		int8_t	ctrl,
		void *	args
	)

Set RF control parameters.

Note

Calling context : Task

Parameters

h	Handle previously returned by RF_open()
ctrl	Control codes
args	Pointer to control arguments

Returns

RF_Stat indicates if API call was successfully completed.

RF_requestAccess()

RF_Stat RF_requestAccess	(	RF_Handle	h,
		RF_AccessParams *	pParams
	)

Request radio access.

Scope:

1. Only supports request access which start immediately.
   
2. The RF_AccessParams duration should be less than a pre-defined value RF_REQ_ACCESS_MAX_DUR_US in RFCC26XX_multiMode.c.
   
3. The RF_AccessParams priority should be set RF_PriorityHighest.
   
4. Single request for a client at anytime.
   
5. Command from different client are blocked until the radio access period is completed.
   

Note

Calling context : Task

Parameters

h	Handle previously returned by RF_open()
pParams	Pointer to RF_AccessRequest parameters

Returns

RF_Stat indicates if API call was successfully completed.

RF_getTxPower()

RF_TxPowerTable_Value RF_getTxPower

(

RF_Handle

h

)

Returns the currently configured transmit power configuration.

This function returns the currently configured transmit power configuration under the assumption that it has been previously set by RF_setTxPower(). The value might be used for reverse lookup in a TX power table. If no power has been programmed, it returns an invalid value.

RF_TxPowerTable_Value value = RF_getTxPower(handle);
if (value.rawValue == RF_TxPowerTable_INVALID_VALUE) {
    // error, value not valid
}

Parameters

h	Handle previously returned by RF_open()

Returns

PA configuration struct

See also

RF_setTxPower(), RF_TxPowerTable_findPowerLevel()

RF_setTxPower()

RF_Stat RF_setTxPower	(	RF_Handle	h,
		RF_TxPowerTable_Value	value
	)

Updates the transmit power configuration of the RF core.

This function programs a new TX power value and returns a status code. The API will return with RF_StatBusyError if there are still pending commands in the internal queue. In case of success, RF_StatSuccess is returned and the new configuration becomes effective from the next radio operation.

Some devices provide an integrated high-power PA in addition to the Default PA. On these devices the API accepts configurations for both, and if value selects a different PA, the globalCallback is invoked. The implementation of globalCallback is board specific and can be used to reconfigure the external RF switches (if any).

Parameters

h	Handle previously returned by RF_open()
value	TX power configuration value.

Returns

RF_StatSuccess on success, otherwise an error code.

See also

RF_getTxPower(), RF_TxPowerTable_Value, RF_TxPowerTable_findValue()

RF_TxPowerTable_findPowerLevel()

int8_t RF_TxPowerTable_findPowerLevel	(	RF_TxPowerTable_Entry	table[],
		RF_TxPowerTable_Value	value
	)

Retrieves a power level in dBm for a given power configuration value.

RF_TxPowerTable_findPowerLevel() searches in a lookup table for a given transmit power configuration value and returns the power level in dBm if a matching configuration is found. If value can not be found, RF_TxPowerTable_INVALID_DBM is returned.

This function does a reverse lookup compared to RF_TxPowerTable_findValue() and has O(n). It is assumed that table is terminated by a RF_TxPowerTable_TERMINATION_ENTRY.

Parameters

table	List of RF_TxPowerTable_Entry entries, terminated by RF_TxPowerTable_TERMINATION_ENTRY.
value	Power configuration value.

Returns

Human readable power level in dBm on success, otherwise RF_TxPowerTable_INVALID_DBM.

RF_TxPowerTable_findValue()

RF_TxPowerTable_Value RF_TxPowerTable_findValue	(	RF_TxPowerTable_Entry	table[],
		int8_t	powerLevel
	)

Retrieves a power configuration value for a given power level in dBm.

RF_TxPowerTable_findValue() searches in a lookup table for a given transmit power level powerLevel in dBm and returns a matching power configuration. If powerLevel can not be found, RF_TxPowerTable_INVALID_VALUE is returned.

This function performs a linear search in table and has O(n). It is assumed that table is defined in ascending order and is terminated by a RF_TxPowerTable_TERMINATION_ENTRY.

The following special values for powerLevel are also accepted:

• RF_TxPowerTable_MIN_DBM which returns always the lowest power value in the table
• RF_TxPowerTable_MAX_DBM which returns always the highest power value in the table

Parameters

table	List of RF_TxPowerTable_Entry entries, terminated by RF_TxPowerTable_TERMINATION_ENTRY.
powerLevel	Human-readable power level in dBm.

Returns

PA configuration value on success. otherwise RF_TxPowerTable_INVALID_VALUE.