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:
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.
Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.
Macros#
Minimum power for CLPC usage in deci-dBm.
Number of temperature values provided for the EFF thermal protection.
Number of deprecated temperature values in EFF thermal protection.
Number of temperature values provided for HFXO metrics.
Total number of temperature values provided by RAIL_GetTemperature().
Number of bytes provided by RAIL_GetSetEffClpcControl().
Functions#
Get the version information for the compiled RAIL library.
Add a 3rd multiprotocol internal state buffer for use by RAIL_Init().
Add a 4th multiprotocol internal state buffer for use by RAIL_Init().
Allocate a DMA channel for RAIL to work with.
Initialize RAIL.
Get RAIL initialization status.
Collect entropy from the radio if available.
Configure PTI pin locations, serial protocols, and baud rates.
Get the currently-active PTI configuration.
Enable Packet Trace Interface (PTI) output of packet data.
Set a protocol that RAIL outputs on PTI.
Get the protocol that RAIL outputs on PTI.
Configure antenna path and pin locations.
Get the default RF path.
Load a static radio configuration.
Modify the currently configured fixed frame length in bytes.
Configure the channels supported by this device.
Get verbose listing of channel metadata for the current channel configuration.
Check whether the channel exists in RAIL.
Cause radio settings associated with a particular channel to be applied to hardware.
Return the current RAIL channel.
Return the current RAIL channel.
Return the symbol rate for the current PHY.
Return the bit rate for the current PHY.
Set the PA capacitor tune value for transmit and receive.
Get the sync words and their length.
Set the selected sync words and their length.
Sets the whitening initialization value.
Returns the CRC initialization value.
Sets the whitening initialization value.
Sets the CRC initialization value.
Restores the whitening initialization value to its initial setting from the Radio Configurator.
Restores the CRC initialization value to its initial setting from the Radio Configurator.
Get the current RAIL time.
Set the current RAIL time.
Blocking delay routine for a specified number of microseconds.
Schedule a timer to expire using the RAIL timebase.
Return the absolute time that the RAIL timer was configured to expire.
Stop the currently scheduled RAIL timer.
Check whether the RAIL timer has expired.
Check whether the RAIL timer is currently running.
Configure the RAIL software timer feature.
Start a multitimer instance.
Stop the currently scheduled RAIL multitimer.
Check if a given timer is running.
Check if a given timer has expired.
Get time left before a given timer instance expires.
Configure RAIL timer synchronization.
Initialize RAIL timer synchronization.
Initialize RAIL timer synchronization.
Stop the RAIL timer and prepare RAIL for sleep.
Wake RAIL from sleep and restart the RAIL timer.
Initialize RAIL Power Manager.
Stop the RAIL Power Manager.
Configure radio events.
RAIL data management configuration.
Write data to the transmit FIFO previously established by RAIL_SetTxFifo().
Set the address of the transmit FIFO, a circular buffer used for TX data.
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.
Set the address of the receive FIFO, a circular buffer used for RX data.
Set up the receive FIFO to use.
Read packet data from RAIL's internal receive FIFO.
Configure the RAIL transmit FIFO almost empty threshold.
Configure the RAIL receive FIFO almost full threshold.
Get the RAIL transmit FIFO almost empty threshold value.
Get the RAIL receive FIFO almost full threshold value.
Reset the RAIL transmit and/or receive FIFOs.
Get the number of bytes used in the receive FIFO.
Get the number of bytes unused in the transmit FIFO.
Configure RAIL automatic state transitions after RX.
Get the current RAIL automatic state transitions after RX.
Configure RAIL automatic state transitions after TX.
Get the current RAIL automatic state transitions after TX.
Set up automatic repeated transmits after the next transmit.
Get the number of transmits remaining in a repeat operation.
Configure RAIL automatic state transition timing.
Place the radio into an idle state.
Get the current radio state.
Get the detailed current radio state.
Enable/disable caching of synth calibration value.
Initialize TX power settings.
Get the TX power settings currently used in the amplifier.
Set the TX power in units of raw units (see rail_chip_specific.h for value ranges).
Return the current power setting of the PA.
Convert raw values written to registers to decibel value (in units of deci-dBm).
Convert the desired decibel value (in units of deci-dBm) to raw integer values used by the TX amplifier registers.
Verify the TX Power Curves on modules.
Set the TX power in terms of deci-dBm instead of raw power level.
Get the TX power in terms of deci-dBm instead of raw power level.
Get the TX PA power setting table and related values.
Set the TX PA power setting used to configure the PA hardware for the PA output power determined by RAIL_SetTxPowerDbm().
Get the TX PA power setting, which is used to configure power configurations when the dBm to paPowerSetting mapping table mode is used.
Enable automatic switching between PAs internally to the RAIL library.
Query status of PA Auto Mode.
Callback that decides which PA and power level should be used while in PA auto mode.
Start a transmit.
Schedule sending a packet.
Start a transmit using CSMA.
Start a transmit using LBT.
Schedule a transmit using CSMA.
Schedule a transmit using LBT.
Stop an active or pending transmit.
Set the CCA threshold in dBm.
Get detailed information about the last packet transmitted.
Get detailed information about the last packet transmitted.
Get detailed information about the last packet transmitted.
Adjust a RAIL TX completion timestamp to refer to the start of the preamble.
Adjust a RAIL TX completion timestamp to refer to the start of the preamble.
Adjust a RAIL TX timestamp to refer to the end of the sync word.
Adjust a RAIL TX timestamp to refer to the end of the sync word.
Adjust a RAIL TX timestamp to refer to the end of frame.
Adjust a RAIL TX timestamp to refer to the end of frame.
Prevent the radio from starting a transmit.
Check whether or not TX hold off is enabled.
Set an alternate transmitter preamble length.
Configure receive options.
Include the code necessary for frame type based length decoding.
Handle frame type length.
Start the receiver on a specific channel.
Schedule a receive window for some future time.
Get basic information about a pending or received packet.
Get information about the live incoming packet (if any).
Copy a full packet to a user-specified contiguous buffer.
Get detailed information about a received packet.
Get detailed information about a received packet.
Adjust a RAIL RX timestamp to refer to the start of the preamble.
Adjust a RAIL RX timestamp to refer to the start of the preamble.
Adjust a RAIL RX timestamp to refer to the end of the sync word.
Adjust a RAIL RX timestamp to refer to the end of the sync word.
Adjust a RAIL RX timestamp to refer to the end of frame.
Adjust a RAIL RX timestamp to refer to the end of frame.
Place a temporary hold on this packet's data and information resources within RAIL.
Copy 'len' bytes of packet data starting from 'offset' from the receive FIFO.
Release RAIL's internal resources for the packet.
Return the current raw RSSI.
Return the current raw RSSI within a definitive time period.
Start the RSSI averaging over a specified time in us.
Query whether the RSSI averaging is done.
Get the RSSI averaged over a specified time in us.
Set the RSSI offset.
Get the RSSI offset.
Set the RSSI detection threshold(in dBm) to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.
Get the RSSI detection threshold(in dBm).
Set up a callback function capable of converting a RX packet's LQI value before being consumed by application code.
Configure address filtering.
Enable address filtering.
Return whether address filtering is currently enabled.
Reset the address filtering configuration.
Set an address for filtering in hardware.
Set an address bit mask for filtering in hardware.
Enable address filtering for the specified address.
Configure and enable automatic acknowledgment.
Return the enable status of the auto-ACK feature.
Load the auto-ACK buffer with ACK data.
Get the address and size of the auto-ACK buffer for direct access.
Pause/resume RX auto-ACK functionality.
Return whether the RX auto-ACK is paused.
Pause/resume TX auto-ACK functionality.
Return whether the TX auto-ACK is paused.
Modify the upcoming ACK to use the Transmit FIFO.
Cancel the upcoming ACK.
Return whether the radio is currently waiting for an ACK.
Initialize RAIL calibration.
Start the calibration process.
Return the current set of pending calibrations.
Apply a given image rejection calibration value.
Apply a given image rejection calibration value.
Run the image rejection calibration.
Run the image rejection calibration.
Run the temperature calibration.
Performs HFXO compensation.
Enable/disable the PA calibration.
Start/stop the RF Sense functionality in Energy Detection Mode for use during low-energy sleep modes.
Start/stop the RF Sense functionality in Selective(OOK Based) Mode for use during low-energy sleep modes.
Switch to RF Sense Selective(OOK) PHY.
Set the transmit payload for waking up a node configured for RF Sense Selective(OOK).
Check whether the RF was sensed.
Configure RX channel hopping.
Enable RX channel hopping.
Get RSSI of one channel in the channel hopping sequence, during channel hopping.
Configure RX duty cycle mode.
Enable RX duty cycle mode.
Get the default RX duty cycle configuration.
Yield the radio to other configurations.
Get the status of the RAIL scheduler.
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.
Change the priority of a specified task type in multiprotocol.
Get time needed to switch between protocols.
Set time needed to switch between protocols.
Configure direct mode for RAIL.
Enable or disable direct mode for RAIL.
Enable or disable direct mode for RAIL.
Get the radio subsystem clock frequency in Hz.
Set the crystal tuning.
Get the crystal tuning.
Set the crystal tuning delta.
Get the crystal tuning delta on EFR32xG2 series devices.
Get the frequency offset.
Set the nominal radio frequency offset.
Start transmitting a stream on a certain channel.
Start transmitting a stream on a certain channel with the ability to select an antenna.
Stop stream transmission.
Stop infinite preamble transmission started and start transmitting the rest of the packet.
Configure the verification of radio memory contents.
Verify radio memory contents.
Configure the attached EFF device.
Get the different temperature measurements in Kelvin done by sequencer or host.
Get the different EFF Control measurements.
Copy the current FEM_DATA pin values into newMode.
Copy the current Rural to Urban trip voltage into newTrip.
Copy the current Urban to Bypass trip voltage into newTrip.
Copy the current Urban dwell time into newDwellTime.
Copy the current Bypass dwell time into newDwellTime.
If changeValues is true, update current CLPC Fast Loop calibration values using the new variables.
If changeValues is true, update current CLPC Fast Loop calibration equations using the new variables.
If changeValues is true, update current CLPC Fast Loop Target and Slope.
Copy the current CLPC Enable in to newClpcEnable.
Get and set the EFF temperature threshold.
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.
Get the current thermal configuration parameter and status.
Callback called upon failed assertion.
Start a thermistor measurement.
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.
Convert the thermistor impedance into temperature, in Celsius.
Compute the crystal PPM deviation from the thermistor temperature.
Configure the GPIO for thermistor usage.
Configure the temperature parameters for HFXO compensation.
Get the temperature parameters for HFXO compensation.
Compute a frequency offset and compensate HFXO accordingly.
Indicate whether RAIL supports 2.4 GHz band operation on this chip.
Indicate whether RAIL supports SubGHz band operation on this chip.
Indicate whether this chip supports dual 2.4 GHz and SubGHz band operation.
Indicate whether this chip supports bit masked address filtering.
Indicate whether this chip supports address filter mask information for incoming packets in RAIL_RxPacketInfo_t::filterMask and RAIL_IEEE802154_Address_t::filterMask.
Indicate whether this chip supports alternate TX power settings.
Indicate whether this chip supports antenna diversity.
Indicate whether RAIL supports AUXADC measurements on this chip.
Indicate whether RAIL supports channel hopping on this chip.
Indicate whether this chip supports direct mode.
Indicate whether this chip supports dual sync words.
Indicate whether this chip supports start to start TX repeats.
Indicate whether this chip supports EFF.
Indicate whether RAIL supports thermistor measurements on this chip.
Indicate whether RAIL supports HFXO compensation on this chip.
Indicate whether this chip supports MFM protocol.
Indicate whether RAIL supports OFDM band operation on this chip.
Indicate whether this chip supports a high-precision LFRCO.
Indicate whether this chip supports radio entropy.
Indicate whether RAIL supports RFSENSE Energy Detection Mode on this chip.
Indicate whether RAIL supports RFSENSE Selective(OOK) Mode on this chip.
Indicate whether this chip supports configurable RSSI threshold set by RAIL_SetRssiDetectThreshold().
Indicate whether this chip supports RX direct mode data to FIFO.
Indicate whether this chip supports raw RX data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.
Indicate whether this chip supports SQ-based PHY.
Indicate whether this chip supports a particular power mode (PA).
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.
Indicate whether this chip supports automatic TX to TX transitions.
Indicate whether RAIL supports the BLE protocol on this chip.
Indicate whether this chip supports BLE 1Mbps Non-Viterbi PHY.
Indicate whether this chip supports BLE 1Mbps Viterbi PHY.
Indicate whether this chip supports BLE 1Mbps operation.
Indicate whether this chip supports BLE 2Mbps Non-Viterbi PHY.
Indicate whether this chip supports BLE 2Mbps Viterbi PHY.
Indicate whether this chip supports BLE 2Mbps operation.
Indicate whether this chip supports BLE Antenna Switching needed for Angle-of-Arrival receives or Angle-of-Departure transmits.
Indicate whether this chip supports BLE Coded PHY used for Long-Range.
Indicate whether this chip supports BLE CTE (Constant Tone Extension) needed for Angle-of-Arrival/Departure transmits.
Indicate whether this chip supports BLE IQ Sampling needed for Angle-of-Arrival/Departure receives.
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.
Indicate whether this chip supports the Quuppa PHY.
Indicate whether this chip supports BLE signal identifier.
Indicate whether this chip supports BLE Simulscan PHY used for simultaneous BLE 1Mbps and Coded PHY reception.
Indicate whether this chip supports the IEEE 802.15.4 protocol.
Indicate whether this chip supports the IEEE 802.15.4 Wi-Fi Coexistence PHY.
Indicate whether this chip supports the IEEE 802.15.4 2.4 GHz band variant.
Indicate whether this chip supports the thermal protection.
Indicate whether this chip supports the IEEE 802.15.4 2.4 RX channel switching.
Indicate whether this chip supports the IEEE 802.15.4 PHY with custom settings.
Indicate whether this chip supports the IEEE 802.15.4 front end module optimized PHY.
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).
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.
Indicate whether RAIL supports dual PA mode on this chip.
Indicate whether this chip supports IEEE 802.15.4E-2012 Enhanced ACKing.
Indicate whether this chip supports IEEE 802.15.4E-2012 Multipurpose frame reception.
Indicate whether this chip supports the IEEE 802.15.4E-2012 feature subset needed for Zigbee R22 GB868.
Indicate whether this chip supports IEEE 802.15.4G-2012 reception and transmission of frames with 4-byte CRC.
Indicate whether this chip supports IEEE 802.15.4G dynamic FEC.
Indicate whether this chip supports Wi-SUN.
Indicate whether this chip supports Wi-SUN mode switching.
Indicate whether this chip supports IEEE 802.15.4G-2012 feature subset needed for Zigbee R22 GB868.
Indicate whether this chip supports IEEE 802.15.4G-2012 reception of unwhitened frames.
Indicate whether this chip supports IEEE 802.15.4G-2012 transmission of unwhitened frames.
Indicate whether this chip supports WMBUS simultaneous M2O RX of T and C modes.
Indicate whether this chip supports the Z-Wave protocol.
Indicate whether this chip supports the Z-Wave concurrent PHY.
Indicate whether this chip supports the Z-Wave energy detect PHY.
Indicate whether this chip supports Z-Wave Region in PTI.
Indicate whether this chip supports IEEE 802.15.4 signal identifier.
Indicate whether this chip supports fast RX2RX.
Indicate whether this chip supports collision detection.
Indicate whether this chip supports Sidewalk protocol.
Macro Definition Documentation#
RAIL_CLPC_MINIMUM_POWER#
#define RAIL_CLPC_MINIMUM_POWERValue:
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.
6169
of file common/rail.h
RAIL_EFF_TEMP_MEASURE_COUNT#
#define RAIL_EFF_TEMP_MEASURE_COUNTValue:
(6U)
Number of temperature values provided for the EFF thermal protection.
6184
of file common/rail.h
RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNT#
#define RAIL_EFF_TEMP_MEASURE_DEPRECATED_COUNTValue:
(2U)
Number of deprecated temperature values in EFF thermal protection.
6186
of file common/rail.h
RAIL_HFXO_TEMP_MEASURE_COUNT#
#define RAIL_HFXO_TEMP_MEASURE_COUNTValue:
(1U)
Number of temperature values provided for HFXO metrics.
6188
of file common/rail.h
RAIL_TEMP_MEASURE_COUNT#
#define RAIL_TEMP_MEASURE_COUNTValue:
Total number of temperature values provided by RAIL_GetTemperature().
6191
of file common/rail.h
RAIL_EFF_CONTROL_SIZE#
#define RAIL_EFF_CONTROL_SIZEValue:
(52U)
Number of bytes provided by RAIL_GetSetEffClpcControl().
6229
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.
[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.
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().
[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.
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().
[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.
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.
[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.
177
of file common/rail.h
RAIL_Init#
RAIL_Handle_t RAIL_Init (RAIL_Config_t * railCfg, RAIL_InitCompleteCallbackPtr_t cb)
Initialize RAIL.
[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.
318
of file common/rail.h
RAIL_IsInitialized#
bool RAIL_IsInitialized (void )
Get RAIL initialization status.
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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[in] | railHandle | A RAIL instance handle. |
Returns
PTI protocol in use.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[in] | railHandle | A RAIL instance handle. |
[in] | channel | The channel to prepare for use. |
Returns
RAIL_STATUS_NO_ERROR on success or RAIL_STATUS_INVALID_PARAMETER if the given channel does not have an associated channel configuration entry.
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.
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.
[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.
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.
[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.
697
of file common/rail.h
RAIL_GetSymbolRate#
uint32_t RAIL_GetSymbolRate (RAIL_Handle_t railHandle)
Return the symbol rate for the current PHY.
[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.
711
of file common/rail.h
RAIL_GetBitRate#
uint32_t RAIL_GetBitRate (RAIL_Handle_t railHandle)
Return the bit rate for the current PHY.
[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.
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.
[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.
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.
[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.
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.
[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.
806
of file common/rail.h
RAIL_GetWhiteningInitVal#
uint16_t RAIL_GetWhiteningInitVal (RAIL_Handle_t railHandle)
Sets the whitening initialization value.
[in] | railHandle | A RAIL instance handle. |
Returns
The whitening initialization value currently being used.
815
of file common/rail.h
RAIL_GetCrcInitVal#
uint32_t RAIL_GetCrcInitVal (RAIL_Handle_t railHandle)
Returns the CRC initialization value.
[in] | railHandle | A RAIL instance handle. |
Returns
The CRC initialization value currently being used.
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.
[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.
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.
[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.
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.
[in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Can use this function after using RAIL_SetWhiteningInitVal().
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.
[in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Can use this function after using RAIL_SetCrcInitVal().
890
of file common/rail.h
RAIL_GetTime#
RAIL_Time_t RAIL_GetTime (void )
Get the current RAIL time.
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.
987
of file common/rail.h
RAIL_SetTime#
RAIL_Status_t RAIL_SetTime (RAIL_Time_t time)
Set the current RAIL time.
[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.
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.
[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.
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.
[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.
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.
[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.
1064
of file common/rail.h
RAIL_CancelTimer#
void RAIL_CancelTimer (RAIL_Handle_t railHandle)
Stop the currently scheduled RAIL timer.
[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. |
1074
of file common/rail.h
RAIL_IsTimerExpired#
bool RAIL_IsTimerExpired (RAIL_Handle_t railHandle)
Check whether the RAIL timer has expired.
[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.
1085
of file common/rail.h
RAIL_IsTimerRunning#
bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)
Check whether the RAIL timer is currently running.
[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.
1094
of file common/rail.h
RAIL_ConfigMultiTimer#
bool RAIL_ConfigMultiTimer (bool enable)
Configure the RAIL software timer feature.
[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.
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.
[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
RAIL_STATUS_NO_ERROR on success.
RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.
1141
of file common/rail.h
RAIL_CancelMultiTimer#
bool RAIL_CancelMultiTimer (RAIL_MultiTimer_t * tmr)
Stop the currently scheduled RAIL multitimer.
[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.
1160
of file common/rail.h
RAIL_IsMultiTimerRunning#
bool RAIL_IsMultiTimerRunning (RAIL_MultiTimer_t * tmr)
Check if a given timer is running.
[in] | tmr | A pointer to the timer structure to query. |
Returns
true if the timer is running. false if the timer is not running.
1171
of file common/rail.h
RAIL_IsMultiTimerExpired#
bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t * tmr)
Check if a given timer has expired.
[in] | tmr | A pointer to the timer structure to query. |
Returns
true if the timer is expired. false if the timer is running.
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.
[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.
1199
of file common/rail.h
RAILCb_ConfigSleepTimerSync#
void RAILCb_ConfigSleepTimerSync (RAIL_TimerSyncConfig_t * timerSyncConfig)
Configure RAIL timer synchronization.
[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;
}
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.
[in] | railHandle | A RAIL instance handle. |
[in] | sleepConfig | A sleep configuration. |
Returns
Status code indicating success of the function call.
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.
[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.
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.
[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.
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.
[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.
1540
of file common/rail.h
RAIL_InitPowerManager#
RAIL_Status_t RAIL_InitPowerManager (void )
Initialize RAIL Power Manager.
N/A |
Returns
Status code indicating success of the function call.
Note
This function must be called only when the application is built and initialized with Power Manager plugin and when the radio is idle. 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.
Warnings
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.
1557
of file common/rail.h
RAIL_DeinitPowerManager#
RAIL_Status_t RAIL_DeinitPowerManager (void )
Stop the RAIL Power Manager.
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.
1568
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.
[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.
1594
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.
[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().
1899
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().
[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.
1934
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.
[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.
1988
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.
[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.
2021
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.
[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.
2064
of file common/rail.h
RAILCb_SetupRxFifo#
RAIL_Status_t RAILCb_SetupRxFifo (RAIL_Handle_t railHandle)
Set up the receive FIFO to use.
[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;
}
2103
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.
[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
This function is intended for use only with RAIL_DataMethod_t::FIFO_MODE and should never be called in RAIL_DataMethod_t::PACKET_MODE where it could lead to receive FIFO corruption.
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.
2140
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.
[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.
2161
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.
[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
To avoid sticking in the event handler (even in idle state):
Disable the event (via the config events API or the RAIL_FIFO_THRESHOLD_DISABLED parameter)
Increase FIFO threshold
Read the FIFO (that's not an option in RAIL_DataMethod_t::PACKET_MODE) in the event handler
2189
of file common/rail.h
RAIL_GetTxFifoThreshold#
uint16_t RAIL_GetTxFifoThreshold (RAIL_Handle_t railHandle)
Get the RAIL transmit FIFO almost empty threshold value.
[in] | railHandle | A RAIL instance handle. |
Returns
Configured TX Threshold value.
Retrieves the configured TX threshold value.
2200
of file common/rail.h
RAIL_GetRxFifoThreshold#
uint16_t RAIL_GetRxFifoThreshold (RAIL_Handle_t railHandle)
Get the RAIL receive FIFO almost full threshold value.
[in] | railHandle | A RAIL instance handle. |
Returns
Configured RX Threshold value.
Retrieves the configured RX threshold value.
2210
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.
[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.
2223
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.
[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.
2243
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.
[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.
2254
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.
[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.
2279
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.
[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.
2292
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.
[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.
2307
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.
[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.
2320
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.
[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
This feature/API is not supported on the EFR32XG1 family of chips. Use the compile time symbol RAIL_SUPPORTS_TX_TO_TX or the runtime call RAIL_SupportsTxToTx() to check whether the platform supports this feature.
2381
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.
[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.
2410
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.
[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.
2426
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.
[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.
2443
of file common/rail.h
RAIL_GetRadioState#
RAIL_RadioState_t RAIL_GetRadioState (RAIL_Handle_t railHandle)
Get the current radio state.
[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
For a more detailed radio state, see RAIL_GetRadioStateDetail
2467
of file common/rail.h
RAIL_GetRadioStateDetail#
RAIL_RadioStateDetail_t RAIL_GetRadioStateDetail (RAIL_Handle_t railHandle)
Get the detailed current radio state.
[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
2533
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.
[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
This function will improve the minimum timings that can be achieved in RAIL_StateTiming_t::idleToRx, RAIL_StateTiming_t::idleToTx, RAIL_StateTiming_t::rxToTx, RAIL_StateTiming_t::txToRx and RAIL_StateTiming_t::txToTx. A call to RAIL_SetStateTiming() is needed to achieve lower transition times.
On a protocol switch the cache is cleared, so it is not suitable for applications where a protocol switch happens frequently, like with Dynamic Multiprotocol.
2562
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.
[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.
2725
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.
[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.
2743
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).
[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.
2769
of file common/rail.h
RAIL_GetTxPower#
RAIL_TxPowerLevel_t RAIL_GetTxPower (RAIL_Handle_t railHandle)
Return the current power setting of the PA.
[in] | railHandle | A RAIL instance handle. |
Returns
The chip-specific RAIL_TxPowerLevel_t value of the current transmit power.
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).
2790
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).
[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.
2816
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.
[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.
2852
of file common/rail.h
RAIL_VerifyTxPowerCurves#
void RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt * config)
Verify the TX Power Curves on modules.
[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.
2863
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.
[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.
2890
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.
[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.
2916
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.
[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
2933
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().
[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.
2949
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.
[in] | railHandle | A RAIL instance handle. |
Returns
The current PA power setting.
2962
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.
[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.
2985
of file common/rail.h
RAIL_IsPaAutoModeEnabled#
bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)
Query status of PA Auto Mode.
[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).
2994
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.
[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.
3024
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.
[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
Status code indicating success of the function call. If successfully initiated, transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3063
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.
[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
Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3098
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.
[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] | 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
Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3146
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.
[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] | 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
Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3194
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.
[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] | 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
Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3247
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.
[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] | 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
Status code indicating success of the function call. If successfully initiated, a transmit completion or failure will be reported by a later RAIL_Config_t::eventsCallback with the appropriate RAIL_Events_t.
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.
3301
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.
[in] | railHandle | A RAIL instance handle. |
[in] | mode | Configure the types of transmits to stop. |
Returns
RAIL_STATUS_NO_ERROR if the transmit was successfully stopped or RAIL_STATUS_INVALID_STATE if there is no transmit operation to stop.
Note
When mode includes RAIL_STOP_MODE_ACTIVE, this can also stop an active auto-ACK transmit. When an active transmit is stopped, RAIL_EVENT_TX_ABORTED or RAIL_EVENT_TXACK_ABORTED should occur. When mode includes RAIL_STOP_MODE_PENDING this can also stop a RAIL_TX_OPTION_CCA_ONLY transmit operation. When a pending transmit is stopped, RAIL_EVENT_TX_BLOCKED should occur.
3326
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.
[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.
3341
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.
[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:
|
Returns
RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.
Note
Consider using RAIL_GetTxPacketDetailsAlt2 for smaller code size.
This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.
3371
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.
[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
RAIL_STATUS_NO_ERROR if pPacketTime was filled in, or an appropriate error code otherwise.
Note
Consider using RAIL_GetTxPacketDetailsAlt2 to pass in a RAIL_PacketTimeStamp_t structure instead of a RAIL_Time_t structure, particularly when RAIL_PacketTimePosition_t information is needed or useful.
This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.
3398
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.
[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:
|
Returns
RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.
This function can only be called from callback context for either RAIL_EVENT_TX_PACKET_SENT or RAIL_EVENT_TXACK_PACKET_SENT events.
3424
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.
[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()).
3459
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.
[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()).
3494
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.
[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.
3517
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.
[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.
3542
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.
[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.
3565
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.
[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.
3591
of file common/rail.h
RAIL_EnableTxHoldOff#
void RAIL_EnableTxHoldOff (RAIL_Handle_t railHandle, bool enable)
Prevent the radio from starting a transmit.
[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.
3610
of file common/rail.h
RAIL_IsTxHoldOffEnabled#
bool RAIL_IsTxHoldOffEnabled (RAIL_Handle_t railHandle)
Check whether or not TX hold off is enabled.
[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.
3623
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.
[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
Attempting to set a preamble length of 0xFFFF bits will result in RAIL_STATUS_INVALID_PARAMETER.
3639
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.
[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
: On chips where RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is true, enabling RAIL_RX_OPTION_CHANNEL_SWITCHING without configuring RX channel switching, via RAIL_IEEE802154_ConfigRxChannelSwitching, will return RAIL_STATUS_INVALID_PARAMETER for only this option. Any other RX options (except antenna selection) would still take effect.
3673
of file common/rail.h
RAIL_IncludeFrameTypeLength#
void RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)
Include the code necessary for frame type based length decoding.
[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.
3688
of file common/rail.h
RAILCb_ConfigFrameTypeLength#
void RAILCb_ConfigFrameTypeLength (RAIL_Handle_t railHandle, const RAIL_FrameType_t * frameType)
Handle frame type length.
[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.
3703
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.
[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.
3721
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.
[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.
3750
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.
[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.
3825
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).
[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.
3858
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.
[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.
3880
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.
[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:
|
This function can be used in any RX mode; it does not free up any internal resources.
Returns
RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.
Note
Certain details are always available, while others are only available if the RAIL_RxOptions_tRAIL_RX_OPTION_REMOVE_APPENDED_INFO option is not in effect and the received packet's RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set. See RAIL_RxPacketDetails_t for clarification.
Consider using RAIL_GetRxPacketDetailsAlt for smaller code size.
3926
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.
[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
RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.
This alternative API allows for smaller code size by deadstripping the timestamp adjustment algorithms which are not in use.
Note
Certain details are always available, while others are only available if the RAIL_RxOptions_tRAIL_RX_OPTION_REMOVE_APPENDED_INFO option is not in effect and the received packet's RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set. See RAIL_RxPacketDetails_t for clarification.
3963
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.
[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.
3990
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.
[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.
4012
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.
[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.
4038
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.
[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.
4060
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.
[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.
4086
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.
[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.
4108
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.
[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.
4137
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.
[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().
4163
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.
[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
RAIL_STATUS_NO_ERROR if the held packet was released or an appropriate error code otherwise.
4190
of file common/rail.h
RAIL_GetRssi#
int16_t RAIL_GetRssi (RAIL_Handle_t railHandle, bool wait)
Return the current raw RSSI.
[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
If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), pass true for the wait parameter otherwise it's very likely RAIL_RSSI_INVALID will be returned.
If RX channel hopping is turned on, do not use this API. Instead, see RAIL_GetChannelHoppingRssi().
When 'wait' is false, this API is equivalent to RAIL_GetRssiAlt with 'waitTimeout' set to RAIL_GET_RSSI_NO_WAIT. When 'wait' is true, this API is equivalent to RAIL_GetRssiAlt with 'waitTimeout' set to RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT. Consider using RAIL_GetRssiAlt if a bounded maximum wait timeout is desired.
4236
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.
[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
If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), pass true for the wait parameter otherwise it's very likely RAIL_RSSI_INVALID will be returned.
If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), the RSSI value returned could come from either antenna and vary between antennas.
If RX channel hopping is turned on, do not use this API. Instead, see RAIL_GetChannelHoppingRssi().
4282
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.
[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
If the radio is idled while RSSI averaging is still in effect, a RAIL_EVENT_RSSI_AVERAGE_DONE event may not occur and RAIL_IsAverageRssiReady may never return true.
4312
of file common/rail.h
RAIL_IsAverageRssiReady#
bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)
Query whether the RSSI averaging is done.
[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.
4329
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.
[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.
4342
of file common/rail.h
RAIL_SetRssiOffset#
RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)
Set the RSSI offset.
[in] | railHandle | a RAIL instance handle. |
[in] | rssiOffset | desired offset to be added to the RSSI measurements. |
Returns
Status code indicating success of the function call. RAIL_STATUS_INVALID_CALL if called with chip-specific handle, such as RAIL_EFR32_HANDLE, after RAIL initialization. RAIL_STATUS_INVALID_PARAMETER if the RSSI offset is deemed large enough to cause the RSSI readings to underflow or overflow.
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
: If RAIL has not been initialized, a chip-specific handle, such as RAIL_EFR32_HANDLE, can be used to set a chip level RSSI offset.
: Setting a large rssiOffset may still cause the RSSI readings to underflow. If that happens, the RSSI value returned by RAIL_GetRssi, RAIL_GetAverageRssi, RAIL_GetChannelHoppingRssi etc. will be RAIL_RSSI_LOWEST
: During RX Channel Hopping this API will not update the RSSI offset immediately if channel hopping has already been configured. A subsequent call to RAIL_ZWAVE_ConfigRxChannelHopping or RAIL_ConfigRxChannelHopping is required for the new RSSI offset to take effect.
4375
of file common/rail.h
RAIL_GetRssiOffset#
int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)
Get the RSSI offset.
[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.
4388
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.
[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
Status code indicating success of the function call. Returns RAIL_STATUS_INVALID_STATE in multiprotocol, if the requested RAIL_Handle_t is not active. Returns RAIL_STATUS_INVALID_CALL if called on parts on which this function is not supported.
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.
4417
of file common/rail.h
RAIL_GetRssiDetectThreshold#
int8_t RAIL_GetRssiDetectThreshold (RAIL_Handle_t railHandle)
Get the RSSI detection threshold(in dBm).
[in] | railHandle | a RAIL instance handle. |
Returns
rssiThreshold (in dBm) corresponding to the current handle.
Note
: The function returns RAIL_RSSI_INVALID_DBM when RAIL_SetRssiDetectThreshold is not supported or disabled. In multiprotocol, the function returns RAIL_RSSI_INVALID_DBM if railHandle is not active. This function is only available on series-2 Sub-GHz parts EFR32XG23 and EFR32XG25.
4432
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.
[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.
4444
of file common/rail.h
RAIL_ConfigAddressFilter#
RAIL_Status_t RAIL_ConfigAddressFilter (RAIL_Handle_t railHandle, const RAIL_AddrConfig_t * addrConfig)
Configure address filtering.
[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.
4527
of file common/rail.h
RAIL_EnableAddressFilter#
bool RAIL_EnableAddressFilter (RAIL_Handle_t railHandle, bool enable)
Enable address filtering.
[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.
4543
of file common/rail.h
RAIL_IsAddressFilterEnabled#
bool RAIL_IsAddressFilterEnabled (RAIL_Handle_t railHandle)
Return whether address filtering is currently enabled.
[in] | railHandle | A RAIL instance handle. |
Returns
True if address filtering is enabled and false otherwise.
4551
of file common/rail.h
RAIL_ResetAddressFilter#
void RAIL_ResetAddressFilter (RAIL_Handle_t railHandle)
Reset the address filtering configuration.
[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.
4562
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.
[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.
4583
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.
[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
This feature/API is not supported on the EFR32XG1 family of chips or the EFR32XG21. Use the compile time symbol RAIL_SUPPORTS_ADDR_FILTER_ADDRESS_BIT_MASK or the runtime call RAIL_SupportsAddrFilterAddressBitMask() to check whether the platform supports this feature.
4615
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.
[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.
4629
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.
[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.
4783
of file common/rail.h
RAIL_IsAutoAckEnabled#
bool RAIL_IsAutoAckEnabled (RAIL_Handle_t railHandle)
Return the enable status of the auto-ACK feature.
[in] | railHandle | A RAIL instance handle. |
Returns
true if auto-ACK is enabled, false if disabled.
4792
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.
[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).
4813
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.
[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.
4833
of file common/rail.h
RAIL_PauseRxAutoAck#
void RAIL_PauseRxAutoAck (RAIL_Handle_t railHandle, bool pause)
Pause/resume RX auto-ACK functionality.
[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.
4848
of file common/rail.h
RAIL_IsRxAutoAckPaused#
bool RAIL_IsRxAutoAckPaused (RAIL_Handle_t railHandle)
Return whether the RX auto-ACK is paused.
[in] | railHandle | A RAIL instance handle. |
Returns
true if RX auto-ACK is paused, false if not paused.
4857
of file common/rail.h
RAIL_PauseTxAutoAck#
void RAIL_PauseTxAutoAck (RAIL_Handle_t railHandle, bool pause)
Pause/resume TX auto-ACK functionality.
[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.
4870
of file common/rail.h
RAIL_IsTxAutoAckPaused#
bool RAIL_IsTxAutoAckPaused (RAIL_Handle_t railHandle)
Return whether the TX auto-ACK is paused.
[in] | railHandle | A RAIL instance handle. |
Returns
true if TX auto-ACK is paused, false if not paused.
4878
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.
[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.
4899
of file common/rail.h
RAIL_CancelAutoAck#
RAIL_Status_t RAIL_CancelAutoAck (RAIL_Handle_t railHandle)
Cancel the upcoming ACK.
[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.
4916
of file common/rail.h
RAIL_IsAutoAckWaitingForAck#
bool RAIL_IsAutoAckWaitingForAck (RAIL_Handle_t railHandle)
Return whether the radio is currently waiting for an ACK.
[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.
4928
of file common/rail.h
RAIL_ConfigCal#
RAIL_Status_t RAIL_ConfigCal (RAIL_Handle_t railHandle, RAIL_CalMask_t calEnable)
Initialize RAIL calibration.
[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.
4997
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.
[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.
5043
of file common/rail.h
RAIL_GetPendingCal#
RAIL_CalMask_t RAIL_GetPendingCal (RAIL_Handle_t railHandle)
Return the current set of pending calibrations.
[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.
5058
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.
[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.