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#
Number of temperature values provided for HFXO metrics.
Total number of temperature values provided by RAIL_GetTemperature().
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 the current RAIL channel configuration.
Cause radio settings associated with a particular channel to be applied to hardware.
Return the most-recently requested RAIL channel.
Return the RAIL channel to which the radio is currently tuned.
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(s) and prepare RAIL for sleep.
Wake RAIL from sleep and restart the RAIL timer(s).
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 receive data.
Set up the receive FIFO to use.
Read packet data from RAIL's 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.
Enable automatic LNA bypass for external FEM.
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 in the receive FIFO and internal packet metadata FIFO.
Copy 'len' bytes of packet data starting from 'offset' from the receive FIFO.
Release RAIL's resources for the packet previously held in the receive FIFO and internal receive metadata FIFO.
Return the current raw RSSI.
Return the current raw RSSI in quarter-dBm 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 in quarter-dBm averaged over a specified time in microseconds.
Set the RSSI offset.
Get the radio or protocol RSSI offset in dB.
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 transmit 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 in deci-dBm 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.
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 and idle the radio.
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 VDET plugin.
Get the VDET plugin configuration.
Enable the VDET plugin.
Check if the VDET plugin is enabled.
Get VDET measurement.
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.
Get the different temperature measurements in Kelvin done by sequencer or host.
Configure retiming options.
Get the currently configured retiming option.
Indicate that the DCDC peripheral bus clock enable has changed allowing RAIL to react accordingly.
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 this chip supports internal RF path 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 VDET.
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.
Indicate whether this chip supports automatic LNA bypass for external FEM.
Macro Definition Documentation#
RAIL_HFXO_TEMP_MEASURE_COUNT#
#define RAIL_HFXO_TEMP_MEASURE_COUNTValue:
(1U)
Number of temperature values provided for HFXO metrics.
6258 of file common/rail.hRAIL_TEMP_MEASURE_COUNT#
#define RAIL_TEMP_MEASURE_COUNTValue:
Total number of temperature values provided by RAIL_GetTemperature().
6261 of file common/rail.hFunction Documentation#
RAIL_GetVersion#
RAIL_Status_t RAIL_GetVersion (RAIL_Version_t * version, bool verbose)
Get the version information for the compiled RAIL library.
| [out] | version | A non-NULL pointer to RAIL_Version_t structure to populate with version information. |
| [in] | verbose | Populate RAIL_Version_t struct with verbose information. |
Returns
Status code indicating success of the function call.
The version information contains a major version number, a minor version number, and a rev (revision) number.
83 of file common/rail.hRAIL_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.
152 of file common/rail.hRAIL_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.
162 of file common/rail.hRAIL_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.
178 of file common/rail.hRAIL_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.
321 of file common/rail.hRAIL_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.
333 of file common/rail.hRAIL_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 | A non-NULL pointer to the buffer to write the collected entropy. |
| [in] | bytes | The number of bytes to fill in the input buffer. |
Returns
The number of bytes of entropy collected. For radios 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 radios 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.
353 of file common/rail.hRAIL_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, e.g., RAIL_EFR32_HANDLE. |
| [in] | ptiConfig | A non-NULL pointer to the PTI configuration structure to use. |
Returns
Status code indicating success of the function call.
This method must be called before RAIL_EnablePti() is called. There is only one PTI configuration that can be active on a radio, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch – RAIL does not save the configuration in a protocol RAIL instance).
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.
387 of file common/rail.hRAIL_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, e.g., RAIL_EFR32_HANDLE. |
| [out] | ptiConfig | A non-NULL pointer to the configuration structure to be filled in 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. This function always returns the active PTI configuration on the radio regardless of the active protocol.
403 of file common/rail.hRAIL_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, e.g., RAIL_EFR32_HANDLE. |
| [in] | enable | PTI is enabled if true; disabled if false. |
Returns
Status code indicating success of the function call.
Similarly to having only one PTI configuration per radio, 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 – RAIL does not save this state in a protocol RAIL instance).
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.
428 of file common/rail.hRAIL_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 app 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.
448 of file common/rail.hRAIL_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.
457 of file common/rail.hRAIL_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, e.g., RAIL_EFR32_HANDLE. |
| [in] | config | A pointer to 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_RX_OPTION_ANTENNA0 and RAIL_RX_OPTION_ANTENNA1 options (and the RAIL_RX_OPTION_ANTENNA_AUTO combination). Antenna selection for transmit is controlled by the RAIL_TX_OPTION_ANTENNA0 and RAIL_TX_OPTION_ANTENNA1 options.
There is only one antenna configuration can be active on a radio, regardless of the number of protocols (unless the application updates the configuration upon a protocol switch – RAIL does not save this configuration in a protocol RAIL instance).
494 of file common/rail.hRAIL_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 | A pointer to RF path updated by the function. |
Returns
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.
509 of file common/rail.hRAIL_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 radio configuration array (pointer). |
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.
548 of file common/rail.hRAIL_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
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.
569 of file common/rail.hRAIL_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 | A pointer to a function called whenever a radio configuration change occurs. May be NULL if do not need a callback. |
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.
591 of file common/rail.hRAIL_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 | A pointer to an app-allocated array that will be populated with channel metadata. |
| [inout] | length | A pointer to the number of entries available in the channelMetadata array. This value will be updated to the number of channels written to the array, not to exceed the length number passed in. |
| [in] | minChannel | Minimum channel number about which to collect data. |
| [in] | maxChannel | Maximum channel number about which to collect data. |
Returns
Status code indicating success of the function 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.
616 of file common/rail.hRAIL_IsValidChannel#
RAIL_Status_t RAIL_IsValidChannel (RAIL_Handle_t railHandle, uint16_t channel)
Check whether the channel exists in the current RAIL channel configuration.
| [in] | railHandle | A RAIL instance handle. |
| [in] | channel | A channel number to check. |
Returns
RAIL_STATUS_NO_ERROR if channel exists or RAIL_STATUS_INVALID_PARAMETER if the given channel does not exist.
630 of file common/rail.hRAIL_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 current RAIL_ChannelConfig_t::configs list and applies the configuration associated with the specified channel if found. 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.
652 of file common/rail.hRAIL_GetChannel#
RAIL_Status_t RAIL_GetChannel (RAIL_Handle_t railHandle, uint16_t * channel)
Return the most-recently requested RAIL channel.
| [in] | railHandle | A RAIL instance handle. |
| [out] | channel | A pointer to the channel for which RAIL was most-recently 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.
673 of file common/rail.hRAIL_GetChannelAlt#
RAIL_Status_t RAIL_GetChannelAlt (RAIL_Handle_t railHandle, uint16_t * channel)
Return the RAIL channel to which the radio is currently tuned.
| [in] | railHandle | A RAIL instance handle. |
| [out] | channel | A pointer to the currently-tuned channel. |
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 to which the radio is currently tuned if the specified RAIL handle is active. It returns the channel to which it will be tuned 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.
690 of file common/rail.hRAIL_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.
704 of file common/rail.hRAIL_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.
732 of file common/rail.hRAIL_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.
Note
This function does nothing on EFR32 Series 2 devices.
765 of file common/rail.hRAIL_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.
777 of file common/rail.hRAIL_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 sync word length is configured to be. Changing the sync word 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 sync word 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.
803 of file common/rail.hRAIL_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.
812 of file common/rail.hRAIL_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.
820 of file common/rail.hRAIL_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.
842 of file common/rail.hRAIL_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.
864 of file common/rail.hRAIL_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().
876 of file common/rail.hRAIL_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().
887 of file common/rail.hRAIL_GetTime#
RAIL_Time_t RAIL_GetTime (void )
Get the current RAIL time.
| N/A |
Returns
The RAIL time 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.
982 of file common/rail.hRAIL_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. |
Returns
Status code indicating the success of the function call.
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.
997 of file common/rail.hRAIL_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.
1016 of file common/rail.hRAIL_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 | A pointer to a callback function that RAIL will call when the timer expires. May be NULL if no callback is desired. |
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.
1042 of file common/rail.hRAIL_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.
1058 of file common/rail.hRAIL_CancelTimer#
RAIL_Status_t RAIL_CancelTimer (RAIL_Handle_t railHandle)
Stop the currently scheduled RAIL timer.
| [in] | railHandle | A RAIL instance handle. |
Returns
RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_CALL if the timer is 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.
1071 of file common/rail.hRAIL_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.
1082 of file common/rail.hRAIL_IsTimerRunning#
bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)
Check whether the RAIL timer is currently running.
| [in] | railHandle | A RAIL instance handle. |
Returns
true if the timer is running and false if the timer has expired or was never set.
1091 of file common/rail.hRAIL_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.
1114 of file common/rail.hRAIL_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. |
Returns
RAIL_STATUS_NO_ERROR on success.
RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.
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.
1135 of file common/rail.hRAIL_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.
1152 of file common/rail.hRAIL_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.
1160 of file common/rail.hRAIL_IsMultiTimerExpired#
bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t * tmr)
Check if a given timer has expired.
| [in] | tmr | A pointer to the timer instance. |
Returns
true if the timer is expired; false if the timer is running.
1168 of file common/rail.hRAIL_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.
1184 of file common/rail.hRAILCb_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. For example:
void RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)
{
timerSyncConfig->prsChannel = MY_TIMERSYNC_PRS_CHANNEL;
timerSyncConfig->rtccChannel = MY_TIMERSYNC_RTCC_CHANNEL;
}
If an unsupported channel is selected by the application, RAIL_ConfigSleep will return RAIL_STATUS_INVALID_PARAMETER.
1467 of file common/rail.hRAIL_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.
1476 of file common/rail.hRAIL_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. |
Returns
Status code indicating success of the function call.
The default structure used to enable timer synchronization across sleep is RAIL_TIMER_SYNC_DEFAULT.
1489 of file common/rail.hRAIL_Sleep#
RAIL_Status_t RAIL_Sleep (uint16_t wakeupProcessTime, bool * deepSleepAllowed)
Stop the RAIL timer(s) and prepare RAIL for sleep.
| [in] | wakeupProcessTime | Time in microseconds that the application and hardware need to recover from sleep state. |
| [out] | deepSleepAllowed | A pointer to boolean that will be set true if system can go to deep sleep or false if system must not go to deep sleep (EM2 or lower energy modes). |
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.
1506 of file common/rail.hRAIL_Wake#
RAIL_Status_t RAIL_Wake (RAIL_Time_t elapsedTime)
Wake RAIL from sleep and restart the RAIL timer(s).
| [in] | elapsedTime | Add this sleep duration in microseconds to the RAIL timer(s) before restarting it(them). |
Returns
Status code indicating success of the function call.
If the timer sync was enabled by RAIL_ConfigSleep, synchronize the RAIL timer(s) using an alternate timer. Otherwise, add elapsedTime to the RAIL timer(s).
Note
This API must not be called if RAIL Power Manager is initialized.
1521 of file common/rail.hRAIL_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.
1538 of file common/rail.hRAIL_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.
1549 of file common/rail.hRAIL_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.
1575 of file common/rail.hRAIL_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 | A pointer to a non-NULL 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().
1888 of file common/rail.hRAIL_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 | A 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 copies writeLength bytes of data from the provided dataPtr into the transmit FIFO previously established by RAIL_SetTxFifo() or RAIL_Init(). 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 raiHhandle 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 utilize a critical section but, depending on the application, calling it within a critical section could be appropriate.
1923 of file common/rail.hRAIL_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
The transmit 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.
1977 of file common/rail.hRAIL_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
The transmit 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.
2010 of file common/rail.hRAIL_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 receive 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.
2054 of file common/rail.hRAILCb_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_BYTES 1024
static __ALIGNED(RAIL_FIFO_ALIGNMENT) uint8_t rxFifo[RX_FIFO_BYTES];
RAIL_Status_t RAILCb_SetupRxFifo(RAIL_Handle_t railHandle)
{
uint16_t rxFifoBytes = RX_FIFO_BYTES;
RAIL_Status_t status = RAIL_SetRxFifo(railHandle, &rxFifo[0], &rxFifoBytes);
if (rxFifoBytes != RX_FIFO_BYTES) {
// 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;
}
2093 of file common/rail.hRAIL_ReadRxFifo#
uint16_t RAIL_ReadRxFifo (RAIL_Handle_t railHandle, uint8_t * dataPtr, uint16_t readLength)
Read packet data from RAIL's 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.
2130 of file common/rail.hRAIL_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.
2151 of file common/rail.hRAIL_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.
2179 of file common/rail.hRAIL_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 in bytes.
Retrieves the configured TX threshold value.
2190 of file common/rail.hRAIL_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 in bytes.
Retrieves the configured RX threshold value.
2200 of file common/rail.hRAIL_ResetFifo#
RAIL_Status_t 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 and its internal metadata FIFO. |
Returns
Status code indicating success of the function call.
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.
2214 of file common/rail.hRAIL_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.
2234 of file common/rail.hRAIL_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.
2245 of file common/rail.hRAIL_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 | A pointer to 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.
2270 of file common/rail.hRAIL_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 | A pointer to the state transitions that RAIL applies 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.
2283 of file common/rail.hRAIL_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 | A pointer to 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.
2298 of file common/rail.hRAIL_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 | A pointer to the state transitions that RAIL applies 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.
2311 of file common/rail.hRAIL_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 | A pointer to 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 PTI Packet Trace 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
Use the compile time symbol RAIL_SUPPORTS_TX_TO_TX or the runtime call RAIL_SupportsTxToTx() to check whether the platform supports this feature.
2371 of file common/rail.hRAIL_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.
2400 of file common/rail.hRAIL_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 | A pointer to the timings used to configure the RAIL state machine. This structure is updated 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.
2416 of file common/rail.hRAIL_Idle#
RAIL_Status_t 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. |
Returns
RAIL_STATUS_NO_ERROR if the radio has idled by the time this function returns, or RAIL_STATUS_SUSPENDED if it is still in the process of idling.
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.
2436 of file common/rail.hRAIL_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
2460 of file common/rail.hRAIL_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
2526 of file common/rail.hRAIL_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 boolean 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.
2555 of file common/rail.hRAIL_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 | A pointer to apower config with the desired initial settings for the TX amplifier. |
Returns
Status code indicating success of the function call.
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.
2717 of file common/rail.hRAIL_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
Status code indicating success of the function call.
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.
2734 of file common/rail.hRAIL_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 radio-specific RAIL_TxPowerLevel_t units. |
Returns
Status code indicating success of the function call.
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 radio 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.
2760 of file common/rail.hRAIL_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 radio-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 Silicon Labs 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).
2781 of file common/rail.hRAIL_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 okay to use either a real protocol handle, or one of the radio-generic ones, such as RAIL_EFR32_HANDLE.
Although the definitions of this function may change, the signature must be as declared here.
2807 of file common/rail.hRAIL_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 okay to use either a real protocol handle, or one of the radio-generic ones, such as RAIL_EFR32_HANDLE.
Although the definitions of this function may change, the signature must be as declared here.
2835 of file common/rail.hRAIL_VerifyTxPowerCurves#
RAIL_Status_t RAIL_VerifyTxPowerCurves (const struct RAIL_TxPowerCurvesConfigAlt * config)
Verify the TX Power Curves on modules.
| [in] | config | A pointer to TX Power Curves to use on this module. |
Returns
Status code indicating success of function call.
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.
2847 of file common/rail.hRAIL_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
Status code indicating success of the function call.
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.
2872 of file common/rail.hRAIL_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.
2897 of file common/rail.hRAIL_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 | A pointer to a RAIL_TxPowerLevel_t, but in deci-dBm units. |
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 output minPower, maxPower, and step parameters. For example, for minPower = 115 (11.5 dBm), maxPower = 300 (30 dBm), and step = 1 (0.1 dBm), the number of entries in table would be 186.
2915 of file common/rail.hRAIL_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
Status code indicating success of the function call.
2930 of file common/rail.hRAIL_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.
2943 of file common/rail.hRAIL_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 RAIL instance handle. |
| [in] | enable | Enable or disable PA Auto Mode. |
Returns
Status code indicating success of the function call.
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.
2967 of file common/rail.hRAIL_IsPaAutoModeEnabled#
bool RAIL_IsPaAutoModeEnabled (RAIL_Handle_t railHandle)
Query status of PA Auto Mode.
| [in] | railHandle | A real RAIL instance handle. |
Returns
Indicator of whether Auto Mode is enabled (true) or not (false).
2975 of file common/rail.hRAILCb_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 | A 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 | A 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 | A 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
Status code indicating success of the 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 radio. The RAIL_PaAutoModeConfig definition for a radio should tend to all the bands supported by the radio and cover the full range of power to find a valid entry for requested power for a specific band.
3006 of file common/rail.hRAIL_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 | A pointer to 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.
3045 of file common/rail.hRAIL_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 | 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 indicating when and how the transmit should occur. |
| [in] | schedulerInfo | A pointer to 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.
3080 of file common/rail.hRAIL_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 | 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 | A pointer to 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 RAIL_CsmaConfig_t::ccaBackoff time is less than the RAIL_StateTiming_t::idleToRx time. If the RAIL_CsmaConfig_t::ccaBackoff time is greater than the RAIL_StateTiming_t::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.
3128 of file common/rail.hRAIL_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 | 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 | A pointer to 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 RAIL_LbtConfig_t::lbtBackoff time is less than the RAIL_StateTiming_t::idleToRx time. If the RAIL_LbtConfig_t::lbtBackoff time is greater than the RAIL_StateTiming_t::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.
3176 of file common/rail.hRAIL_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 | 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 | A pointer to 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.
This is a scheduled variation of RAIL_StartCcaCsmaTx(); refer to that function for CSMA details.
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.
3216 of file common/rail.hRAIL_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 | 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 | A pointer to 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.
This is a scheduled variation of RAIL_StartCcaLbtTx; refer to that function for LBT details.
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.
3257 of file common/rail.hRAIL_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 | Specifies the type(s) of transmit 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.
3282 of file common/rail.hRAIL_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.
3297 of file common/rail.hRAIL_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.
3327 of file common/rail.hRAIL_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.
3354 of file common/rail.hRAIL_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 field 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.
3381 of file common/rail.hRAIL_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()).
3416 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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()).
3451 of file common/rail.hRAIL_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.
3474 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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. After this function, the timeSent 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 the timestamp adjustment function in the same transmit-complete event-handling context as RAIL_GetTxPacketDetailsAlt2() is called.
3498 of file common/rail.hRAIL_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.
3521 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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. After this function, the timeSent field packetTime will be updated with the time that this packet finished on air. |
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.
3544 of file common/rail.hRAIL_EnableTxHoldOff#
RAIL_Status_t 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. |
Returns
Status code indicating success of the function call.
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.
3564 of file common/rail.hRAIL_IsTxHoldOffEnabled#
bool RAIL_IsTxHoldOffEnabled (RAIL_Handle_t railHandle)
Check whether or not TX hold off is enabled.
| [in] | railHandle | A RAIL instance handle. |
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.
3577 of file common/rail.hRAIL_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.
3593 of file common/rail.hRAIL_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.
3621 of file common/rail.hRAIL_IncludeFrameTypeLength#
RAIL_Status_t RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)
Include the code necessary for frame type based length decoding.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
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.
3637 of file common/rail.hRAILCb_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 pointer to 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.
3652 of file common/rail.hRAIL_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 | A pointer to 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.
3670 of file common/rail.hRAIL_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 | A pointer to a configuration structure to define the receive window. |
| [in] | schedulerInfo | A pointer to 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.
3699 of file common/rail.hRAIL_EnableAutoLnaBypass#
RAIL_Status_t RAIL_EnableAutoLnaBypass (RAIL_Handle_t railHandle, bool enable, const RAIL_AutoLnaBypassConfig_t * pAutoLnaBypassConfig)
Enable automatic LNA bypass for external FEM.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | enable | Enable/Disable automatic LNA bypass. |
| [in] | pAutoLnaBypassConfig | A pointer to an automatic LNA bypass configuration structure. It must be non-NULL to enable the feature. |
Returns
Status code indicating success of the function call.
If automatic LNA bypass is enabled on chip that supports the feature (RAIL_SUPPORTS_AUTO_LNA_BYPASS), GPIO is used to bypass external FEM LNA when the received power exceed a threshold. The bypass is turned off after frame reception or after timeout if no frame has been detected.
Note
As this automatic LNA bypass relies on GPIO and RAIL is meant to run in TrustZone non-secure world, the feature is not supported if GPIO is configured as secure peripheral.
3723 of file common/rail.hRAIL_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 | A non-NULL pointer to a RAIL_RxPacketInfo_t to store info for the requested packet. |
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 any receive FIFO or internal receive resources. If used in receive 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.
3797 of file common/rail.hRAIL_GetRxIncomingPacketInfo#
RAIL_Status_t 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 | A non-NULL 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.
Returns
Status code indicating success of the function call.
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.
3831 of file common/rail.hRAIL_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 | A non-NULL 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 | A non-NULL pointer to the 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.
3853 of file common/rail.hRAIL_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 any receive FIFO or internal receive 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.
3899 of file common/rail.hRAIL_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 | A non-NULL application-provided 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 any receive FIFO or receive 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.
This function should be called soon (no more than a minute) after packet reception for the packet timestamp information to be valid.
3939 of file common/rail.hRAIL_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 | A pointer to 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.
3966 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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.
3988 of file common/rail.hRAIL_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 | A pointer to 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.
4014 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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.
4036 of file common/rail.hRAIL_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 | A pointer to 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.
4062 of file common/rail.hRAIL_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 | A non-NULL pointer to the 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.
4084 of file common/rail.hRAIL_HoldRxPacket#
RAIL_RxPacketHandle_t RAIL_HoldRxPacket (RAIL_Handle_t railHandle)
Place a temporary hold on this packet's data in the receive FIFO and internal packet metadata FIFO.
| [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 the packet data and metadata after the callback returns. This function tells RAIL to hold onto those resources in the receive FIFO and internal metadata FIFO 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 and internal receive metadata FIFO are reset during protocol switches losing any held packets. It is best to avoid using RAIL_HoldRxPacket in DMP or to at least invalidate any held packet handles and related RAIL_RxPacketInfo_t information when the RAIL_EVENT_CONFIG_UNSCHEDULED occurs.
4116 of file common/rail.hRAIL_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().
4142 of file common/rail.hRAIL_ReleaseRxPacket#
RAIL_Status_t RAIL_ReleaseRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)
Release RAIL's resources for the packet previously held in the receive FIFO and internal receive metadata FIFO.
| [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.
4171 of file common/rail.hRAIL_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.
4217 of file common/rail.hRAIL_GetRssiAlt#
int16_t RAIL_GetRssiAlt (RAIL_Handle_t railHandle, RAIL_Time_t waitTimeout)
Return the current raw RSSI in quarter-dBm within a definitive time period.
| [in] | railHandle | A RAIL instance handle. |
| [in] | waitTimeout | Sets the maximum time in microseconds 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().
4263 of file common/rail.hRAIL_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 | A pointer to 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.
Completion of RSSI averaging, marked by RAIL event RAIL_EVENT_RSSI_AVERAGE_DONE, will return the radio to idle state.
4296 of file common/rail.hRAIL_IsAverageRssiReady#
bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)
Query whether the RSSI averaging is done.
| [in] | railHandle | A RAIL instance handle. |
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.
4313 of file common/rail.hRAIL_GetAverageRssi#
int16_t RAIL_GetAverageRssi (RAIL_Handle_t railHandle)
Get the RSSI in quarter-dBm averaged over a specified time in microseconds.
| [in] | railHandle | A RAIL instance handle. |
Returns
The RSSI in quarter-dBm (dBm * 4), or RAIL_RSSI_INVALID if the receiver is disabled or an an RSSI value couldn't be obtained.
Gets the hardware RSSI average after issuing RAIL_StartAverageRssi. Use after RAIL_StartAverageRssi.
4325 of file common/rail.hRAIL_SetRssiOffset#
RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)
Set the RSSI offset.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | rssiOffset | desired dB offset to be added to the RSSI measurements. |
Returns
Status code indicating success of the function call. RAIL_STATUS_INVALID_CALL if called with radio-generic 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 radio-generic handle, such as RAIL_EFR32_HANDLE, can be used to set a radio's RSSI offset applied to all protocols on that radio.
: 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.
4359 of file common/rail.hRAIL_GetRssiOffset#
int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)
Get the radio or protocol RSSI offset in dB.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
The RSSI offset in dB corresponding to the railHandle.
Note
: A radio-generic handle, such as RAIL_EFR32_HANDLE, can be used to get the radio's RSSI offset otherwise this will return the RSSI offset value associated with the RAIL protocol instance handle, exclusive of any radio RSSI offset correction, if any.
4372 of file common/rail.hRAIL_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 EFR32 Series 2 Sub-GHz parts EFR32XG23 and EFR32XG25.
4401 of file common/rail.hRAIL_GetRssiDetectThreshold#
int8_t RAIL_GetRssiDetectThreshold (RAIL_Handle_t railHandle)
Get the RSSI detection threshold in dBm.
| [in] | railHandle | a RAIL instance handle. |
Returns
The RSSI threshold in dBm corresponding to the railHandle.
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 EFR32 Series 2 Sub-GHz parts EFR32XG23 and EFR32XG25.
4417 of file common/rail.hRAIL_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.
4429 of file common/rail.hRAIL_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 | A pointer to the configuration structure, which defines how addresses are set up in your packets. May be NULL to reset address filtering. |
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.
4512 of file common/rail.hRAIL_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.
4528 of file common/rail.hRAIL_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.
4536 of file common/rail.hRAIL_ResetAddressFilter#
RAIL_Status_t RAIL_ResetAddressFilter (RAIL_Handle_t railHandle)
Reset the address filtering configuration.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
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.
4548 of file common/rail.hRAIL_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.
4569 of file common/rail.hRAIL_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 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.
4601 of file common/rail.hRAIL_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.
4615 of file common/rail.hRAIL_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 | A pointer to an Auto-ACK configuration structure. |
Returns
Status code indicating success of the function call.
Configures the RAIL state machine 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:
RAIL_SetTxTransitions() Indeed, when auto-ACKing is enabled, only one state transition can be defined (without notion of success or error). Thus if you are enabling auto-ACK (i.e., "config.enable" field is true) the "error" fields of config.rxTransitions and config.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). On the oppsite, if you are disabling auto-ACK (i.e., "config.enable" field is false), transitions are reconfigured using all fields of config.rxTransitions and config.txTransitions. 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(void)
{
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.
4775 of file common/rail.hRAIL_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.
4784 of file common/rail.hRAIL_WriteAutoAckFifo#
RAIL_Status_t RAIL_WriteAutoAckFifo (RAIL_Handle_t railHandle, const uint8_t * ackData, uint16_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 auto-ACK 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).
4805 of file common/rail.hRAIL_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 transmit 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 auto-ACK FIFO buffer. |
| [inout] | ackBufferBytes | A pointer to a uint16_t that will be updated to the size of the auto-ACK FIFO buffer, in bytes, currently RAIL_AUTOACK_MAX_LENGTH. |
Returns
Status code indicating success of the function call.
Applications can use this to more flexibly write auto-ACK 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.
4825 of file common/rail.hRAIL_PauseRxAutoAck#
RAIL_Status_t 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. |
Returns
Status code indicating success of the function call.
When RX auto-ACKing is paused, the radio transitions to RAIL_AutoAckConfig_t::rxTransitions's RAIL_StateTransitions_t::success 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.
4842 of file common/rail.hRAIL_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.
4851 of file common/rail.hRAIL_PauseTxAutoAck#
RAIL_Status_t 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. |
Returns
Status code indicating success of the function call.
When TX auto-ACKing is paused, the radio transitions to RAIL_AutoAckConfig_t::txTransitions's RAIL_StateTransitions_t::success 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.
4866 of file common/rail.hRAIL_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.
4874 of file common/rail.hRAIL_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 auto-ACK when IEEE 802.15.4, Z-Wave, or BLE protocols are active.
4895 of file common/rail.hRAIL_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.
4912 of file common/rail.hRAIL_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.
4924 of file common/rail.hRAIL_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 radio-specific. |
Returns
Status code indicating success of the function call.
Calibration initialization provides the calibration settings that correspond to the current radio configuration.
5001 of file common/rail.hRAIL_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 pointer to 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 calibration-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.
5047 of file common/rail.hRAIL_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.
5062 of file common/rail.hRAIL_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
Status code indicating success of the function call.
Take an image rejection calibration value and apply it. This value should be determined from a previous run of RAIL_CalibrateIr on the same physical device with the same radio configuration. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
DeprecatedPlease use RAIL_ApplyIrCalibrationAlt instead.
5082 of file common/rail.hRAIL_ApplyIrCalibrationAlt#
RAIL_Status_t RAIL_ApplyIrCalibrationAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Apply a given image rejection calibration value.
| [in] | railHandle | A RAIL instance handle. |
| [in] | imageRejection | A pointer to the image rejection values to apply. |
| [in] | rfPath | RF path(s) to calibrate. |
Returns
Status code indicating success of the function call.
Take image rejection calibration values and apply them. These values should be determined from a previous run of RAIL_CalibrateIrAlt on the same physical device with the same radio configuration. The imageRejection values will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible.
Note
: To make sure the imageRejection values are stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
5105 of file common/rail.hRAIL_CalibrateIr#
RAIL_Status_t RAIL_CalibrateIr (RAIL_Handle_t railHandle, uint32_t * imageRejection)
Run the image rejection calibration.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | The result of the image rejection calibration. |
Returns
Status code indicating success of the function call.
Run the image rejection calibration and apply the resulting value. If the imageRejection parameter is not NULL, store the value at that location. The imageRejection value will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image.
If multiple protocols are used, this function will make the given railHandle active, if not already, and perform calibration. If called during a protocol switch, it will return RAIL_STATUS_INVALID_STATE. In this case, RAIL_ApplyIrCalibration may be called to apply a previously determined IR calibration value, or the app must defer calibration until the protocol switch is complete. Silicon Labs recommends calling this function from the application main loop.
DeprecatedPlease use RAIL_CalibrateIrAlt instead.
5134 of file common/rail.hRAIL_CalibrateIrAlt#
RAIL_Status_t RAIL_CalibrateIrAlt (RAIL_Handle_t railHandle, RAIL_IrCalValues_t * imageRejection, RAIL_AntennaSel_t rfPath)
Run the image rejection calibration.
| [in] | railHandle | A RAIL instance handle. |
| [out] | imageRejection | A pointer to the image rejection results. |
| [in] | rfPath | RF path(s) to calibrate. |
Returns
Status code indicating success of the function call.
Run the image rejection calibration and apply the resulting values. If the imageRejection parameter is not NULL, store the values at that location. The imageRejection values will also be stored to the RAIL_ChannelConfigEntry_t::attr, if possible. This is a long-running calibration that adds significant code space when run and can be run with a separate firmware image on each device to save code space in the final image. Note
: To make sure the imageRejection values are stored/configured correctly, RAIL_ConfigAntenna should be called before calling this API.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the caller must attempt to re-call this function later.
5159 of file common/rail.hRAIL_CalibrateTemp#
RAIL_Status_t RAIL_CalibrateTemp (RAIL_Handle_t railHandle)
Run the temperature calibration.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Run the temperature calibration, which needs to recalibrate the synth if the temperature crosses 0C or the temperature delta since the last calibration exceeds 70C while in receive. RAIL will run the VCO calibration automatically upon entering receive or transmit states, so the application can omit this calibration if the stack re-enters receive or transmit with enough frequency to avoid reaching the temperature delta. If the application does not calibrate for temperature, it's possible to miss receive packets due to a drift in the carrier frequency.
If multiple protocols are used, this function will return RAIL_STATUS_INVALID_STATE if it is called and the given railHandle is not active. In that case, the calibration will be automatically performed next time the radio enters receive.
5183 of file common/rail.hRAIL_CalibrateHFXO#
RAIL_Status_t RAIL_CalibrateHFXO (RAIL_Handle_t railHandle, int8_t * crystalPPMError)
Performs HFXO compensation.
| [in] | railHandle | A RAIL instance handle. |
| [out] | crystalPPMError | A pointer for RAIL to store the current deviation that has been corrected, measured in PPM. May be NULL. |
Returns
Status code indicating the result of the function call.
Compute the PPM correction using the thermistor value available when RAIL_EVENT_THERMISTOR_DONE occurs, after RAIL_StartThermistorMeasurement() call. Then correct the RF frequency as well as TX and RX sampling.
This function calls the following RAIL functions in sequence saving having to call them individually:
Note
This function makes the radio idle.
5206 of file common/rail.hRAIL_EnablePaCal#
void RAIL_EnablePaCal (bool enable)
Enable/disable the PA calibration.
| [in] | enable | Enables/disables the PA calibration. |
Enabling will ensure that the PA power remains constant chip-to-chip. This feature is enabled by default on Series-2 platforms.
On EFR32xG21 and EFR32xG24 platforms, particularly the 20 dBm variants, it is recommended to keep this feature enabled in order to utilize the chip-specific calibrations designated for the chip.
The chip-specific define SL_RAIL_UTIL_PA_CALIBRATION_ENABLE in the Power Amplifier (PA) Utility plugin also enables/disables PA calibrations on initialization, which can override the default state of the feature.
Note
Call this function before RAIL_ConfigTxPower() if this feature is desired.
5227 of file common/rail.hRAIL_StartRfSense#
RAIL_Time_t RAIL_StartRfSense (RAIL_Handle_t railHandle, RAIL_RfSenseBand_t band, RAIL_Time_t senseTime, RAIL_RfSense_CallbackPtr_t cb)
Start/stop the RF Sense functionality in Energy Detection Mode for use during low-energy sleep modes.
| [in] | railHandle | A RAIL instance handle. |
| [in] | band | The frequency band(s) on which to sense the RF energy. To stop RF Sense, specify RAIL_RFSENSE_OFF. |
| [in] | senseTime | The time (in microseconds) the RF energy must be continually detected to be considered "sensed". |
| [in] | cb | RAIL_RfSense_CallbackPtr_t is called when the RF is sensed. Set NULL if using RAIL_EVENT_RF_SENSED or polling via RAIL_IsRfSensed(). |
Returns
The actual senseTime used, which may be different than requested due to limitations of the hardware. If 0, RF sense was disabled or could not be enabled (no callback or event will be issued).
Some EFR32 radios have the ability to sense the presence of RF energy above -20 dBm within either or both the 2.4 GHz and Sub-GHz bands and trigger an event if that energy is continuously present for certain durations of time. An application can check when RF energy is sensed either by enabling the event RAIL_EVENT_RF_SENSED, by polling on the RAIL_IsRfSensed API, or by using the cb callback.
Note
After RF energy has been sensed, the RF Sense is automatically disabled and RAIL_StartRfSense() must be called again to reactivate it. If RF energy has not been sensed and to manually disable RF Sense, RAIL_StartRfSense() must be called with band specified as RAIL_RFSENSE_OFF or with senseTime set to 0 microseconds.
Packet reception is not guaranteed to work correctly once RF Sense is enabled, both in single protocol and multiprotocol RAIL. To be safe, an application should turn this on only after idling the radio to stop receive and turn it off before attempting to restart receive. Since EM4 sleep causes the chip to come up through the reset vector any wake from EM4 must also shut off RF Sense to ensure proper receive functionality.
Warnings
For some radios, RF Sense functionality is only guaranteed within a specified temperature range. See chip-specific documentation for more details.
5280 of file common/rail.hRAIL_StartSelectiveOokRfSense#
RAIL_Status_t RAIL_StartSelectiveOokRfSense (RAIL_Handle_t railHandle, RAIL_RfSenseSelectiveOokConfig_t * config)
Start/stop the RF Sense functionality in Selective(OOK Based) Mode for use during low-energy sleep modes.
| [in] | railHandle | A RAIL instance handle. |
| [in] | config | A pointer to a RAIL_RfSenseSelectiveOokConfig_t which holds the RFSENSE configuration for Selective(OOK) mode. |
Returns
Status code indicating success of the function call.
Some radios support Selective RF energy detection (OOK mode) where the user can program the radio to look for a particular sync word pattern (1byte - 4bytes) sent using OOK and wake only when that is detected. See chip-specific documentation for more details.
The following code gives an example of how to use RF Sense functionality in Selective(OOK Based) Mode.
// Sync word length in bytes, 1-4 bytes.
#define NUM_SYNC_WORD_BYTES (2U)
// Sync word value.
#define SYNC_WORD (0xB16FU)
// Configure the transmitting node for sending the wakeup packet.
RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true);
RAIL_ConfigRfSenseSelectiveOokWakeupPhy(railHandle);
RAIL_SetRfSenseSelectiveOokWakeupPayload(railHandle, NUM_SYNC_WORD_BYTES, SYNC_WORD);
RAIL_StartTx(railHandle, channel, RAIL_TX_OPTIONS_DEFAULT, NULL);
// Configure the receiving node (EFR32XG22) for RF Sense.
RAIL_RfSenseSelectiveOokConfig_t config = {
.band = rfBand,
.syncWordNumBytes = NUM_SYNC_WORD_BYTES,
.syncWord = SYNC_WORD,
.cb = &RAILCb_SensedRf
};
RAIL_StartSelectiveOokRfSense(railHandle, &config);
Note
After RF energy has been sensed, the RF Sense is automatically disabled and RAIL_StartSelectiveOokRfSense() must be called again to reactivate. If RF energy has not been sensed and to manually disable RF Sense, RAIL_StartSelectiveOokRfSense() must be called with band specified as RAIL_RFSENSE_OFF or with RAIL_RfSenseSelectiveOokConfig_t as NULL.
Packet reception is not guaranteed to work correctly once RF Sense is enabled, both in single protocol and multiprotocol RAIL. To be safe, an application should turn this on only after idling the radio to stop receive and turn it off before attempting to restart receive. Since EM4 sleep causes the chip to come up through the reset vector any wake from EM4 must also shut off RF Sense to ensure proper receive functionality.
5337 of file common/rail.hRAIL_ConfigRfSenseSelectiveOokWakeupPhy#
RAIL_Status_t RAIL_ConfigRfSenseSelectiveOokWakeupPhy (RAIL_Handle_t railHandle)
Switch to RF Sense Selective(OOK) PHY.
| [in] | railHandle | A handle for RAIL instance. |
Returns
Status code indicating success of the function call.
This function switches to the RFSENSE Selective(OOK) PHY for transmitting a packet to wake up a chip that supports Selective RF energy detection (OOK mode). You may only call this function while the radio is idle. While the radio is configured for this PHY, receive functionality should not be used.
Note
The user must also set up the transmit FIFO, via RAIL_SetRfSenseSelectiveOokWakeupPayload, post this function call to include the first byte as the Preamble Byte, followed by the Sync word (1-4 bytes). See chip-specific documentation for more details.
5357 of file common/rail.hRAIL_SetRfSenseSelectiveOokWakeupPayload#
RAIL_Status_t RAIL_SetRfSenseSelectiveOokWakeupPayload (RAIL_Handle_t railHandle, uint8_t numSyncwordBytes, uint32_t syncword)
Set the transmit payload for waking up a node configured for RF Sense Selective(OOK).
| [in] | railHandle | A handle for RAIL instance. |
| [in] | numSyncwordBytes | Sync word length in bytes, 1-4 bytes. |
| [in] | syncword | Sync word value. |
Returns
Status code indicating success of the function call.
Note
You must call this function after the chip has been set up with the RF Sense Selective(OOK) PHY, using RAIL_ConfigRfSenseSelectiveOokWakeupPhy.
5372 of file common/rail.hRAIL_IsRfSensed#
bool RAIL_IsRfSensed (RAIL_Handle_t railHandle)
Check whether the RF was sensed.
| [in] | railHandle | A RAIL instance handle. |
Returns
true if RF was sensed since the last call to RAIL_StartRfSense. false otherwise.
This function is useful if RAIL_StartRfSense is called with a NULL callback. It is generally used after EM4 reboot but can be used any time.
5386 of file common/rail.hRAIL_ConfigRxChannelHopping#
RAIL_Status_t RAIL_ConfigRxChannelHopping (RAIL_Handle_t railHandle, RAIL_RxChannelHoppingConfig_t * config)
Configure RX channel hopping.
| [in] | railHandle | A RAIL instance handle. |
| [in] | config | A pointer to the configuration parameters for RX Channel Hopping. |
Returns
Status code indicating success of the function call.
Configure channel hopping channels, conditions, and parameters. This API must be called before RAIL_EnableRxChannelHopping(). This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled.
Note
Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
Calling this function will overwrite any settings configured with RAIL_ConfigRxDutyCycle.
5472 of file common/rail.hRAIL_EnableRxChannelHopping#
RAIL_Status_t RAIL_EnableRxChannelHopping (RAIL_Handle_t railHandle, bool enable, bool reset)
Enable RX channel hopping.
| [in] | railHandle | A RAIL instance handle. |
| [in] | enable | Enable (true) or disable (false) RX Channel Hopping. |
| [in] | reset | Start from the first channel of the channel hopping sequence (true) or from wherever hopping left off last time the code left RX. |
Returns
Status code indicating success of the function call.
Enable or disable Channel Hopping. Additionally, specify whether hopping should be reset to start from the first channel index, or continue from the channel last hopped to. The radio should not be on when this API is called. RAIL_ConfigRxChannelHopping must be called successfully before this API is called.
Note
Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
RX Channel Hopping may not be enabled while auto-ACKing is enabled.
Calling this function will overwrite any settings configured with RAIL_EnableRxDutyCycle.
5500 of file common/rail.hRAIL_GetChannelHoppingRssi#
int16_t RAIL_GetChannelHoppingRssi (RAIL_Handle_t railHandle, uint8_t channelIndex)
Get RSSI in deci-dBm of one channel in the channel hopping sequence, during channel hopping.
| [in] | railHandle | A RAIL instance handle. |
| [in] | channelIndex | Index in the channel hopping sequence of the channel of interest |
Returns
Latest RSSI in deci-dBm for the channel at the specified index.
Note
Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t.
RAIL_ConfigRxChannelHopping must be called successfully before this API is called.
When the Z-Wave protocol is active, running RAIL_GetChannelHoppingRssi() on the 9.6kbps PHY returns the RSSI measurement of the 40kpbs PHY. This is because the 9.6kbps PHY has trouble with RSSI measurements on EFR32XG2 family of chips.
5527 of file common/rail.hRAIL_ConfigRxDutyCycle#
RAIL_Status_t RAIL_ConfigRxDutyCycle (RAIL_Handle_t railHandle, const RAIL_RxDutyCycleConfig_t * config)
Configure RX duty cycle mode.
| [in] | railHandle | A RAIL instance handle. |
| [in] | config | A non-NULL pointer to a configuration structure specifying duty cycle parameters. |
Returns
Status code indicating success of the function call.
Configure RX duty cycle mode. With this mode enabled, every time the radio enters RX, it will duty cycle on and off to save power. The duty cycle ratio can be altered dynamically and intelligently by the hardware by staying on longer if a preamble or other packet segments are detected in the air. This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled. For short delays (in the order of microseconds), RAIL_RxDutyCycleConfig_t::delay, this can be used to save receive current while having little impact on the radio performance, for protocols with long preambles. For long delays (in the order of milliseconds or higher) the chip can be put into EM2 energy mode before re-entering RX, to save extra power, with some application hooks as shown below.
#include "rail.h"
extern RAIL_Handle_t railHandle;
RAIL_Time_t periodicWakeupUs;
volatile bool dutyCycleEnd = true;
void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
// Omitting other event handlers
if (events & RAIL_EVENT_RX_DUTY_CYCLE_RX_END) {
dutyCycleEnd = true;
}
}
void main(void)
{
RAIL_Status_t status;
bool shouldSleep = false;
initializeRail(); // Call RAIL_Init() and such
// This function depends on your board/chip but it must enable the LFCLK
// you intend to use for RTCC sync before we configure sleep as that
// function will attempt to auto detect the clock.
BoardSetupLFCLK();
// Initialize Power Manager module
sl_power_manager_init();
// Initialize RAIL Power Manager
RAIL_InitPowerManager();
// Configure sleep for timer synchronization
RAIL_TimerSyncConfig_t timerSyncConfig = RAIL_TIMER_SYNC_DEFAULT;
status = RAIL_ConfigSleep(railHandle, &timerSyncConfig);
assert(status == RAIL_STATUS_NO_ERROR);
// Configure RX duty-cycling
RAIL_RxDutyCycleConfig_t duty_cycle_config = {
.mode = RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE,
.parameter = DUTY_CYCLE_ON_TIME,
.delay_us = DUTY_CYCLE_OFF_TIME,
.delay_mode = RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC,
.options = RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE,
};
status = RAIL_ConfigRxDutyCycle(rail_handle, &duty_cycle_config);
assert(status == RAIL_STATUS_NO_ERROR);
status = RAIL_EnableRxDutyCycle(rail_handle, true);
assert(status == RAIL_STATUS_NO_ERROR);
// Application main loop
while (1) {
if (dutyCycleEnd) {
dutyCycleEnd = false;
// Schedule the next receive.
RAIL_ScheduleRxConfig_t rxConfig = {
.start = periodicWakeupUs,
.startMode = RAIL_TIME_DELAY,
.end = 0U,
.endMode = RAIL_TIME_DISABLED,
.rxTransitionEndSchedule = 0U,
.hardWindowEnd = 0U
};
RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true);
RAIL_StartScheduledRx(railHandle, channel, &rxConfig, NULL);
}
// ... do normal app stuff and set shouldSleep when we want to sleep
if (shouldSleep) {
// Let the CPU go to sleep if the system allows it.
sl_power_manager_sleep();
}
}
}
Note
Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
Calling this function will overwrite any settings configured with RAIL_ConfigRxChannelHopping.
5631 of file common/rail.hRAIL_EnableRxDutyCycle#
RAIL_Status_t RAIL_EnableRxDutyCycle (RAIL_Handle_t railHandle, bool enable)
Enable RX duty cycle mode.
| [in] | railHandle | A RAIL instance handle. |
| [in] | enable | Enable (true) or disable (false) RX Duty Cycling. |
Returns
Status code indicating success of the function call.
Enable or disable RX duty cycle mode. After this is called, the radio will begin duty cycling each time it enters RX, based on the configuration passed to RAIL_ConfigRxDutyCycle. This API must not be called while the radio is on.
Note
Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
Calling this function will overwrite any settings configured with RAIL_EnableRxChannelHopping.
5653 of file common/rail.hRAIL_GetDefaultRxDutyCycleConfig#
RAIL_Status_t RAIL_GetDefaultRxDutyCycleConfig (RAIL_Handle_t railHandle, RAIL_RxDutyCycleConfig_t * config)
Get the default RX duty cycle configuration.
| [in] | railHandle | A RAIL instance handle. |
| [out] | config | An application-provided non-NULL pointer to store the default RX duty cycle configuration. |
Returns
Status code indicating success of the function call. Note that RAIL_STATUS_INVALID_PARAMETER will be returned if the current channel's radio configuration does not support the requested information.
To save power during RX, an application may want to go to low power as long as possible by periodically waking up and trying to "sense" if there are any incoming packets. This API returns the recommended RX duty cycle configuration, so the application can enter low power mode periodically without missing packets. To wake up earlier, the application can reduce the delay parameter. Note that these value might be different if any configuration / channel has changed.
5675 of file common/rail.hRAIL_YieldRadio#
RAIL_Status_t RAIL_YieldRadio (RAIL_Handle_t railHandle)
Yield the radio to other configurations.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
This function is used to indicate that the previous transmit or scheduled receive operation has completed. It must be used in multiprotocol RAIL because the scheduler assumes that any transmit or receive operation that is started can go on indefinitely based on state transitions and your protocol. RAIL will not allow a lower priority tasks to run until this is called so it can negatively impact performance of those protocols if this is omitted or delayed. It is also possible to call the RAIL_Idle() API to both terminate the operation and idle the radio. In single protocol RAIL this API does nothing, however, if RAIL Power Manager is initialized, calling RAIL_YieldRadio after scheduled TX/RX and instantaneous TX completion, is required, to indicate to the Power Manager that the the radio is no longer busy and can be idled for sleeping.
See Yielding the Radio for more details.
5710 of file common/rail.hRAIL_GetSchedulerStatus#
RAIL_SchedulerStatus_t RAIL_GetSchedulerStatus (RAIL_Handle_t railHandle)
Get the status of the RAIL scheduler.
| [in] | railHandle | A RAIL instance handle. |
Returns
RAIL_SchedulerStatus_t status.
This function can only be called from a callback context after the RAIL_EVENT_SCHEDULER_STATUS event occurs.
5721 of file common/rail.hRAIL_GetSchedulerStatusAlt#
RAIL_Status_t RAIL_GetSchedulerStatusAlt (RAIL_Handle_t railHandle, RAIL_SchedulerStatus_t * pSchedulerStatus, RAIL_Status_t * pRailStatus)
Get the status of the RAIL scheduler, specific to the radio operation, along with RAIL_Status_t returned by RAIL API invoked by the RAIL scheduler.
| [in] | railHandle | A RAIL instance handle. |
| [out] | pSchedulerStatus | An application-provided pointer to store RAIL_SchedulerStatus_t status. Can be NULL as long as pRailStatus is not NULL. |
| [out] | pRailStatus | An application-provided pointer to store RAIL_Status_t of the RAIL API invoked by the RAIL scheduler. Can be NULL as long as pSchedulerStatus is not NULL. |
Returns
Status code indicating success of the function call.
This function can only be called from a callback context after the RAIL_EVENT_SCHEDULER_STATUS event occurs.
5740 of file common/rail.hRAIL_SetTaskPriority#
RAIL_Status_t RAIL_SetTaskPriority (RAIL_Handle_t railHandle, uint8_t priority, RAIL_TaskType_t taskType)
Change the priority of a specified task type in multiprotocol.
| [in] | railHandle | A RAIL instance handle. |
| [in] | priority | Desired new priority for the railHandle's active task |
| [in] | taskType | Type of task whose priority should be updated |
Returns
Status code indicating success of the function call.
While the application can use this function however it likes, a major use case is being able to increase an infinite receive priority while receiving a packet. In other words, a given RAIL_Handle_t can maintain a very low priority background receive, but upon getting a RAIL_EVENT_RX_SYNC1_DETECT_SHIFT or RAIL_EVENT_RX_SYNC2_DETECT_SHIFT event, the app can call this function to increase the background RX priority to lower the risk another protocol might preempt during packet reception.
5761 of file common/rail.hRAIL_GetTransitionTime#
RAIL_Time_t RAIL_GetTransitionTime (void )
Get time needed to switch between protocols.
| N/A |
Returns
RAIL_Time_t Time needed to switch between protocols.
5770 of file common/rail.hRAIL_SetTransitionTime#
void RAIL_SetTransitionTime (RAIL_Time_t transitionTime)
Set time needed to switch between protocols.
| [in] | transitionTime | Time needed to switch between protocols. |
Call this API only once, before any protocol is initialized via RAIL_Init(). Changing this value during normal operation can result in improper scheduling behavior.
5780 of file common/rail.hRAIL_ConfigDirectMode#
RAIL_Status_t RAIL_ConfigDirectMode (RAIL_Handle_t railHandle, const RAIL_DirectModeConfig_t * directModeConfig)
Configure direct mode for RAIL.
| [in] | railHandle | A RAIL instance handle. |
| [in] | directModeConfig | A pointer to a configuration structure to specify direct mode parameters. Default configuration will be used if NULL is passed. |
Returns
RAIL_STATUS_NO_ERROR on success and an error code on failure.
This API configures direct mode and should be called before calling RAIL_EnableDirectMode(). If this function is not called, the following default RAIL_DirectModeConfig_t configuration will be used:
RAIL_DirectModeConfig_t defaultConfig = {
.syncRx = false,
.syncTx = false,
.doutPort = gpioPortA,
.doutPin = 5,
.dinPort = gpioPortA,
.dinPin = 7,
.dclkPort = gpioPortA,
.dclkPin = 6,
};
Warnings
This API is not safe to use in a multiprotocol app.
5819 of file common/rail.hRAIL_EnableDirectMode#
RAIL_Status_t RAIL_EnableDirectMode (RAIL_Handle_t railHandle, bool enable)
Enable or disable direct mode for RAIL.
| [in] | railHandle | A RAIL instance handle. |
| [in] | enable | Whether or not to enable direct mode for TX and RX. |
Returns
RAIL_STATUS_NO_ERROR on success and an error code on failure.
See RAIL_EnableDirectModeAlt() for more detailed function description.
Warnings
New applications should consider using RAIL_EnableDirectModeAlt() for this functionality.
Note
This feature is only available on certain devices. RAIL_SupportsDirectMode() can be used to check if a particular device supports this feature or not.
Warnings
This API is not safe to use in a multiprotocol app.
5841 of file common/rail.hRAIL_EnableDirectModeAlt#
RAIL_Status_t RAIL_EnableDirectModeAlt (RAIL_Handle_t railHandle, bool enableDirectTx, bool enableDirectRx)
Enable or disable direct mode for RAIL.
| [in] | railHandle | A RAIL instance handle. |
| [in] | enableDirectTx | Enable direct mode for data being transmitted out of the radio. |
| [in] | enableDirectRx | Enable direct mode for data being received from the radio. |
Returns
RAIL_STATUS_NO_ERROR on success and an error code on failure.
This API enables or disables the modem and GPIOs for direct mode operation. see RAIL_ConfigDirectMode for information on selecting the correct hardware configuration. If direct mode is enabled, packets are output and input directly to the radio via GPIO and RAIL packet handling is ignored.
Note
This feature is only available on certain chips. RAIL_SupportsDirectMode() can be used to check if a particular chip supports this feature or not.
Warnings
This API is not safe to use in a multiprotocol app.
5866 of file common/rail.hRAIL_GetRadioClockFreqHz#
uint32_t RAIL_GetRadioClockFreqHz (RAIL_Handle_t railHandle)
Get the radio subsystem clock frequency in Hz.
| [in] | railHandle | A RAIL instance handle. |
Returns
Radio subsystem clock frequency in Hz.
5876 of file common/rail.hRAIL_SetTune#
RAIL_Status_t RAIL_SetTune (RAIL_Handle_t railHandle, uint32_t tune)
Set the crystal tuning.
| [in] | railHandle | A RAIL instance handle. |
| [in] | tune | A chip-dependent crystal capacitor bank tuning parameter. |
Returns
Status code indicating success of the function call.
Tunes the crystal that the radio depends on to change the location of the center frequency for transmitting and receiving. This function will only succeed if the radio is idle at the time of the call.
Note
This function proportionally affects the entire chip's timing across all its peripherals, including radio tuning and channel spacing. It is recommended to call this function only when HFXO is not being used, as it can cause disturbance on the HFXO frequency. A separate function, RAIL_SetFreqOffset(), can be used to adjust just the radio tuner without disturbing channel spacing or other chip peripheral timing.
This API sets CTUNEXIANA and internally CTUNEXOANA = CTUNEXIANA + delta where delta is set or changed by RAIL_SetTuneDelta. The default delta may not be 0 on some devices.
5900 of file common/rail.hRAIL_GetTune#
uint32_t RAIL_GetTune (RAIL_Handle_t railHandle)
Get the crystal tuning.
| [in] | railHandle | A RAIL instance handle. |
Returns
A chip-dependent crystal capacitor bank tuning parameter.
Retrieves the current tuning value used by the crystal that the radio depends on. Note
This is the CTUNEXIANA value.
5912 of file common/rail.hRAIL_SetTuneDelta#
RAIL_Status_t RAIL_SetTuneDelta (RAIL_Handle_t railHandle, int32_t delta)
Set the crystal tuning delta.
| [in] | railHandle | A RAIL instance handle. |
| [in] | delta | A chip-dependent crystal capacitor bank tuning delta. |
Returns
Status code indicating success of the function call.
Set the CTUNEXOANA delta for RAIL_SetTune to use: CTUNEXOANA = CTUNEXIANA + delta. This function does not change CTUNE values; call RAIL_SetTune to put a new delta into effect.
5926 of file common/rail.hRAIL_GetTuneDelta#
int32_t RAIL_GetTuneDelta (RAIL_Handle_t railHandle)
Get the crystal tuning delta.
| [in] | railHandle | A RAIL instance handle. |
Returns
A chip-dependent crystal capacitor bank tuning delta.
Retrieves the current tuning delta used by RAIL_SetTune. Note
The default delta if RAIL_SetTuneDelta has never been called is device-dependent and may not be 0.
5938 of file common/rail.hRAIL_GetRxFreqOffset#
RAIL_FrequencyOffset_t RAIL_GetRxFreqOffset (RAIL_Handle_t railHandle)
Get the frequency offset.
| [in] | railHandle | A RAIL instance handle. |
Returns
The measured frequency offset on a received packet. The units are described in the RAIL_FrequencyOffset_t documentation. If this returns RAIL_FREQUENCY_OFFSET_INVALID, it was called while the radio wasn't active and there is no way to get the frequency offset.
Retrieves the measured frequency offset used during the previous received packet, which includes the current radio frequency offset (see RAIL_SetFreqOffset()). If the chip has not been in RX, it returns the nominal radio frequency offset.
Note
Changing to any non-idle radio state after reception can cause this value to be overwritten so it is safest to capture during packet reception.
5958 of file common/rail.hRAIL_SetFreqOffset#
RAIL_Status_t RAIL_SetFreqOffset (RAIL_Handle_t railHandle, RAIL_FrequencyOffset_t freqOffset)
Set the nominal radio frequency offset.
| [in] | railHandle | A RAIL instance handle. |
| [in] | freqOffset | RAIL_FrequencyOffset_t parameter (signed, 2's complement). |
Returns
Status code indicating success of the function call.
This function is used to adjust the radio's tuning frequency slightly up or down. It might be used in conjunction with RAIL_GetRxFreqOffset() after receiving a packet from a peer to adjust the tuner to better match the peer's tuned frequency.
Note
Unlike RAIL_SetTune(), which affects the entire chip's timing including radio tuning and channel spacing, this function only affects radio tuning without disturbing channel spacing or other chip peripheral timing.
5978 of file common/rail.hRAIL_StartTxStream#
RAIL_Status_t RAIL_StartTxStream (RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode)
Start transmitting a stream on a certain channel.
| [in] | railHandle | A RAIL instance handle. |
| [in] | channel | A channel on which to emit a stream. |
| [in] | mode | Choose the stream mode (PN9, and so on). |
Returns
Status code indicating success of the function call.
Begins streaming onto the given channel. The sources can either be an unmodulated carrier wave or an encoded stream of bits from a PN9 source. All ongoing radio operations will be stopped before transmission begins.
5993 of file common/rail.hRAIL_StartTxStreamAlt#
RAIL_Status_t RAIL_StartTxStreamAlt (RAIL_Handle_t railHandle, uint16_t channel, RAIL_StreamMode_t mode, RAIL_TxOptions_t options)
Start transmitting a stream on a certain channel with the ability to select an antenna.
| [in] | railHandle | A RAIL instance handle. |
| [in] | channel | A channel on which to emit a stream. |
| [in] | mode | Choose the stream mode (PN9, and so on). |
| [in] | options | Choose the TX Antenna option. Takes only RAIL_TX_OPTION_ANTENNA0, RAIL_TX_OPTION_ANTENNA1, RAIL_TX_OPTIONS_DEFAULT or RAIL_TX_OPTIONS_NONE from the RAIL_TxOptions_t. If some other value is used then, transmission is possible on any antenna. |
Returns
Status code indicating success of the function call.
Begins streaming onto the given channel. The sources can either be an unmodulated carrier wave or an encoded stream of bits from a PN9 source. All ongoing radio operations will be stopped before transmission begins.
6015 of file common/rail.hRAIL_StopTxStream#
RAIL_Status_t RAIL_StopTxStream (RAIL_Handle_t railHandle)
Stop stream transmission and idle the radio.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call.
Halts the transmission started by RAIL_StartTxStream().
6028 of file common/rail.hRAIL_StopInfinitePreambleTx#
RAIL_Status_t RAIL_StopInfinitePreambleTx (RAIL_Handle_t railHandle)
Stop infinite preamble transmission started and start transmitting the rest of the packet.
| [in] | railHandle | A RAIL instance handle. |
Returns
Status code indicating success of the function call: RAIL_STATUS_NO_ERROR if infinite preamble was stopped; RAIL_STATUS_INVALID_CALL if the radio isn't configured for infinite preamble; RAIL_STATUS_INVALID_STATE if the radio isn't transmitting.
This function is only useful for radio configurations that specify an infinite preamble. Call this API only after RAIL_EVENT_TX_STARTED has occurred and the radio is transmitting.
6045 of file common/rail.hRAIL_ConfigVerification#
RAIL_Status_t RAIL_ConfigVerification (RAIL_Handle_t railHandle, RAIL_VerifyConfig_t * configVerify, RAIL_RadioConfig_t radioConfig, RAIL_VerifyCallbackPtr_t cb)
Configure the verification of radio memory contents.
| [in] | railHandle | A RAIL instance handle. |
| [inout] | configVerify | A pointer to a configuration structure made available to RAIL to perform radio state verification. 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] | radioConfig | A radioConfig (pointer) that is to be used as a white list for verifying memory contents. |
| [in] | cb | A callback that notifies the application of a mismatch in expected vs actual memory contents. A NULL parameter may be passed in if a callback is not needed by the application. |
Returns
RAIL_STATUS_NO_ERROR if setup of the verification feature successfully occurred. RAIL_STATUS_INVALID_PARAMETER is returned if the provided railHandle or configVerify structures are invalid.
6065 of file common/rail.hRAIL_Verify#
RAIL_Status_t RAIL_Verify (RAIL_VerifyConfig_t * configVerify, uint32_t durationUs, bool restart)
Verify radio memory contents.
| [inout] | configVerify | A pointer to the configuration structure previously established by RAIL_ConfigVerification(). |
| [in] | durationUs | The duration (in microseconds) for how long memory verification should occur before returning to the application. A value of RAIL_VERIFY_DURATION_MAX indicates that all memory contents should be verified before returning to the application. |
| [in] | restart | This flag only has meaning if a previous call of this function returned RAIL_STATUS_SUSPENDED. By restarting (true), the verification process starts over from the beginning, or by resuming where verification left off after being suspended (false), verification can proceed towards completion. |
Returns
RAIL_STATUS_NO_ERROR if the contents of all applicable memory locations have been verified. RAIL_STATUS_SUSPENDED is returned if the provided test duration expired but the time was not sufficient to verify all memory contents. By calling RAIL_Verify again, further verification will commence. RAIL_STATUS_INVALID_PARAMETER is returned if the provided verifyConfig structure pointer is not configured for use by the active RAIL handle. RAIL_STATUS_INVALID_STATE is returned if any of the verified memory contents are different from their reference values.
6095 of file common/rail.hRAIL_ConfigVdet#
RAIL_Status_t RAIL_ConfigVdet (RAIL_Handle_t genericRailHandle, const RAIL_VdetConfig_t * config)
Configure the VDET plugin.
| [in] | genericRailHandle | A radio-generic RAIL handle. |
| [in] | config | A pointer to a RAIL_VdetConfig_t struct that contains configuration data for the VDET. |
Returns
Return values
RAIL_STATUS_NO_ERROR: - All went well
RAIL_STATUS_INVALID_STATE: - VDET is enabled. Must be disabled first.
RAIL_STATUS_INVALID_PARAMETER: - mode/resolution/delayUs out-of-bounds.
6154 of file common/rail.hRAIL_GetVdetConfig#
RAIL_Status_t RAIL_GetVdetConfig (RAIL_Handle_t genericRailHandle, RAIL_VdetConfig_t * config)
Get the VDET plugin configuration.
| [in] | genericRailHandle | A radio-generic RAIL handle. |
| [out] | config | A pointer to a RAIL_VdetConfig_t struct that will return configuration data for the VDET. |
Returns
RAIL_Status_t
Return values
RAIL_STATUS_NO_ERROR: - All went well.
6166 of file common/rail.hRAIL_EnableVdet#
RAIL_Status_t RAIL_EnableVdet (RAIL_Handle_t genericRailHandle, bool enable)
Enable the VDET plugin.
| [in] | genericRailHandle | A RAIL instance handle. |
| [in] | enable | Enable or disable RAIL_VDET_MODE_AUTOMATIC mode captures. Begins measurement if in RAIL_VDET_MODE_IMMEDIATE. |
Returns
Return values
RAIL_STATUS_NO_ERROR: - All went well, VDET is enabled or disabled.
RAIL_STATUS_INVALID_STATE: - VDET has not been configured or VDET was not idle. VDET is disabled.
6179 of file common/rail.hRAIL_IsVdetEnabled#
bool RAIL_IsVdetEnabled (RAIL_Handle_t genericRailHandle)
Check if the VDET plugin is enabled.
| [in] | genericRailHandle | A RAIL instance handle. |
Returns
bool
6188 of file common/rail.hRAIL_GetVdet#
RAIL_Status_t RAIL_GetVdet (RAIL_Handle_t genericRailHandle, uint32_t * pVdetMv)
Get VDET measurement.
| [in] | genericRailHandle | A RAIL instance handle. |
| [out] | pVdetMv | A pointer to a uint32_t for returning the measurement. |
A processed measurement in millivolts.
Returns
Return values
RAIL_STATUS_NO_ERROR: - All went well, value in *pVdetMv is valid.
RAIL_STATUS_INVALID_CALL: - VDET is in progress, wait until VDET capture is complete and try again.
RAIL_STATUS_INVALID_STATE: - VDET is not enabled or valid. Wait until next packet and try reading again.
RAIL_STATUS_INVALID_PARAMETER: - In
RAIL_STATUS_SUSPENDED: - Blocked by AuxADC contention. Wait until next packet and try reading again.
6207 of file common/rail.hRAIL_ConfigThermalProtection#
RAIL_Status_t RAIL_ConfigThermalProtection (RAIL_Handle_t genericRailHandle, const RAIL_ChipTempConfig_t * chipTempConfig)
Enable or disable the thermal protection if RAIL_SUPPORTS_THERMAL_PROTECTION is defined and update the temperature threshold and cool down hysteresis preventing or allowing transmissions.
| [in] | genericRailHandle | A radio-generic RAIL handle. |
| [in] | chipTempConfig | A pointer to a RAIL_ChipTempConfig_t that contains the configuration to be applied. |
Returns
Status code indicating the result of the function call. Returns RAIL_STATUS_INVALID_PARAMETER if enable field from RAIL_ChipTempConfig_t is set to false when an EFF is present on the board.
When the temperature threshold minus a precise number of degrees specified by the cool down hysteresis parameter is exceeded, any future transmits are blocked until the temperature decreases below that limit. Besides, if the temperature threshold is exceeded, any active transmit is aborted.
By default the threshold is set to RAIL_CHIP_TEMP_THRESHOLD_MAX and the cool down hysteresis is set to RAIL_CHIP_TEMP_COOLDOWN_DEFAULT.
Note
The thermal protection is automatically enabled when an EFF is present on the board. There is no use in calling this API in this case.
6243 of file common/rail.hRAIL_GetThermalProtection#
RAIL_Status_t RAIL_GetThermalProtection (RAIL_Handle_t genericRailHandle, RAIL_ChipTempConfig_t * chipTempConfig)
Get the current thermal configuration parameter and status.
| [in] | genericRailHandle | A radio-generic RAIL handle. |
| [out] | chipTempConfig | A non-NULL pointer to a RAIL_ChipTempConfig_t that will by updated with the current configuration. |
Returns
Status code indicating the result of the function call.
6254 of file common/rail.hRAIL_GetTemperature#
RAIL_Status_t RAIL_GetTemperature (RAIL_Handle_t railHandle, int16_t tempBuffer, bool reset)
Get the different temperature measurements in Kelvin done by sequencer or host.
| [in] | railHandle | A RAIL instance handle. |
| [in] | tempBuffer | Reset the temperature statistics. |
| [out] | reset | The address of the array that will contain temperatures. tempBuffer array must be at least RAIL_TEMP_MEASURE_COUNT int16_t. |
Values that are not populated yet or incorrect are set to 0.
Temperatures, in Kelvin, are stored in tempBuffer such as: tempBuffer[0] is the chip temperature tempBuffer[1] is the minimal chip temperature tempBuffer[2] is the maximal chip temperature
If RAIL_SUPPORTS_HFXO_COMPENSATION tempBuffer[3] is the HFXO temperature
Returns
Status code indicating success of the function call.
6282 of file common/rail.hRAIL_ConfigRetimeOptions#
RAIL_Status_t RAIL_ConfigRetimeOptions (RAIL_Handle_t railHandle, RAIL_RetimeOptions_t mask, RAIL_RetimeOptions_t options)
Configure retiming options.
| [in] | railHandle | A handle of RAIL instance. |
| [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_RetimeOptions_t. |
Returns
Status code indicating success of the function call.
6311 of file common/rail.hRAIL_GetRetimeOptions#
RAIL_Status_t RAIL_GetRetimeOptions (RAIL_Handle_t railHandle, RAIL_RetimeOptions_t * pOptions)
Get the currently configured retiming option.
| [in] | railHandle | A handle of RAIL instance. |
| [out] | pOptions | A pointer to configured retiming options bitmask indicating which are enabled. |
Returns
Status code indicating success of the function call.
6323 of file common/rail.hRAIL_ChangedDcdc#
RAIL_Status_t RAIL_ChangedDcdc (void )
Indicate that the DCDC peripheral bus clock enable has changed allowing RAIL to react accordingly.
| N/A |
Returns
Status code indicating success of the function call.
Note
This should be called after DCDC has been enabled or disabled.
6334 of file common/rail.hRAILCb_AssertFailed#
void RAILCb_AssertFailed (RAIL_Handle_t railHandle, RAIL_AssertErrorCodes_t errorCode)
Callback called upon failed assertion.
| [in] | railHandle | A RAIL instance handle. |
| [in] | errorCode | Value passed in by the calling assertion API indicating the RAIL assertion that failed. |
6425 of file common/rail.hRAIL_StartThermistorMeasurement#
RAIL_Status_t RAIL_StartThermistorMeasurement (RAIL_Handle_t railHandle)
Start a thermistor measurement.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
Status code indicating success of the function call. Returns RAIL_STATUS_INVALID_STATE if the thermistor is started while the radio is transmitting.
To get the thermistor impedance, call the function RAIL_GetThermistorImpedance. On platforms having RAIL_SUPPORTS_EXTERNAL_THERMISTOR, this function reconfigures GPIO_THMSW_EN_PIN located in GPIO_THMSW_EN_PORT. To locate this pin, refer to the data sheet or appropriate header files of the device. For proper operation, RAIL_Init must be called before using this function.
Note
When an EFF is attached, this function must not be called during transmit.
Warnings
This API is not safe to use in a multiprotocol app.
6465 of file common/rail.hRAIL_GetThermistorImpedance#
RAIL_Status_t RAIL_GetThermistorImpedance (RAIL_Handle_t railHandle, uint32_t * thermistorImpedance)
Get the thermistor impedance measurement and return RAIL_INVALID_THERMISTOR_VALUE if the thermistor is not properly configured or the thermistor measurement is not ready.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [out] | thermistorImpedance | A pointer to a uint32_t updated with the current thermistor impedance measurement in Ohms. |
Returns
Status code indicating success of the function call.
Note
This function is already called in RAIL_CalibrateHFXO(). It does not need to be manually called during the compensation sequence.
6480 of file common/rail.hRAIL_ConvertThermistorImpedance#
RAIL_Status_t RAIL_ConvertThermistorImpedance (RAIL_Handle_t railHandle, uint32_t thermistorImpedance, int16_t * thermistorTemperatureC)
Convert the thermistor impedance into temperature, in Celsius.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | thermistorImpedance | Current thermistor impedance measurement in Ohms. |
| [out] | thermistorTemperatureC | A non-NULL pointer to an int16_t updated with the current thermistor temperature in eighth of Celsius degrees. |
Returns
Status code indicating success of the function call.
A version of this function is provided in the Thermistor Utility plugin for Silicon Labs radio boards. For custom boards this function can be modified and re-implemented as needed.
Note
This plugin is mandatory on EFR32xG25 platform.
6499 of file common/rail.hRAIL_ComputeHFXOPPMError#
RAIL_Status_t RAIL_ComputeHFXOPPMError (RAIL_Handle_t railHandle, int16_t crystalTemperatureC, int8_t * crystalPPMError)
Compute the crystal PPM deviation from the thermistor temperature.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | crystalTemperatureC | Current crystal temperature, in Celsius. |
| [out] | crystalPPMError | A non-NULL pointer to an int16_t updated with the current ppm error in ppm units. |
Returns
Status code indicating success of the function call.
This function is provided in the rail_util_thermistor plugin to get accurate values from our boards thermistor. For a custom board, this function could be modified and re-implemented for other needs.
Note
This plugin is mandatory on EFR32xG25 platform.
6518 of file common/rail.hRAIL_ConfigHFXOThermistor#
RAIL_Status_t RAIL_ConfigHFXOThermistor (RAIL_Handle_t railHandle, const RAIL_HFXOThermistorConfig_t * pHfxoThermistorConfig)
Configure the GPIO for thermistor usage.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | pHfxoThermistorConfig | A pointer to the thermistor configuration indicating the GPIO port and pin to use. |
Returns
Status code indicating the result of the function call.
Note
The port and pin that must be passed in RAIL_HFXOThermistorConfig_t are GPIO_THMSW_EN_PORT and GPIO_THMSW_EN_PIN respectively.
6533 of file common/rail.hRAIL_ConfigHFXOCompensation#
RAIL_Status_t RAIL_ConfigHFXOCompensation (RAIL_Handle_t railHandle, const RAIL_HFXOCompensationConfig_t * pHfxoCompensationConfig)
Configure the temperature parameters for HFXO compensation.
| [in] | railHandle | A RAIL instance handle. |
| [in] | pHfxoCompensationConfig | A pointer to HFXO compensation parameters indicating the temperature variations used to trigger a compensation. |
Returns
Status code indicating the result of the function call.
Note
This function must be called after RAIL_ConfigHFXOThermistor to succeed.
In RAIL_HFXOCompensationConfig_t, deltaNominal and deltaCritical define the temperature variation triggering a new compensation. The field zoneTemperatureC defines the temperature separating the nominal case (below) from the critical one (above).
When enabled and either deltaNominal or deltaCritical are exceeded, RAIL raises event RAIL_EVENT_CAL_NEEDED with RAIL_CAL_TEMP_HFXO bit set. The API RAIL_StartThermistorMeasurement() must be called afterwards. The latter will raise RAIL_EVENT_THERMISTOR_DONE with calibration bit RAIL_CAL_COMPENSATE_HFXO set and RAIL_CalibrateHFXO() must follow.
Note
Set deltaNominal and deltaCritical to 0 to perform compensation after each transmit.
6562 of file common/rail.hRAIL_GetHFXOCompensationConfig#
RAIL_Status_t RAIL_GetHFXOCompensationConfig (RAIL_Handle_t railHandle, RAIL_HFXOCompensationConfig_t * pHfxoCompensationConfig)
Get the temperature parameters for HFXO compensation.
| [in] | railHandle | A RAIL instance handle. |
| [out] | pHfxoCompensationConfig | A non-NULL pointer to HFXO compensation parameters filled in by the function. |
Returns
Status code indicating the result of the function call.
6573 of file common/rail.hRAIL_CompensateHFXO#
RAIL_Status_t RAIL_CompensateHFXO (RAIL_Handle_t railHandle, int8_t crystalPPMError)
Compute a frequency offset and compensate HFXO accordingly.
| [in] | railHandle | A RAIL instance handle. |
| [in] | crystalPPMError | The current ppm error. Positive values indicate the HFXO frequency is too high; negative values indicate it's too low. |
Returns
Status code indicating success of the function call.
Note
This function only works for platforms having RAIL_SUPPORTS_EXTERNAL_THERMISTOR alongside RAIL_SUPPORTS_HFXO_COMPENSATION.
6587 of file common/rail.hRAIL_Supports2p4GHzBand#
bool RAIL_Supports2p4GHzBand (RAIL_Handle_t railHandle)
Indicate whether RAIL supports 2.4 GHz band operation on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the 2.4 GHz band is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_2P4GHZ_BAND.
6603 of file common/rail.hRAIL_SupportsSubGHzBand#
bool RAIL_SupportsSubGHzBand (RAIL_Handle_t railHandle)
Indicate whether RAIL supports SubGHz band operation on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the SubGHz band is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_SUBGHZ_BAND.
6613 of file common/rail.hRAIL_SupportsDualBand#
bool RAIL_SupportsDualBand (RAIL_Handle_t railHandle)
Indicate whether this chip supports dual 2.4 GHz and SubGHz band operation.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the dual band is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_DUAL_BAND.
6623 of file common/rail.hRAIL_SupportsAddrFilterAddressBitMask#
bool RAIL_SupportsAddrFilterAddressBitMask (RAIL_Handle_t railHandle)
Indicate whether this chip supports bit masked address filtering.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if bit masked address filtering is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_ADDR_FILTER_ADDRESS_BIT_MASK.
6634 of file common/rail.hRAIL_SupportsAddrFilterMask#
bool RAIL_SupportsAddrFilterMask (RAIL_Handle_t railHandle)
Indicate whether this chip supports address filter mask information for incoming packets in RAIL_RxPacketInfo_t::filterMask and RAIL_IEEE802154_Address_t::filterMask.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if address filter information is supported; false otherwise (in which case RAIL_RxPacketInfo_t::filterMask value is undefined).
Runtime refinement of compile-time RAIL_SUPPORTS_ADDR_FILTER_MASK.
6648 of file common/rail.hRAIL_SupportsAlternateTxPower#
bool RAIL_SupportsAlternateTxPower (RAIL_Handle_t railHandle)
Indicate whether this chip supports alternate TX power settings.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if alternate TX power settings are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_ALTERNATE_TX_POWER.
6659 of file common/rail.hRAIL_SupportsAntennaDiversity#
bool RAIL_SupportsAntennaDiversity (RAIL_Handle_t railHandle)
Indicate whether this chip supports antenna diversity.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if antenna diversity is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_ANTENNA_DIVERSITY.
Note
Certain radio configurations may not support this feature even if the chip in general claims to support it.
6672 of file common/rail.hRAIL_SupportsPathDiversity#
bool RAIL_SupportsPathDiversity (RAIL_Handle_t railHandle)
Indicate whether this chip supports internal RF path diversity.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if RF path diversity is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PATH_DIVERSITY.
Note
Certain radio configurations may not support this feature even if the chip in general claims to support it.
6685 of file common/rail.hRAIL_SupportsAuxAdc#
bool RAIL_SupportsAuxAdc (RAIL_Handle_t railHandle)
Indicate whether RAIL supports AUXADC measurements on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if AUXADC measurements are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_AUXADC.
6695 of file common/rail.hRAIL_SupportsChannelHopping#
bool RAIL_SupportsChannelHopping (RAIL_Handle_t railHandle)
Indicate whether RAIL supports channel hopping on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if channel hopping is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_CHANNEL_HOPPING.
6705 of file common/rail.hRAIL_SupportsDirectMode#
bool RAIL_SupportsDirectMode (RAIL_Handle_t railHandle)
Indicate whether this chip supports direct mode.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if direct mode is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_DIRECT_MODE.
6716 of file common/rail.hRAIL_SupportsDualSyncWords#
bool RAIL_SupportsDualSyncWords (RAIL_Handle_t railHandle)
Indicate whether this chip supports dual sync words.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if dual sync words are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_DUAL_SYNC_WORDS.
Note
Certain radio configurations may not support this feature even if the chip in general claims to support it.
6729 of file common/rail.hRAIL_SupportsTxRepeatStartToStart#
bool RAIL_SupportsTxRepeatStartToStart (RAIL_Handle_t railHandle)
Indicate whether this chip supports start to start TX repeats.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if start to start TX repeats are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_TX_REPEAT_START_TO_START.
6740 of file common/rail.hRAIL_SupportsVdet#
bool RAIL_SupportsVdet (RAIL_Handle_t railHandle)
Indicate whether this chip supports VDET.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if VDET is supported; false otherwise.
6748 of file common/rail.hRAIL_SupportsExternalThermistor#
bool RAIL_SupportsExternalThermistor (RAIL_Handle_t railHandle)
Indicate whether RAIL supports thermistor measurements on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if thermistor measurements are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_EXTERNAL_THERMISTOR.
6758 of file common/rail.hRAIL_SupportsHFXOCompensation#
bool RAIL_SupportsHFXOCompensation (RAIL_Handle_t railHandle)
Indicate whether RAIL supports HFXO compensation on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if HFXO compensation is supported and RAIL_ConfigHFXOThermistor() has been successfully called; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_HFXO_COMPENSATION.
6770 of file common/rail.hRAIL_SupportsMfm#
bool RAIL_SupportsMfm (RAIL_Handle_t railHandle)
Indicate whether this chip supports MFM protocol.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if MFM protocol is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_MFM.
6780 of file common/rail.hRAIL_SupportsOFDMPA#
bool RAIL_SupportsOFDMPA (RAIL_Handle_t railHandle)
Indicate whether RAIL supports OFDM band operation on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if OFDM operation is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_OFDM_PA.
6790 of file common/rail.hRAIL_SupportsPrecisionLFRCO#
bool RAIL_SupportsPrecisionLFRCO (RAIL_Handle_t railHandle)
Indicate whether this chip supports a high-precision LFRCO.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if high-precision LFRCO is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PRECISION_LFRCO.
6800 of file common/rail.hRAIL_SupportsRadioEntropy#
bool RAIL_SupportsRadioEntropy (RAIL_Handle_t railHandle)
Indicate whether this chip supports radio entropy.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if radio entropy is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RADIO_ENTROPY.
6810 of file common/rail.hRAIL_SupportsRfSenseEnergyDetection#
bool RAIL_SupportsRfSenseEnergyDetection (RAIL_Handle_t railHandle)
Indicate whether RAIL supports RFSENSE Energy Detection Mode on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if RFSENSE Energy Detection Mode is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RFSENSE_ENERGY_DETECTION.
6821 of file common/rail.hRAIL_SupportsRfSenseSelectiveOok#
bool RAIL_SupportsRfSenseSelectiveOok (RAIL_Handle_t railHandle)
Indicate whether RAIL supports RFSENSE Selective(OOK) Mode on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if RFSENSE Selective(OOK) Mode is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RFSENSE_SELECTIVE_OOK.
6831 of file common/rail.hRAIL_SupportsRssiDetectThreshold#
bool RAIL_SupportsRssiDetectThreshold (RAIL_Handle_t railHandle)
Indicate whether this chip supports configurable RSSI threshold set by RAIL_SetRssiDetectThreshold().
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if setting configurable RSSI is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RSSI_DETECT_THRESHOLD.
6842 of file common/rail.hRAIL_SupportsRxDirectModeDataToFifo#
bool RAIL_SupportsRxDirectModeDataToFifo (RAIL_Handle_t railHandle)
Indicate whether this chip supports RX direct mode data to FIFO.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if direct mode data to FIFO is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RX_DIRECT_MODE_DATA_TO_FIFO.
6853 of file common/rail.hRAIL_SupportsRxRawData#
bool RAIL_SupportsRxRawData (RAIL_Handle_t railHandle)
Indicate whether this chip supports raw RX data sources other than RAIL_RxDataSource_t::RX_PACKET_DATA.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if direct mode is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_RX_RAW_DATA.
6864 of file common/rail.hRAIL_SupportsSQPhy#
bool RAIL_SupportsSQPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports SQ-based PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the SQ-based PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_SQ_PHY.
6874 of file common/rail.hRAIL_SupportsTxPowerMode#
bool RAIL_SupportsTxPowerMode (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t powerMode, RAIL_TxPowerLevel_t * pMaxPowerLevel)
Indicate whether this chip supports a particular power mode (PA).
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [in] | powerMode | The power mode to check if supported. |
| [out] | pMaxPowerLevel | A pointer to a RAIL_TxPowerLevel_t that if non-NULL will be filled in with the power mode's highest power level allowed if this function returns true. |
Returns
true if the powerMode is supported; false otherwise.
This function has no compile-time equivalent.
Note
Consider using RAIL_SupportsTxPowerModeAlt to also get the power mode's lowest allowed power level.
6891 of file common/rail.hRAIL_SupportsTxPowerModeAlt#
bool RAIL_SupportsTxPowerModeAlt (RAIL_Handle_t railHandle, RAIL_TxPowerMode_t * powerMode, RAIL_TxPowerLevel_t * maxPowerLevel, RAIL_TxPowerLevel_t * minPowerLevel)
Indicate whether this chip supports a particular power mode (PA) and provides the maximum and minimum power level for that power mode if supported by the chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
| [inout] | powerMode | A pointer to PA power mode to check if supported. For platforms that support RAIL_TX_POWER_MODE_2P4GIG_HIGHEST or RAIL_TX_POWER_MODE_SUBGIG_HIGHEST the powerMode is updated to the highest corresponding PA available on the chip. |
| [out] | maxPowerLevel | A pointer to a RAIL_TxPowerLevel_t that if non-NULL will be filled in with the power mode's highest power level allowed if this function returns true. |
| [out] | minPowerLevel | A pointer to a RAIL_TxPowerLevel_t that if non-NULL will be filled in with the power mode's lowest power level allowed if this function returns true. |
Returns
true if powerMode is supported; false otherwise.
6913 of file common/rail.hRAIL_SupportsTxToTx#
bool RAIL_SupportsTxToTx (RAIL_Handle_t railHandle)
Indicate whether this chip supports automatic TX to TX transitions.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if TX to TX transitions are supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_TX_TO_TX.
6926 of file common/rail.hRAIL_SupportsProtocolBLE#
bool RAIL_SupportsProtocolBLE (RAIL_Handle_t railHandle)
Indicate whether RAIL supports the BLE protocol on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PROTOCOL_BLE.
6936 of file common/rail.hRAIL_BLE_Supports1MbpsNonViterbi#
bool RAIL_BLE_Supports1MbpsNonViterbi (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 1Mbps Non-Viterbi PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 1Mbps Non-Viterbi is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_1MBPS_NON_VITERBI.
6946 of file common/rail.hRAIL_BLE_Supports1MbpsViterbi#
bool RAIL_BLE_Supports1MbpsViterbi (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 1Mbps Viterbi PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 1Mbps Viterbi is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_1MBPS_VITERBI.
6956 of file common/rail.hRAIL_BLE_Supports1Mbps#
static bool RAIL_BLE_Supports1Mbps (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 1Mbps operation.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 1Mbps operation is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_1MBPS.
6967 of file common/rail.hRAIL_BLE_Supports2MbpsNonViterbi#
bool RAIL_BLE_Supports2MbpsNonViterbi (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 2Mbps Non-Viterbi PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 2Mbps Non-Viterbi is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_2MBPS_NON_VITERBI.
6982 of file common/rail.hRAIL_BLE_Supports2MbpsViterbi#
bool RAIL_BLE_Supports2MbpsViterbi (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 2Mbps Viterbi PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 2Mbps Viterbi is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_2MBPS_VITERBI.
6992 of file common/rail.hRAIL_BLE_Supports2Mbps#
static bool RAIL_BLE_Supports2Mbps (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE 2Mbps operation.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE 2Mbps operation is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_2MBPS.
7003 of file common/rail.hRAIL_BLE_SupportsAntennaSwitching#
bool RAIL_BLE_SupportsAntennaSwitching (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE Antenna Switching needed for Angle-of-Arrival receives or Angle-of-Departure transmits.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE Antenna Switching is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_ANTENNA_SWITCHING.
7019 of file common/rail.hRAIL_BLE_SupportsCodedPhy#
bool RAIL_BLE_SupportsCodedPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE Coded PHY used for Long-Range.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE Coded PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_CODED_PHY.
7029 of file common/rail.hRAIL_BLE_SupportsCte#
bool RAIL_BLE_SupportsCte (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE CTE (Constant Tone Extension) needed for Angle-of-Arrival/Departure transmits.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE CTE is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_CTE.
7040 of file common/rail.hRAIL_BLE_SupportsIQSampling#
bool RAIL_BLE_SupportsIQSampling (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE IQ Sampling needed for Angle-of-Arrival/Departure receives.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE IQ Sampling is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_IQ_SAMPLING.
7063 of file common/rail.hRAIL_BLE_SupportsPhySwitchToRx#
bool RAIL_BLE_SupportsPhySwitchToRx (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE PHY switch to RX functionality, which is used to switch BLE PHYs at a specific time to receive auxiliary packets.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE PHY switch to RX is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_PHY_SWITCH_TO_RX.
7075 of file common/rail.hRAIL_BLE_SupportsQuuppa#
bool RAIL_BLE_SupportsQuuppa (RAIL_Handle_t railHandle)
Indicate whether this chip supports the Quuppa PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the Quuppa is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_QUUPPA.
7085 of file common/rail.hRAIL_BLE_SupportsSignalIdentifier#
bool RAIL_BLE_SupportsSignalIdentifier (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE signal identifier.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if signal identifier is supported; false otherwise.
7093 of file common/rail.hRAIL_BLE_SupportsSimulscanPhy#
bool RAIL_BLE_SupportsSimulscanPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports BLE Simulscan PHY used for simultaneous BLE 1Mbps and Coded PHY reception.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if BLE Simulscan PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_BLE_SUPPORTS_SIMULSCAN_PHY.
7104 of file common/rail.hRAIL_SupportsProtocolIEEE802154#
bool RAIL_SupportsProtocolIEEE802154 (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 protocol.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the 802.15.4 protocol is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PROTOCOL_IEEE802154.
7114 of file common/rail.hRAIL_IEEE802154_SupportsCoexPhy#
bool RAIL_IEEE802154_SupportsCoexPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 Wi-Fi Coexistence PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the 802.15.4 COEX PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_COEX_PHY.
7136 of file common/rail.hRAIL_SupportsIEEE802154Band2P4#
bool RAIL_SupportsIEEE802154Band2P4 (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 2.4 GHz band variant.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if IEEE 802.15.4 2.4 GHz band variant is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_IEEE802154_BAND_2P4.
7147 of file common/rail.hRAIL_SupportsThermalProtection#
bool RAIL_SupportsThermalProtection (RAIL_Handle_t railHandle)
Indicate whether this chip supports the thermal protection.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if thermal protection is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_THERMAL_PROTECTION.
7158 of file common/rail.hRAIL_IEEE802154_SupportsRxChannelSwitching#
bool RAIL_IEEE802154_SupportsRxChannelSwitching (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 2.4 RX channel switching.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if IEEE 802.15.4 2.4 GHz RX channel switching is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING.
7169 of file common/rail.hRAIL_IEEE802154_SupportsCustom1Phy#
bool RAIL_IEEE802154_SupportsCustom1Phy (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 PHY with custom settings.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the 802.15.4 PHY with custom settings is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_CUSTOM1_PHY.
7179 of file common/rail.hRAIL_IEEE802154_SupportsFemPhy#
bool RAIL_IEEE802154_SupportsFemPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4 front end module optimized PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if a front end module is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_FEM_PHY.
7190 of file common/rail.hRAIL_IEEE802154_SupportsCancelFramePendingLookup#
bool RAIL_IEEE802154_SupportsCancelFramePendingLookup (RAIL_Handle_t railHandle)
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).
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if canceling the lookup event is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_CANCEL_FRAME_PENDING_LOOKUP.
7204 of file common/rail.hRAIL_IEEE802154_SupportsEarlyFramePendingLookup#
bool RAIL_IEEE802154_SupportsEarlyFramePendingLookup (RAIL_Handle_t railHandle)
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.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if early triggering is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_EARLY_FRAME_PENDING_LOOKUP.
7217 of file common/rail.hRAIL_IEEE802154_SupportsDualPaConfig#
bool RAIL_IEEE802154_SupportsDualPaConfig (RAIL_Handle_t railHandle)
Indicate whether RAIL supports dual PA mode on this chip.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the dual PA mode is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_DUAL_PA_CONFIG.
7227 of file common/rail.hRAIL_IEEE802154_SupportsEEnhancedAck#
bool RAIL_IEEE802154_SupportsEEnhancedAck (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4E-2012 Enhanced ACKing.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4E Enhanced ACKing is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_E_ENHANCED_ACK.
7238 of file common/rail.hRAIL_IEEE802154_SupportsEMultipurposeFrames#
bool RAIL_IEEE802154_SupportsEMultipurposeFrames (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4E-2012 Multipurpose frame reception.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if Multipurpose frame reception is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_E_MULTIPURPOSE_FRAMES.
7250 of file common/rail.hRAIL_IEEE802154_SupportsESubsetGB868#
bool RAIL_IEEE802154_SupportsESubsetGB868 (RAIL_Handle_t railHandle)
Indicate whether this chip supports the IEEE 802.15.4E-2012 feature subset needed for Zigbee R22 GB868.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4E GB868 subset is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_E_SUBSET_GB868.
7262 of file common/rail.hRAIL_IEEE802154_SupportsG4ByteCrc#
bool RAIL_IEEE802154_SupportsG4ByteCrc (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4G-2012 reception and transmission of frames with 4-byte CRC.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4G 4-byte CRC is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_4BYTE_CRC.
7274 of file common/rail.hRAIL_IEEE802154_SupportsGDynFec#
bool RAIL_IEEE802154_SupportsGDynFec (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4G dynamic FEC.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if dynamic FEC is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_DYNFEC.
7285 of file common/rail.hRAIL_SupportsProtocolWiSUN#
bool RAIL_SupportsProtocolWiSUN (RAIL_Handle_t railHandle)
Indicate whether this chip supports Wi-SUN.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if Wi-SUN is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PROTOCOL_WI_SUN.
7296 of file common/rail.hRAIL_IEEE802154_SupportsGModeSwitch#
bool RAIL_IEEE802154_SupportsGModeSwitch (RAIL_Handle_t railHandle)
Indicate whether this chip supports Wi-SUN mode switching.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if Wi-SUN mode switching is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_MODESWITCH.
7307 of file common/rail.hRAIL_IEEE802154_SupportsGSubsetGB868#
bool RAIL_IEEE802154_SupportsGSubsetGB868 (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4G-2012 feature subset needed for Zigbee R22 GB868.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4G GB868 subset is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_SUBSET_GB868.
7319 of file common/rail.hRAIL_IEEE802154_SupportsGUnwhitenedRx#
bool RAIL_IEEE802154_SupportsGUnwhitenedRx (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4G-2012 reception of unwhitened frames.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4G unwhitened frame reception is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_UNWHITENED_RX.
7332 of file common/rail.hRAIL_IEEE802154_SupportsGUnwhitenedTx#
bool RAIL_IEEE802154_SupportsGUnwhitenedTx (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4G-2012 transmission of unwhitened frames.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if 802.15.4G unwhitened frame transmit is supported; false otherwise.
Runtime refinement of compile-time RAIL_IEEE802154_SUPPORTS_G_UNWHITENED_TX.
7345 of file common/rail.hRAIL_WMBUS_SupportsSimultaneousTCRx#
bool RAIL_WMBUS_SupportsSimultaneousTCRx (RAIL_Handle_t railHandle)
Indicate whether this chip supports WMBUS simultaneous M2O RX of T and C modes.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the WMBUS simultaneous M2O RX of T and C modes is supported; false otherwise.
Runtime refinement of compile-time RAIL_WMBUS_SUPPORTS_SIMULTANEOUS_T_C_RX.
7355 of file common/rail.hRAIL_SupportsProtocolZWave#
bool RAIL_SupportsProtocolZWave (RAIL_Handle_t railHandle)
Indicate whether this chip supports the Z-Wave protocol.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the Z-Wave protocol is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PROTOCOL_ZWAVE.
7365 of file common/rail.hRAIL_ZWAVE_SupportsConcPhy#
bool RAIL_ZWAVE_SupportsConcPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports the Z-Wave concurrent PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the Z-Wave concurrent PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_ZWAVE_SUPPORTS_CONC_PHY.
7375 of file common/rail.hRAIL_ZWAVE_SupportsEnergyDetectPhy#
bool RAIL_ZWAVE_SupportsEnergyDetectPhy (RAIL_Handle_t railHandle)
Indicate whether this chip supports the Z-Wave energy detect PHY.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if the Z-Wave energy detect PHY is supported; false otherwise.
Runtime refinement of compile-time RAIL_ZWAVE_SUPPORTS_ED_PHY.
7385 of file common/rail.hRAIL_ZWAVE_SupportsRegionPti#
bool RAIL_ZWAVE_SupportsRegionPti (RAIL_Handle_t railHandle)
Indicate whether this chip supports Z-Wave Region in PTI.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if ZWAVE Region in PTI is supported; false otherwise.
Runtime refinement of compile-time RAIL_ZWAVE_SUPPORTS_REGION_PTI.
7395 of file common/rail.hRAIL_IEEE802154_SupportsSignalIdentifier#
bool RAIL_IEEE802154_SupportsSignalIdentifier (RAIL_Handle_t railHandle)
Indicate whether this chip supports IEEE 802.15.4 signal identifier.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if signal identifier is supported; false otherwise.
7403 of file common/rail.hRAIL_SupportsFastRx2Rx#
bool RAIL_SupportsFastRx2Rx (RAIL_Handle_t railHandle)
Indicate whether this chip supports fast RX2RX.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if fast RX2RX is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_FAST_RX2RX.
7413 of file common/rail.hRAIL_SupportsCollisionDetection#
bool RAIL_SupportsCollisionDetection (RAIL_Handle_t railHandle)
Indicate whether this chip supports collision detection.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if collision detection is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_COLLISION_DETECTION.
7423 of file common/rail.hRAIL_SupportsProtocolSidewalk#
bool RAIL_SupportsProtocolSidewalk (RAIL_Handle_t railHandle)
Indicate whether this chip supports Sidewalk protocol.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if Sidewalk protocol is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_PROTOCOL_SIDEWALK.
7433 of file common/rail.hRAIL_SupportsAutoLnaBypass#
bool RAIL_SupportsAutoLnaBypass (RAIL_Handle_t railHandle)
Indicate whether this chip supports automatic LNA bypass for external FEM.
| [in] | railHandle | A radio-generic or real RAIL instance handle. |
Returns
true if automatic LNA bypass is supported; false otherwise.
Runtime refinement of compile-time RAIL_SUPPORTS_AUTO_LNA_BYPASS.
7443 of file common/rail.h