Receive#

APIs related to packet receive.

Modules#

RAIL_ScheduleRxConfig_t

RAIL_RxPacketInfo_t

RAIL_RxPacketDetails_t

Address Filtering

Packet Information

Enumerations#

enum
RAIL_RX_OPTION_STORE_CRC_SHIFT = 0
RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT = 1
RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT = 2
RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT = 3
RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT = 4
RAIL_RX_OPTION_ANTENNA0_SHIFT = 5
RAIL_RX_OPTION_ANTENNA1_SHIFT = 6
RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT = 7
RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT = 10
RAIL_RX_OPTION_FAST_RX2RX_SHIFT = 11
RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT = 12
}

Receive options, in reality a bitmask.

enum
RAIL_RX_PACKET_NONE = 0
RAIL_RX_PACKET_ABORT_FORMAT = 1
RAIL_RX_PACKET_ABORT_FILTERED = 2
RAIL_RX_PACKET_ABORT_ABORTED = 3
RAIL_RX_PACKET_ABORT_OVERFLOW = 4
RAIL_RX_PACKET_ABORT_CRC_ERROR = 5
RAIL_RX_PACKET_READY_CRC_ERROR = 6
RAIL_RX_PACKET_READY_SUCCESS = 7
RAIL_RX_PACKET_RECEIVING = 8
}

The packet status code associated with a packet received or currently being received.

Typedefs#

typedef const void *

A handle used to reference a packet during reception processing.

typedef uint8_t(*
RAIL_ConvertLqiCallback_t)(uint8_t lqi, int8_t rssi)

A pointer to a function called before LQI is copied into the RAIL_RxPacketDetails_t structure.

Functions#

RAIL_ConfigRxOptions(RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)

Configure receive options.

