EasyLink API reference¶

EasyLink RF API for CC13xx/CC26xx family.

Overview

The EasyLink API should be used in application code. The EasyLink API is intended to abstract the RF Driver in order to give a simple API for customers to use as is or extend to suit their application use cases.

General Behavior

Before using the EasyLink API:

The EasyLink Layer is initialized by calling EasyLink_init(). This initializes and opens the RF driver and configuring a modulation scheme passed to EasyLink_init().
The RX and TX can operate independently of each other.

The following is true for receive operation:

RX is enabled by calling EasyLink_receive() or EasyLink_receiveAsync().
Entering RX can be immediate or scheduled.
EasyLink_receive() is blocking and EasyLink_receiveAsync() is nonblocking.
the EasyLink API does not queue messages so calling another API function while in EasyLink_receiveAsync() will return EasyLink_Status_Busy_Error
an Async operation can be cancelled with EasyLink_abort()

The following apply for transmit operation:

TX is enabled by calling EasyLink_transmit() or EasyLink_transmitAsync().
TX can be immediate or scheduled.
EasyLink_transmit() is blocking and EasyLink_transmitAsync() is nonblocking
EasyLink_transmit() for a scheduled command, or if TX can not start
the EasyLink API does not queue messages so calling another API function while in EasyLink_transmitAsync() will return EasyLink_Status_Busy_Error
an Async operation can be cancelled with EasyLink_abort()

Error handling

The EasyLink API will return EasyLink_Status containing success or error code. The EasyLink_Status code are:

EasyLink_Status_Success
EasyLink_Status_Config_Error
EasyLink_Status_Param_Error
EasyLink_Status_Mem_Error
EasyLink_Status_Cmd_Error
EasyLink_Status_Tx_Error
EasyLink_Status_Rx_Error
EasyLink_Status_Rx_Timeout
EasyLink_Status_Busy_Error
EasyLink_Status_Aborted
EasyLink_Status_Cmd_Rejected

Power Management

The TI-RTOS power management framework will try to put the device into the most power efficient mode whenever possible. Please see the technical reference manual for further details on each power mode.

The EasyLink Layer uses the power management offered by the RF driver Refer to the RF drive documentation for more details.

Frame Structure

The EasyLink implements a basic header for transmitting and receiving data. This header supports addressing for a star or point-to-point network with acknowledgments.

Packet structure:

 _________________________________________________________
|           |                   |                         |
| 1B Length | 1-64b Dst Address |         Payload         |
|___________|___________________|_________________________|

Defines

EASYLINK_API_VERSION¶: EasyLink API Version.

EASYLINK_MAX_ADDR_SIZE¶: defines the Tx/Rx Max Address Size

EASYLINK_MAX_ADDR_FILTERS¶: defines the Max number of Rx Address filters

EASYLINK_WHITENING_MODE¶: defines the whitening mode

EasyLink_RadioTime_To_ms(radioTime)¶: macro to convert from Radio Time Ticks to ms

EasyLink_ms_To_RadioTime(ms)¶: macro to convert from ms to Radio Time Ticks

EasyLink_us_To_RadioTime(us)¶: macro to convert from us to Radio Time Ticks

EasyLink_PHY_CUSTOM¶: Phy Type defines so we can use them in checks.

EasyLink_PHY_50KBPS2GFSK¶

EasyLink_PHY_625BPSLRM¶

EasyLink_PHY_2_4_200KBPS2GFSK¶

EasyLink_PHY_5KBPSSLLR¶

EasyLink_PHY_2_4_100KBPS2GFSK¶

EasyLink_PHY_2_4_250KBPS2GFSK¶

EasyLink_PHY_200KBPS2GFSK¶

Typedefs

typedef uint32_t(* EasyLink_GetRandomNumber)(void)¶: EasyLink 32-bit Random number generator function type used in the clear channel assessment algorithm.

typedef void(* EasyLink_ReceiveCb)(EasyLink_RxPacket *rxPacket, EasyLink_Status status)¶: EasyLink Callback function type for Received packet, registered with EasyLink_ReceiveAsync()

typedef void(* EasyLink_TxDoneCb)(EasyLink_Status status)¶: EasyLink Callback function type for Tx Done registered with EasyLink_TransmitAsync()

Enums

EasyLink_Status¶

EasyLink Status and error codes.

Values:

0¶: Success.

1¶: Configuration error.

2¶: Param error.

3¶: Memory Error.

4¶: Memory Error.

5¶: Tx Error.

6¶: Rx Error.

7¶: Rx Error.

8¶: Rx Buffer Error.

9¶: Busy Error.

10¶: Command stopped or aborted.

11¶: Command Rejected by RF Driver (Scheduling conflict)

EasyLink_PhyType¶

