The main header file for the RAIL library.

It describes the external APIs available to a RAIL user

License#

Copyright 2020 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

Macros#

#define

Minimum power for CLPC usage in deci-dBm.

#define

Number of temperature values provided for the EFF thermal protection.

#define

Number of deprecated temperature values in EFF thermal protection.

#define

Number of temperature values provided for HFXO metrics.

#define

Total number of temperature values provided by RAIL_GetTemperature().

#define

Number of bytes provided by RAIL_GetSetEffClpcControl().

Functions#

void
RAIL_GetVersion(RAIL_Version_t *version, bool verbose)

Get the version information for the compiled RAIL library.

RAIL_AddStateBuffer3(RAIL_Handle_t genericRailHandle)

Add a 3rd multiprotocol internal state buffer for use by RAIL_Init().

RAIL_AddStateBuffer4(RAIL_Handle_t genericRailHandle)

Add a 4th multiprotocol internal state buffer for use by RAIL_Init().

RAIL_UseDma(uint8_t channel)

Allocate a DMA channel for RAIL to work with.

RAIL_Init(RAIL_Config_t *railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

bool

Get RAIL initialization status.

uint16_t
RAIL_GetRadioEntropy(RAIL_Handle_t railHandle, uint8_t *buffer, uint16_t bytes)

Collect entropy from the radio if available.

RAIL_ConfigPti(RAIL_Handle_t railHandle, const RAIL_PtiConfig_t *ptiConfig)

Configure PTI pin locations, serial protocols, and baud rates.

RAIL_GetPtiConfig(RAIL_Handle_t railHandle, RAIL_PtiConfig_t *ptiConfig)

Get the currently-active PTI configuration.

RAIL_EnablePti(RAIL_Handle_t railHandle, bool enable)

Enable Packet Trace Interface (PTI) output of packet data.

RAIL_SetPtiProtocol(RAIL_Handle_t railHandle, RAIL_PtiProtocol_t protocol)

Set a protocol that RAIL outputs on PTI.

RAIL_GetPtiProtocol(RAIL_Handle_t railHandle)

Get the protocol that RAIL outputs on PTI.

RAIL_ConfigAntenna(RAIL_Handle_t railHandle, const RAIL_AntennaConfig_t *config)

Configure antenna path and pin locations.

RAIL_GetRfPath(RAIL_Handle_t railHandle, RAIL_AntennaSel_t *rfPath)

Get the default RF path.

RAIL_ConfigRadio(RAIL_Handle_t railHandle, RAIL_RadioConfig_t config)

Load a static radio configuration.

uint16_t
RAIL_SetFixedLength(RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

uint16_t
RAIL_ConfigChannels(RAIL_Handle_t railHandle, const RAIL_ChannelConfig_t *config, RAIL_RadioConfigChangedCallback_t cb)

Configure the channels supported by this device.

RAIL_GetChannelMetadata(RAIL_Handle_t railHandle, RAIL_ChannelMetadata_t *channelMetadata, uint16_t *length, uint16_t minChannel, uint16_t maxChannel)

Get verbose listing of channel metadata for the current channel configuration.

RAIL_IsValidChannel(RAIL_Handle_t railHandle, uint16_t channel)

Check whether the channel exists in RAIL.

RAIL_PrepareChannel(RAIL_Handle_t railHandle, uint16_t channel)

Cause radio settings associated with a particular channel to be applied to hardware.

RAIL_GetChannel(RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

RAIL_GetChannelAlt(RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

uint32_t
RAIL_GetSymbolRate(RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

uint32_t
RAIL_GetBitRate(RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

RAIL_SetPaCTune(RAIL_Handle_t railHandle, uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue)

Set the PA capacitor tune value for transmit and receive.

RAIL_GetSyncWords(RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t *syncWordConfig)

Get the sync words and their length.

RAIL_ConfigSyncWords(RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t *syncWordConfig)

Set the selected sync words and their length.

uint16_t
RAIL_GetWhiteningInitVal(RAIL_Handle_t railHandle)

Sets the whitening initialization value.

uint32_t
RAIL_GetCrcInitVal(RAIL_Handle_t railHandle)

Returns the CRC initialization value.

RAIL_SetWhiteningInitVal(RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

RAIL_SetCrcInitVal(RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

RAIL_ResetWhiteningInitVal(RAIL_Handle_t railHandle)

Restores the whitening initialization value to its initial setting from the Radio Configurator.

RAIL_ResetCrcInitVal(RAIL_Handle_t railHandle)

Restores the CRC initialization value to its initial setting from the Radio Configurator.

Get the current RAIL time.

RAIL_SetTime(RAIL_Time_t time)

Set the current RAIL time.

RAIL_DelayUs(RAIL_Time_t microseconds)

Blocking delay routine for a specified number of microseconds.

RAIL_SetTimer(RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb)

Schedule a timer to expire using the RAIL timebase.

RAIL_GetTimer(RAIL_Handle_t railHandle)

Return the absolute time that the RAIL timer was configured to expire.

void
RAIL_CancelTimer(RAIL_Handle_t railHandle)

Stop the currently scheduled RAIL timer.

bool
RAIL_IsTimerExpired(RAIL_Handle_t railHandle)

Check whether the RAIL timer has expired.

bool
RAIL_IsTimerRunning(RAIL_Handle_t railHandle)

Check whether the RAIL timer is currently running.

bool

Configure the RAIL software timer feature.

RAIL_SetMultiTimer(RAIL_MultiTimer_t *tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void *cbArg)

Start a multitimer instance.

bool
RAIL_CancelMultiTimer(RAIL_MultiTimer_t *tmr)

Stop the currently scheduled RAIL multitimer.

bool
RAIL_IsMultiTimerRunning(RAIL_MultiTimer_t *tmr)

Check if a given timer is running.

bool
RAIL_IsMultiTimerExpired(RAIL_MultiTimer_t *tmr)

Check if a given timer has expired.

RAIL_GetMultiTimer(RAIL_MultiTimer_t *tmr, RAIL_TimeMode_t timeMode)

Get time left before a given timer instance expires.

void
RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)

Configure RAIL timer synchronization.

RAIL_ConfigSleep(RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)

Initialize RAIL timer synchronization.

RAIL_ConfigSleepAlt(RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t *syncConfig)

Initialize RAIL timer synchronization.

RAIL_Sleep(uint16_t wakeupProcessTime, bool *deepSleepAllowed)

Stop the RAIL timer and prepare RAIL for sleep.

RAIL_Wake(RAIL_Time_t elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Initialize RAIL Power Manager.

Stop the RAIL Power Manager.

RAIL_ConfigEvents(RAIL_Handle_t railHandle, RAIL_Events_t mask, RAIL_Events_t events)

Configure radio events.

RAIL_ConfigData(RAIL_Handle_t railHandle, const RAIL_DataConfig_t *dataConfig)

RAIL data management configuration.

uint16_t
RAIL_WriteTxFifo(RAIL_Handle_t railHandle, const uint8_t *dataPtr, uint16_t writeLength, bool reset)

Write data to the transmit FIFO previously established by RAIL_SetTxFifo().

uint16_t
RAIL_SetTxFifo(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data.

uint16_t
RAIL_SetTxFifoAlt(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t startOffset, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data which can start at offset distance from the FIFO base address.

RAIL_SetRxFifo(RAIL_Handle_t railHandle, uint8_t *addr, uint16_t *size)

Set the address of the receive FIFO, a circular buffer used for RX data.

RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)

Set up the receive FIFO to use.

uint16_t
RAIL_ReadRxFifo(RAIL_Handle_t railHandle, uint8_t *dataPtr, uint16_t readLength)

Read packet data from RAIL's internal receive FIFO.

uint16_t
RAIL_SetTxFifoThreshold(RAIL_Handle_t railHandle, uint16_t txThreshold)

Configure the RAIL transmit FIFO almost empty threshold.

uint16_t
RAIL_SetRxFifoThreshold(RAIL_Handle_t railHandle, uint16_t rxThreshold)

Configure the RAIL receive FIFO almost full threshold.

uint16_t
RAIL_GetTxFifoThreshold(RAIL_Handle_t railHandle)

Get the RAIL transmit FIFO almost empty threshold value.

uint16_t
RAIL_GetRxFifoThreshold(RAIL_Handle_t railHandle)

Get the RAIL receive FIFO almost full threshold value.

void
RAIL_ResetFifo(RAIL_Handle_t railHandle, bool txFifo, bool rxFifo)

Reset the RAIL transmit and/or receive FIFOs.

uint16_t
RAIL_GetRxFifoBytesAvailable(RAIL_Handle_t railHandle)

Get the number of bytes used in the receive FIFO.

uint16_t
RAIL_GetTxFifoSpaceAvailable(RAIL_Handle_t railHandle)

Get the number of bytes unused in the transmit FIFO.

RAIL_SetRxTransitions(RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)

Configure RAIL automatic state transitions after RX.

RAIL_GetRxTransitions(RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)

Get the current RAIL automatic state transitions after RX.

RAIL_SetTxTransitions(RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)

Configure RAIL automatic state transitions after TX.

RAIL_GetTxTransitions(RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)

Get the current RAIL automatic state transitions after TX.

RAIL_SetNextTxRepeat(RAIL_Handle_t railHandle, const RAIL_TxRepeatConfig_t *repeatConfig)

Set up automatic repeated transmits after the next transmit.

uint16_t
RAIL_GetTxPacketsRemaining(RAIL_Handle_t railHandle)

Get the number of transmits remaining in a repeat operation.

RAIL_SetStateTiming(RAIL_Handle_t railHandle, RAIL_StateTiming_t *timings)

Configure RAIL automatic state transition timing.

void
RAIL_Idle(RAIL_Handle_t railHandle, RAIL_IdleMode_t mode, bool wait)

Place the radio into an idle state.

RAIL_GetRadioState(RAIL_Handle_t railHandle)

Get the current radio state.

RAIL_GetRadioStateDetail(RAIL_Handle_t railHandle)

Get the detailed current radio state.

RAIL_EnableCacheSynthCal(RAIL_Handle_t railHandle, bool enable)

Enable/disable caching of synth calibration value.

RAIL_ConfigTxPower(RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t *config)

Initialize TX power settings.

RAIL_GetTxPowerConfig(RAIL_Handle_t railHandle, RAIL_TxPowerConfig_t *config)

Get the TX power settings currently used in the amplifier.

RAIL_SetTxPower(RAIL_Handle_t railHandle, RAIL_TxPowerLevel_t powerLevel)

Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).

RAIL_GetTxPower(RAIL_Handle_t railHandle)

Return the current power setting of the PA.

RAIL_ConvertRawToDbm(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPowerLevel_t powerLevel)

Convert raw values written to registers to decibel value (in units of deci-dBm).

RAIL_ConvertDbmToRaw(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t power)

Convert the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.

void
RAIL_VerifyTxPowerCurves(const struct RAIL_TxPowerCurvesConfigAlt *config)

Verify the TX Power Curves on modules.

RAIL_SetTxPowerDbm(RAIL_Handle_t railHandle, RAIL_TxPower_t power)

Set the TX power in terms of deci-dBm instead of raw power level.

RAIL_GetTxPowerDbm(RAIL_Handle_t railHandle)

Get the TX power in terms of deci-dBm instead of raw power level.

RAIL_GetPowerSettingTable(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t *minPower, RAIL_TxPower_t *maxPower, RAIL_TxPowerLevel_t *step)

Get the TX PA power setting table and related values.

RAIL_SetPaPowerSetting(RAIL_Handle_t railHandle, RAIL_PaPowerSetting_t paPowerSetting, RAIL_TxPower_t minPowerDbm, RAIL_TxPower_t maxPowerDbm, RAIL_TxPower_t currentPowerDbm)

Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().

RAIL_GetPaPowerSetting(RAIL_Handle_t railHandle)

Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.

RAIL_EnablePaAutoMode(RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

bool
RAIL_IsPaAutoModeEnabled(RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

RAILCb_PaAutoModeDecision(RAIL_Handle_t railHandle, RAIL_TxPower_t *power, RAIL_TxPowerMode_t *mode, const RAIL_ChannelConfigEntry_t *chCfgEntry)

Callback that decides which PA and power level should be used while in PA auto mode.

RAIL_StartTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit.

RAIL_StartScheduledTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *config, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule sending a packet.

RAIL_StartCcaCsmaTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_CsmaConfig_t *csmaConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit using CSMA.

RAIL_StartCcaLbtTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_LbtConfig_t *lbtConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit using LBT.

RAIL_StartScheduledCcaCsmaTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *scheduleTxConfig, const RAIL_CsmaConfig_t *csmaConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a transmit using CSMA.

RAIL_StartScheduledCcaLbtTx(RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *scheduleTxConfig, const RAIL_LbtConfig_t *lbtConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a transmit using LBT.

RAIL_StopTx(RAIL_Handle_t railHandle, RAIL_StopMode_t mode)

Stop an active or pending transmit.

RAIL_SetCcaThreshold(RAIL_Handle_t railHandle, int8_t ccaThresholdDbm)

Set the CCA threshold in dBm.

RAIL_GetTxPacketDetails(RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Get detailed information about the last packet transmitted.

RAIL_GetTxPacketDetailsAlt(RAIL_Handle_t railHandle, bool isAck, RAIL_Time_t *pPacketTime)

Get detailed information about the last packet transmitted.

RAIL_GetTxPacketDetailsAlt2(RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Get detailed information about the last packet transmitted.

RAIL_GetTxTimePreambleStart(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

RAIL_GetTxTimePreambleStartAlt(RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

RAIL_GetTxTimeSyncWordEnd(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

RAIL_GetTxTimeSyncWordEndAlt(RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

RAIL_GetTxTimeFrameEnd(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of frame.

RAIL_GetTxTimeFrameEndAlt(RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of frame.

void
RAIL_EnableTxHoldOff(RAIL_Handle_t railHandle, bool enable)

Prevent the radio from starting a transmit.

bool
RAIL_IsTxHoldOffEnabled(RAIL_Handle_t railHandle)

Check whether or not TX hold off is enabled.

RAIL_SetTxAltPreambleLength(RAIL_Handle_t railHandle, uint16_t length)

Set an alternate transmitter preamble length.

RAIL_ConfigRxOptions(RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)

Configure receive options.

void
RAIL_IncludeFrameTypeLength(RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

void
RAILCb_ConfigFrameTypeLength(RAIL_Handle_t railHandle, const RAIL_FrameType_t *frameType)

Handle frame type length.

RAIL_StartRx(RAIL_Handle_t railHandle, uint16_t channel, const RAIL_SchedulerInfo_t *schedulerInfo)

Start the receiver on a specific channel.

RAIL_ScheduleRx(RAIL_Handle_t railHandle, uint16_t channel, const RAIL_ScheduleRxConfig_t *cfg, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a receive window for some future time.

RAIL_GetRxPacketInfo(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketInfo_t *pPacketInfo)

Get basic information about a pending or received packet.

void
RAIL_GetRxIncomingPacketInfo(RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t *pPacketInfo)

Get information about the live incoming packet (if any).

void
RAIL_CopyRxPacket(uint8_t *pDest, const RAIL_RxPacketInfo_t *pPacketInfo)

Copy a full packet to a user-specified contiguous buffer.

RAIL_GetRxPacketDetails(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Get detailed information about a received packet.

RAIL_GetRxPacketDetailsAlt(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Get detailed information about a received packet.

RAIL_GetRxTimePreambleStart(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

RAIL_GetRxTimePreambleStartAlt(RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

RAIL_GetRxTimeSyncWordEnd(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

RAIL_GetRxTimeSyncWordEndAlt(RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

RAIL_GetRxTimeFrameEnd(RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of frame.

RAIL_GetRxTimeFrameEndAlt(RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of frame.

RAIL_HoldRxPacket(RAIL_Handle_t railHandle)

Place a temporary hold on this packet's data and information resources within RAIL.

uint16_t
RAIL_PeekRxPacket(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, uint8_t *pDst, uint16_t len, uint16_t offset)

Copy 'len' bytes of packet data starting from 'offset' from the receive FIFO.

RAIL_ReleaseRxPacket(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)

Release RAIL's internal resources for the packet.

int16_t
RAIL_GetRssi(RAIL_Handle_t railHandle, bool wait)

Return the current raw RSSI.

int16_t
RAIL_GetRssiAlt(RAIL_Handle_t railHandle, RAIL_Time_t waitTimeout)

Return the current raw RSSI within a definitive time period.

RAIL_StartAverageRssi(RAIL_Handle_t railHandle, uint16_t channel, RAIL_Time_t averagingTimeUs, const RAIL_SchedulerInfo_t *schedulerInfo)

Start the RSSI averaging over a specified time in us.

bool
RAIL_IsAverageRssiReady(RAIL_Handle_t railHandle)

Query whether the RSSI averaging is done.

int16_t
RAIL_GetAverageRssi(RAIL_Handle_t railHandle)

Get the RSSI averaged over a specified time in us.

RAIL_SetRssiOffset(RAIL_Handle_t railHandle, int8_t rssiOffset)

Set the RSSI offset.

int8_t
RAIL_GetRssiOffset(RAIL_Handle_t railHandle)

Get the RSSI offset.

RAIL_SetRssiDetectThreshold(RAIL_Handle_t railHandle, int8_t rssiThresholdDbm)

Set the RSSI detection threshold(in dBm) to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.

int8_t
RAIL_GetRssiDetectThreshold(RAIL_Handle_t railHandle)

Get the RSSI detection threshold(in dBm).

RAIL_ConvertLqi(RAIL_Handle_t railHandle, RAIL_ConvertLqiCallback_t cb)

Set up a callback function capable of converting a RX packet's LQI value before being consumed by application code.

RAIL_ConfigAddressFilter(RAIL_Handle_t railHandle, const RAIL_AddrConfig_t *addrConfig)

Configure address filtering.

bool
RAIL_EnableAddressFilter(RAIL_Handle_t railHandle, bool enable)

Enable address filtering.

bool
RAIL_IsAddressFilterEnabled(RAIL_Handle_t railHandle)

Return whether address filtering is currently enabled.

void
RAIL_ResetAddressFilter(RAIL_Handle_t railHandle)

Reset the address filtering configuration.

RAIL_SetAddressFilterAddress(RAIL_Handle_t railHandle, uint8_t field, uint8_t index, const uint8_t *value, bool enable)

Set an address for filtering in hardware.

RAIL_SetAddressFilterAddressMask(RAIL_Handle_t railHandle, uint8_t field, const uint8_t *bitMask)

Set an address bit mask for filtering in hardware.

RAIL_EnableAddressFilterAddress(RAIL_Handle_t railHandle, bool enable, uint8_t field, uint8_t index)

Enable address filtering for the specified address.

RAIL_ConfigAutoAck(RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t *config)

Configure and enable automatic acknowledgment.

bool
RAIL_IsAutoAckEnabled(RAIL_Handle_t railHandle)

Return the enable status of the auto-ACK feature.

RAIL_WriteAutoAckFifo(RAIL_Handle_t railHandle, const uint8_t *ackData, uint8_t ackDataLen)

Load the auto-ACK buffer with ACK data.

RAIL_GetAutoAckFifo(RAIL_Handle_t railHandle, uint8_t **ackBuffer, uint16_t *ackBufferBytes)

Get the address and size of the auto-ACK buffer for direct access.

void
RAIL_PauseRxAutoAck(RAIL_Handle_t railHandle, bool pause)

Pause/resume RX auto-ACK functionality.

bool
RAIL_IsRxAutoAckPaused(RAIL_Handle_t railHandle)

Return whether the RX auto-ACK is paused.

void
RAIL_PauseTxAutoAck(RAIL_Handle_t railHandle, bool pause)

Pause/resume TX auto-ACK functionality.

bool
RAIL_IsTxAutoAckPaused(RAIL_Handle_t railHandle)

Return whether the TX auto-ACK is paused.

RAIL_UseTxFifoForAutoAck(RAIL_Handle_t railHandle)

Modify the upcoming ACK to use the Transmit FIFO.

RAIL_CancelAutoAck(RAIL_Handle_t railHandle)

Cancel the upcoming ACK.

bool
RAIL_IsAutoAckWaitingForAck(RAIL_Handle_t railHandle)

Return whether the radio is currently waiting for an ACK.

RAIL_ConfigCal(RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)

Initialize RAIL calibration.

RAIL_Calibrate(RAIL_Handle_t railHandle, RAIL_CalValues_t *calValues, RAIL_CalMask_t calForce)

Start the calibration process.

RAIL_GetPendingCal(RAIL_Handle_t railHandle)

Return the current set of pending calibrations.

RAIL_ApplyIrCalibration(RAIL_Handle_t railHandle, uint32_t imageRejection)

Apply a given image rejection calibration value.

RAIL_ApplyIrCalibrationAlt(RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Apply a given image rejection calibration value.

RAIL_CalibrateIr(RAIL_Handle_t railHandle, uint32_t *imageRejection)

Run the image rejection calibration.

RAIL_CalibrateIrAlt(RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Run the image rejection calibration.

RAIL_CalibrateTemp(RAIL_Handle_t railHandle)

Run the temperature calibration.

RAIL_CalibrateHFXO(RAIL_Handle_t railHandle, int8_t *crystalPPMError)

Performs HFXO compensation.

void
RAIL_EnablePaCal(bool enable)

Enable/disable the PA calibration.

RAIL_StartRfSense(RAIL_Handle_t railHandle, RAIL_RfSenseBand_t band, RAIL_Time_t senseTime, RAIL_RfSense_CallbackPtr_t cb)

Start/stop the RF Sense functionality in Energy Detection Mode for use during low-energy sleep modes.

RAIL_StartSelectiveOokRfSense(RAIL_Handle_t railHandle, RAIL_RfSenseSelectiveOokConfig_t *config)

Start/stop the RF Sense functionality in Selective(OOK Based) Mode for use during low-energy sleep modes.

RAIL_ConfigRfSenseSelectiveOokWakeupPhy(RAIL_Handle_t railHandle)

Switch to RF Sense Selective(OOK) PHY.

RAIL_SetRfSenseSelectiveOokWakeupPayload(RAIL_Handle_t railHandle, uint8_t numSyncwordBytes, uint32_t syncword)

Set the transmit payload for waking up a node configured for RF Sense Selective(OOK).

bool
RAIL_IsRfSensed(RAIL_Handle_t railHandle)

Check whether the RF was sensed.

RAIL_ConfigRxChannelHopping(RAIL_Handle_t railHandle, RAIL_RxChannelHoppingConfig_t *config)

Configure RX channel hopping.

RAIL_EnableRxChannelHopping(RAIL_Handle_t railHandle, bool enable, bool reset)

Enable RX channel hopping.

int16_t
RAIL_GetChannelHoppingRssi(RAIL_Handle_t railHandle, uint8_t channelIndex)

Get RSSI of one channel in the channel hopping sequence, during channel hopping.

RAIL_ConfigRxDutyCycle(RAIL_Handle_t railHandle, const RAIL_RxDutyCycleConfig_t *config)

Configure RX duty cycle mode.

RAIL_EnableRxDutyCycle(RAIL_Handle_t railHandle, bool enable)

Enable RX duty cycle mode.

RAIL_GetDefaultRxDutyCycleConfig(RAIL_Handle_t railHandle, RAIL_RxDutyCycleConfig_t *config)

Get the default RX duty cycle configuration.

void
RAIL_YieldRadio(RAIL_Handle_t railHandle)

Yield the radio to other configurations.

RAIL_GetSchedulerStatus(RAIL_Handle_t railHandle)

Get the status of the RAIL scheduler.

RAIL_GetSchedulerStatusAlt(RAIL_Handle_t railHandle, RAIL_SchedulerStatus_t *pSchedulerStatus, RAIL_Status_t *pRailStatus)

Get the status of the RAIL scheduler, specific to the radio operation, along with RAIL_Status_t returned by RAIL API invoked by the RAIL scheduler.

RAIL_SetTaskPriority(RAIL_Handle_t railHandle, uint8_t priority, RAIL_TaskType_t taskType)

Change the priority of a specified task type in multiprotocol.

Get time needed to switch between protocols.

void
RAIL_SetTransitionTime(RAIL_Time_t transitionTime)

Set time needed to switch between protocols.

RAIL_ConfigDirectMode(RAIL_Handle_t railHandle, const RAIL_DirectModeConfig_t *directModeConfig)

Configure direct mode for RAIL.

RAIL_EnableDirectMode(RAIL_Handle_t railHandle, bool enable)

Enable or disable direct mode for RAIL.

RAIL_EnableDirectModeAlt(RAIL_Handle_t railHandle, bool enableDirectTx, bool enableDirectRx)

Enable or disable direct mode for RAIL.

uint32_t
RAIL_GetRadioClockFreqHz(RAIL_Handle_t railHandle)

Get the radio subsystem clock frequency in Hz.

RAIL_SetTune(RAIL_Handle_t railHandle, uint32_t tune)

Set the crystal tuning.

uint32_t
RAIL_GetTune(RAIL_Handle_t railHandle)

Get the crystal tuning.

RAIL_SetTuneDelta(RAIL_Handle_t railHandle, int32_t delta)

Set the crystal tuning delta.

int32_t
RAIL_GetTuneDelta(RAIL_Handle_t railHandle)

Get the crystal tuning delta on EFR32xG2 series devices.

RAIL_GetRxFreqOffset(RAIL_Handle_t railHandle)

Get the frequency offset.

RAIL_SetFreqOffset(RAIL_Handle_t railHandle, RAIL_FrequencyOffset_t freqOffset)

Set the nominal radio frequency offset.

RAIL_StartTxStream(RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode)

Start transmitting a stream on a certain channel.

RAIL_StartTxStreamAlt(RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode, RAIL_TxOptions_t options)

Start transmitting a stream on a certain channel with the ability to select an antenna.

RAIL_StopTxStream(RAIL_Handle_t railHandle)

Stop stream transmission.

RAIL_StopInfinitePreambleTx(RAIL_Handle_t railHandle)

Stop infinite preamble transmission started and start transmitting the rest of the packet.

RAIL_ConfigVerification(RAIL_Handle_t railHandle, RAIL_VerifyConfig_t *configVerify, RAIL_RadioConfig_t radioConfig, RAIL_VerifyCallbackPtr_t cb)

Configure the verification of radio memory contents.

RAIL_Verify(RAIL_VerifyConfig_t *configVerify, uint32_t durationUs, bool restart)

Verify radio memory contents.

RAIL_ConfigEff(RAIL_Handle_t genericRailHandle, const RAIL_EffConfig_t *config)

Configure the attached EFF device.

RAIL_GetTemperature(RAIL_Handle_t railHandle, int16_t tempBuffer[((3U)+(6U)+(2U)+(1U))], bool reset)

Get the different temperature measurements in Kelvin done by sequencer or host.

RAIL_GetSetEffClpcControl(RAIL_Handle_t railHandle, uint16_t tempBuffer[(52U)/sizeof(uint16_t)], bool reset)

Get the different EFF Control measurements.

RAIL_GetSetEffClpcFemdata(RAIL_Handle_t railHandle, uint8_t *newMode, bool changeMode)

Copy the current FEM_DATA pin values into newMode.

RAIL_GetSetEffLnaRuralUrbanMv(RAIL_Handle_t railHandle, uint16_t *newTrip, bool changeTrip)

Copy the current Rural to Urban trip voltage into newTrip.

RAIL_GetSetEffLnaUrbanBypassMv(RAIL_Handle_t railHandle, uint16_t *newTrip, bool changeTrip)

Copy the current Urban to Bypass trip voltage into newTrip.

RAIL_GetSetEffLnaUrbanDwellTimeMs(RAIL_Handle_t railHandle, uint32_t *newDwellTime, bool changeDwellTime)

Copy the current Urban dwell time into newDwellTime.

RAIL_GetSetEffLnaBypassDwellTimeMs(RAIL_Handle_t railHandle, uint32_t *newDwellTime, bool changeDwellTime)

Copy the current Bypass dwell time into newDwellTime.

RAIL_GetSetEffClpcFastLoopCal(RAIL_Handle_t railHandle, RAIL_EffModeSensor_t modeSensorIndex, RAIL_EffCalConfig_t *calibrationEntry, bool changeValues)

If changeValues is true, update current CLPC Fast Loop calibration values using the new variables.

RAIL_GetSetEffClpcFastLoopCalSlp(RAIL_Handle_t railHandle, RAIL_EffModeSensor_t modeSensorIndex, int16_t *newSlope1e1MvPerDdbm, int16_t *newoffset290Ddbm, bool changeValues)

If changeValues is true, update current CLPC Fast Loop calibration equations using the new variables.

RAIL_GetSetEffClpcFastLoop(RAIL_Handle_t railHandle, RAIL_EffModeSensor_t modeSensorIndex, uint16_t *newTargetMv, uint16_t *newSlopeMvPerPaLevel, bool changeValues)

If changeValues is true, update current CLPC Fast Loop Target and Slope.

RAIL_GetSetEffClpcEnable(RAIL_Handle_t railHandle, uint8_t *newClpcEnable, bool changeClpcEnable)

Copy the current CLPC Enable in to newClpcEnable.

RAIL_GetSetEffTempThreshold(RAIL_Handle_t railHandle, uint16_t *newThresholdK, bool changeThreshold)

Get and set the EFF temperature threshold.

RAIL_ConfigThermalProtection(RAIL_Handle_t genericRailHandle, const RAIL_ChipTempConfig_t *chipTempConfig)

Enable or disable the thermal protection if RAIL_SUPPORTS_THERMAL_PROTECTION is defined and update the temperature threshold and cool down hysteresis preventing or allowing transmissions.

RAIL_GetThermalProtection(RAIL_Handle_t genericRailHandle, RAIL_ChipTempConfig_t *chipTempConfig)

Get the current thermal configuration parameter and status.

void
RAILCb_AssertFailed(RAIL_Handle_t railHandle, RAIL_AssertErrorCodes_t errorCode)

Callback called upon failed assertion.

RAIL_StartThermistorMeasurement(RAIL_Handle_t railHandle)

Start a thermistor measurement.

RAIL_GetThermistorImpedance(RAIL_Handle_t railHandle, uint32_t *thermistorImpedance)

Get the thermistor impedance measurement and return RAIL_INVALID_THERMISTOR_VALUE if the thermistor is not properly configured or the thermistor measurement is not ready.

RAIL_ConvertThermistorImpedance(RAIL_Handle_t railHandle, uint32_t thermistorImpedance, int16_t *thermistorTemperatureC)

Convert the thermistor impedance into temperature, in Celsius.

RAIL_ComputeHFXOPPMError(RAIL_Handle_t railHandle, int16_t crystalTemperatureC, int8_t *crystalPPMError)

Compute the crystal PPM deviation from the thermistor temperature.

RAIL_ConfigHFXOThermistor(RAIL_Handle_t railHandle, const RAIL_HFXOThermistorConfig_t *pHfxoThermistorConfig)

Configure the GPIO for thermistor usage.

RAIL_ConfigHFXOCompensation(RAIL_Handle_t railHandle, const RAIL_HFXOCompensationConfig_t *pHfxoCompensationConfig)

Configure the temperature parameters for HFXO compensation.

RAIL_GetHFXOCompensationConfig(RAIL_Handle_t railHandle, RAIL_HFXOCompensationConfig_t *pHfxoCompensationConfig)

Get the temperature parameters for HFXO compensation.

RAIL_CompensateHFXO(RAIL_Handle_t railHandle, int8_t crystalPPMError)

Compute a frequency offset and compensate HFXO accordingly.

bool
RAIL_Supports2p4GHzBand(RAIL_Handle_t railHandle)

Indicate whether RAIL supports 2.4 GHz band operation on this chip.

bool
RAIL_SupportsSubGHzBand(RAIL_Handle_t railHandle)

Indicate whether RAIL supports SubGHz band operation on this chip.

bool
RAIL_SupportsDualBand(RAIL_Handle_t railHandle)

Indicate whether this chip supports dual 2.4 GHz and SubGHz band operation.

bool
RAIL_SupportsAddrFilterAddressBitMask(RAIL_Handle_t railHandle)

Indicate whether this chip supports bit masked address filtering.

bool
RAIL_SupportsAddrFilterMask(RAIL_Handle_t railHandle)

Indicate whether this chip supports address filter mask information for incoming packets in RAIL_RxPacketInfo_t::filterMask and RAIL_IEEE802154_Address_t::filterMask.

bool
RAIL_SupportsAlternateTxPower(RAIL_Handle_t railHandle)

Indicate whether this chip supports alternate TX power settings.

bool
RAIL_SupportsAntennaDiversity(RAIL_Handle_t railHandle)

Indicate whether this chip supports antenna diversity.

bool
RAIL_SupportsAuxAdc(RAIL_Handle_t railHandle)

Indicate whether RAIL supports AUXADC measurements on this chip.

bool
RAIL_SupportsChannelHopping(RAIL_Handle_t railHandle)

Indicate whether RAIL supports channel hopping on this chip.

bool
RAIL_SupportsDirectMode(RAIL_Handle_t railHandle)

Indicate whether this chip supports direct mode.

bool
RAIL_SupportsDualSyncWords(RAIL_Handle_t railHandle)

Indicate whether this chip supports dual sync words.

bool
RAIL_SupportsTxRepeatStartToStart(RAIL_Handle_t railHandle)

Indicate whether this chip supports start to start TX repeats.

bool
RAIL_SupportsEff(RAIL_Handle_t railHandle)

Indicate whether this chip supports EFF.

bool
RAIL_SupportsExternalThermistor(RAIL_Handle_t railHandle)

Indicate whether RAIL supports thermistor measurements on this chip.

bool
RAIL_SupportsHFXOCompensation(RAIL_Handle_t railHandle)

Indicate whether RAIL supports HFXO compensation on this chip.

bool
RAIL_SupportsMfm(RAIL_Handle_t railHandle)

Indicate whether this chip supports MFM protocol.

bool
RAIL_SupportsOFDMPA(RAIL_Handle_t railHandle)

Indicate whether RAIL supports OFDM band operation on this chip.

bool
RAIL_SupportsPrecisionLFRCO(RAIL_Handle_t railHandle)

Indicate whether this chip supports a high-precision LFRCO.

bool
RAIL_SupportsRadioEntropy(RAIL_Handle_t railHandle)

Indicate whether this chip supports radio entropy.

bool
RAIL_SupportsRfSenseEnergyDetection(RAIL_Handle_t railHandle)

Indicate whether RAIL supports RFSENSE Energy Detection Mode on this chip.

bool
RAIL_SupportsRfSenseSelectiveOok(RAIL_Handle_t railHandle)

Indicate whether RAIL supports RFSENSE Selective(OOK) Mode on this chip.

bool
RAIL_SupportsRssiDetectThreshold(RAIL_Handle_t railHandle)

Indicate whether this chip supports configurable RSSI threshold set by RAIL_SetRssiDetectThreshold().

bool
RAIL_SupportsRxDirectModeDataToFifo(RAIL_Handle_t railHandle)

Indicate whether this chip supports RX direct mode data to FIFO.

bool
RAIL_SupportsRxRawData(RAIL_Handle_t railHandle)

Indicate whether this chip supports raw RX data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.

bool
RAIL_SupportsSQPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports SQ-based PHY.

bool
RAIL_SupportsTxPowerMode(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t powerMode, RAIL_TxPowerLevel_t *pMaxPowerLevel)

Indicate whether this chip supports a particular power mode (PA).

bool
RAIL_SupportsTxPowerModeAlt(RAIL_Handle_t railHandle, RAIL_TxPowerMode_t *powerMode, RAIL_TxPowerLevel_t *maxPowerLevel, RAIL_TxPowerLevel_t *minPowerLevel)

Indicate whether this chip supports a particular power mode (PA) and provides the maximum and minimum power level for that power mode if supported by the chip.

bool
RAIL_SupportsTxToTx(RAIL_Handle_t railHandle)

Indicate whether this chip supports automatic TX to TX transitions.

bool
RAIL_SupportsProtocolBLE(RAIL_Handle_t railHandle)

Indicate whether RAIL supports the BLE protocol on this chip.

bool
RAIL_BLE_Supports1MbpsNonViterbi(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 1Mbps Non-Viterbi PHY.

bool
RAIL_BLE_Supports1MbpsViterbi(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 1Mbps Viterbi PHY.

bool
RAIL_BLE_Supports1Mbps(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 1Mbps operation.

bool
RAIL_BLE_Supports2MbpsNonViterbi(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 2Mbps Non-Viterbi PHY.

bool
RAIL_BLE_Supports2MbpsViterbi(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 2Mbps Viterbi PHY.

bool
RAIL_BLE_Supports2Mbps(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE 2Mbps operation.

bool
RAIL_BLE_SupportsAntennaSwitching(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE Antenna Switching needed for Angle-of-Arrival receives or Angle-of-Departure transmits.

bool
RAIL_BLE_SupportsCodedPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE Coded PHY used for Long-Range.

bool
RAIL_BLE_SupportsCte(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE CTE (Constant Tone Extension) needed for Angle-of-Arrival/Departure transmits.

bool
RAIL_BLE_SupportsIQSampling(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE IQ Sampling needed for Angle-of-Arrival/Departure receives.

bool
RAIL_BLE_SupportsPhySwitchToRx(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE PHY switch to RX functionality, which is used to switch BLE PHYs at a specific time to receive auxiliary packets.

bool
RAIL_BLE_SupportsQuuppa(RAIL_Handle_t railHandle)

Indicate whether this chip supports the Quuppa PHY.

bool
RAIL_BLE_SupportsSignalIdentifier(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE signal identifier.

bool
RAIL_BLE_SupportsSimulscanPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports BLE Simulscan PHY used for simultaneous BLE 1Mbps and Coded PHY reception.

bool
RAIL_SupportsProtocolIEEE802154(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4 protocol.

bool
RAIL_IEEE802154_SupportsCoexPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4 Wi-Fi Coexistence PHY.

bool
RAIL_SupportsIEEE802154Band2P4(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4 2.4 GHz band variant.

bool
RAIL_SupportsThermalProtection(RAIL_Handle_t railHandle)

Indicate whether this chip supports the thermal protection.

bool

Indicate whether this chip supports the IEEE 802.15.4 2.4 RX channel switching.

bool
RAIL_IEEE802154_SupportsCustom1Phy(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4 PHY with custom settings.

bool
RAIL_IEEE802154_SupportsFemPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4 front end module optimized PHY.

bool

Indicate whether this chip supports canceling the frame-pending lookup event RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND when the radio transitions to a state that renders the the reporting of this event moot (i.e., too late for the stack to influence the outgoing ACK).

bool

Indicate whether this chip supports early triggering of the frame-pending lookup event RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND just after MAC address fields have been received.

bool
RAIL_IEEE802154_SupportsDualPaConfig(RAIL_Handle_t railHandle)

Indicate whether RAIL supports dual PA mode on this chip.

bool
RAIL_IEEE802154_SupportsEEnhancedAck(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4E-2012 Enhanced ACKing.

bool

Indicate whether this chip supports IEEE 802.15.4E-2012 Multipurpose frame reception.

bool
RAIL_IEEE802154_SupportsESubsetGB868(RAIL_Handle_t railHandle)

Indicate whether this chip supports the IEEE 802.15.4E-2012 feature subset needed for Zigbee R22 GB868.

bool
RAIL_IEEE802154_SupportsG4ByteCrc(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4G-2012 reception and transmission of frames with 4-byte CRC.

bool
RAIL_IEEE802154_SupportsGDynFec(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4G dynamic FEC.

bool
RAIL_SupportsProtocolWiSUN(RAIL_Handle_t railHandle)

Indicate whether this chip supports Wi-SUN.

bool
RAIL_IEEE802154_SupportsGModeSwitch(RAIL_Handle_t railHandle)

Indicate whether this chip supports Wi-SUN mode switching.

bool
RAIL_IEEE802154_SupportsGSubsetGB868(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4G-2012 feature subset needed for Zigbee R22 GB868.

bool
RAIL_IEEE802154_SupportsGUnwhitenedRx(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4G-2012 reception of unwhitened frames.

bool
RAIL_IEEE802154_SupportsGUnwhitenedTx(RAIL_Handle_t railHandle)

Indicate whether this chip supports IEEE 802.15.4G-2012 transmission of unwhitened frames.

bool
RAIL_WMBUS_SupportsSimultaneousTCRx(RAIL_Handle_t railHandle)

Indicate whether this chip supports WMBUS simultaneous M2O RX of T and C modes.

bool
RAIL_SupportsProtocolZWave(RAIL_Handle_t railHandle)

Indicate whether this chip supports the Z-Wave protocol.

bool
RAIL_ZWAVE_SupportsConcPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports the Z-Wave concurrent PHY.

bool
RAIL_ZWAVE_SupportsEnergyDetectPhy(RAIL_Handle_t railHandle)

Indicate whether this chip supports the Z-Wave energy detect PHY.

bool
RAIL_ZWAVE_SupportsRegionPti(RAIL_Handle_t railHandle)

Indicate whether this chip supports Z-Wave Region in PTI.

bool

Indicate whether this chip supports IEEE 802.15.4 signal identifier.

bool
RAIL_SupportsFastRx2Rx(RAIL_Handle_t railHandle)

Indicate whether this chip supports fast RX2RX.

bool
RAIL_SupportsCollisionDetection(RAIL_Handle_t railHandle)

Indicate whether this chip supports collision detection.

bool
RAIL_SupportsProtocolSidewalk(RAIL_Handle_t railHandle)

Indicate whether this chip supports Sidewalk protocol.

Macro Definition Documentation#

RAIL_CLPC_MINIMUM_POWER#

#define RAIL_CLPC_MINIMUM_POWER
Value:
180

Minimum power for CLPC usage in deci-dBm.

Below this power CLPC will not activate. Recommend staying above 19 dBm for best performance. Signed unit, do not add U.


Definition at line 6167 of file common/rail.h

RAIL_EFF_TEMP_MEASURE_COUNT#

#define RAIL_EFF_TEMP_MEASURE_COUNT
Value:
(6U)

Number of temperature values provided for the EFF thermal protection.


Definition at line 6182 of file common/rail.h

RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT#

#define RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT
Value:
(2U)

Number of deprecated temperature values in EFF thermal protection.


Definition at line 6184 of file common/rail.h

RAIL_HFXO_TEMP_MEASURE_COUNT#

#define RAIL_HFXO_TEMP_MEASURE_COUNT
Value:
(1U)

Number of temperature values provided for HFXO metrics.


Definition at line 6186 of file common/rail.h

RAIL_TEMP_MEASURE_COUNT#

#define RAIL_TEMP_MEASURE_COUNT
Value:
(RAIL_CHIP_TEMP_MEASURE_COUNT \
+ RAIL_EFF_TEMP_MEASURE_COUNT \
+ RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT \
+ RAIL_HFXO_TEMP_MEASURE_COUNT)

Total number of temperature values provided by RAIL_GetTemperature().


Definition at line 6189 of file common/rail.h

RAIL_EFF_CONTROL_SIZE#

#define RAIL_EFF_CONTROL_SIZE
Value:
(52U)

Number of bytes provided by RAIL_GetSetEffClpcControl().


Definition at line 6227 of file common/rail.h

Function Documentation#

RAIL_GetVersion#

void RAIL_GetVersion (RAIL_Version_t *version, bool verbose)

Get the version information for the compiled RAIL library.

Parameters
[out]version

A pointer to RAIL_Version_t structure to populate with version information.

[in]verbose

Populate RAIL_Version_t struct with verbose information.

The version information contains a major version number, a minor version number, and a rev (revision) number.


Definition at line 82 of file common/rail.h

RAIL_AddStateBuffer3#

RAIL_Status_t RAIL_AddStateBuffer3 (RAIL_Handle_t genericRailHandle)

Add a 3rd multiprotocol internal state buffer for use by RAIL_Init().

Parameters
[in]genericRailHandle

A generic RAIL instance handle.

Returns

  • Status code indicating success of the function call. An error is returned if the 3rd state buffer was previously added or this isn't the RAIL multiprotocol library.


Definition at line 151 of file common/rail.h

RAIL_AddStateBuffer4#

RAIL_Status_t RAIL_AddStateBuffer4 (RAIL_Handle_t genericRailHandle)

Add a 4th multiprotocol internal state buffer for use by RAIL_Init().

Parameters
[in]genericRailHandle

A generic RAIL instance handle.

Returns

  • Status code indicating success of the function call. An error is returned if the 4th state buffer was previously added. or this isn't the RAIL multiprotocol library.


Definition at line 161 of file common/rail.h

RAIL_UseDma#

RAIL_Status_t RAIL_UseDma (uint8_t channel)

Allocate a DMA channel for RAIL to work with.

Parameters
[in]channel

The DMA channel to use when copying memory. If a value of RAIL_DMA_INVALID is passed, RAIL will stop using any DMA channel.

Returns

  • Status code indicating success of the function call.

To use this API, the application must initialize the DMA engine on the chip and allocate a DMA channel. This channel will be used periodically to copy memory more efficiently. Call this function before RAIL_Init to have the most benefit. If the application needs to take back control of the DMA channel that RAIL is using, this API may be called with a channel of RAIL_DMA_INVALID to tell RAIL to stop using DMA.


Definition at line 177 of file common/rail.h

RAIL_Init#

RAIL_Handle_t RAIL_Init (RAIL_Config_t *railCfg, RAIL_InitCompleteCallbackPtr_t cb)

Initialize RAIL.

Parameters
[inout]railCfg

The configuration and state structure for setting up the library, which contains memory and other options that RAIL needs. This structure must be allocated in application global read-write memory. RAIL may modify fields within or referenced by this structure during its operation.

[in]cb

A callback that notifies the application when the radio is finished initializing and is ready for further configuration. This callback is useful for potential transceiver products that require a power up sequence before further configuration is available. After the callback fires, the radio is ready for additional configuration before transmit and receive operations.

Returns

  • Handle for initialized rail instance or NULL if an invalid value was passed in the railCfg.

Note

  • Call this function only once per protocol. If called again, it will do nothing and return NULL.


Definition at line 318 of file common/rail.h

RAIL_IsInitialized#

bool RAIL_IsInitialized (void)

Get RAIL initialization status.

Parameters
N/A

Returns

  • True if the radio has finished initializing and false otherwise.

RAIL APIs, e.g., RAIL_GetTime(), which work only if RAIL_Init() has been called, can use RAIL_IsInitialized() to determine whether RAIL has been initialized or not.


Definition at line 330 of file common/rail.h

RAIL_GetRadioEntropy#

uint16_t RAIL_GetRadioEntropy (RAIL_Handle_t railHandle, uint8_t *buffer, uint16_t bytes)

Collect entropy from the radio if available.

Parameters
[in]railHandle

A RAIL instance handle.

[out]buffer

The buffer to write the collected entropy.

[in]bytes

The number of bytes to fill in the input buffer.

Returns

  • Returns the number of bytes of entropy collected. For chips that don't support entropy collection, the function returns 0. Values less than the requested amount may also be returned on platforms that use entropy pools to collect random data periodically.

Attempts to fill the provided buffer with the requested number of bytes of entropy. If the requested number of bytes can't be provided, as many bytes as possible will be filled and returned. For chips that do not support this function, 0 bytes are always returned. For information about the specific mechanism for gathering entropy, see documentation for the chip family.


Definition at line 350 of file common/rail.h

RAIL_ConfigPti#

RAIL_Status_t RAIL_ConfigPti (RAIL_Handle_t railHandle, const RAIL_PtiConfig_t *ptiConfig)

Configure PTI pin locations, serial protocols, and baud rates.

Parameters
[in]railHandle

A RAIL instance handle (currently not used).

[in]ptiConfig

A configuration structure applied to the relevant PTI registers. A NULL ptiConfig will produce undefined behavior.

Returns

  • Status code indicating success of the function call.

This method must be called before RAIL_EnablePti() is called. Although a RAIL handle is included for potential future expansion of this function, it is currently not used. That is, there is only one PTI configuration that can be active on a chip, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch), and the configuration is not saved in the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

PTI should be configured only when the radio is off (idle).

Note

  • On EFR32 platforms GPIO configuration must be unlocked (see GPIO->LOCK register) to configure or use PTI.


Definition at line 389 of file common/rail.h

RAIL_GetPtiConfig#

RAIL_Status_t RAIL_GetPtiConfig (RAIL_Handle_t railHandle, RAIL_PtiConfig_t *ptiConfig)

Get the currently-active PTI configuration.

Parameters
[in]railHandle

A RAIL instance handle (currently not used).

[out]ptiConfig

A configuration structure filled with the active PTI configuration.

Returns

  • RAIL status indicating success of the function call.

Although most combinations of configurations can be set, it is safest to call this method after configuration to confirm which values were actually set. As in RAIL_ConfigPti, railHandle is not used. This function always returns the single active PTI configuration regardless of the active protocol. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.


Definition at line 407 of file common/rail.h

RAIL_EnablePti#

RAIL_Status_t RAIL_EnablePti (RAIL_Handle_t railHandle, bool enable)

Enable Packet Trace Interface (PTI) output of packet data.

Parameters
[in]railHandle

A RAIL instance handle (currently not used).

[in]enable

PTI is enabled if true; disable if false.

Returns

  • RAIL status indicating success of the function call.

Similarly to having only one PTI configuration per chip, PTI can only be enabled or disabled for all protocols. It cannot be individually set to enabled and disabled per protocol (unless the application switches it when the protocol switches), and enable/disable is not saved as part of the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.

PTI should be enabled or disabled only when the radio is off (idle).

Warnings

  • On EFR32 platforms GPIO configuration must be unlocked (see GPIO->LOCK register) to configure or use PTI, otherwise a fault or assert might occur. If GPIO configuration locking is desired, PTI must be disabled beforehand either with this function or with RAIL_ConfigPti() using RAIL_PTI_MODE_DISABLED.


Definition at line 434 of file common/rail.h

RAIL_SetPtiProtocol#

RAIL_Status_t RAIL_SetPtiProtocol (RAIL_Handle_t railHandle, RAIL_PtiProtocol_t protocol)

Set a protocol that RAIL outputs on PTI.

Parameters
[in]railHandle

A RAIL instance handle.

[in]protocol

The enumeration representing which protocol the node is using.

Returns

  • Status code indicating success of the function call.

The protocol is output via PTI for each packet. Before any protocol is set, the default value is RAIL_PTI_PROTOCOL_CUSTOM. Use one of the enumeration values so that the Network Analyzer can decode the packet.

Note

  • This function cannot be called unless the radio is currently in the RAIL_RF_STATE_IDLE or RAIL_RF_STATE_INACTIVE states. For this reason, call this function early on before starting radio operations and not changed later.


Definition at line 454 of file common/rail.h

RAIL_GetPtiProtocol#

RAIL_PtiProtocol_t RAIL_GetPtiProtocol (RAIL_Handle_t railHandle)

Get the protocol that RAIL outputs on PTI.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • PTI protocol in use.


Definition at line 463 of file common/rail.h

RAIL_ConfigAntenna#

RAIL_Status_t RAIL_ConfigAntenna (RAIL_Handle_t railHandle, const RAIL_AntennaConfig_t *config)

Configure antenna path and pin locations.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A configuration structure applied to the relevant Antenna Configuration registers. A NULL configuration will produce undefined behavior.

Warnings

  • This API must be called before any TX or RX occurs. Otherwise, the antenna configurations for those functions will not take effect.

Returns

  • Status code indicating success of the function call.

This function informs RAIL how to select each antenna, but not when. Antenna selection for receive is controlled by the RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA0 and RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA1 options (and the RAIL_RxOptions_t::RAIL_RX_OPTION_ANTENNA_AUTO combination). Antenna selection for transmit is controlled by the RAIL_TxOptions_t::RAIL_TX_OPTION_ANTENNA0 and RAIL_TxOptions_t::RAIL_TX_OPTION_ANTENNA1 options.

Although a RAIL handle is included for potential future expansion of this function, it is currently not used. That is, only one antenna configuration can be active on a chip, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch), and the configuration is not saved in the RAIL instance. For optimal future compatibility, pass in a chip-specific handle, such as RAIL_EFR32_HANDLE.


Definition at line 504 of file common/rail.h

RAIL_GetRfPath#

RAIL_Status_t RAIL_GetRfPath (RAIL_Handle_t railHandle, RAIL_AntennaSel_t *rfPath)

Get the default RF path.

Parameters
[in]railHandle

A RAIL instance handle.

[out]rfPath

Pointer to RF path.

Returns

  • A status code indicating success of the function call.

If multiple protocols are used, this function returns RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later, for example when RAIL_EVENT_CONFIG_SCHEDULED trigger.


Definition at line 519 of file common/rail.h

RAIL_ConfigRadio#

RAIL_Status_t RAIL_ConfigRadio (RAIL_Handle_t railHandle, RAIL_RadioConfig_t config)

Load a static radio configuration.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to a radio configuration.

Returns

  • Status code indicating success of the function call.

The configuration passed into this function should be auto-generated and not manually created or edited. By default, do not call this function in RAIL 2.x and later unless instructed by Silicon Labs because it may bypass updating certain RAIL state. In RAIL 2.x and later, the RAIL_ConfigChannels function applies the default radio configuration automatically.


Definition at line 559 of file common/rail.h

RAIL_SetFixedLength#

uint16_t RAIL_SetFixedLength (RAIL_Handle_t railHandle, uint16_t length)

Modify the currently configured fixed frame length in bytes.

Parameters
[in]railHandle

A RAIL instance handle.

[in]length

The expected fixed frame length. A value of 0 is infinite. A value of RAIL_SETFIXEDLENGTH_INVALID restores the frame's length back to the length specified by the default frame type configuration.

Returns

  • Length configured; The new frame length configured into the hardware for use. 0 if in infinite mode, or RAIL_SETFIXEDLENGTH_INVALID if the frame length has not yet been overridden by a valid value.

Sets the fixed-length configuration for transmit and receive. Be careful when using this function in receive and transmit as this function changes the default frame configuration and remains in force until it is called again with an input value of RAIL_SETFIXEDLENGTH_INVALID. This function will override any fixed or variable length settings from a radio configuration.


Definition at line 580 of file common/rail.h

RAIL_ConfigChannels#

uint16_t RAIL_ConfigChannels (RAIL_Handle_t railHandle, const RAIL_ChannelConfig_t *config, RAIL_RadioConfigChangedCallback_t cb)

Configure the channels supported by this device.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

A pointer to the channel configuration for your device. This pointer will be cached in the library so it must exist for the runtime of the application. Typically, this should be what is stored in Flash by the configuration tool.

[in]cb

Function called whenever a radio configuration change occurs.

Returns

  • Returns the first available channel in the configuration.

When configuring channels on EFR32, the radio tuner is reconfigured based on the frequency and channel spacing in the channel configuration.

Note

  • config can be NULL to simply register or unregister the cb callback function when using RAIL internal protocol-specific radio configuration APIs for BLE, IEEE 802.15.4, or Z-Wave, which lack callback specification. In this use case, 0 is returned.


Definition at line 601 of file common/rail.h

RAIL_GetChannelMetadata#

RAIL_Status_t RAIL_GetChannelMetadata (RAIL_Handle_t railHandle, RAIL_ChannelMetadata_t *channelMetadata, uint16_t *length, uint16_t minChannel, uint16_t maxChannel)

Get verbose listing of channel metadata for the current channel configuration.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channelMetadata

Allocated array that will be populated with channel metadata.

[inout]length

Pointer to the length of the channelMetadata. This value will be updated to the number of channels written to the array.

[in]minChannel

Minimum channel number about which to collect data.

[in]maxChannel

Maximum channel number about which to collect data.

Returns

  • Status of the call. RAIL_STATUS_INVALID_PARAMETER means that, based on the currently active radio configuration, there are more channels to write than there is space provided in the allocated channelMetadata. However, the channel metadata that was written is valid. RAIL_STATUS_INVALID_STATE indicates that the channel configuration has not been configured. RAIL_STATUS_NO_ERROR indicates complete success.


Definition at line 623 of file common/rail.h

RAIL_IsValidChannel#

RAIL_Status_t RAIL_IsValidChannel (RAIL_Handle_t railHandle, uint16_t channel)

Check whether the channel exists in RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel number to check.

Returns

  • Returns RAIL_STATUS_NO_ERROR if channel exists

Returns RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist in the channel configuration currently used or RAIL_STATUS_NO_ERROR if the channel is valid.


Definition at line 640 of file common/rail.h

RAIL_PrepareChannel#

RAIL_Status_t RAIL_PrepareChannel (RAIL_Handle_t railHandle, uint16_t channel)

Cause radio settings associated with a particular channel to be applied to hardware.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The channel to prepare for use.

Returns

This function walks the channelConfigEntry list and applies the configuration associated with the specified channel. This function manually changes channels without starting a TX or RX operation.

When successful, the radio is idled. When unsuccessful, the radio state will not be altered.


Definition at line 660 of file common/rail.h

RAIL_GetChannel#

RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channel

The channel for which RAIL is currently configured.

Returns

  • RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or RAIL_STATUS_INVALID_PARAMETER if channel parameter is NULL.

This function returns the channel most recently specified in API calls that pass in a channel to tune to, namely RAIL_PrepareChannel, RAIL_StartTx, RAIL_StartScheduledTx, RAIL_StartCcaCsmaTx, RAIL_StartCcaLbtTx, RAIL_StartScheduledCcaCsmaTx, RAIL_StartScheduledCcaLbtTx, RAIL_StartRx, RAIL_ScheduleRx, RAIL_StartAverageRssi, RAIL_StartTxStream, RAIL_StartTxStreamAlt. It doesn't follow changes RAIL performs implicitly during channel hopping and mode switch.


Definition at line 680 of file common/rail.h

RAIL_GetChannelAlt#

RAIL_Status_t RAIL_GetChannelAlt (RAIL_Handle_t railHandle, uint16_t *channel)

Return the current RAIL channel.

Parameters
[in]railHandle

A RAIL instance handle.

[out]channel

The channel for which RAIL is currently configured.

Returns

  • RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_CALL if the radio is not configured for any channel or RAIL_STATUS_INVALID_PARAMETER if channel parameter is NULL.

This function returns the channel the radio is currently tuned to if the specified RAIL handle is active. It returns the channel it will be tuned to during the next protocol switch if the handle is inactive. The channel returned may be different than what RAIL_GetChannel returns when channel hopping or mode switch are involved.


Definition at line 697 of file common/rail.h

RAIL_GetSymbolRate#

uint32_t RAIL_GetSymbolRate (RAIL_Handle_t railHandle)

Return the symbol rate for the current PHY.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The symbol rate in symbols per second or 0.

The symbol rate is the rate of symbol changes over the air. For non-DSSS PHYs, this is the same as the baudrate. For DSSS PHYs, it is the baudrate divided by the length of a chipping sequence. For more information, see the modem calculator documentation. If the rate cannot be calculated, this function returns 0.


Definition at line 711 of file common/rail.h

RAIL_GetBitRate#

uint32_t RAIL_GetBitRate (RAIL_Handle_t railHandle)

Return the bit rate for the current PHY.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The bit rate in bits per second or 0.

The bit rate is the effective over-the-air data rate. It does not account for extra spreading for forward error correction, and so on, but accounts for modulation schemes, DSSS, and other configurations. For more information, see the modem calculator documentation. If the rate cannot be calculated, this function returns 0.


Definition at line 739 of file common/rail.h

RAIL_SetPaCTune#

RAIL_Status_t RAIL_SetPaCTune (RAIL_Handle_t railHandle, uint8_t txPaCtuneValue, uint8_t rxPaCtuneValue)

Set the PA capacitor tune value for transmit and receive.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txPaCtuneValue

PA Ctune value for TX mode.

[in]rxPaCtuneValue

PA Ctune value for RX mode.

Returns

  • Status code indicating success of the function call.

Tunes the impedance of the transmit and receive modes by changing the amount of capacitance at the PA output. Changes made to the TX Power configuration, e.g., calling RAIL_ConfigTxPower, will undo changes made to PA capacitor tune value for transmit and receive via RAIL_SetPaCTune.


Definition at line 769 of file common/rail.h

RAIL_GetSyncWords#

RAIL_Status_t RAIL_GetSyncWords (RAIL_Handle_t railHandle, RAIL_SyncWordConfig_t *syncWordConfig)

Get the sync words and their length.

Parameters
[in]railHandle

A RAIL instance handle.

[out]syncWordConfig

An application-provided non-NULL pointer to store RAIL_SyncWordConfig_t sync word information.

Returns

  • Status code indicating success of the function call.


Definition at line 781 of file common/rail.h

RAIL_ConfigSyncWords#

RAIL_Status_t RAIL_ConfigSyncWords (RAIL_Handle_t railHandle, const RAIL_SyncWordConfig_t *syncWordConfig)

Set the selected sync words and their length.

Parameters
[in]railHandle

A RAIL instance handle.

[in]syncWordConfig

A non-NULL pointer to RAIL_SyncWordConfig_t specifying the sync words and their length. The desired length should be between 2 and 32 bits inclusive, however it is recommended to not change the length below what the PHY syncWord length is configured to be. Changing the syncWord length, especially to that which is lower than the default length, may result in a decrease in packet reception rate or may not work at all. Other values will result in RAIL_STATUS_INVALID_PARAMETER. The default syncWord continues to be valid.

Returns

  • Status code indicating success of the function call. When the custom sync word(s) applied by this API are no longer needed, or to revert to default sync word, calling RAIL_ConfigChannels() will re-establish the sync words specified in the radio configuration.

This function will return RAIL_STATUS_INVALID_STATE if called when BLE has been enabled for this railHandle. When changing sync words in BLE mode, use RAIL_BLE_ConfigChannelRadioParams instead.


Definition at line 806 of file common/rail.h

RAIL_GetWhiteningInitVal#

uint16_t RAIL_GetWhiteningInitVal (RAIL_Handle_t railHandle)

Sets the whitening initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The whitening initialization value currently being used.


Definition at line 815 of file common/rail.h

RAIL_GetCrcInitVal#

uint32_t RAIL_GetCrcInitVal (RAIL_Handle_t railHandle)

Returns the CRC initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The CRC initialization value currently being used.


Definition at line 823 of file common/rail.h

RAIL_SetWhiteningInitVal#

RAIL_Status_t RAIL_SetWhiteningInitVal (RAIL_Handle_t railHandle, uint16_t whiteInit)

Sets the whitening initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]whiteInit

A whitening initialization value.

Returns

  • Status code indicating success of the function call.

Use this function to override the whitening initialization value defined by the current PHY's radio configuration. The new value will persist until this function is called again, RAIL_ResetWhiteningInitVal() is called, or the PHY is changed.

Note

  • Overriding a PHY's whitening initialization value will break communication with peers unless they effect a similar change.

Warnings

  • This API must not be used when either 802.15.4 or BLE modes are enabled.


Definition at line 845 of file common/rail.h

RAIL_SetCrcInitVal#

RAIL_Status_t RAIL_SetCrcInitVal (RAIL_Handle_t railHandle, uint32_t crcInit)

Sets the CRC initialization value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]crcInit

A CRC initialization value.

Returns

  • Status code indicating success of the function call.

Use this function to override the CRC initialization value defined by the current PHY's radio configuration. The new value will persist until this function is called again, RAIL_ResetCrcInitVal() is called, or the PHY is changed.

Note

  • Overriding a PHY's CRC initialization value will break communication with peers unless they effect a similar change.

Warnings

  • This API must not be used when either 802.15.4 or BLE modes are enabled.


Definition at line 867 of file common/rail.h

RAIL_ResetWhiteningInitVal#

RAIL_Status_t RAIL_ResetWhiteningInitVal (RAIL_Handle_t railHandle)

Restores the whitening initialization value to its initial setting from the Radio Configurator.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Can use this function after using RAIL_SetWhiteningInitVal().


Definition at line 879 of file common/rail.h

RAIL_ResetCrcInitVal#

RAIL_Status_t RAIL_ResetCrcInitVal (RAIL_Handle_t railHandle)

Restores the CRC initialization value to its initial setting from the Radio Configurator.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call.

Can use this function after using RAIL_SetCrcInitVal().


Definition at line 890 of file common/rail.h

RAIL_GetTime#

RAIL_Time_t RAIL_GetTime (void)

Get the current RAIL time.

Parameters
N/A

Returns

  • Returns the RAIL timebase in microseconds. Note that this wraps after about 1.19 hours since it's stored in a 32 bit value.

Returns the current time in the RAIL timebase (microseconds). It can be used to compare with packet timestamps or to schedule transmits.


Definition at line 987 of file common/rail.h

RAIL_SetTime#

RAIL_Status_t RAIL_SetTime (RAIL_Time_t time)

Set the current RAIL time.

Parameters
[in]time

Set the RAIL timebase to this value in microseconds.

Warnings

  • Use this API only for testing purposes or in very limited circumstances during RAIL Timer Synchronization. Undefined behavior can result by calling it in multiprotocol or when the radio is not idle or timed events are active. Applications using RAIL_GetTime() may not be designed for discontinuous changes to the RAIL time base.

Returns

  • Status code indicating the success of the function call.

Sets the current time in the RAIL timebase in microseconds.


Definition at line 1004 of file common/rail.h

RAIL_DelayUs#

RAIL_Status_t RAIL_DelayUs (RAIL_Time_t microseconds)

Blocking delay routine for a specified number of microseconds.

Parameters
[in]microseconds

Delay duration in microseconds.

Returns

  • Status code indicating success of the function call.

Use this RAIL API only for short blocking delays because it has less overhead than calling RAIL_GetTime() in a loop. Note

  • Passing large delay values may give unpredictable results or trigger the Watchdog reset. Also, this function will start the clocks required for the RAIL timebase if they are not running, except between RAIL_Sleep() and RAIL_Wake() where the timer must remain stopped. Interrupts are not disabled during the delay, so the delay may be longer if an interrupt extends beyond the delay duration.


Definition at line 1023 of file common/rail.h

RAIL_SetTimer#

RAIL_Status_t RAIL_SetTimer (RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb)

Schedule a timer to expire using the RAIL timebase.

Parameters
[in]railHandle

A RAIL instance handle.

[in]time

The timer's expiration time in the RAIL timebase.

[in]mode

Indicates whether the time argument is an absolute RAIL time or relative to the current RAIL time. Specifying mode RAIL_TIME_DISABLED is the same as calling RAIL_CancelTimer().

[in]cb

The callback for RAIL to call when the timer expires.

Returns

  • RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_PARAMETER if the timer can't be scheduled.

Configures a timer to expire after a period in the RAIL timebase. This timer can be used to implement low-level protocol features.

Warnings

  • Attempting to schedule the timer when it is still running from a previous request is bad practice, unless the cb callback is identical to that used in the previous request, in which case the timer is rescheduled to the new time. Note that if the original timer expires as it is being rescheduled, the callback may or may not occur. It is generally good practice to cancel a running timer before rescheduling it to minimize ambiguity.


Definition at line 1048 of file common/rail.h

RAIL_GetTimer#

RAIL_Time_t RAIL_GetTimer (RAIL_Handle_t railHandle)

Return the absolute time that the RAIL timer was configured to expire.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The absolute time that this timer was set to expire.

Provides the absolute time regardless of the RAIL_TimeMode_t that was passed into RAIL_SetTimer. Note that the time might be in the past if the timer has already expired. The return value is undefined if the timer was never set.


Definition at line 1064 of file common/rail.h

RAIL_CancelTimer#

void RAIL_CancelTimer (RAIL_Handle_t railHandle)

Stop the currently scheduled RAIL timer.

Parameters
[in]railHandle

A RAIL instance handle. Cancels the timer. If this function is called before the timer expires, the cb callback specified in the earlier RAIL_SetTimer() call will never be called.


Definition at line 1074 of file common/rail.h

RAIL_IsTimerExpired#

bool RAIL_IsTimerExpired (RAIL_Handle_t railHandle)

Check whether the RAIL timer has expired.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • True if the previously scheduled timer has expired and false otherwise.

Polling with this function is an alternative to the callback.


Definition at line 1085 of file common/rail.h

RAIL_IsTimerRunning#

bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)

Check whether the RAIL timer is currently running.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Returns true if the timer is running and false if the timer has expired or was never set.


Definition at line 1094 of file common/rail.h

RAIL_ConfigMultiTimer#

bool RAIL_ConfigMultiTimer (bool enable)

Configure the RAIL software timer feature.

Parameters
[in]enable

Enables/disables the RAIL multitimer.

Returns

  • True if the multitimer was successfully enabled/disabled, false otherwise.

Turning this on will add a software timer layer above the physical RAIL timer so that the user can have as many timers as desired. It is not necessary to call this function if the MultiTimer APIs are not used.

Note

  • This function must be called before calling RAIL_SetMultiTimer. This function is a no-op on multiprotocol as this layer is already used under the hood. Do not call this function while the RAIL timer is running. Call RAIL_IsTimerRunning before enabling/disabling the multitimer. If the multitimer is not needed, do not call this function to allow the multitimer code to be dead stripped. If the multitimer is enabled for use, the multitimer and timer APIs can both be used. However, no timer can be in use while this function is being called.


Definition at line 1117 of file common/rail.h

RAIL_SetMultiTimer#

RAIL_Status_t RAIL_SetMultiTimer (RAIL_MultiTimer_t *tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void *cbArg)

Start a multitimer instance.

Parameters
[inout]tmr

A pointer to the timer instance to start.

[in]expirationTime

A time when the timer is set to expire.

[in]expirationMode

Select mode of expirationTime. See RAIL_TimeMode_t.

[in]callback

A function to call on timer expiry. See RAIL_MultiTimerCallback_t. NULL is a legal value.

[in]cbArg

An extra callback function parameter for the user application.

Note

  • It is legal to start an already running timer. If this is done, the timer will first be stopped before the new configuration is applied. If expirationTime is 0, the callback is called immediately.

Returns


Definition at line 1141 of file common/rail.h

RAIL_CancelMultiTimer#

bool RAIL_CancelMultiTimer (RAIL_MultiTimer_t *tmr)

Stop the currently scheduled RAIL multitimer.

Parameters
[inout]tmr

A RAIL timer instance handle.

Returns

  • true if the timer was successfully canceled. false if the timer was not running.

Cancels the timer. If this function is called before the timer expires, the cb callback specified in the earlier RAIL_SetTimer() call will never be called.


Definition at line 1160 of file common/rail.h

RAIL_IsMultiTimerRunning#

bool RAIL_IsMultiTimerRunning (RAIL_MultiTimer_t *tmr)

Check if a given timer is running.

Parameters
[in]tmr

A pointer to the timer structure to query.

Returns

  • true if the timer is running. false if the timer is not running.


Definition at line 1171 of file common/rail.h

RAIL_IsMultiTimerExpired#

bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t *tmr)

Check if a given timer has expired.

Parameters
[in]tmr

A pointer to the timer structure to query.

Returns

  • true if the timer is expired. false if the timer is running.


Definition at line 1182 of file common/rail.h

RAIL_GetMultiTimer#

RAIL_Time_t RAIL_GetMultiTimer (RAIL_MultiTimer_t *tmr, RAIL_TimeMode_t timeMode)

Get time left before a given timer instance expires.

Parameters
[in]tmr

A pointer to the timer structure to query.

[in]timeMode

Indicates how the function provides the time remaining. By choosing RAIL_TimeMode_t::RAIL_TIME_ABSOLUTE, the function returns the absolute expiration time, and by choosing RAIL_TimeMode_t::RAIL_TIME_DELAY, the function returns the amount of time remaining before the timer's expiration.

Returns

  • Time left expressed in RAIL's time units. 0 if the soft timer is not running or has already expired.


Definition at line 1199 of file common/rail.h

RAILCb_ConfigSleepTimerSync#

void RAILCb_ConfigSleepTimerSync (RAIL_TimerSyncConfig_t *timerSyncConfig)

Configure RAIL timer synchronization.

Parameters
[inout]timerSyncConfig

A pointer to the RAIL_TimerSyncConfig_t structure containing the configuration parameters for timer sync. The RAIL_TimerSyncConfig_t::sleep field is ignored in this call.

This function is optional to implement.

This function is called during RAIL_ConfigSleep to allow an application to configure the PRS and RTCC channels used for timer sync to values other than their defaults. The default channels are populated in timerSyncConfig and can be overwritten by the application. If this function is not implemented by the application, a default implementation from within the RAIL library will be used that simply maintains the default channel values in timerSyncConfig.

If an unsupported channel is selected by the application, RAIL_ConfigSleep will return RAIL_STATUS_INVALID_PARAMETER.

void RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)
{
  timerSyncConfig->prsChannel = MY_TIMERSYNC_PRS_CHANNEL;
  timerSyncConfig->rtccChannel = MY_TIMERSYNC_RTCC_CHANNEL;
}

Definition at line 1481 of file common/rail.h

RAIL_ConfigSleep#

RAIL_Status_t RAIL_ConfigSleep (RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)

Initialize RAIL timer synchronization.

Parameters
[in]railHandle

A RAIL instance handle.

[in]sleepConfig

A sleep configuration.

Returns

  • Status code indicating success of the function call.


Definition at line 1491 of file common/rail.h

RAIL_ConfigSleepAlt#

RAIL_Status_t RAIL_ConfigSleepAlt (RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t *syncConfig)

Initialize RAIL timer synchronization.

Parameters
[in]railHandle

A RAIL instance handle.

[in]syncConfig

A pointer to the timer synchronization configuration.

The default structure used to enable timer synchronization across sleep is RAIL_TIMER_SYNC_DEFAULT.

Returns

  • Status code indicating success of the function call.


Definition at line 1505 of file common/rail.h

RAIL_Sleep#

RAIL_Status_t RAIL_Sleep (uint16_t wakeupProcessTime, bool *deepSleepAllowed)

Stop the RAIL timer and prepare RAIL for sleep.

Parameters
[in]wakeupProcessTime

Time in microseconds that the application and hardware need to recover from sleep state.

[out]deepSleepAllowed

true - system can go to deep sleep. false - system should not go to deep sleep. Deep sleep should be blocked in this case.

Returns

  • Status code indicating success of the function call.

Warnings

  • The active RAIL configuration must be idle to enable sleep.

Note

  • This API must not be called if RAIL Power Manager is initialized.


Definition at line 1524 of file common/rail.h

RAIL_Wake#

RAIL_Status_t RAIL_Wake (RAIL_Time_t elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Parameters
[in]elapsedTime

Add the sleep duration to the RAIL timer before restarting the RAIL timer.

Returns

  • Status code indicating success of the function call.

If the timer sync was enabled by RAIL_ConfigSleep, synchronize the RAIL timer using an alternate timer. Otherwise, add elapsedTime to the RAIL timer.

Note

  • This API must not be called if RAIL Power Manager is initialized.


Definition at line 1540 of file common/rail.h

RAIL_InitPowerManager#

RAIL_Status_t RAIL_InitPowerManager (void)

Initialize RAIL Power Manager.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • Call this function only when the application is built and initialized with Power Manager plugin. RAIL will perform timer synchronization, upon transitioning from EM2 or lower to EM1 or higher energy mode or vice-versa, in the Power Manager EM transition callback. Since EM transition callbacks are not called in a deterministic order, it is suggested to not call any RAIL time dependent APIs in an EM transition callback.


Definition at line 1555 of file common/rail.h

RAIL_DeinitPowerManager#

RAIL_Status_t RAIL_DeinitPowerManager (void)

Stop the RAIL Power Manager.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • The active RAIL configuration must be idle to disable radio power manager and there should be no outstanding requirements by radio power manager.


Definition at line 1566 of file common/rail.h

RAIL_ConfigEvents#

RAIL_Status_t RAIL_ConfigEvents (RAIL_Handle_t railHandle, RAIL_Events_t mask, RAIL_Events_t events)

Configure radio events.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mask

A bitmask of events to configure.

[in]events

A bitmask of events to trigger RAIL_Config_t::eventsCallback For a full list of available callbacks, see RAIL_EVENT_* set of defines.

Returns

  • Status code indicating success of the function call.

Sets up which radio interrupts generate a RAIL event. The full list of options is in RAIL_Events_t.


Definition at line 1592 of file common/rail.h

RAIL_ConfigData#

RAIL_Status_t RAIL_ConfigData (RAIL_Handle_t railHandle, const RAIL_DataConfig_t *dataConfig)

RAIL data management configuration.

Parameters
[in]railHandle

A RAIL instance handle.

[in]dataConfig

RAIL data configuration structure.

Returns

  • Status code indicating success of the function call.

This function configures how RAIL manages data. The application can configure RAIL to receive data in a packet-based or FIFO-based manner. RAIL_DataMethod_t::FIFO_MODE is necessary to receive packets larger than the radio's receive FIFO. It is also required for receive data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.

Generally with RAIL_DataMethod_t::FIFO_MODE, the application sets appropriate FIFO thresholds via RAIL_SetTxFifoThreshold() and RAIL_SetRxFifoThreshold() and then enables and handles the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event callback (to feed more packet data via RAIL_WriteTxFifo() before the FIFO underflows) and the RAIL_EVENT_RX_FIFO_ALMOST_FULL event callback (to consume packet data via RAIL_ReadRxFifo() before the receive FIFO overflows).

When configuring TX for RAIL_DataMethod_t::FIFO_MODE, this function resets the transmit FIFO. When configuring TX or RX for RAIL_DataMethod_t::PACKET_MODE, this function will reset the corresponding FIFO thresholds such that they won't trigger the RAIL_EVENT_RX_FIFO_ALMOST_FULL or RAIL_EVENT_TX_FIFO_ALMOST_EMPTY events.

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::FIFO_MODE, the radio won't drop packet data of aborted or CRC error packets, but will present it to the application to deal with accordingly. On completion of erroneous packets, the RAIL_Config_t::eventsCallback with RAIL_EVENT_RX_PACKET_ABORTED, RAIL_EVENT_RX_FRAME_ERROR, or RAIL_EVENT_RX_ADDRESS_FILTERED will tell the application it can drop any data it read via RAIL_ReadRxFifo() during reception. For CRC error packets when the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option is in effect, the application should check for that from the RAIL_RxPacketStatus_t obtained by calling RAIL_GetRxPacketInfo(). RAIL will automatically flush any remaining packet data after reporting one of these packet completion events or the application can explicitly flush it by calling RAIL_ReleaseRxPacket().

When RAIL_DataConfig_t::rxMethod is set to RAIL_DataMethod_t::PACKET_MODE, the radio will roll back (drop) all packet data associated with aborted packets including those with CRC errors (unless configured to ignore CRC errors via the RAIL_RX_OPTION_IGNORE_CRC_ERRORS RX option). The application will never have to deal with packet data from these packets. In either mode, the application can set RX options as needed.

When RAIL_DataConfig_t::rxSource is set to a value other than RX_PACKET_DATA and RAIL_Config_t::eventsCallbackRAIL_EVENT_RX_FIFO_OVERFLOW is enabled RX will be terminated if a RX FIFO overflow occurs. If RAIL_EVENT_RX_FIFO_OVERFLOW is not enabled, data will be discarded until the overflow condition is resolved. To continue capturing data RX must be restarted using RAIL_StartRx().


Definition at line 1897 of file common/rail.h

RAIL_WriteTxFifo#

uint16_t RAIL_WriteTxFifo (RAIL_Handle_t railHandle, const uint8_t *dataPtr, uint16_t writeLength, bool reset)

Write data to the transmit FIFO previously established by RAIL_SetTxFifo().

Parameters
[in]railHandle

A RAIL instance handle.

[in]dataPtr

An application-provided pointer to transmit data.

[in]writeLength

A number of bytes to write to the transmit FIFO.

[in]reset

If true, resets transmit FIFO before writing the data.

Returns

  • The number of bytes written to the transmit FIFO.

This function reads data from the provided dataPtr and writes it to the transmit FIFO that was previously established by RAIL_SetTxFifo(). If the requested writeLength exceeds the current number of bytes open in the transmit FIFO, the function only writes until the transmit FIFO is full. The function returns the number of bytes written to the transmit FIFO or returns zero if railHandle is NULL or if the transmit FIFO is full.

Note

  • The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the writeLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes, which the packet configuration causes to be sent automatically.

  • This function does not create a critical section but, depending on the application, a critical section could be appropriate.


Definition at line 1932 of file common/rail.h

RAIL_SetTxFifo#

uint16_t RAIL_SetTxFifo (RAIL_Handle_t railHandle, uint8_t *addr, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

An appropriately-aligned (see below) pointer to a read-write memory location in RAM used as the transmit FIFO. This memory must persist until the next call to this function or RAIL_SetTxFifoAlt.

[in]initLength

A number of initial bytes already in the transmit FIFO.

[in]size

A desired size of the transmit FIFO in bytes.

Returns

  • Returns the FIFO size in bytes, 0 if an error occurs.

This function sets the memory location for the transmit FIFO. RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size, in that case 0 is returned. If the initLength parameter is larger than the returned size, the FIFO will be filled up to its size.

A user may write to the custom memory location directly before calling this function, or use RAIL_WriteTxFifo to write to the memory location after calling this function. Users must specify the initLength for previously-written memory to be set in the transmit FIFO.

This function reserves the block of RAM starting at addr with a length of the returned FIFO size, which is used internally as a circular buffer for the transmit FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via calls to RAIL_WriteTxFifo) until the next call to this function.

Note

  • The protocol's packet configuration, as set up by the radio configurator or via RAIL_SetFixedLength(), determines how many bytes of data are consumed from the transmit FIFO for a successful transmit operation, not the initLength value passed in. If not enough data has been put into the transmit FIFO, a RAIL_EVENT_TX_UNDERFLOW event will occur. If too much data is put into the transmit FIFO, the extra data will either become the first bytes sent in a subsequent packet, or will be thrown away if the FIFO gets reset prior to the next transmit. In general, the proper number of packet bytes to put into the transmit FIFO are all payload bytes except for any CRC bytes which the packet configuration causes to be sent automatically.


Definition at line 1986 of file common/rail.h

RAIL_SetTxFifoAlt#

uint16_t RAIL_SetTxFifoAlt (RAIL_Handle_t railHandle, uint8_t *addr, uint16_t startOffset, uint16_t initLength, uint16_t size)

Set the address of the transmit FIFO, a circular buffer used for TX data which can start at offset distance from the FIFO base address.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

An appropriately-aligned (see RAIL_SetTxFifo description) pointer to a read-write memory location in RAM used as the transmit FIFO. This memory must persist until the next call to this function or RAIL_SetTxFifo.

[in]startOffset

A number of bytes defining the start position of the TX data from the transmit FIFO base address, only valid if initLength is not 0.

[in]initLength

The number of valid bytes already in the transmit FIFO after startOffset.

[in]size

A desired size of the transmit FIFO in bytes.

Returns

  • Returns the FIFO size in bytes, 0 if an error occurs.

This function is similar to RAIL_SetTxFifo except a startOffset can be specified to indicate where the transmit packet data starts. This allows an application to place unaligned initial packet data within the aligned transmit FIFO (initLength > 0). Specifying a startOffset will not reduce the FIFO threshold or affect RAIL_GetTxFifoSpaceAvailable(). RAIL_SetTxFifo or RAIL_SetTxFifoAlt must be called at least once before any transmit operations occur. FIFO size handling is quite same as RAIL_SetTxFifo. Only difference is that if the initLength plus startOffset parameters are larger than the returned size, the FIFO will be filled up to its size from startOffset. Note that the startOffset is essentially forgotten after the next transmit – i.e. it applies onto to the next transmit operation, and is not re-established when the transmit FIFO is reset.


Definition at line 2019 of file common/rail.h

RAIL_SetRxFifo#

RAIL_Status_t RAIL_SetRxFifo (RAIL_Handle_t railHandle, uint8_t *addr, uint16_t *size)

Set the address of the receive FIFO, a circular buffer used for RX data.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]addr

A pointer to a read-write memory location in RAM used as the receive FIFO. This memory must persist until the next call to this function.

[inout]size

A desired size of the receive FIFO in bytes. This will be populated with the actual size during the function call.

Returns

  • Status code indicating success of the function call.

This function sets the memory location for the receive FIFO. It must be called at least once before any receive operations occur.

Note

  • After it is called, any prior receive FIFO is orphaned. To avoid orphaning the default internal 512-byte receive FIFO so it does not unnecessarily consume RAM resources in your application, implement RAILCb_SetupRxFifo() to call this function.

FIFO size can be determined by the return value of this function. The chosen size is determined based on the available FIFO sizes supported by the hardware. Similarly, some hardware has stricter FIFO alignment requirements; 32-bit alignment provides the maximum portability across all RAIL platforms. For more on supported FIFO sizes and alignments, see chip-specific documentation, such as EFR32. The returned FIFO size will be the closest allowed size less than or equal to the passed in size parameter, unless the size parameter is smaller than the minimum FIFO size.

This function reserves the block of RAM starting at addr with a length of size, which is used internally as a circular buffer for the receive FIFO. It must be able to hold the entire FIFO size. The caller must guarantee that the custom FIFO remains intact and unchanged (except via incoming packet data being written) until the next call to this function.

In multiprotocol, RAIL currently shares one receive FIFO across all protocols. This function will return RAIL_STATUS_INVALID_STATE if the requested RAIL_Handle_t is not active.


Definition at line 2062 of file common/rail.h

RAILCb_SetupRxFifo#

RAIL_Status_t RAILCb_SetupRxFifo (RAIL_Handle_t railHandle)

Set up the receive FIFO to use.

Parameters
[in]railHandle

A RAIL instance handle.

This function is optional to implement.

Returns

  • Status code indicating success of the function call.

This function is called during the RAIL_Init process to set up the FIFO to use for received packets. If not implemented by the application, a default implementation from within the RAIL library will be used to initialize an internal default 512-byte receive FIFO.

If this function returns an error, the RAIL_Init process will fail.

During this function, the application should generally call RAIL_SetRxFifo. If that does not happen, the application needs to set up the receive FIFO via a call to RAIL_SetRxFifo before attempting to receive any packets. An example implementation may look like the following:

#define RX_FIFO_SIZE 1024
static uint8_t rxFifo[RX_FIFO_SIZE];

RAIL_Status_t RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)
{
  uint16_t rxFifoSize = RX_FIFO_SIZE;
  RAIL_Status_t status = RAIL_SetRxFifo(railHandle, &rxFifo[0], &rxFifoSize);
  if (rxFifoSize != RX_FIFO_SIZE) {
    // We set up an incorrect FIFO size
    return RAIL_STATUS_INVALID_PARAMETER;
  }
  if (status == RAIL_STATUS_INVALID_STATE) {
    // Allow failures due to multiprotocol
    return RAIL_STATUS_NO_ERROR;
  }
  return status;
}

Definition at line 2101 of file common/rail.h

RAIL_ReadRxFifo#

uint16_t RAIL_ReadRxFifo (RAIL_Handle_t railHandle, uint8_t *dataPtr, uint16_t readLength)

Read packet data from RAIL's internal receive FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

[out]dataPtr

An application-provided pointer to store data. If NULL, the data is thrown away rather than copied out.

[in]readLength

A number of packet bytes to read from the FIFO.

Returns

  • The number of packet bytes read from the receive FIFO.

This function reads packet data from the head of receive FIFO and writes it to the provided dataPtr. It does not permit reading more data than is available in the FIFO, nor does it permit reading more data than remains in the oldest unreleased packet.

Because this function does not have a critical section, use it only in one context or make sure function calls are protected to prevent buffer corruption.

Warnings

Note

  • When reading data from an arriving packet that is not yet complete, keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the receive FIFO could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid reading this info because it will corrupt the packet's details and possibly corrupt the receive FIFO.


Definition at line 2138 of file common/rail.h

RAIL_SetTxFifoThreshold#

uint16_t RAIL_SetTxFifoThreshold (RAIL_Handle_t railHandle, uint16_t txThreshold)

Configure the RAIL transmit FIFO almost empty threshold.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txThreshold

The threshold below which the RAIL_EVENT_TX_FIFO_ALMOST_EMPTY event will fire.

Returns

  • Configured transmit FIFO threshold value.

This function configures the threshold for the transmit FIFO. When the number of bytes in the transmit FIFO falls below the configured threshold, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_TX_FIFO_ALMOST_EMPTY set. The txThreshold value should be smaller than or equal to the transmit FIFO size; higher values will be pegged to the FIFO size. A value of 0 or RAIL_FIFO_THRESHOLD_DISABLED will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.


Definition at line 2159 of file common/rail.h

RAIL_SetRxFifoThreshold#

uint16_t RAIL_SetRxFifoThreshold (RAIL_Handle_t railHandle, uint16_t rxThreshold)

Configure the RAIL receive FIFO almost full threshold.

Parameters
[in]railHandle

A RAIL instance handle.

[in]rxThreshold

The threshold above which the RAIL_EVENT_RX_FIFO_ALMOST_FULL event will fire.

Returns

  • Configured receive FIFO threshold value.

This function configures the threshold for the receive FIFO. When the number of bytes of packet data in the receive FIFO exceeds the configured threshold, RAIL_Config_t::eventsCallback will keep firing with RAIL_EVENT_RX_FIFO_ALMOST_FULL set as long as the number of bytes in the receive FIFO exceeds the configured threshold value. The rxThreshold value should be smaller than the receive FIFO size; anything else, including a value of RAIL_FIFO_THRESHOLD_DISABLED, will disable the threshold, returning RAIL_FIFO_THRESHOLD_DISABLED.

Note


Definition at line 2187 of file common/rail.h

RAIL_GetTxFifoThreshold#

uint16_t RAIL_GetTxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL transmit FIFO almost empty threshold value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Configured TX Threshold value.

Retrieves the configured TX threshold value.


Definition at line 2198 of file common/rail.h

RAIL_GetRxFifoThreshold#

uint16_t RAIL_GetRxFifoThreshold (RAIL_Handle_t railHandle)

Get the RAIL receive FIFO almost full threshold value.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Configured RX Threshold value.

Retrieves the configured RX threshold value.


Definition at line 2208 of file common/rail.h

RAIL_ResetFifo#

void RAIL_ResetFifo (RAIL_Handle_t railHandle, bool txFifo, bool rxFifo)

Reset the RAIL transmit and/or receive FIFOs.

Parameters
[in]railHandle

A RAIL instance handle.

[in]txFifo

If true, reset the transmit FIFO.

[in]rxFifo

If true, reset the receive FIFO.

This function can reset each FIFO independently. The application should not reset the receive FIFO while receiving a frame, nor should it reset the transmit FIFO while transmitting a frame.


Definition at line 2221 of file common/rail.h

RAIL_GetRxFifoBytesAvailable#

uint16_t RAIL_GetRxFifoBytesAvailable (RAIL_Handle_t railHandle)

Get the number of bytes used in the receive FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

Only use this function in RX RAIL_DataMethod_t::FIFO_MODE. Apps should use RAIL_GetRxPacketInfo() instead.

Returns

  • Number of bytes used in the receive FIFO.

This function indicates how much packet-related data exists in the receive FIFO that could be read.

Note

  • The number of bytes returned may not just reflect the current packet's data but could also include raw appended info bytes added after successful packet reception and bytes from subsequently received packets. It is up to the app to never try to consume more than the packet's actual data when using the value returned here in a subsequent call to RAIL_ReadRxFifo(), otherwise the receive FIFO will be corrupted.


Definition at line 2241 of file common/rail.h

RAIL_GetTxFifoSpaceAvailable#

uint16_t RAIL_GetTxFifoSpaceAvailable (RAIL_Handle_t railHandle)

Get the number of bytes unused in the transmit FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Number of bytes unused in the transmit FIFO.

This function indicates how much space is available in the transmit FIFO for writing additional packet data.


Definition at line 2252 of file common/rail.h

RAIL_SetRxTransitions#

RAIL_Status_t RAIL_SetRxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)

Configure RAIL automatic state transitions after RX.

Parameters
[in]railHandle

A RAIL instance handle.

[in]transitions

The state transitions to apply after reception.

Returns

  • Status code indicating success of the function call.

This function fails if unsupported transitions are passed in or if the radio is currently in the RX state. Success can transition to TX, RX, or IDLE, while error can transition to RX or IDLE. The timings of state transitions from the RX state are not guaranteed when packets are longer than 16 seconds on-air.


Definition at line 2277 of file common/rail.h

RAIL_GetRxTransitions#

RAIL_Status_t RAIL_GetRxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)

Get the current RAIL automatic state transitions after RX.

Parameters
[in]railHandle

A RAIL instance handle.

[out]transitions

The state transitions that apply after receive.

Returns

  • Status code indicating a success of the function call.

Retrieves the current state transitions after RX and stores them in the transitions argument.


Definition at line 2290 of file common/rail.h

RAIL_SetTxTransitions#

RAIL_Status_t RAIL_SetTxTransitions (RAIL_Handle_t railHandle, const RAIL_StateTransitions_t *transitions)

Configure RAIL automatic state transitions after TX.

Parameters
[in]railHandle

A RAIL instance handle.

[in]transitions

The state transitions to apply after transmission.

Returns

  • Status code indicating a success of the function call.

This function fails if unsupported transitions are passed in or if the radio is currently in the TX state. Success and error can each transition to RX or IDLE. For the ability to run repeated transmits, see RAIL_SetNextTxRepeat.


Definition at line 2305 of file common/rail.h

RAIL_GetTxTransitions#

RAIL_Status_t RAIL_GetTxTransitions (RAIL_Handle_t railHandle, RAIL_StateTransitions_t *transitions)

Get the current RAIL automatic state transitions after TX.

Parameters
[in]railHandle

A RAIL instance handle.

[out]transitions

The state transitions that apply after transmission.

Returns

  • Status code indicating a success of the function call.

Retrieves the current state transitions after TX and stores them in the transitions argument.


Definition at line 2318 of file common/rail.h

RAIL_SetNextTxRepeat#

RAIL_Status_t RAIL_SetNextTxRepeat (RAIL_Handle_t railHandle, const RAIL_TxRepeatConfig_t *repeatConfig)

Set up automatic repeated transmits after the next transmit.

Parameters
[in]railHandle

A RAIL instance handle.

[in]repeatConfig

The configuration structure for repeated transmits.

Returns

  • Status code indicating a success of the function call.

Repeated transmits will occur after an application-initiated transmit caused by calling one of the Packet Transmit APIs. The repetition will only occur after the first application-initiated transmit after this function is called. Future repeated transmits must be requested by calling this function again.

Each repeated transmit that occurs will have full Packet Trace (PTI) information, and will receive events such as RAIL_EVENT_TX_PACKET_SENT as normal.

If a TX error occurs during the repetition, the process will abort and the TX error transition from RAIL_SetTxTransitions will be used. If the repetition completes successfully, then the TX success transition from RAIL_SetTxTransitions will be used.

Use RAIL_GetTxPacketsRemaining() if need to know how many transmit completion events are expected before the repeating sequence is done, or how many were not performed due to a transmit error.

Any call to RAIL_Idle or RAIL_StopTx will clear the pending repeated transmits. The state will also be cleared by another call to this function. A DMP switch will clear this state only if the initial transmit triggering the repeated transmits has started.

One can change the repeated transmit configuration by re-calling this function with new parameters as long as that occurs prior to calling a Packet Transmit API. Passing a RAIL_TxRepeatConfig_t::iterations count of 0 will prevent the next transmit from repeating.

The application is responsible for populating the transmit data to be used by the repeated transmits via RAIL_SetTxFifo or RAIL_WriteTxFifo. Data will be transmitted from the Transmit FIFO. If the Transmit FIFO does not have sufficient data to transmit, a TX error will be caused and a RAIL_EVENT_TX_UNDERFLOW will occur. In order to avoid an underflow, the application should queue data to be transmitted as early as possible. Consider using RAIL_TX_OPTION_RESEND if the same packet data is to be repeated: then the Transmit FIFO only needs to be set/written once.

Do not call this function after starting a transmit operation via a Packet Transmit API call or before processing the final transmit completion event of a prior transmit. This function will fail to (re)configure the repetition if a transmit of any kind is ongoing, including during the time between an initial transmit and the end of a previously-configured repetition.

Note


Definition at line 2379 of file common/rail.h

RAIL_GetTxPacketsRemaining#

uint16_t RAIL_GetTxPacketsRemaining (RAIL_Handle_t railHandle)

Get the number of transmits remaining in a repeat operation.

Parameters
[in]railHandle

A RAIL instance handle.

Must only be called from within event callback context when handling one of the RAIL_EVENTS_TX_COMPLETION events.

Returns

  • transmits remaining as described below.

If the TX completion event is RAIL_EVENT_TX_PACKET_SENT the returned value indicates how many more such events are expected before the repeat transmit operation is done. Due to interrupt latency and timing, this may be an overcount if greater than 0 but is guaranteed to be accurate when 0.

If the TX completion event is an error, the returned value indicates the number of requested transmits that were not performed. For RAIL_EVENT_TX_ABORTED and RAIL_EVENT_TX_UNDERFLOW the count does not include the failing transmit itself. For the other errors where a transmit never started or was blocked, the count would include the failing transmit, which may be one higher than the configured RAIL_TxRepeatConfig_t::iterations if it was the original transmit that was blocked.

If an infinite repeat was configured, this will return RAIL_TX_REPEAT_INFINITE_ITERATIONS.


Definition at line 2408 of file common/rail.h

RAIL_SetStateTiming#

RAIL_Status_t RAIL_SetStateTiming (RAIL_Handle_t railHandle, RAIL_StateTiming_t *timings)

Configure RAIL automatic state transition timing.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]timings

The timings used to configure the RAIL state machine. This structure is overwritten with the actual times that were set, if an input timing is invalid.

Returns

  • Status code indicating a success of the function call.

The timings given are close to the actual transition time. However, a still uncharacterized software overhead occurs. Also, timings are not always adhered to when using an automatic transition after an error, due to the cleanup required to recover from the error.


Definition at line 2424 of file common/rail.h

RAIL_Idle#

void RAIL_Idle (RAIL_Handle_t railHandle, RAIL_IdleMode_t mode, bool wait)

Place the radio into an idle state.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

The method for shutting down the radio.

[in]wait

Whether this function should wait for the radio to reach idle before returning.

This function is used to remove the radio from TX and RX states. How these states are left is defined by the mode parameter.

In multiprotocol, this API will also cause the radio to be yielded so that other tasks can be run. See Yielding the Radio for more details.


Definition at line 2441 of file common/rail.h

RAIL_GetRadioState#

RAIL_RadioState_t RAIL_GetRadioState (RAIL_Handle_t railHandle)

Get the current radio state.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • An enumeration for the current radio state.

Returns the state of the radio as a bitmask containing: RAIL_RF_STATE_IDLE, RAIL_RF_STATE_RX, RAIL_RF_STATE_TX, and RAIL_RF_STATE_ACTIVE. RAIL_RF_STATE_IDLE, RAIL_RF_STATE_RX, and RAIL_RF_STATE_TX bits are mutually exclusive. The radio can transition through intermediate states, which are not reported but are instead considered part of the state most closely associated. For example, when the radio is warming up or shutting down the transmitter or receiver, this function returns RAIL_RF_STATE_TX or RAIL_RF_STATE_RX, respectively. When transitioning directly from RX to TX or vice-versa, this function returns the earlier state.

Note


Definition at line 2465 of file common/rail.h

RAIL_GetRadioStateDetail#

RAIL_RadioStateDetail_t RAIL_GetRadioStateDetail (RAIL_Handle_t railHandle)

Get the detailed current radio state.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • An enumeration for the current detailed radio state.

Returns the state of the radio as a bitmask. The three core radio states IDLE, RX, and TX are represented by mutually exclusive bits RAIL_RF_STATE_DETAIL_IDLE_STATE, RAIL_RF_STATE_DETAIL_RX_STATE, and RAIL_RF_STATE_DETAIL_TX_STATE respectively. If the radio is transitioning between these three states, the returned bitmask will have RAIL_RF_STATE_DETAIL_TRANSITION set along with a bit corresponding to the destination core radio state. If, while in the receive state, the radio is actively receiving a packet, RAIL_RF_STATE_DETAIL_ACTIVE will be set; otherwise, this bit will be clear. If frame detection is disabled, RAIL_RF_STATE_DETAIL_NO_FRAMES in the returned state bitmask will be set; otherwise, this bit will be clear. If the radio is performing an LBT/CSMA operation (e.g., a backoff period) RAIL_RF_STATE_DETAIL_LBT in the returned state bitmask will be set; otherwise, this bit will be clear.

For the most part, the more detailed radio states returned by this API correspond to radio states returned by RAIL_GetRadioState as follows:

RAIL_RadioStateDetail_tRAIL_RadioState_t RAIL_RF_STATE_DETAIL_INACTIVE RAIL_RF_STATE_INACTIVE RAIL_RF_STATE_DETAIL_IDLE_STATE | RAIL_STATE_DETAIL_TRANSITION If RX overflow or leaving RX unforced: RAIL_RF_STATE_RX Else if leaving TX unforced: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_IDLE RAIL_RF_STATE_DETAIL_IDLE_STATE RAIL_RF_STATE_IDLE RAIL_RF_STATE_DETAIL_IDLE_STATE | RAIL_STATE_DETAIL_LBT RAIL_RF_STATE_TX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_STATE_DETAIL_TRANSITION If leaving TX: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_TRANSITION | RAIL_RF_STATE_DETAIL_NO_FRAMES If leaving TX: RAIL_RF_STATE_TX Else: RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_NO_FRAMES RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_LBT RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_NO_FRAMES | RAIL_RF_STATE_DETAIL_LBT RAIL_RF_STATE_RX RAIL_RF_STATE_DETAIL_RX_STATE | RAIL_RF_STATE_DETAIL_ACTIVE RAIL_RF_STATE_RX_ACTIVE RAIL_RF_STATE_DETAIL_TX_STATE | RAIL_RF_STATE_TRANSITION If leaving RX: RAIL_RF_STATE_RX Else: RAIL_RF_STATE_TX RAIL_RF_STATE_DETAIL_TX_STATE | RAIL_RF_STATE_ACTIVE RAIL_RF_STATE_TX_ACTIVE


Definition at line 2531 of file common/rail.h

RAIL_EnableCacheSynthCal#

RAIL_Status_t RAIL_EnableCacheSynthCal (RAIL_Handle_t railHandle, bool enable)

Enable/disable caching of synth calibration value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

A booloean to enable or disable caching of synth calibration.

Returns

  • Status code indicating success of the function call.

Once enabled, the sequencer will start caching synth calibration values for channels and apply them instead of performing calibration on every state transition and channel change. This will increase the transition time for the first time calibration is performed. Subsequent state transitions will be faster. The cache size is 2. RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING internally uses this feature and there is no need to enable/disable it. This function returns RAIL_STATUS_INVALID_STATE if we try to disable it while RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is enabled.

Note


Definition at line 2560 of file common/rail.h

RAIL_ConfigTxPower#

RAIL_Status_t RAIL_ConfigTxPower (RAIL_Handle_t railHandle, const RAIL_TxPowerConfig_t *config)

Initialize TX power settings.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

An instance which contains desired initial settings for the TX amplifier.

Returns

  • RAIL_Status_t indicating success or an error.

These settings include the selection between the multiple TX amplifiers, voltage supplied to the TX power amplifier, and ramp times. This must be called before any transmit occurs or RAIL_SetTxPower is called. While this function should always be called during initialization, it can also be called any time if these settings need to change to adapt to a different application/protocol. This API also resets TX power to RAIL_TX_POWER_LEVEL_INVALID, so RAIL_SetTxPower must be called afterwards.

At times, certain combinations of configurations cannot be achieved. This API attempts to get as close as possible to the requested settings. The following "RAIL_Get..." API can be used to determine what values were set. A change in RAIL_TxPowerConfig_t::rampTime may affect the minimum timings that can be achieved in RAIL_StateTiming_t::idleToTx and RAIL_StateTiming_t::rxToTx. Call RAIL_SetStateTiming() again to check whether these times have changed.


Definition at line 2723 of file common/rail.h

RAIL_GetTxPowerConfig#

RAIL_Status_t RAIL_GetTxPowerConfig (RAIL_Handle_t railHandle, RAIL_TxPowerConfig_t *config)

Get the TX power settings currently used in the amplifier.

Parameters
[in]railHandle

A RAIL instance handle.

[out]config

A pointer to memory allocated to hold the current TxPower configuration structure. A NULL configuration will produce undefined behavior.

Returns

  • RAIL status variable indicating whether or not the get was successful.

Note that this API does not return the current TX power, which is separately managed by the RAIL_GetTxPower / RAIL_SetTxPower APIs. Use this API to determine which values were set as a result of RAIL_ConfigTxPower.


Definition at line 2741 of file common/rail.h

RAIL_SetTxPower#

RAIL_Status_t RAIL_SetTxPower (RAIL_Handle_t railHandle, RAIL_TxPowerLevel_t powerLevel)

Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).

Parameters
[in]railHandle

A RAIL instance handle.

[in]powerLevel

Power in chip-specific RAIL_TxPowerLevel_t units.

Returns

  • RAIL_Status_t indicating success or an error.

To convert between decibels and the integer values that the registers take, call RAIL_ConvertDbmToRaw. A weak version of this function, which works well with our boards is provided. However, customers using a custom board need to characterize chip operation on that board and override the function to convert appropriately from the desired dB values to raw integer values.

Depending on the configuration used in RAIL_ConfigTxPower, not all power levels are achievable. This API will get as close as possible to the desired power without exceeding it, and calling RAIL_GetTxPower is the only way to know the exact value written.

Calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower) will return an error.


Definition at line 2767 of file common/rail.h

RAIL_GetTxPower#

RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)

Return the current power setting of the PA.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

This API returns the raw value that was set by RAIL_SetTxPower. A weak version of RAIL_ConvertRawToDbm that works with our boards to convert the raw values into actual output dBm values is provided. However, customers using a custom board need to re-characterize the relationship between raw and decibel values and rewrite the provided function.

Calling this function before configuring the PA (i.e., before a successful call to RAIL_ConfigTxPower) will return an error (RAIL_TX_POWER_LEVEL_INVALID).


Definition at line 2788 of file common/rail.h

RAIL_ConvertRawToDbm#

RAIL_TxPower_t RAIL_ConvertRawToDbm (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPowerLevel_t powerLevel)

Convert raw values written to registers to decibel value (in units of deci-dBm).

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to convert.

[in]powerLevel

A raw amplifier register value to be converted to deci-dBm.

Returns

  • raw amplifier values converted to units of deci-dBm.

A weak version of this function is provided that is tuned to provide accurate values for our boards. For a custom board, the relationship between what is written to the TX amplifier and the actual output power should be re-characterized and implemented in an overriding version of RAIL_ConvertRawToDbm. For minimum code size and best speed, use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.


Definition at line 2814 of file common/rail.h

RAIL_ConvertDbmToRaw#

RAIL_TxPowerLevel_t RAIL_ConvertDbmToRaw (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t power)

Convert the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to do the conversion.

[in]power

Desired dBm values in units of deci-dBm.

Returns

  • deci-dBm value converted to a raw integer value that can be used directly with RAIL_SetTxPower.

A weak version of this function is provided that is tuned to provide accurate values for our boards. For a custom board, the relationship between what is written to the TX amplifier and the actual output power should be characterized and implemented in an overriding version of RAIL_ConvertDbmToRaw. For minimum code size and best speed use only raw values with the TxPower API and override this function with a smaller function. In the weak version provided with the RAIL library, railHandle is only used to indicate to the user from where the function was called, so it is OK to use either a real protocol handle, or one of the chip-specific ones, such as RAIL_EFR32_HANDLE.

Although the definitions of this function may change, the signature must be as declared here.

Note

  • This function is called from within the RAIL library for comparison between channel limitations and current power. It will throw an assert if you haven't called RAIL_InitTxPowerCurves which initializes the mappings between raw power levels and actual dBm powers. To avoid the assert, ensure that the maxPower of all channel configuration entries is RAIL_TX_POWER_MAX or above, or override this function to always return 255.


Definition at line 2850 of file common/rail.h

RAIL_VerifyTxPowerCurves#

void RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt *config)

Verify the TX Power Curves on modules.

Parameters
[in]config

TX Power Curves to use on this module.

This function only needs to be called when using a module and has no effect otherwise. Transmit will not work before this function is called.


Definition at line 2861 of file common/rail.h

RAIL_SetTxPowerDbm#

RAIL_Status_t RAIL_SetTxPowerDbm (RAIL_Handle_t railHandle, RAIL_TxPower_t power)

Set the TX power in terms of deci-dBm instead of raw power level.

Parameters
[in]railHandle

A RAIL instance handle.

[in]power

A desired deci-dBm power to be set.

Returns

  • RAIL Status variable indicate whether setting the power was successful.

This is a utility function for user convenience. Normally, to set TX power in dBm, do the following:

RAIL_TxPower_t power = 100; // 100 deci-dBm, 10 dBm
RAIL_TxPowerConfig_t txPowerConfig;
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertDbmToRaw will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPowerLevel_t powerLevel = RAIL_ConvertDbmToRaw(railHandle,
                                                      txPowerConfig.mode,
                                                      power);
RAIL_SetTxPower(railHandle, powerLevel);

This function wraps all those calls in a single function with power passed in as a parameter.


Definition at line 2888 of file common/rail.h

RAIL_GetTxPowerDbm#

RAIL_TxPower_t RAIL_GetTxPowerDbm (RAIL_Handle_t railHandle)

Get the TX power in terms of deci-dBm instead of raw power level.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The current output power in deci-dBm.

This is a utility function for user convenience. Normally, to get TX power in dBm, do the following:

RAIL_TxPowerLevel_t powerLevel = RAIL_GetTxPower(railHandle);
RAIL_TxPowerConfig_t txPowerConfig;
RAIL_GetTxPowerConfig(railHandle, &txPowerConfig);
// RAIL_ConvertRawToDbm will be the weak version provided by Silicon Labs
// by default, or the customer version, if overwritten.
RAIL_TxPower_t power = RAIL_ConvertRawToDbm(railHandle,
                                            txPowerConfig.mode,
                                            powerLevel);
return power;

This function wraps all those calls in a single function with power returned as the result.


Definition at line 2914 of file common/rail.h

RAIL_GetPowerSettingTable#

const RAIL_PaPowerSetting_t * RAIL_GetPowerSettingTable (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t mode, RAIL_TxPower_t *minPower, RAIL_TxPower_t *maxPower, RAIL_TxPowerLevel_t *step)

Get the TX PA power setting table and related values.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

PA mode for which to get the powersetting table

[out]minPower

A pointer to a RAIL_TxPower_t

[out]maxPower

A pointer to a RAIL_TxPower_t

[out]step

In deci-dBm increments. A pointer to a RAIL_TxPowerLevel_t

Returns

  • Power setting table start address. When NULL is returned all out params above won't be set.

The number of entries in the table can be calculated based on the minPower, maxPower, and step parameters. For example, for minPower = 115 (11.5 dBm), maxPower = 300 (30 dBm), and step = 1, the number of entries in table would be 186


Definition at line 2931 of file common/rail.h

RAIL_SetPaPowerSetting#

RAIL_Status_t RAIL_SetPaPowerSetting (RAIL_Handle_t railHandle, RAIL_PaPowerSetting_t paPowerSetting, RAIL_TxPower_t minPowerDbm, RAIL_TxPower_t maxPowerDbm, RAIL_TxPower_t currentPowerDbm)

Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().

Parameters
[in]railHandle

A RAIL instance handle.

[in]paPowerSetting

The desired PA power setting.

[in]minPowerDbm

The minimum power in dBm that the PA can output.

[in]maxPowerDbm

The maximum power in dBm that the PA can output.

[in]currentPowerDbm

The corresponding output power in dBm for this power setting.

Returns

  • RAIL Status variable indicate whether setting the PA power setting was successful.


Definition at line 2947 of file common/rail.h

RAIL_GetPaPowerSetting#

RAIL_PaPowerSetting_t RAIL_GetPaPowerSetting (RAIL_Handle_t railHandle)

Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The current PA power setting.


Definition at line 2960 of file common/rail.h

RAIL_EnablePaAutoMode#

RAIL_Status_t RAIL_EnablePaAutoMode (RAIL_Handle_t railHandle, bool enable)

Enable automatic switching between PAs internally to the RAIL library.

Parameters
[in]railHandle

A real (not generic) RAIL instance handle.

[in]enable

Enable or disable PA Auto Mode.

While PA Automode is enabled, the PA will be chosen and set automatically whenever RAIL_SetTxPowerDbm is called or whenever powers are coerced automatically, internally to the RAIL library during a channel change. While PA Auto Mode is enabled, users cannot call RAIL_ConfigTxPower or RAIL_SetTxPower. When entering auto mode, RAIL_SetTxPowerDbm must be called to specify the desired power. When leaving auto mode, RAIL_ConfigTxPower as well as one of RAIL_SetTxPower or RAIL_SetTxPowerDbm must be called to re-specify the desired PA and power level combination.

Note

  • : Power conversion curves must be initialized before calling this function. That is, RAIL_ConvertDbmToRaw and RAIL_ConvertRawToDbm most both be able to operate properly to ensure that PA Auto Mode functions correctly. See the PA Conversions plugin or AN1127 for more details.

Returns

  • Status parameter indicating success of function call.


Definition at line 2983 of file common/rail.h

RAIL_IsPaAutoModeEnabled#

bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)

Query status of PA Auto Mode.

Parameters
[in]railHandle

A real (not generic) RAIL instance handle on which to query PA Auto Mode status.

Returns

  • Indicator of whether Auto Mode is enabled (true) or not (false).


Definition at line 2992 of file common/rail.h

RAILCb_PaAutoModeDecision#

RAIL_Status_t RAILCb_PaAutoModeDecision (RAIL_Handle_t railHandle, RAIL_TxPower_t *power, RAIL_TxPowerMode_t *mode, const RAIL_ChannelConfigEntry_t *chCfgEntry)

Callback that decides which PA and power level should be used while in PA auto mode.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]power

Pointer to the dBm output power (in deci-dBm, 10*dBm) being requested. The value this points to when the function returns will be applied to the radio.

[out]mode

Pointer to the RAIL_TxPowerMode_t to be used to achieve the requested power. The value this points to when the function returns will be applied to the radio.

[in]chCfgEntry

Pointer to a RAIL_ChannelConfigEntry_t. While switching channels, it will be the entry RAIL is switch to, during a call to RAIL_SetTxPowerDbm, it will be the entry RAIL is already on. Can be NULL if a channel configuration was not set or no valid channels are present.

Returns

  • Return status indicating result of function call. If this is anything except RAIL_STATUS_NO_ERROR, neither PA's nor their powers will be configured automatically.

Whatever values mode and powerLevel point to when this function return will be applied to the PA hardware and used for transmits. Note

  • The mode and power level provided by this function depends on the RAIL_PaAutoModeConfig provided for the chip. The RAIL_PaAutoModeConfig definition for a chip should tend to all the bands supported by the chip and cover the full range of power to find a valid entry for requested power for a specific band.


Definition at line 3022 of file common/rail.h

RAIL_StartTx#

RAIL_Status_t RAIL_StartTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

The transmit process will begin immediately or as soon as a packet being received has finished. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo().

Returns an error if a previous transmit is still in progress. If changing channels, any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3061 of file common/rail.h

RAIL_StartScheduledTx#

RAIL_Status_t RAIL_StartScheduledTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *config, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule sending a packet.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]config

A pointer to the RAIL_ScheduleTxConfig_t structure containing when the transmit should occur.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

The transmit process will begin at the scheduled time. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). The time (in microseconds) and whether that time is absolute or relative is specified using the RAIL_ScheduleTxConfig_t structure. What to do if a scheduled transmit fires in the middle of receiving a packet is also specified in this structure.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and will abort any ongoing packet reception.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3096 of file common/rail.h

RAIL_StartCcaCsmaTx#

RAIL_Status_t RAIL_StartCcaCsmaTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_CsmaConfig_t *csmaConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit using CSMA.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]csmaConfig

A pointer to the RAIL_CsmaConfig_t structure describing the CSMA parameters to use for this transmit. In multiprotocol this must point to global or heap storage that remains valid after the API returns until the transmit is actually started.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

Perform the Carrier Sense Multiple Access (CSMA) algorithm, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during CSMA backoff periods if receive is active throughout the CSMA process. This will happen either by starting the CSMA process while receive is already active, or if the csmaBackoff time in the RAIL_CsmaConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the csmaBackoff time is greater than the idleToRx time, receive will only be active during CSMA's clear channel assessments.

If the CSMA algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

Returns an error if a scheduled RX is still in progress.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3144 of file common/rail.h

RAIL_StartCcaLbtTx#

RAIL_Status_t RAIL_StartCcaLbtTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_LbtConfig_t *lbtConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Start a transmit using LBT.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]lbtConfig

A pointer to the RAIL_LbtConfig_t structure describing the LBT parameters to use for this transmit. In multiprotocol this must point to global or heap storage that remains valid after the API returns until the transmit is actually started.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

Performs the Listen Before Talk (LBT) algorithm, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during LBT backoff periods if receive is active throughout the LBT process. This will happen either by starting the LBT process while receive is already active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the lbtBackoff time is greater than the idleToRx time, receive will only be active during LBT's clear channel assessments.

If the LBT algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

Returns an error if a scheduled RX is still in progress.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3192 of file common/rail.h

RAIL_StartScheduledCcaCsmaTx#

RAIL_Status_t RAIL_StartScheduledCcaCsmaTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *scheduleTxConfig, const RAIL_CsmaConfig_t *csmaConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a transmit using CSMA.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]scheduleTxConfig

A pointer to the RAIL_ScheduleTxConfig_t structure describing the CSMA parameters to use for this transmit.

[in]csmaConfig

A pointer to the RAIL_CsmaConfig_t structure describing the CSMA parameters to use for this transmit. In multiprotocol this must point to global or heap storage that remains valid after the API returns until the transmit is actually started.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

Internally, the RAIL library needs a PRS channel for this feature. It will allocate an available PRS channel to use and hold onto that channel for future use. If no PRS channel is available, the function returns with RAIL_STATUS_INVALID_CALL.

Perform the Carrier Sense Multiple Access (CSMA) algorithm at the scheduled time, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during CSMA backoff periods if receive is active throughout the CSMA process. This will happen either by starting the CSMA process while receive is already active, or if the csmaBackoff time in the RAIL_CsmaConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the csmaBackoff time is greater than the idleToRx time, receive will only be active during CSMA's clear channel assessments.

If the CSMA algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3245 of file common/rail.h

RAIL_StartScheduledCcaLbtTx#

RAIL_Status_t RAIL_StartScheduledCcaLbtTx (RAIL_Handle_t railHandle, uint16_t channel, RAIL_TxOptions_t options, const RAIL_ScheduleTxConfig_t *scheduleTxConfig, const RAIL_LbtConfig_t *lbtConfig, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a transmit using LBT.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

Define the channel to transmit on.

[in]options

TX options to be applied to this transmit only.

[in]scheduleTxConfig

A pointer to the RAIL_ScheduleTxConfig_t structure describing the CSMA parameters to use for this transmit.

[in]lbtConfig

A pointer to the RAIL_LbtConfig_t structure describing the LBT parameters to use for this transmit. In multiprotocol this must point to global or heap storage that remains valid after the API returns until the transmit is actually started.

[in]schedulerInfo

Information to allow the radio scheduler to place this transmit appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

Internally, the RAIL library needs a PRS channel for this feature. It will allocate an available PRS channel to use and hold onto that channel for future use. If no PRS channel is available, the function returns with RAIL_STATUS_INVALID_CALL.

Performs the Listen Before Talk (LBT) algorithm at the scheduled time, and if the channel is deemed clear (RSSI below the specified threshold), it will commence transmission. The data to be transmitted must have been previously established via RAIL_SetTxFifo() and/or RAIL_WriteTxFifo(). Packets can be received during LBT backoff periods if receive is active throughout the LBT process. This will happen either by starting the LBT process while receive is already active, or if the lbtBackoff time in the RAIL_LbtConfig_t is less than the idleToRx time (set by RAIL_SetStateTiming()). If the lbtBackoff time is greater than the idleToRx time, receive will only be active during LBT's clear channel assessments.

If the LBT algorithm deems the channel busy, the RAIL_Config_t::eventsCallback occurs with RAIL_EVENT_TX_CHANNEL_BUSY, and the contents of the transmit FIFO remain intact.

Returns an error if a previous transmit is still in progress. If changing channels, the channel is changed immediately and any ongoing packet reception is aborted.

In multiprotocol, ensure that the radio is properly yielded after this operation completes. See Yielding the Radio for more details.


Definition at line 3299 of file common/rail.h

RAIL_StopTx#

RAIL_Status_t RAIL_StopTx (RAIL_Handle_t railHandle, RAIL_StopMode_t mode)

Stop an active or pending transmit.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mode

Configure the types of transmits to stop.

Returns

Note


Definition at line 3324 of file common/rail.h

RAIL_SetCcaThreshold#

RAIL_Status_t RAIL_SetCcaThreshold (RAIL_Handle_t railHandle, int8_t ccaThresholdDbm)

Set the CCA threshold in dBm.

Parameters
[in]railHandle

A RAIL instance handle.

[in]ccaThresholdDbm

The CCA threshold in dBm.

Returns

  • Status code indicating success of the function call.

Unlike RAIL_StartCcaCsmaTx() or RAIL_StartCcaLbtTx(), which can cause a transmit, this function only modifies the CCA threshold. A possible use case for this function involves setting the CCA threshold to invalid RSSI of -128 which blocks transmission by preventing clear channel assessments from succeeding.


Definition at line 3339 of file common/rail.h

RAIL_GetTxPacketDetails#

RAIL_Status_t RAIL_GetTxPacketDetails (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Get detailed information about the last packet transmitted.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

An application-provided pointer to store RAIL_TxPacketDetails_t corresponding to the transmit event. The isAck and timeSent fields totalPacketBytes and timePosition must be initialized prior to each call:

  • isAck true to obtain details about the most recent ACK transmit, false to obtain details about the most recent app-initiated transmit.

  • totalPacketBytes with the total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes sent over the air after the Preamble and Sync word(s), including CRC bytes.

  • timePosition with a RAIL_PacketTimePosition_t value specifying the packet position to put in the timeSent field on return. This field will also be updated with the actual position corresponding to the timeSent value filled in.

Returns

Note

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.


Definition at line 3369 of file common/rail.h

RAIL_GetTxPacketDetailsAlt#

RAIL_Status_t RAIL_GetTxPacketDetailsAlt (RAIL_Handle_t railHandle, bool isAck, RAIL_Time_t *pPacketTime)

Get detailed information about the last packet transmitted.

Parameters
[in]railHandle

A RAIL instance handle.

[in]isAck

True to obtain details about the most recent ACK transmit. False to obtain details about the most recent app-initiated transmit.

[out]pPacketTime

An application-provided non-NULL pointer to store a RAIL_Time_t corresponding to the transmit event. This will be populated with a timestamp corresponding to an arbitrary location in the packet. Call RAIL_GetTxTimePreambleStart, RAIL_GetTxTimeSyncWordEnd, or RAIL_GetTxTimeFrameEnd to adjust the timestamp for different locations in the packet.

Returns

Note

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.


Definition at line 3396 of file common/rail.h

RAIL_GetTxPacketDetailsAlt2#

RAIL_Status_t RAIL_GetTxPacketDetailsAlt2 (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Get detailed information about the last packet transmitted.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

An application-provided pointer to store RAIL_TxPacketDetails_t corresponding to the transmit event. The isAck must be initialized prior to each call:

  • isAck true to obtain details about the most recent ACK transmit, false to obtain details about the most recent app-initiated transmit. The timeSent field packetTime will be populated with a timestamp corresponding to a default location in the packet. The timeSent field timePosition will be populated with a RAIL_PacketTimePosition_t value specifying that default packet location. Call RAIL_GetTxTimePreambleStartAlt, RAIL_GetTxTimeSyncWordEndAlt, or RAIL_GetTxTimeFrameEndAlt to adjust the timestamp for different locations in the packet.

Returns

This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.


Definition at line 3422 of file common/rail.h

RAIL_GetTxTimePreambleStart#

RAIL_Status_t RAIL_GetTxTimePreambleStart (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the transmitted packet for RAIL to use when adjusting the provided timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below).

[inout]pPacketTime

This points to the RAIL_Time_t returned from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. That time will be updated with the time that the preamble for this packet started on air. Must be non-NULL.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully determined or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, totalPacketBytes must be RAIL_TX_STARTED_BYTES, and pPacketTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt()).


Definition at line 3457 of file common/rail.h

RAIL_GetTxTimePreambleStartAlt#

RAIL_Status_t RAIL_GetTxTimePreambleStartAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX completion timestamp to refer to the start of the preamble.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that the preamble for this packet started on air.

Also used to retrieve the RAIL_EVENT_TX_STARTED timestamp.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

When used for timestamp adjustment, call this function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.

This function may be called when handling the RAIL_EVENT_TX_STARTED event to retrieve that event's start-of-normal-TX timestamp. (ACK transmits currently have no equivalent event or associated timestamp.) In this case, the timeSent field totalPacketBytes must be RAIL_TX_STARTED_BYTES, and the timeSent field packetTime is an output-only parameter filled in with that time (so no need to initialize it beforehand by calling RAIL_GetTxPacketDetailsAlt2()).


Definition at line 3492 of file common/rail.h

RAIL_GetTxTimeSyncWordEnd#

RAIL_Status_t RAIL_GetTxTimeSyncWordEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes.

[inout]pPacketTime

The time that was returned in a RAIL_Time_t from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.


Definition at line 3515 of file common/rail.h

RAIL_GetTxTimeSyncWordEndAlt#

RAIL_Status_t RAIL_GetTxTimeSyncWordEndAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of the sync word.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.


Definition at line 3540 of file common/rail.h

RAIL_GetTxTimeFrameEnd#

RAIL_Status_t RAIL_GetTxTimeFrameEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL TX timestamp to refer to the end of frame.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the transmitted packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes.

[inout]pPacketTime

The time that was returned in a RAIL_Time_t from a previous call to RAIL_GetTxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt() is called.


Definition at line 3563 of file common/rail.h

RAIL_GetTxTimeFrameEndAlt#

RAIL_Status_t RAIL_GetTxTimeFrameEndAlt (RAIL_Handle_t railHandle, RAIL_TxPacketDetails_t *pPacketDetails)

Adjust a RAIL TX timestamp to refer to the end of frame.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetTxPacketDetailsAlt2 for this same packet. The application must update the timeSent field totalPacketBytes to be the total number of bytes of the sent packet for RAIL to use when calculating the specified timestamp. This should account for all bytes transmitted over the air after the Preamble and Sync word(s), including CRC bytes. Pass RAIL_TX_STARTED_BYTES to retrieve the start-of-normal-TX timestamp (see below). After this function, the timeSent field packetTime will be updated with the time that this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.


Definition at line 3589 of file common/rail.h

RAIL_EnableTxHoldOff#

void RAIL_EnableTxHoldOff (RAIL_Handle_t railHandle, bool enable)

Prevent the radio from starting a transmit.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

Enable/Disable TX hold off.

Enable TX hold off to prevent the radio from starting any transmits. Disable TX hold off to allow the radio to transmit again. Attempting to transmit with the TX hold off enabled will result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.

Note

  • This function does not affect a transmit that has already started. To stop an already-started transmission, use RAIL_Idle() with RAIL_IDLE_ABORT.


Definition at line 3608 of file common/rail.h

RAIL_IsTxHoldOffEnabled#

bool RAIL_IsTxHoldOffEnabled (RAIL_Handle_t railHandle)

Check whether or not TX hold off is enabled.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Returns true if TX hold off is enabled, false otherwise.

TX hold off can be enabled/disabled using RAIL_EnableTxHoldOff. Attempting to transmit with the TX hold off enabled will block the transmission and result in RAIL_EVENT_TX_BLOCKED and/or RAIL_EVENT_TXACK_BLOCKED events.


Definition at line 3621 of file common/rail.h

RAIL_SetTxAltPreambleLength#

RAIL_Status_t RAIL_SetTxAltPreambleLength (RAIL_Handle_t railHandle, uint16_t length)

Set an alternate transmitter preamble length.

Parameters
[in]railHandle

A RAIL instance handle.

[in]length

The desired preamble length, in bits.

Returns

  • Status code indicating success of the function call.

To cause a transmission to use this alternate preamble length, specify RAIL_TX_OPTION_ALT_PREAMBLE_LEN in the txOptions parameter passed to the respective RAIL transmit API.

Note


Definition at line 3637 of file common/rail.h

RAIL_ConfigRxOptions#

RAIL_Status_t RAIL_ConfigRxOptions (RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)

Configure receive options.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mask

A bitmask containing which options should be modified.

[in]options

A bitmask containing desired configuration settings. Bit positions for each option are found in the RAIL_RxOptions_t.

Returns

  • Status code indicating success of the function call.

Configure the radio receive flow based on the list of available options. Only the options indicated by the mask parameter will be affected. Pass RAIL_RX_OPTIONS_ALL to set all parameters. The previous settings may affect the current frame if a packet is received during this configuration.

Note


Definition at line 3671 of file common/rail.h

RAIL_IncludeFrameTypeLength#

void RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

Parameters
[in]railHandle

A RAIL instance handle.

This function must be called before RAIL_ConfigChannels to allow configurations using a frame type based length setup. In RAIL 2.x, it is called by default in the RAILCb_ConfigFrameTypeLength API which can be overridden to save code space. In future versions, the user may be required to call this API explicitly.


Definition at line 3686 of file common/rail.h

RAILCb_ConfigFrameTypeLength#

void RAILCb_ConfigFrameTypeLength (RAIL_Handle_t railHandle, const RAIL_FrameType_t *frameType)

Handle frame type length.

Parameters
[in]railHandle

A RAIL instance handle.

[in]frameType

A frame type configuration structure.

This function is implemented in the radio configuration. Currently, the frame type passed in only handles packet length decoding. If NULL is passed into this function, it clears any currently configured frame type settings. This will either be implemented as an empty function in the radio configuration if it is not needed, to assist in dead code elimination.


Definition at line 3701 of file common/rail.h

RAIL_StartRx#

RAIL_Status_t RAIL_StartRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_SchedulerInfo_t *schedulerInfo)

Start the receiver on a specific channel.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The channel to listen on.

[in]schedulerInfo

Information to allow the radio scheduler to place this receive appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

  • Status code indicating success of the function call.

This is a non-blocking function. Whenever a packet is received, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_RX_PACKET_RECEIVED set. If you call this while not idle but with a different channel, any ongoing receive or transmit operation will be aborted.


Definition at line 3719 of file common/rail.h

RAIL_ScheduleRx#

RAIL_Status_t RAIL_ScheduleRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_ScheduleRxConfig_t *cfg, const RAIL_SchedulerInfo_t *schedulerInfo)

Schedule a receive window for some future time.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel to listen on.

[in]cfg

The configuration structure to define the receive window.

[in]schedulerInfo

Information to allow the radio scheduler to place this receive appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

  • Status code indicating success of the function call.

This API immediately changes the channel and schedules receive to start at the specified time and end at the given end time. If you do not specify an end time, you may call this API later with an end time as long as you set the start time to disabled. You can also terminate the receive operation immediately using the RAIL_Idle() function. Note that relative end times are always relative to the start unless no start time is specified. If changing channels, the channel is changed immediately and will abort any ongoing packet transmission or reception.

Returns an error if a CSMA or LBT transmit is still in progress.

In multiprotocol, ensure that you properly yield the radio after this call. See Yielding the Radio for more details.


Definition at line 3748 of file common/rail.h

RAIL_GetRxPacketInfo#

RAIL_RxPacketHandle_t RAIL_GetRxPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketInfo_t *pPacketInfo)

Get basic information about a pending or received packet.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle for the unreleased packet as returned from a previous call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST.

[out]pPacketInfo

An application-provided pointer to store RAIL_RxPacketInfo_t for the requested packet. Must be non-NULL.

Returns

  • The packet handle for the requested packet: if packetHandle was one of the sentinel values, returns the actual packet handle for that packet, otherwise returns packetHandle. It may return RAIL_RX_PACKET_HANDLE_INVALID to indicate an error.

This function can be used in any RX mode. It does not free up any internal resources. If used in RX RAIL_DataMethod_t::FIFO_MODE, the value in RAIL_RxPacketInfo_t::packetBytes will only return the data remaining in the FIFO. Any data read via earlier calls to RAIL_ReadRxFifo() is not included.

Note

  • When getting information about an arriving packet that is not yet complete, (i.e., pPacketInfo->packetStatus == RAIL_RX_PACKET_RECEIVING), keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.


Definition at line 3823 of file common/rail.h

RAIL_GetRxIncomingPacketInfo#

void RAIL_GetRxIncomingPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t *pPacketInfo)

Get information about the live incoming packet (if any).

Parameters
[in]railHandle

A RAIL instance handle.

[out]pPacketInfo

Application provided pointer to store RAIL_RxPacketInfo_t for the incoming packet.

Differs from RAIL_GetRxPacketInfo() by only returning information about a packet actively being received, something which even the RAIL_RX_PACKET_HANDLE_NEWEST may not represent if there are completed but unprocessed packets in the receive FIFO.

This function can only be called from callback context, e.g., when handling RAIL_EVENT_RX_FILTER_PASSED or RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND. It must not be used with receive RAIL_DataMethod_t::FIFO_MODE if any portion of an incoming packet has already been extracted from the receive FIFO.

Note

  • The incomplete data of an arriving packet is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.


Definition at line 3856 of file common/rail.h

RAIL_CopyRxPacket#

static void RAIL_CopyRxPacket (uint8_t *pDest, const RAIL_RxPacketInfo_t *pPacketInfo)

Copy a full packet to a user-specified contiguous buffer.

Parameters
[out]pDest

An application-provided pointer to a buffer of at least pPacketInfo->packetBytes in size to store the packet data contiguously. This buffer must never overlay RAIL's receive FIFO buffer. Exactly pPacketInfo->packetBytes of packet data will be written into it.

[in]pPacketInfo

RAIL_RxPacketInfo_t for the requested packet.

Note

  • This is a convenience helper function, which is intended to be expedient. As a result, it does not check the validity of its arguments, so don't pass either as NULL, and don't pass a pDest pointer to a buffer that's too small for the packet's data.

  • If only a portion of the packet is needed, use RAIL_PeekRxPacket() instead.


Definition at line 3878 of file common/rail.h

RAIL_GetRxPacketDetails#

RAIL_Status_t RAIL_GetRxPacketDetails (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Get detailed information about a received packet.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle for the unreleased packet as returned from a previous call to RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket(), or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST.

[inout]pPacketDetails

An application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived fields totalPacketBytes and timePosition must be initialized prior to each call:

  • totalPacketBytes with the total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.

  • timePosition with a RAIL_PacketTimePosition_t value specifying the packet position to put in the timeReceived field on return. This field will also be updated with the actual position corresponding to the timeReceived value filled in.

This function can be used in any RX mode; it does not free up any internal resources.

Returns

Note


Definition at line 3924 of file common/rail.h

RAIL_GetRxPacketDetailsAlt#

RAIL_Status_t RAIL_GetRxPacketDetailsAlt (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Get detailed information about a received packet.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle for the unreleased packet as returned from a previous call to RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket(), or sentinel values RAIL_RX_PACKET_HANDLE_OLDESTRAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST.

[out]pPacketDetails

An application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived field packetTime will be populated with a timestamp corresponding to a default location in the packet. The timeReceived field timePosition will be populated with a RAIL_PacketTimePosition_t value specifying that default packet location. Call RAIL_GetRxTimePreambleStart, RAIL_GetRxTimeSyncWordEnd, or RAIL_GetRxTimeFrameEnd to adjust that timestamp for different locations in the packet.

This function can be used in any RX mode. It does not free up any internal resources.

Returns

This alternative API allows for smaller code size by deadstripping the timestamp adjustment algorithms which are not in use.

Note


Definition at line 3961 of file common/rail.h

RAIL_GetRxTimePreambleStart#

RAIL_Status_t RAIL_GetRxTimePreambleStart (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.

[inout]pPacketTime

The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the preamble for this packet started on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 3988 of file common/rail.h

RAIL_GetRxTimePreambleStartAlt#

RAIL_Status_t RAIL_GetRxTimePreambleStartAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the start of the preamble.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the timeReceived field packetTime will be updated with the time that the preamble for this packet started on air.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.


Definition at line 4010 of file common/rail.h

RAIL_GetRxTimeSyncWordEnd#

RAIL_Status_t RAIL_GetRxTimeSyncWordEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.

[inout]pPacketTime

The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 4036 of file common/rail.h

RAIL_GetRxTimeSyncWordEndAlt#

RAIL_Status_t RAIL_GetRxTimeSyncWordEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of the sync word.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the timeReceived field packetTime will be updated with the time that the sync word for this packet finished on air.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.


Definition at line 4058 of file common/rail.h

RAIL_GetRxTimeFrameEnd#

RAIL_Status_t RAIL_GetRxTimeFrameEnd (RAIL_Handle_t railHandle, uint16_t totalPacketBytes, RAIL_Time_t *pPacketTime)

Adjust a RAIL RX timestamp to refer to the end of frame.

Parameters
[in]railHandle

A RAIL instance handle.

[in]totalPacketBytes

The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.

[inout]pPacketTime

The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that this packet finished on air. Must be non-NULL.

Returns

  • RAIL_STATUS_NO_ERROR if pPacketTime was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 4084 of file common/rail.h

RAIL_GetRxTimeFrameEndAlt#

RAIL_Status_t RAIL_GetRxTimeFrameEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX timestamp to refer to the end of frame.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]pPacketDetails

The non-NULL details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the timeReceived field packetTime will be updated with the time that the packet finished on air.

Returns

  • RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.


Definition at line 4106 of file common/rail.h

RAIL_HoldRxPacket#

RAIL_RxPacketHandle_t RAIL_HoldRxPacket (RAIL_Handle_t railHandle)

Place a temporary hold on this packet's data and information resources within RAIL.

Parameters
[in]railHandle

A RAIL instance handle.

This function can only be called from within RAIL callback context. It can be used in any RX mode.

Normally, when RAIL issues its callback indicating a packet is ready or aborted, it expects the application's callback to retrieve and copy (or discard) the packet's information and data, and will free up its internal packet data after the callback returns. This function tells RAIL to hold onto those resources after the callback returns in case the application wants to defer processing the packet to a later time, e.g., outside of callback context.

Returns

  • The packet handle for the packet associated with the callback, RAIL_RX_PACKET_HANDLE_INVALID if no such packet yet exists or railHandle is not active.

Note

  • When using multiprotocol the receive FIFO is reset during protocol switches so any packets held with RAIL_HoldRxPacket() will be lost. It is best to avoid using this in DMP or to at least reset any internal held packet information when the RAIL_EVENT_CONFIG_UNSCHEDULED occurs.


Definition at line 4135 of file common/rail.h

RAIL_PeekRxPacket#

uint16_t RAIL_PeekRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, uint8_t *pDst, uint16_t len, uint16_t offset)

Copy 'len' bytes of packet data starting from 'offset' from the receive FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle as returned from a previous RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST.

[out]pDst

A pointer to the location where the received bytes will be copied. If NULL, no copying occurs.

[in]len

A number of packet data bytes to copy.

[in]offset

A byte offset within remaining packet data from which to copy.

Those bytes remain valid for re-peeking.

Returns

  • Number of packet bytes copied.

Note

  • Peek does not permit peeking beyond the requested packet's available packet data (though there is a small chance it might for a RAIL_RX_PACKET_HANDLE_NEWEST packet at the very end of still being received). Nor can one peek into already-consumed data read by RAIL_ReadRxFifo(). len and offset are relative to the remaining data available in the packet, if any was already consumed by RAIL_ReadRxFifo().


Definition at line 4161 of file common/rail.h

RAIL_ReleaseRxPacket#

RAIL_Status_t RAIL_ReleaseRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)

Release RAIL's internal resources for the packet.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle as returned from a previous RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST. The latter might be used within RAIL callback context to explicitly release the packet associated with the callback early, before it's released automatically by RAIL on callback return (unless explicitly held).

This function must be called for any packet previously held via RAIL_HoldRxPacket(). It may optionally be called within a callback context to release RAIL resources sooner than at callback completion time when not holding the packet. This function can be used in any RX mode.

Returns


Definition at line 4188 of file common/rail.h

RAIL_GetRssi#

int16_t RAIL_GetRssi (RAIL_Handle_t railHandle, bool wait)

Return the current raw RSSI.

Parameters
[in]railHandle

A RAIL instance handle.

[in]wait

if false returns instant RSSI with no checks.

Returns

  • RAIL_RSSI_INVALID if the receiver is disabled and an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm, dbm*4.

Gets the current RSSI value. This value represents the current energy of the channel. It can change rapidly and will be low if no RF energy is in the current channel. The function from the value reported to dBm is an offset dependent on the PHY and the PCB layout. Characterize the RSSI received on your hardware and apply an offset in the application to account for board and PHY parameters. When 'wait' is false, the radio needs to be currently in RX and have been in there for a sufficient amount of time for a fresh RSSI value to be read and returned. Otherwise, the RSSI is considered stale and RAIL_RSSI_INVALID is returned instead. When 'wait' is true, if the radio is transitioning to or already in RX, this function will wait for a valid RSSI to be read and return it. Otherwise, if the radio is in or transitions to IDLE or TX, RAIL_RSSI_INVALID will be returned. On low datarate PHYs, this function can take a significantly longer time when wait is true.

In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t. Additionally, 'wait' should never be set 'true' in multiprotocol as the wait time is not consistent, so scheduling a scheduler slot cannot be done accurately. Rather if waiting for a valid RSSI is desired, use RAIL_GetRssiAlt instead to apply a bounded time period.

Note


Definition at line 4234 of file common/rail.h

RAIL_GetRssiAlt#

int16_t RAIL_GetRssiAlt (RAIL_Handle_t railHandle, RAIL_Time_t waitTimeout)

Return the current raw RSSI within a definitive time period.

Parameters
[in]railHandle

A RAIL instance handle.

[in]waitTimeout

Sets the maximum time to wait for a valid RSSI. If equal to RAIL_GET_RSSI_NO_WAIT returns instant RSSI with no checks. If equal to RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT waits for a valid RSSI with no maximum timeout.

Returns

  • RAIL_RSSI_INVALID if the receiver is disabled and an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm, dbm*4.

Gets the current RSSI value. This value represents the current energy of the channel. It can change rapidly, and will be low if no RF energy is in the current channel. The function from the value reported to dBm is an offset dependent on the PHY and the PCB layout. Characterize the RSSI received on your hardware and apply an offset in the application to account for board and PHY parameters. If a value of RAIL_GET_RSSI_NO_WAIT is given for waitTimeout, the radio needs to be currently in RX and have been in there for a sufficient amount of time for a fresh RSSI value to be read and returned. Otherwise the RSSI is considered stale and RAIL_RSSI_INVALID is returned instead. For non-zero values of waitTimeout, if the radio is transitioning to or already in RX, this function will wait a maximum time equal to waitTimeout (or indefinitely if waitTimeout is set to RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT) for a valid RSSI to be read and return it. Otherwise, if the waitTimeout is reached, or the radio is in or transitions to IDLE or TX, RAIL_RSSI_INVALID will be returned. On low datarate PHYs, this function can take a significantly longer time when waitTimeout is non-zero.

In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t. Additionally, 'waitTimeout' should never be set to a value other than RAIL_GET_RSSI_NO_WAIT in multiprotocol as the integration between this feature and the radio scheduler has not been implemented.

Note


Definition at line 4280 of file common/rail.h

RAIL_StartAverageRssi#

RAIL_Status_t RAIL_StartAverageRssi (RAIL_Handle_t railHandle, uint16_t channel, RAIL_Time_t averagingTimeUs, const RAIL_SchedulerInfo_t *schedulerInfo)

Start the RSSI averaging over a specified time in us.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The physical channel to set.

[in]averagingTimeUs

Averaging time in microseconds.

[in]schedulerInfo

Information to allow the radio scheduler to place this operation appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

Returns

  • Status code indicating success of the function call.

Starts a non-blocking hardware-based RSSI averaging mechanism. Only a single instance of RSSI averaging can be run at any time and the radio must be idle to start.

In multiprotocol, this is a scheduled event. It will start when railHandle becomes active. railHandle needs to stay active until the averaging completes. If the averaging is interrupted, calls to RAIL_GetAverageRssi will return RAIL_RSSI_INVALID.

Also in multiprotocol, the user is required to call RAIL_YieldRadio after this event completes (i.e., when RAIL_EVENT_RSSI_AVERAGE_DONE occurs).

Note


Definition at line 4310 of file common/rail.h

RAIL_IsAverageRssiReady#

bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)

Query whether the RSSI averaging is done.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Returns true if done and false otherwise.

This function can be used to poll for completion of the RSSI averaging to avoid relying on an interrupt-based callback.

Note

  • If the radio is idled while RSSI averaging is still in effect, this function may never return true.


Definition at line 4327 of file common/rail.h

RAIL_GetAverageRssi#

int16_t RAIL_GetAverageRssi (RAIL_Handle_t railHandle)

Get the RSSI averaged over a specified time in us.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Return RAIL_RSSI_INVALID if the receiver is disabled an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm,dbm*4.

Gets the hardware RSSI average after issuing RAIL_StartAverageRssi. Use after RAIL_StartAverageRssi.


Definition at line 4340 of file common/rail.h

RAIL_SetRssiOffset#

RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)

Set the RSSI offset.

Parameters
[in]railHandle

a RAIL instance handle.

[in]rssiOffset

desired offset to be added to the RSSI measurements.

Returns

Adds an offset to the RSSI in dBm. This offset affects all functionality that depends on RSSI values, such as CCA functions. Do not modify the offset dynamically during packet reception. This function can only be called while the radio is off, or in the case of multiprotocol, on an inactive protocol.

Note


Definition at line 4373 of file common/rail.h

RAIL_GetRssiOffset#

int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)

Get the RSSI offset.

Parameters
[in]railHandle

a RAIL instance handle.

Returns

  • rssiOffset in dBm corresponding to the current handle.

Note

  • : A chip-specific handle, such as RAIL_EFR32_HANDLE, can be used to get the chip level RSSI offset otherwise this will return the RSSI offset value associated with the RAIL instance handle, exclusive of any chip level RSSI offset correction, if any.


Definition at line 4386 of file common/rail.h

RAIL_SetRssiDetectThreshold#

RAIL_Status_t RAIL_SetRssiDetectThreshold (RAIL_Handle_t railHandle, int8_t rssiThresholdDbm)

Set the RSSI detection threshold(in dBm) to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.

Parameters
[in]railHandle

a RAIL instance handle.

[in]rssiThresholdDbm

desired RSSI threshold(in dBm) over which the event RAIL_EVENT_DETECT_RSSI_THRESHOLD is triggered.

Returns

When in receive, RSSI is sampled and if it exceeds the threshold, RAIL_EVENT_DETECT_RSSI_THRESHOLD is triggered.

Note

  • : If the radio is idled or this function is called with rssiThresholdDbm as RAIL_RSSI_INVALID_DBM while RSSI detect is still in effect, a RAIL_EVENT_DETECT_RSSI_THRESHOLD may not occur and the detection is disabled. If the RSSI is already above threshold when this function is called then RAIL_EVENT_DETECT_RSSI_THRESHOLD will occur. Once the RSSI goes over the configured threshold and RAIL_EVENT_DETECT_RSSI_THRESHOLD occurs, this function needs to be called again to reactivate the RSSI threshold detection. This function is only available on series-2 Sub-GHz parts EFR32XG23 and EFR32XG25.


Definition at line 4415 of file common/rail.h

RAIL_GetRssiDetectThreshold#

int8_t RAIL_GetRssiDetectThreshold (RAIL_Handle_t railHandle)

Get the RSSI detection threshold(in dBm).

Parameters
[in]railHandle

a RAIL instance handle.

Returns

  • rssiThreshold (in dBm) corresponding to the current handle.

Note


Definition at line 4430 of file common/rail.h

RAIL_ConvertLqi#

RAIL_Status_t RAIL_ConvertLqi (RAIL_Handle_t railHandle, RAIL_ConvertLqiCallback_t cb)

Set up a callback function capable of converting a RX packet's LQI value before being consumed by application code.

Parameters
[in]railHandle

A RAIL instance handle.

[in]cb

A callback of type RAIL_ConvertLqiCallback_t that is called before the RX packet LQI value is loaded into the RAIL_RxPacketDetails_t structure for application consumption.

Returns

  • Status code indicating success of the function call.


Definition at line 4442 of file common/rail.h

RAIL_ConfigAddressFilter#

RAIL_Status_t RAIL_ConfigAddressFilter (RAIL_Handle_t railHandle, const RAIL_AddrConfig_t *addrConfig)

Configure address filtering.

Parameters
[in]railHandle

A RAIL instance handle.

[in]addrConfig

The configuration structure, which defines how addresses are set up in your packets.

Returns

  • Status code indicating success of the function call.

You must call this function to set up address filtering. You may call it multiple times but all previous information is wiped out each time you call and any configured addresses must be reset.


Definition at line 4525 of file common/rail.h

RAIL_EnableAddressFilter#

bool RAIL_EnableAddressFilter (RAIL_Handle_t railHandle, bool enable)

Enable address filtering.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

An argument to indicate whether or not to enable address filtering.

Returns

  • True if address filtering was enabled to start with and false otherwise.

Only allow packets through that pass the current address filtering configuration. This does not reset or change the configuration so you can set that up before turning on this feature.


Definition at line 4541 of file common/rail.h

RAIL_IsAddressFilterEnabled#

bool RAIL_IsAddressFilterEnabled (RAIL_Handle_t railHandle)

Return whether address filtering is currently enabled.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • True if address filtering is enabled and false otherwise.


Definition at line 4549 of file common/rail.h

RAIL_ResetAddressFilter#

void RAIL_ResetAddressFilter (RAIL_Handle_t railHandle)

Reset the address filtering configuration.

Parameters
[in]railHandle

A RAIL instance handle.

Resets all structures related to address filtering. This does not disable address filtering. It leaves the radio in a state where no packets pass filtering.


Definition at line 4560 of file common/rail.h

RAIL_SetAddressFilterAddress#

RAIL_Status_t RAIL_SetAddressFilterAddress (RAIL_Handle_t railHandle, uint8_t field, uint8_t index, const uint8_t *value, bool enable)

Set an address for filtering in hardware.

Parameters
[in]railHandle

A RAIL instance handle.

[in]field

Indicates an address field for this address.

[in]index

Indicates a match entry for this address for a given field.

[in]value

A pointer to the address data. This must be at least as long as the size specified in RAIL_ConfigAddressFilter(). The first byte, value[0], will be compared to the first byte received over the air for this address field.

[in]enable

A boolean to indicate whether this address should be enabled immediately.

Returns

  • Status code indicating success of the function call.

This function loads the given address into hardware for filtering and starts filtering if you set the enable parameter to true. Otherwise, call RAIL_EnableAddressFilterAddress() to turn it on later.


Definition at line 4581 of file common/rail.h

RAIL_SetAddressFilterAddressMask#

RAIL_Status_t RAIL_SetAddressFilterAddressMask (RAIL_Handle_t railHandle, uint8_t field, const uint8_t *bitMask)

Set an address bit mask for filtering in hardware.

Parameters
[in]railHandle

A RAIL instance handle.

[in]field

Indicates an address field for this address bit mask.

[in]bitMask

A pointer to the address bitmask. This must be at least as long as the size specified in RAIL_ConfigAddressFilter(). The first byte, bitMask[0], will be applied to the first byte received over the air for this address field. Bits set to 1 in the bit mask indicate which bit positions in the incoming packet to compare against the stored addresses during address filtering. Bits set to 0 indicate which bit positions to ignore in the incoming packet during address filtering. This bit mask is applied to all address entries.

Returns

  • Status code indicating success of the function call.

This function loads the given address bit mask into hardware for use when address filtering is enabled. All bits in the stored address bit mask are set to 1 during hardware initialization and when either RAIL_ConfigAddressFilter() or RAIL_ResetAddressFilter() are called.

Note


Definition at line 4613 of file common/rail.h

RAIL_EnableAddressFilterAddress#

RAIL_Status_t RAIL_EnableAddressFilterAddress (RAIL_Handle_t railHandle, bool enable, uint8_t field, uint8_t index)

Enable address filtering for the specified address.

Parameters
[in]railHandle

A RAIL instance handle.

[in]enable

An argument to indicate whether or not to enable address filtering.

[in]field

Indicates an address for the address.

[in]index

Indicates a match entry in the given field you want to enable.

Returns

  • Status code indicating success of the function call.


Definition at line 4627 of file common/rail.h

RAIL_ConfigAutoAck#

RAIL_Status_t RAIL_ConfigAutoAck (RAIL_Handle_t railHandle, const RAIL_AutoAckConfig_t *config)

Configure and enable automatic acknowledgment.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

Auto-ACK configuration structure.

Returns

  • Status code indicating success of the function call.

Configures the RAIL state machine to for hardware-accelerated automatic acknowledgment. ACK timing parameters are defined in the configuration structure.

While auto-ACKing is enabled, do not call the following RAIL functions:

Note that if you are enabling auto-ACK (i.e., "enable" field is true) the "error" fields of rxTransitions and txTransitions are ignored. After all ACK sequences, (success or fail) the state machine will return the radio to the "success" state, which can be either RAIL_RF_STATE_RX or RAIL_RF_STATE_IDLE (returning to RAIL_RF_STATE_TX is not supported). If you need information about the actual success of the ACK sequence, use RAIL events such as RAIL_EVENT_TXACK_PACKET_SENT to make sure an ACK was sent, or RAIL_EVENT_RX_ACK_TIMEOUT to make sure that an ACK was received within the specified timeout.

To set a certain turnaround time (i.e., txToRx and rxToTx in RAIL_StateTiming_t), make txToRx lower than desired to ensure you get to RX in time to receive the ACK. Silicon Labs recommends setting 10 us lower than desired:

void setAutoAckStateTimings()
{
  RAIL_StateTiming_t timings;

  // User is already in auto-ACK and wants a turnaround of 192 us.
  timings.rxToTx = 192;
  timings.txToRx = 192 - 10;

  // Set other fields of timings...
  timings.idleToRx = 100;
  timings.idleToTx = 100;
  timings.rxSearchTimeout = 0;
  timings.txToRxSearchTimeout = 0;

  RAIL_SetStateTiming(railHandle, &timings);
}

As opposed to an explicit "Disable" API, set the "enable" field of the RAIL_AutoAckConfig_t to false. Then, auto-ACK will be disabled and state transitions will be returned to the values set in RAIL_AutoAckConfig_t. When disabling, the "ackTimeout" field isn't used.

Note

  • Auto-ACKing may not be enabled while RX Channel Hopping is enabled, or when BLE is enabled.


Definition at line 4781 of file common/rail.h

RAIL_IsAutoAckEnabled#

bool RAIL_IsAutoAckEnabled (RAIL_Handle_t railHandle)

Return the enable status of the auto-ACK feature.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if auto-ACK is enabled, false if disabled.


Definition at line 4790 of file common/rail.h

RAIL_WriteAutoAckFifo#

RAIL_Status_t RAIL_WriteAutoAckFifo (RAIL_Handle_t railHandle, const uint8_t *ackData, uint8_t ackDataLen)

Load the auto-ACK buffer with ACK data.

Parameters
[in]railHandle

A RAIL instance handle.

[in]ackData

A pointer to ACK data to transmit. This may be NULL, in which case it's assumed the data has already been emplaced into the ACK buffer and RAIL just needs to be told how many bytes are there. Use RAIL_GetAutoAckFifo() to get the address of RAIL's AutoACK buffer in RAM and its size.

[in]ackDataLen

The number of bytes in ACK data.

Returns

  • Status code indicating success of the function call.

If the ACK buffer is available for updates, load the ACK buffer with data. If it is not available, RAIL_STATUS_INVALID_STATE is returned. If ackDataLen exceeds RAIL_AUTOACK_MAX_LENGTH then RAIL_STATUS_INVALID_PARAMETER will be returned and nothing is written to the ACK buffer (unless ackData is NULL in which case this indicates the application has already likely corrupted RAM).


Definition at line 4811 of file common/rail.h

RAIL_GetAutoAckFifo#

RAIL_Status_t RAIL_GetAutoAckFifo (RAIL_Handle_t railHandle, uint8_t **ackBuffer, uint16_t *ackBufferBytes)

Get the address and size of the auto-ACK buffer for direct access.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]ackBuffer

A pointer to a uint8_t pointer that will be updated to the RAM base address of the TXACK buffer.

[inout]ackBufferBytes

A pointer to a uint16_t that will be updated to the size of the TXACK buffer, in bytes, which is currently RAIL_AUTOACK_MAX_LENGTH.

Returns

  • Status code indicating success of the function call.

Applications can use this to more flexibly write AutoAck data into the buffer directly and in pieces, passing NULL ackData parameter to RAIL_WriteAutoAckFifo() or RAIL_IEEE802154_WriteEnhAck() to inform RAIL of its final length.


Definition at line 4831 of file common/rail.h

RAIL_PauseRxAutoAck#

void RAIL_PauseRxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume RX auto-ACK functionality.

Parameters
[in]railHandle

A RAIL instance handle.

[in]pause

Pause or resume RX auto-ACKing.

When RX auto-ACKing is paused, the radio transitions to default state after receiving a packet and does not transmit an ACK. When RX auto-ACK is resumed, the radio resumes automatically ACKing every successfully received packet.


Definition at line 4846 of file common/rail.h

RAIL_IsRxAutoAckPaused#

bool RAIL_IsRxAutoAckPaused (RAIL_Handle_t railHandle)

Return whether the RX auto-ACK is paused.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if RX auto-ACK is paused, false if not paused.


Definition at line 4855 of file common/rail.h

RAIL_PauseTxAutoAck#

void RAIL_PauseTxAutoAck (RAIL_Handle_t railHandle, bool pause)

Pause/resume TX auto-ACK functionality.

Parameters
[in]railHandle

A RAIL instance handle.

[in]pause

Pause or resume TX auto-ACKing.

When TX auto-ACKing is paused, the radio transitions to a default state after transmitting a packet and does not wait for an ACK. When TX auto-ACK is resumed, the radio resumes automatically waiting for an ACK after a successful transmit.


Definition at line 4868 of file common/rail.h

RAIL_IsTxAutoAckPaused#

bool RAIL_IsTxAutoAckPaused (RAIL_Handle_t railHandle)

Return whether the TX auto-ACK is paused.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if TX auto-ACK is paused, false if not paused.


Definition at line 4876 of file common/rail.h

RAIL_UseTxFifoForAutoAck#

RAIL_Status_t RAIL_UseTxFifoForAutoAck (RAIL_Handle_t railHandle)

Modify the upcoming ACK to use the Transmit FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call. The call will fail if it is too late to modify the outgoing ACK.

This function allows the application to use the normal Transmit FIFO as the data source for the upcoming ACK. The ACK modification to use the Transmit FIFO only applies to one ACK transmission.

This function only returns true if the following conditions are met:

  • Radio has not already decided to use the ACK buffer AND

  • Radio is either looking for sync, receiving the packet after sync, or in the Rx2Tx turnaround before the ACK is sent.

Note

  • The Transmit FIFO must not be used for AutoACK when IEEE 802.15.4, Z-Wave, or BLE protocols are active.


Definition at line 4897 of file common/rail.h

RAIL_CancelAutoAck#

RAIL_Status_t RAIL_CancelAutoAck (RAIL_Handle_t railHandle)

Cancel the upcoming ACK.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • Status code indicating success of the function call. This call will fail if it is too late to modify the outgoing ACK.

This function allows the application to cancel the upcoming automatic acknowledgment.

This function only returns true if the following conditions are met:

  • Radio has not already decided to transmit the ACK AND

  • Radio is either looking for sync, receiving the packet after sync or in the Rx2Tx turnaround before the ACK is sent.


Definition at line 4914 of file common/rail.h

RAIL_IsAutoAckWaitingForAck#

bool RAIL_IsAutoAckWaitingForAck (RAIL_Handle_t railHandle)

Return whether the radio is currently waiting for an ACK.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • True if radio is waiting for ACK, false if radio is not waiting for an ACK.

This function allows the application to query whether the radio is currently waiting for an ACK after a transmit operation.


Definition at line 4926 of file common/rail.h

RAIL_ConfigCal#

RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)

Initialize RAIL calibration.

Parameters
[in]railHandle

A RAIL instance handle.

[in]calEnable

A bitmask that indicates which calibrations to enable for a callback notification. The exact meaning of these bits is chip-specific.

Returns

  • Status code indicating success of the function call.

Calibration initialization provides the calibration settings that correspond to the current radio configuration.


Definition at line 4995 of file common/rail.h

RAIL_Calibrate#

RAIL_Status_t RAIL_Calibrate (RAIL_Handle_t railHandle, RAIL_CalValues_t *calValues, RAIL_CalMask_t calForce)

Start the calibration process.

Parameters
[in]railHandle

A RAIL instance handle.

[inout]calValues

A structure of calibration values to apply. If a valid calibration structure is provided and the structure contains valid calibration values, those values will be applied to the hardware and the RAIL library will cache those values for use again later. If a valid calibration structure is provided and the structure contains a calibration value of RAIL_CAL_INVALID_VALUE for the desired calibration, the desired calibration will run, the calibration values structure will be updated with a valid calibration value, and the RAIL library will cache that value for use again later. If a NULL pointer is provided, the desired calibration will run and the RAIL library will cache that value for use again later. However, the valid calibration value will not be returned to the application.

[in]calForce

A mask to force specific calibration(s) to execute. To run all pending calibrations, use the value RAIL_CAL_ALL_PENDING. Only the calibrations specified will run, even if not enabled during initialization.

Returns

  • Status code indicating success of the function call.

If calibrations were performed previously and the application saves the calibration values (i.e., call this function with a calibration values structure containing calibration values of RAIL_CAL_INVALID_VALUE before a reset), the application can later bypass the time it would normally take to recalibrate hardware by reusing previous calibration values (i.e., call this function with a calibration values structure containing valid calibration values after a reset).

If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, to perform an IR calibration for the first time, it will return RAIL_STATUS_INVALID_STATE, in which case the application must defer calibration until after the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.

Note

  • Instead of this function, consider using the individual chip-specific functions. Using the individual functions will allow for better dead-stripping if not all calibrations are run.

  • Some calibrations should only be executed when the radio is IDLE. See chip-specific documentation for more details.


Definition at line 5041 of file common/rail.h

RAIL_GetPendingCal#

RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)

Return the current set of pending calibrations.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • A mask of all pending calibrations that the user has been asked to perform.

This function returns a full set of pending calibrations. The only way to clear pending calibrations is to perform them using the RAIL_Calibrate() API with the appropriate list of calibrations.


Definition at line 5056 of file common/rail.h

RAIL_ApplyIrCalibration#

RAIL_Status_t RAIL_ApplyIrCalibration (RAIL_Handle_t railHandle, uint32_t imageRejection)

Apply a given image rejection calibration value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]imageRejection

The image rejection value to apply.

Returns

  • A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIr on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.

DeprecatedPlease use RAIL_ApplyIrCalibrationAlt instead.


Definition at line 5076 of file common/rail.h

RAIL_ApplyIrCalibrationAlt#

RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Apply a given image rejection calibration value.

Parameters
[in]railHandle

A RAIL instance handle.

[in]imageRejection

Pointer to the image rejection value to apply.

[in]rfPath

RF path to calibrate.

Returns

  • A status code indicating success of the function call.

Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIrAlt on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. Note

  • : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.


Definition at line 5098 of file common/rail.h

RAIL_CalibrateIr#

RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t *imageRejection)

Run the image rejection calibration.

Parameters
[in]railHandle

A RAIL instance handle.

[out]imageRejection

The result of the image rejection calibration.

Returns

  • A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image.

If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, it will return RAIL_STATUS_INVALID_STATE. In this case, RAIL_ApplyIrCalibration may be called to apply a previously determined IR calibration value, or the app must defer calibration until the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.

DeprecatedPlease use RAIL_CalibrateIrAlt instead.


Definition at line 5127 of file common/rail.h

RAIL_CalibrateIrAlt#

RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t *imageRejection, RAIL_AntennaSel_t rfPath)

Run the image rejection calibration.

Parameters
[in]railHandle

A RAIL instance handle.

[out]imageRejection

Pointer to the image rejection result.

[in]rfPath

RF path to calibrate.

Returns

  • A status code indicating success of the function call.

Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image. Note

  • : To make sure the imageRejection value is stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.


Definition at line 5152 of file common/rail.h

RAIL_CalibrateTemp#

RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)

Run the temperature calibration.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • A status code indicating success of the function call.

Run the temperature calibration, which needs to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.

If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.


Definition at line 5176 of file common/rail.h

RAIL_CalibrateHFXO#

RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t *crystalPPMError)

Performs HFXO compensation.

Parameters
[in]railHandle

A RAIL instance handle.

[out]crystalPPMError

Current deviation that has been corrected, measured in PPM. May be NULL.

Returns

  • A status code indicating the result of the function call.

Compute the PPM correction using the thermistor value available when RAIL_EVENT_THERMISTOR_DONE occurs, after RAIL_StartThermistorMeasurement() call. Then correct the RF frequency as well as TX and RX sampling.

This function calls the following RAIL functions in sequence saving having to call them individually:

Note

  • This function makes the radio idle.


Definition at line 5199 of file common/rail.h

RAIL_EnablePaCal#

void RAIL_EnablePaCal (bool enable)

Enable/disable the PA calibration.

Parameters
[in]enable

Enables/disables the PA calibration.

Enabling will ensure that the PA power remains constant chip-to-chip. By default, this feature is disabled after reset.

Note


Definition at line 5212 of file common/rail.h

RAIL_StartRfSense#

RAIL_Time_t RAIL_StartRfSense (RAIL_Handle_t railHandle, RAIL_RfSenseBand_t band, RAIL_Time_t senseTime, RAIL_RfSense_CallbackPtr_t cb)

Start/stop the RF Sense functionality in Energy Detection Mode for use during low-energy sleep modes.

Parameters
[in]railHandle

A RAIL instance handle.

[in]band

The frequency band(s) on which to sense the RF energy. To stop RF Sense, specify RAIL_RFSENSE_OFF.

[in]senseTime

The time (in microseconds) the RF energy must be continually detected to be considered "sensed".

[in]cb

RAIL_RfSense_CallbackPtr_t is called when the RF is sensed. Set null if polling via RAIL_IsRfSensed().

Returns

  • The actual senseTime used, which may be different than requested due to limitations of the hardware. If 0, RF sense was disabled or could not be enabled (no callback will be issued).

The EFR32 has the ability to sense the presence of RF Energy above -20 dBm within either or both the 2.4 GHz and Sub-GHz bands and trigger an event if that energy is continuously present for certain durations of time.

Note

  • After RF energy has been sensed, the RF Sense is automatically disabled and RAIL_StartRfSense() must be called again to reactivate it. If RF energy has not been sensed and to manually disable RF Sense, RAIL_StartRfSense() must be called with band specified as RAIL_RFSENSE_OFF or with senseTime set to 0 microseconds.

  • Packet reception is not guaranteed to work correctly once RF Sense is enabled, both in single protocol and multiprotocol RAIL. To be safe, an application should turn this on only after idling the radio to stop receive and turn it off before attempting to restart receive. Since EM4 sleep causes the chip to come up through the reset vector any wake from EM4 must also shut off RF Sense to ensure proper receive functionality.

Warnings

  • For some chips, RF Sense functionality is only guaranteed within a specified temperature range. See chip-specific documentation for more details.


Definition at line 5261 of file common/rail.h

RAIL_StartSelectiveOokRfSense#

RAIL_Status_t RAIL_StartSelectiveOokRfSense (RAIL_Handle_t railHandle, RAIL_RfSenseSelectiveOokConfig_t *config)

Start/stop the RF Sense functionality in Selective(OOK Based) Mode for use during low-energy sleep modes.

Parameters
[in]railHandle

A RAIL instance handle.

[in]config

RAIL_RfSenseSelectiveOokConfig_t holds the RFSENSE configuration for Selective(OOK) mode.

Returns

  • Status code indicating success of the function call.

Some chips support Selective RF energy detection (OOK mode) where the user can program the chip to look for a particular sync word pattern (1byte - 4bytes) sent using OOK and wake only when that is detected. See chip-specific documentation for more details.

The following code gives an example of how to use RF Sense functionality in Selective(OOK Based) Mode.

// Syncword Length in bytes, 1-4 bytes.
#define NUMSYNCWORDBYTES (2U)
// Syncword Value.
#define SYNCWORD         (0xB16FU)

// Configure the transmitting node for sending the wakeup packet.
RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true);
RAIL_ConfigRfSenseSelectiveOokWakeupPhy(railHandle);
RAIL_SetRfSenseSelectiveOokWakeupPayload(railHandle, NUMSYNCWORDBYTES, SYNCWORD);
RAIL_StartTx(railHandle, channel, RAIL_TX_OPTIONS_DEFAULT, NULL);

// Configure the receiving node (EFR32XG22) for RF Sense.
RAIL_RfSenseSelectiveOokConfig_t config = {
 .band = rfBand,
 .syncWordNumBytes = NUMSYNCWORDBYTES,
 .syncWord = SYNCWORD,
 .cb = &RAILCb_SensedRf
};
RAIL_StartSelectiveOokRfSense(railHandle, &config);

Note

  • After RF energy has been sensed, the RF Sense is automatically disabled and RAIL_StartSelectiveOokRfSense() must be called again to reactivate. If RF energy has not been sensed and to manually disable RF Sense, RAIL_StartSelectiveOokRfSense() must be called with band specified as RAIL_RFSENSE_OFF or with RAIL_RfSenseSelectiveOokConfig_t as NULL.

  • Packet reception is not guaranteed to work correctly once RF Sense is enabled, both in single protocol and multiprotocol RAIL. To be safe, an application should turn this on only after idling the radio to stop receive and turn it off before attempting to restart receive. Since EM4 sleep causes the chip to come up through the reset vector any wake from EM4 must also shut off RF Sense to ensure proper receive functionality.


Definition at line 5320 of file common/rail.h

RAIL_ConfigRfSenseSelectiveOokWakeupPhy#

RAIL_Status_t RAIL_ConfigRfSenseSelectiveOokWakeupPhy (RAIL_Handle_t railHandle)

Switch to RF Sense Selective(OOK) PHY.

Parameters
[in]railHandle

A handle for RAIL instance.

Returns

  • A status code indicating success of the