RAIL_IncludeFrameTypeLength(RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

void
RAILCb_ConfigFrameTypeLength(RAIL_Handle_t railHandle, const RAIL_FrameType_t *frameType)

Handle frame type length.

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

Start the receiver on a specific channel.

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

Schedule a receive window for some future time.

RAIL_HoldRxPacket(RAIL_Handle_t railHandle)

Place a temporary hold on this packet's data in the receive FIFO and internal packet metadata FIFO.

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

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

RAIL_ReleaseRxPacket(RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)

Release RAIL's resources for the packet previously held in the receive FIFO and internal receive metadata FIFO.

int16_t
RAIL_GetRssi(RAIL_Handle_t railHandle, bool wait)

Return the current raw RSSI.

int16_t
RAIL_GetRssiAlt(RAIL_Handle_t railHandle, RAIL_Time_t waitTimeout)

Return the current raw RSSI in quarter-dBm within a definitive time period.

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

Start the RSSI averaging over a specified time in us.

bool
RAIL_IsAverageRssiReady(RAIL_Handle_t railHandle)

Query whether the RSSI averaging is done.

int16_t
RAIL_GetAverageRssi(RAIL_Handle_t railHandle)

Get the RSSI in quarter-dBm averaged over a specified time in microseconds.

RAIL_SetRssiOffset(RAIL_Handle_t railHandle, int8_t rssiOffset)

Set the RSSI offset.

int8_t
RAIL_GetRssiOffset(RAIL_Handle_t railHandle)

Get the radio or protocol RSSI offset in dB.

RAIL_SetRssiDetectThreshold(RAIL_Handle_t railHandle, int8_t rssiThresholdDbm)

Set the RSSI detection threshold in dBm to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.

int8_t
RAIL_GetRssiDetectThreshold(RAIL_Handle_t railHandle)

Get the RSSI detection threshold in dBm.

RAIL_ConvertLqi(RAIL_Handle_t railHandle, RAIL_ConvertLqiCallback_t cb)

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

Macros#

#define

A value representing no options enabled.

#define
RAIL_RX_OPTIONS_DEFAULT RAIL_RX_OPTIONS_NONE

All options are disabled by default.

#define
RAIL_RX_OPTION_STORE_CRC (1UL << RAIL_RX_OPTION_STORE_CRC_SHIFT)

An option to configure whether the CRC portion of the packet is included in the packet payload exposed to the app on packet reception.

#define
RAIL_RX_OPTION_IGNORE_CRC_ERRORS (1UL << RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT)

An option to configure whether CRC errors will be ignored.

#define
RAIL_RX_OPTION_ENABLE_DUALSYNC (1UL << RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT)

An option to control which sync words will be accepted.

#define
RAIL_RX_OPTION_TRACK_ABORTED_FRAMES (1UL << RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT)

An option to configure whether frames which are aborted during reception should continue to be tracked.

#define
RAIL_RX_OPTION_REMOVE_APPENDED_INFO (1UL << RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT)

An option to suppress capturing the appended information after received frames.

#define
RAIL_RX_OPTION_ANTENNA0 (1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)

An option to select the use of antenna 0 during receive (including Auto-ACK receive).

#define
RAIL_RX_OPTION_ANTENNA1 (1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)

An option to select the use of antenna 1 during receive (including Auto-ACK receive).

#define
RAIL_RX_OPTION_ANTENNA_AUTO (RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)

An option combination to automatically choose an antenna during receive (including Auto-ACK receive).

#define
RAIL_RX_OPTION_DISABLE_FRAME_DETECTION (1UL << RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT)

An option to disable frame detection.

#define
RAIL_RX_OPTION_CHANNEL_SWITCHING (1U << RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT)

An option to enable IEEE 802.15.4 RX channel switching.

#define
RAIL_RX_OPTION_FAST_RX2RX (1U << RAIL_RX_OPTION_FAST_RX2RX_SHIFT)

An option to enable fast RX2RX state transition.

#define
RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION (1U << RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT)

An option to enable collision detection.

#define
RAIL_RX_OPTIONS_ALL 0xFFFFFFFFUL

A value representing all possible options.

#define

The value returned by RAIL for an invalid RSSI, in dBm.

#define
RAIL_RSSI_INVALID ((int16_t)(RAIL_RSSI_INVALID_DBM * 4))

The value returned by RAIL for an invalid RSSI: in quarter dBm.

#define
RAIL_RSSI_LOWEST ((int16_t)(RAIL_RSSI_INVALID + 1))

The lowest RSSI value returned by RAIL: in quarter dBm.

#define

Maximum absolute value for RSSI offset.

#define
RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT ((RAIL_Time_t)0xFFFFFFFFU)

A sentinel value to indicate waiting for a valid RSSI without a timeout.

#define
RAIL_GET_RSSI_NO_WAIT ((RAIL_Time_t)0U)

A sentinel value to indicate no waiting for a valid RSSI.

#define

An invalid RX packet handle value.

#define
RAIL_RX_PACKET_HANDLE_OLDEST ((RAIL_RxPacketHandle_t) 1)

A special RX packet handle to refer to the oldest unreleased packet.

#define
RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE ((RAIL_RxPacketHandle_t) 2)

A special RX packet handle to refer to the oldest unreleased complete packet.

#define
RAIL_RX_PACKET_HANDLE_NEWEST ((RAIL_RxPacketHandle_t) 3)

A special RX packet handle to refer to the newest unreleased packet when in callback context.

Enumeration Documentation#

RAIL_RxOptions_t#

RAIL_RxOptions_t

Receive options, in reality a bitmask.

Enumerator
RAIL_RX_OPTION_STORE_CRC_SHIFT

Shift position of RAIL_RX_OPTION_STORE_CRC bit.

RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT

Shift position of RAIL_RX_OPTION_IGNORE_CRC_ERRORS bit.

RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT

Shift position of RAIL_RX_OPTION_ENABLE_DUALSYNC bit.

RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT

Shift position of RAIL_RX_OPTION_TRACK_ABORTED_FRAMES bit.

RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT

Shift position of RAIL_RX_OPTION_REMOVE_APPENDED_INFO bit.

RAIL_RX_OPTION_ANTENNA0_SHIFT

Shift position of RAIL_RX_OPTION_ANTENNA0 bit.

RAIL_RX_OPTION_ANTENNA1_SHIFT

Shift position of RAIL_RX_OPTION_ANTENNA1 bit.

RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT

Shift position of RAIL_RX_OPTION_DISABLE_FRAME_DETECTION bit.

RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT

Shift position of RAIL_RX_OPTION_CHANNEL_SWITCHING bit.

RAIL_RX_OPTION_FAST_RX2RX_SHIFT

Shift position of RAIL_RX_OPTION_FAST_RX2RX bit.

RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT

Shift position of RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION bit.


Definition at line 3779 of file common/rail_types.h

RAIL_RxPacketStatus_t#

RAIL_RxPacketStatus_t

The packet status code associated with a packet received or currently being received.

Note

  • RECEIVING implies some packet data may be available, but is untrustworthy (not CRC-verified) and might disappear if the packet is rolled back on error. No packet details are yet available.

  • In RX RAIL_DataMethod_t::FIFO_MODE, ABORT statuses imply some packet data may be available, but it's incomplete and not trustworthy.

Enumerator
RAIL_RX_PACKET_NONE

The radio is idle or searching for a packet.

RAIL_RX_PACKET_ABORT_FORMAT

The packet was aborted during filtering because of illegal frame length, CRC or block decoding errors, other RAIL built-in protocol-specific packet content errors, or by the application or multiprotocol scheduler idling the radio with RAIL_IDLE_ABORT or higher.

RAIL_RX_PACKET_ABORT_FILTERED

The packet failed address filtering.

RAIL_RX_PACKET_ABORT_ABORTED

The packet passed any filtering but was aborted by the application or multiprotocol scheduler idling the radio with RAIL_IDLE_ABORT or higher.

RAIL_RX_PACKET_ABORT_OVERFLOW

The packet overflowed the receive buffer.

RAIL_RX_PACKET_ABORT_CRC_ERROR

The packet passed any filtering but subsequently failed CRC check(s) block decoding, or illegal frame length, and was aborted.

RAIL_RX_PACKET_READY_CRC_ERROR

The packet passed any filtering but subsequently failed CRC check(s) with RAIL_RX_OPTION_IGNORE_CRC_ERRORS in effect.

RAIL_RX_PACKET_READY_SUCCESS

The packet was successfully received, passing CRC check(s).

RAIL_RX_PACKET_RECEIVING

A packet is being received and is not yet complete.


Definition at line 4068 of file common/rail_types.h

Typedef Documentation#

RAIL_RxPacketHandle_t#

RAIL_RxPacketHandle_t

A handle used to reference a packet during reception processing.

There are several sentinel handle values that pertain to certain circumstances: RAIL_RX_PACKET_HANDLE_INVALID, RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE and RAIL_RX_PACKET_HANDLE_NEWEST.


Definition at line 4153 of file common/rail_types.h

RAIL_ConvertLqiCallback_t#

RAIL_ConvertLqiCallback_t )(uint8_t lqi, int8_t rssi)