Phy Type passed to EasyLink_init()

Values:

0: Customer Phy specific settings exported from SmartRF Studio.

1: Phy settings for Sub1G 50kbps data rate, IEEE 802.15.4g GFSK.

2: Phy settings for Sub1G 625bps data rate, Long Range Mode.

3: Phy settings for 2.4Ghz 200kbps data rate, IEEE 802.15.4g GFSK.

4: SimpleLink Long Range (5 kbps)

5: Phy settings for 2.4Ghz 100kbps data rate, IEEE 802.15.4g GFSK.

6: Phy settings for 2.4Ghz 250kbps data rate, IEEE 802.15.4g GFSK.

7: Phy settings for 200kbps data rate, IEEE 802.15.4g GFSK.

EasyLink_Num_Phy_Settings¶

EasyLink_CtrlOption¶

Advance configuration options.

Values:

0: Set the number of bytes in Addr for both Addr Filter and Tx/Rx operations

1: Set a timeout value for inactivity on the radio, i.e. if the radio stays idle for this amount of time it is automatically powered down

2: Set Multiclient mode for application that will use multiple RF clients. Must be set before calling EasyLink_init().

3: Relative time in ticks from Async Rx start to TimeOut. A value of 0 means no timeout

4: Set the command priority with a value from EasyLink_Priority

5: Enable/Disable Test mode for Tone.

6: Enable/Disable Test mode for Signal.

7: Enable/Disable Rx Test mode for Tone.

EasyLink_Activity¶

Activity table.

+———–+———————————–+ | Activity | Priority | +———–+———+———+———+ | | Normal | High | Urgent | | TX | 0X03090000 | 0X03090001 | 0X03090002 | | RX | 0X03070000 | 0X03070001 | 0X03070002 | +———–+———————————–+

Values:

0x309¶: Activity code for the Tx operation.

0x307¶: Activity code for the Rx operation.

EasyLink_Priority¶

Transmit and Receive Command Priority - These are only applicable in a multi-client use-case.

Values:

0x0¶

0x1¶

0x2¶

EasyLink_Priority_NEntries¶

Functions

void EasyLink_Params_init(EasyLink_Params * params)¶

Initializes the radio with specified Phy settings and RF client events.