A pointer to a function called before LQI is copied into the RAIL_RxPacketDetails_t structure.

Parameters
[in]lqi

The LQI value obtained by hardware and being readied for application consumption. This LQI value is in integral units ranging from 0 to 255.

[in]rssi

The RSSI value corresponding to the packet from which the hardware LQI value was obtained. This RSSI value is in integral dBm units.

Returns

  • uint8_t The converted LQI value that will be loaded into the RAIL_RxPacketDetails_t structure in preparation for application consumption. This value should likewise be in integral units ranging from 0 to 255.


Definition at line 4369 of file common/rail_types.h

Function Documentation#

RAIL_ConfigRxOptions#

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

Configure receive options.

Parameters
[in]railHandle

A RAIL instance handle.

[in]mask

A bitmask containing which options should be modified.

[in]options

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

Returns

  • Status code indicating success of the function call.

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


Definition at line 3621 of file common/rail.h

RAIL_IncludeFrameTypeLength#

RAIL_Status_t RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

Parameters
[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.


Definition at line 3637 of file common/rail.h

RAILCb_ConfigFrameTypeLength#

void RAILCb_ConfigFrameTypeLength (RAIL_Handle_t railHandle, const RAIL_FrameType_t *frameType)

Handle frame type length.

Parameters
[in]railHandle

A RAIL instance handle.

[in]frameType

A 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.


Definition at line 3652 of file common/rail.h

RAIL_StartRx#

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

Start the receiver on a specific channel.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The channel to listen on.

[in]schedulerInfo

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.


Definition at line 3670 of file common/rail.h

RAIL_ScheduleRx#

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

Schedule a receive window for some future time.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

A channel to listen on.

[in]cfg

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.


Definition at line 3699 of file common/rail.h

RAIL_HoldRxPacket#

RAIL_RxPacketHandle_t RAIL_HoldRxPacket (RAIL_Handle_t railHandle)

Place a temporary hold on this packet's data in the receive FIFO and internal packet metadata FIFO.

Parameters
[in]railHandle

A RAIL instance handle.

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

Normally, when RAIL issues its callback indicating a packet is ready or aborted, it expects the application's callback to retrieve and copy (or discard) the packet's information and data, and will free 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.


Definition at line 4093 of file common/rail.h

RAIL_PeekRxPacket#

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

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

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

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

[out]pDst

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

[in]len

A number of packet data bytes to copy.

[in]offset

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

Those bytes remain valid for re-peeking.

Returns

  • Number of packet bytes copied.

Note

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


Definition at line 4119 of file common/rail.h

RAIL_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.

Parameters
[in]railHandle

A RAIL instance handle.

[in]packetHandle

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

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

Returns


Definition at line 4148 of file common/rail.h

RAIL_GetRssi#

int16_t RAIL_GetRssi (RAIL_Handle_t railHandle, bool wait)

Return the current raw RSSI.

Parameters
[in]railHandle

A RAIL instance handle.

[in]wait

if false returns instant RSSI with no checks.

Returns

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

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

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

Note


Definition at line 4194 of file common/rail.h

RAIL_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.

Parameters
[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


Definition at line 4240 of file common/rail.h

RAIL_StartAverageRssi#

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

Start the RSSI averaging over a specified time in us.

Parameters
[in]railHandle

A RAIL instance handle.

[in]channel

The physical channel to set.

[in]averagingTimeUs

Averaging time in microseconds.

[in]schedulerInfo

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


Definition at line 4273 of file common/rail.h

RAIL_IsAverageRssiReady#

bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)

Query whether the RSSI averaging is done.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if done and false otherwise.

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

Note

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


Definition at line 4290 of file common/rail.h

RAIL_GetAverageRssi#

int16_t RAIL_GetAverageRssi (RAIL_Handle_t railHandle)

Get the RSSI in quarter-dBm averaged over a specified time in microseconds.

Parameters
[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.


Definition at line 4302 of file common/rail.h

RAIL_SetRssiOffset#

RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)

Set the RSSI offset.

Parameters
[in]railHandle

A radio-generic or real RAIL instance handle.

[in]rssiOffset

desired dB offset to be added to the RSSI measurements.

Returns

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

Note


Definition at line 4336 of file common/rail.h

RAIL_GetRssiOffset#

int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)