This function configures the radio phy settings. If the ui32ModType is EasyLink_Phy_Custom then the configuration is taken from srf_settings.h. If a specific phy configuration is required (and not supported by any of the defined Phy types in EasyLink_PhyType then you can cut and past the RF setting from the SmartRF Studio code export tool. This will copy and use the RF_prop, RF_cmdPropRadioDivSetup and RF_cmdFs commands, as well as the Sync word from the RF_cmdPropTx and RF_cmdPropRx commands. The function configures the callback for client events. The client events that trigger the callback are set using the nClientEventMask type in EasyLink_Params. A pointer to the desired callback should be provided to the pClientEventCb type of the EasyLink_Params structure.

Default values are: ui32ModType = EasyLink_Phy_50kbps2gfsk RF_ClientCallback = NULL RF_ClientEventMask = 0 pGrnFxn = (EasyLink_GetRandomNumber)rand

Parameters

params: The descriptor for the Phy mode and event callback settings

Return: EasyLink_Status

EasyLink_Status EasyLink_init(EasyLink_Params * params)¶

Initializes the radio with specified Phy settings, CCA random number generator, and RF client events.

This function configures the radio phy settings. If the ui32ModType is EasyLink_Phy_Custom then the configuration is taken from srf_settings.h. If a specific phy configuration is required (and not supported by any of the defined Phy types in EasyLink_PhyType then you can cut and past the RF setting from the SmartRF Studio code export tool. This will copy and use the RF_prop, RF_cmdPropRadioDivSetup and RF_cmdFs commands, as well as the Sync word from the RF_cmdPropTx and RF_cmdPropRx commands. The function configures the callback for client events. The client events that trigger the callback are set using the nClientEventMask type in EasyLink_Params. A pointer to the desired callback should be provided to the pClientEventCb type of the EasyLink_Params structure.

Return

EasyLink_Status

Parameters

params: The descriptor for the Phy mode, random number generator, and event callback settings

EasyLink_Status EasyLink_getAbsTime(uint32_t * pui32AbsTime)¶

Gets the absolute radio time.

This function returns the absolute radio time and can be used for monitoring or Tx/Rx events using the EasyLink_TxPacket and EasyLink_RxPacket::absTime field.

Return

EasyLink_Status

Parameters

pui32AbsTime: Pointer to return the signed RSSI value (dBm)

EasyLink_Status EasyLink_getRssi(int8_t * pi8Rssi)¶

Gets the RSSI value of an ongoing Radio Operation.

This function returns the RSSI from an ongoing receiver radio operation. It is useful in receiver test modes to detect the presence of both modulated and unmodulated carrier waves

Return

EasyLink_Status

Note

if no RSSI is available the function writes -128 to the value argument

Parameters

pi8Rssi: Pointer to return the signed RSSI value (dBm)

EasyLink_Status EasyLink_transmit(EasyLink_TxPacket * txPacket)¶

Sends a Packet with blocking call.

This function is a blocking call to send a packet. If the Tx is successfully scheduled then the function will block until the Tx is complete.

Return

EasyLink_Status

Parameters

txPacket: The descriptor for the packet to be Tx’ed.

EasyLink_Status EasyLink_transmitAsync(EasyLink_TxPacket * txPacket, EasyLink_TxDoneCb cb)¶

Sends a Packet with non blocking call.

This function is a non blocking call to send a packet. If the Tx is successfully scheduled then the callback will be call once the Tx is complete.

Return

EasyLink_Status

Parameters

txPacket: The descriptor for the packet to be Tx’ed.
cb: The tx done function pointer.

EasyLink_Status EasyLink_transmitCcaAsync(EasyLink_TxPacket * txPacket, EasyLink_TxDoneCb cb)¶

Sends a Packet with non blocking call if the channel is idle.

This function is a non blocking call to send a packet. It will check for a clear channel prior to transmission. If the channel is busy it will backoff for a random period, in time units of EASYLINK_CCA_BACKOFF_TIMEUNITS, before reassessing. It does this a certain number (EASYLINK_MAX_CCA_BACKOFF_WINDOW - EASYLINK_MIN_CCA_BACKOFF_WINDOW) of times before quitting unsuccessfully and running to the callback. If the Tx is successfully scheduled then the callback will be called once the Tx is complete.

Return

EasyLink_Status

Parameters

txPacket: The descriptor for the packet to be Tx’ed.
cb: The tx done function pointer.

EasyLink_Status EasyLink_receive(EasyLink_RxPacket * rxPacket)¶

Blocking call that waits for an Rx Packet.

This function is a blocking call to wait for an Rx packet.

Return

EasyLink_Status

Parameters

rxPacket: The descriptor for the packet to be Rx’ed.

EasyLink_Status EasyLink_receiveAsync(EasyLink_ReceiveCb cb, uint32_t absTime)¶

Enables Asynchronous Packet Rx with non blocking call.

This function is a non blocking call to Rx a packet. The Rx is turned on and the Callback is called once a packet is received. The Rx will timeout if EasyLink_Ctrl_AsyncRx_TimeOut ctrl message is used to set the timeout to something other than 0.

Return

EasyLink_Status

Parameters

cb: The rx function pointer.
absTime: Start time of Rx (0: now !0: absolute radio time to start Rx)

EasyLink_Status EasyLink_abort(void)¶

Abort a previously call Async Tx/Rx.

This function is a blocking call to abort a previous Async Tx/Rx

Return: EasyLink_Status

EasyLink_Status EasyLink_setFrequency(uint32_t ui32Frequency)¶

Sets the Frequency.

This function set the radio to the specified frequency. Note that this will be rounded to the nearest frequency supported by the Frequency Synthesizer.

Return

EasyLink_Status

Parameters

ui32Frequency: Frequency in units of kHz

uint32_t EasyLink_getFrequency(void)¶

Gets the Frequency.

This function gets Frequency in units of kHz. This function will return the value set in the Frequency Synthesizer, and may not be the same as set using EasyLink_setFrequency(). Note that this value does not include any offsets for deviations due to factors such as temperature and hence this API should not be used to get an accurate measure of frequency.

Return: Frequency in units of kHz

EasyLink_Status EasyLink_enableRxAddrFilter(uint8_t * pui8AddrFilterTable, uint8_t ui8AddrSize, uint8_t ui8NumAddrs)¶

Enables the address filter.

This function enables the address filter to filter out address that are not in the address table provided.

Return

EasyLink_Status

Parameters

pui8AddrFilterTable: A uint8 pointer to a variable size 2d array containing the addresses to filter on.
ui8AddrSize: The size of the address elements
ui8NumAddrs: The number of address elements

EasyLink_Status EasyLink_getIeeeAddr(uint8_t * ieeeAddr)¶

Gets the IEEE address.

This function gets the IEEE address

Return

EasyLink_Status

Parameters

ieeeAddr: pointer to an 8 element byte array to write the IEEE address to.

EasyLink_Status EasyLink_setRfPower(int8_t i8TxPowerDbm)¶

Sets the TX Power.

This function sets the Tx Power

Note

The PA mode is chosen at build time, run-time switching from high PA to default PA (or vice versa) is not supported.

Return

EasyLink_Status

Parameters

i8TxPowerDbm: The Tx power in dBm’s to be set.
1. All platforms other than the CC1352P: Value of -10 dBm or values in the range of 0-14 dBm are accepted. Values above 14 are set to 14 dBm while those below 0 are set to -10 dBm
2. CC1352P Default PA: -20 to 14 dBm. Values above 14 dBm will be set to 14 dBm, while values below -20 dBm will cause a configuration error
3. CC1352P High PA: 14 to 20 dBm. Values above 20 dBm will be set to 20 dBm, while values below 14 dBm will cause a configuration error

EasyLink_Status EasyLink_getRfPower(int8_t * pi8TxPowerDbm)¶

Gets the TX Power.

This function gets the Tx Power in dBm, values ranging from -10 to 14 dBm should be expect

Return

EasyLink_Status

Parameters

pi8TxPowerDbm: Pointer to return the transmission power value (dBm)

EasyLink_Status EasyLink_setCtrl(EasyLink_CtrlOption Ctrl, uint32_t ui32Value)¶

Sets advanced configuration options.

This function allows setting some of the advanced configuration options

Return

EasyLink_Status

Parameters

Ctrl: The control option to be set
ui32Value: The value to set the control option to

EasyLink_Status EasyLink_getCtrl(EasyLink_CtrlOption Ctrl, uint32_t * pui32Value)¶

Gets advanced configuration options.

This function allows getting some of the advanced configuration options

Return

EasyLink_Status

Parameters

Ctrl: The control option to get
pui32Value: Pointer to return the control option value

Variables

EasyLink_RfSetting EasyLink_supportedPhys[]: Array containing all the supported EasyLink_rfSettings.

const uint8_t EasyLink_numSupportedPhys¶: Size of the EasyLink_supportedPhys array.

struct EasyLink_Params¶

#include <EasyLink.h>

Structure for EasyLink_init() and EasyLink_Params_init()

Public Members

EasyLink_PhyType ui32ModType¶: PHY type.

RF_ClientCallback pClientEventCb¶: Client event callback function.

RF_ClientEventMask nClientEventMask¶: Client event mask.

EasyLink_GetRandomNumber pGrnFxn¶: Pointer to function that returns a 32-bit unsigned random number.

struct EasyLink_RfSetting¶

#include <EasyLink.h>

Structure for EasyLink_init() containing pointers to all the commands necessary to define an RF setting.

Public Members

EasyLink_PhyType EasyLink_phyType¶: The PHY type that this RF setting defines

RF_Mode* RF_pProp¶: Pointer to RF Mode Command.

rfc_CMD_PROP_RADIO_DIV_SETUP_t* RF_pCmdPropRadioDivSetup¶

rfc_CMD_PROP_RADIO_SETUP_t* RF_pCmdPropRadioSetup¶

union EasyLink_RfSetting::@0 RF_uCmdPropRadio¶: Union containing either a pointer to a divided radio setup command or a pointer to a radio setup command

rfc_CMD_FS_t* RF_pCmdFs¶: Pointer to a frequency setup command.

rfc_CMD_PROP_TX_t* RF_pCmdPropTx¶: Pointer to a RF TX command.

rfc_CMD_PROP_TX_ADV_t* RF_pCmdPropTxAdv¶: Pointer to an advanced RF TX command

rfc_CMD_PROP_RX_ADV_t* RF_pCmdPropRxAdv¶: Pointer to an advanced RF RX command

RF_TxPowerTable_Entry* RF_pTxPowerTable¶: Pointer to a Tx power table.

uint8_t RF_txPowerTableSize¶: Tx power table size.

struct EasyLink_TxPacket¶

#include <EasyLink.h>

Structure for the TX Packet.

Public Members

uint8_t EasyLink_TxPacket::dstAddr[8]: Destination address.

uint32_t absTime¶: Absolute time to Tx packet (0 for immediate) Layer will use last SeqNum used + 1

uint8_t len¶: Payload Length.

uint8_t EasyLink_TxPacket::payload[128]: Payload.

struct EasyLink_RxPacket¶

#include <EasyLink.h>

Structure for the RX’ed Packet.

Public Members

uint8_t EasyLink_RxPacket::dstAddr[8]: Dst Address of RX’ed packet.

int8_t rssi¶: rssi of RX’ed packet

uint32_t absTime¶: Absolute time to turn on Rx when passed (0 for immediate), Or Absolute time that packet was Rx when returned.

uint32_t rxTimeout¶: Relative time in ticks from Rx start to Rx TimeOut a value of 0 means no timeout

uint8_t len¶: length of RX’ed packet

uint8_t EasyLink_RxPacket::payload[128]: payload of RX’ed packet

Warning

doxygenfile: Cannot find file “easylink_config.h