Get the radio or protocol RSSI offset in dB.

Parameters
[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.


Definition at line 4349 of file common/rail.h

RAIL_SetRssiDetectThreshold#

RAIL_Status_t RAIL_SetRssiDetectThreshold (RAIL_Handle_t railHandle, int8_t rssiThresholdDbm)

Set the RSSI detection threshold in dBm to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.

Parameters
[in]railHandle

A RAIL instance handle.

[in]rssiThresholdDbm

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

Returns

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

Note

This function is only available on EFR32 Series 2 Sub-GHz parts EFR32XG23 and EFR32XG25.


Definition at line 4378 of file common/rail.h

RAIL_GetRssiDetectThreshold#

int8_t RAIL_GetRssiDetectThreshold (RAIL_Handle_t railHandle)

Get the RSSI detection threshold in dBm.

Parameters
[in]railHandle

a RAIL instance handle.

Returns

  • The RSSI threshold in dBm corresponding to the railHandle.

Note

This function is only available on EFR32 Series 2 Sub-GHz parts EFR32XG23 and EFR32XG25.


Definition at line 4394 of file common/rail.h

RAIL_ConvertLqi#

RAIL_Status_t RAIL_ConvertLqi (RAIL_Handle_t railHandle, RAIL_ConvertLqiCallback_t cb)

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

Parameters
[in]railHandle

A RAIL instance handle.

[in]cb

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

Returns

  • Status code indicating success of the function call.


Definition at line 4406 of file common/rail.h

Macro Definition Documentation#

RAIL_RX_OPTIONS_NONE#

#define RAIL_RX_OPTIONS_NONE
Value:
0

A value representing no options enabled.


Definition at line 3811 of file common/rail_types.h

RAIL_RX_OPTIONS_DEFAULT#

#define RAIL_RX_OPTIONS_DEFAULT
Value:
RAIL_RX_OPTIONS_NONE

All options are disabled by default.


Definition at line 3813 of file common/rail_types.h

RAIL_RX_OPTION_STORE_CRC#

#define RAIL_RX_OPTION_STORE_CRC
Value:
(1UL << RAIL_RX_OPTION_STORE_CRC_SHIFT)

An option to configure whether the CRC portion of the packet is included in the packet payload exposed to the app on packet reception.

Defaults to false.


Definition at line 3820 of file common/rail_types.h

RAIL_RX_OPTION_IGNORE_CRC_ERRORS#

#define RAIL_RX_OPTION_IGNORE_CRC_ERRORS
Value:
(1UL << RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT)

An option to configure whether CRC errors will be ignored.

If this is set, RX will still be successful, even if the CRC does not pass the check. Defaults to false.

Note


Definition at line 3831 of file common/rail_types.h

RAIL_RX_OPTION_ENABLE_DUALSYNC#

#define RAIL_RX_OPTION_ENABLE_DUALSYNC
Value:
(1UL << RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT)

An option to control which sync words will be accepted.

Setting it to 0 (default) will cause the receiver to listen for SYNC1 only. Setting it to 1 causes the receiver to listen for either SYNC1 or SYNC2. RX appended info will contain which sync word was detected. Note, this only affects which sync word(s) are received, but not what each of the sync words actually are. This feature may not be available on some combinations of chips, PHYs, and protocols. Use the compile time symbol RAIL_SUPPORTS_DUAL_SYNC_WORDS or the runtime call RAIL_SupportsDualSyncWords() to check whether the platform supports this feature. Also, DUALSYNC may be incompatible with certain radio configurations. In these cases, setting this bit will be ignored. See the data sheet or support team for more details.


Definition at line 3846 of file common/rail_types.h

RAIL_RX_OPTION_TRACK_ABORTED_FRAMES#

#define RAIL_RX_OPTION_TRACK_ABORTED_FRAMES
Value:
(1UL << RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT)

An option to configure whether frames which are aborted during reception should continue to be tracked.

Setting this option allows viewing Packet Trace information for frames which get discarded. Defaults to false.

This option is ignored when doing a RAIL_IDLE_FORCE_SHUTDOWN or RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS.

Note

  • This option should not be used with coded PHYs since packet data received after the abort will not be decoded properly.


Definition at line 3859 of file common/rail_types.h

RAIL_RX_OPTION_REMOVE_APPENDED_INFO#

#define RAIL_RX_OPTION_REMOVE_APPENDED_INFO
Value:
(1UL << RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT)

An option to suppress capturing the appended information after received frames.

Defaults to false. When suppressed, certain RAIL_RxPacketDetails_t details will not be available for received packets whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set.

Warnings


Definition at line 3873 of file common/rail_types.h

RAIL_RX_OPTION_ANTENNA0#

#define RAIL_RX_OPTION_ANTENNA0
Value:
(1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)

An option to select the use of antenna 0 during receive (including Auto-ACK receive).

If no antenna option is selected, the packet will be received on the last antenna used for receive or transmit. Defaults to false. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna().


Definition at line 3882 of file common/rail_types.h

RAIL_RX_OPTION_ANTENNA1#

#define RAIL_RX_OPTION_ANTENNA1
Value:
(1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)

An option to select the use of antenna 1 during receive (including Auto-ACK receive).

If no antenna option is selected, the packet will be received on the last antenna used for receive or transmit. Defaults to false. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna().


Definition at line 3891 of file common/rail_types.h

RAIL_RX_OPTION_ANTENNA_AUTO#

#define RAIL_RX_OPTION_ANTENNA_AUTO
Value:
(RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)

An option combination to automatically choose an antenna during receive (including Auto-ACK receive).

If both antenna 0 and antenna 1 options are set, the radio will dynamically switch between antennas during packet detection and choose the best one for completing the reception. This option is only valid when the antenna diversity field is properly configured via Simplicity Studio. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna().


Definition at line 3903 of file common/rail_types.h

RAIL_RX_OPTION_DISABLE_FRAME_DETECTION#

#define RAIL_RX_OPTION_DISABLE_FRAME_DETECTION
Value:
(1UL << RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT)

An option to disable frame detection.

This can be useful for doing energy detection without risking packet reception. Enabling this will abort any frame currently being received in addition to preventing further frames from being received. Defaults to false.


Definition at line 3911 of file common/rail_types.h

RAIL_RX_OPTION_CHANNEL_SWITCHING#

#define RAIL_RX_OPTION_CHANNEL_SWITCHING
Value:
(1U << RAIL_RX_OPTION_CHANNEL_SWITCHING_SHIFT)

An option to enable IEEE 802.15.4 RX channel switching.

See RAIL_IEEE802154_ConfigRxChannelSwitching() for more information. Defaults to false.

Note


Definition at line 3945 of file common/rail_types.h

RAIL_RX_OPTION_FAST_RX2RX#

#define RAIL_RX_OPTION_FAST_RX2RX
Value:
(1U << RAIL_RX_OPTION_FAST_RX2RX_SHIFT)

An option to enable fast RX2RX state transition.

Once enabled, the sequencer will send the radio to RXSEARCH and get ready to receive the next packet while still processing the previous one. This will reduce RX to RX state transition time but risks impacting receive capability.

Note


Definition at line 3957 of file common/rail_types.h

RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION#

#define RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION
Value:
(1U << RAIL_RX_OPTION_ENABLE_COLLISION_DETECTION_SHIFT)

An option to enable collision detection.

Once enabled, when a collision with a strong enough packet is detected, the demod will stop the current packet decoding and try to detect the preamble of the incoming packet.

Note


Definition at line 3969 of file common/rail_types.h

RAIL_RX_OPTIONS_ALL#

#define RAIL_RX_OPTIONS_ALL
Value:
0xFFFFFFFFUL

A value representing all possible options.


Definition at line 3972 of file common/rail_types.h

RAIL_RSSI_INVALID_DBM#

#define RAIL_RSSI_INVALID_DBM
Value:
(-128)

The value returned by RAIL for an invalid RSSI, in dBm.


Definition at line 3975 of file common/rail_types.h

RAIL_RSSI_INVALID#

#define RAIL_RSSI_INVALID
Value:
((int16_t)(RAIL_RSSI_INVALID_DBM * 4))

The value returned by RAIL for an invalid RSSI: in quarter dBm.


Definition at line 3977 of file common/rail_types.h

RAIL_RSSI_LOWEST#

#define RAIL_RSSI_LOWEST
Value:
((int16_t)(RAIL_RSSI_INVALID + 1))

The lowest RSSI value returned by RAIL: in quarter dBm.


Definition at line 3979 of file common/rail_types.h

RAIL_RSSI_OFFSET_MAX#

#define RAIL_RSSI_OFFSET_MAX
Value:
35

Maximum absolute value for RSSI offset.


Definition at line 3982 of file common/rail_types.h

RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT#

#define RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT
Value:
((RAIL_Time_t)0xFFFFFFFFU)

A sentinel value to indicate waiting for a valid RSSI without a timeout.


Definition at line 3985 of file common/rail_types.h

RAIL_GET_RSSI_NO_WAIT#

#define RAIL_GET_RSSI_NO_WAIT
Value:
((RAIL_Time_t)0U)

A sentinel value to indicate no waiting for a valid RSSI.


Definition at line 3987 of file common/rail_types.h

RAIL_RX_PACKET_HANDLE_INVALID#

#define RAIL_RX_PACKET_HANDLE_INVALID
Value:
(NULL)

An invalid RX packet handle value.


Definition at line 4156 of file common/rail_types.h

RAIL_RX_PACKET_HANDLE_OLDEST#

#define RAIL_RX_PACKET_HANDLE_OLDEST
Value:
((RAIL_RxPacketHandle_t) 1)

A special RX packet handle to refer to the oldest unreleased packet.

This includes the newest unread packet which is possibly incomplete or not yet started. This handle is used implicitly by RAIL_ReadRxFifo().


Definition at line 4163 of file common/rail_types.h

RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE#

#define RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE
Value:
((RAIL_RxPacketHandle_t) 2)

A special RX packet handle to refer to the oldest unreleased complete packet.

This never includes incomplete or unstarted packets. (Using RAIL_RX_PACKET_HANDLE_OLDEST is inappropriate for this purpose because it can refer to an unstarted, incomplete, or unheld packet which are inappropriate to be consumed by the application.)


Definition at line 4171 of file common/rail_types.h

RAIL_RX_PACKET_HANDLE_NEWEST#

#define RAIL_RX_PACKET_HANDLE_NEWEST
Value:
((RAIL_RxPacketHandle_t) 3)

A special RX packet handle to refer to the newest unreleased packet when in callback context.

For a callback involving a completed receive event, this refers to the packet just completed. For other callback events, this refers to the next packet to be completed, which might be in-progress or might not have even started yet.


Definition at line 4180 of file common/rail_types.h