Receive

APIs related to packet receive.

Modules

Address Filtering
Configuration APIs for receive packet address filtering.

Data Structures

struct  RAIL_ScheduleRxConfig_t
 Configures the scheduled RX algorithm.
 
struct  RAIL_RxPacketInfo_t
 Basic information about a packet being received or already completed and awaiting processing, including memory pointers to its data in the circular RX FIFO buffer.
 
struct  RAIL_RxPacketDetails_t
 Successfully received packet details obtained via RAIL_GetRxPacketDetails().

Macros

#define RAIL_RX_OPTIONS_NONE   0
 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 configure whether the appended information is included after received frames.
 
#define RAIL_RX_OPTION_ANTENNA0   (1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)
 An option to select the use of antenna 0 when doing RX.
 
#define RAIL_RX_OPTION_ANTENNA1   (1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)
 An option to select the use of antenna 1 when doing RX.
 
#define RAIL_RX_OPTION_ANTENNA_AUTO   (RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)
 Am option to automatically choose an antenna.
 
#define RAIL_RX_OPTION_DISABLE_FRAME_DETECTION   (1UL << RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT)
 An option to disable frame detection.
 
#define RAIL_RX_OPTIONS_ALL   0xFFFFFFFFUL
 A value representing all possible options.
 
#define RAIL_RSSI_INVALID_DBM   (-128)
 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_RX_PACKET_HANDLE_INVALID   (NULL)
 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_NEWEST   ((RAIL_RxPacketHandle_t) 2)
 A special RX packet handle to refer to the newest unreleased packet when in callback context.

Typedefs

typedef const void * RAIL_RxPacketHandle_t
 A handle used to reference a packet during reception processing.

Enumerations

enum  RAIL_RxOptions_t {
  RAIL_RX_OPTION_STORE_CRC_SHIFT = 0,
  RAIL_RX_OPTION_IGNORE_CRC_ERRORS_SHIFT,
  RAIL_RX_OPTION_ENABLE_DUALSYNC_SHIFT,
  RAIL_RX_OPTION_TRACK_ABORTED_FRAMES_SHIFT,
  RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT,
  RAIL_RX_OPTION_ANTENNA0_SHIFT,
  RAIL_RX_OPTION_ANTENNA1_SHIFT,
  RAIL_RX_OPTION_DISABLE_FRAME_DETECTION_SHIFT
}
 Receive options, in reality a bitmask.
 
enum  RAIL_RxPacketStatus_t {
  RAIL_RX_PACKET_NONE = 0,
  RAIL_RX_PACKET_ABORT_FORMAT,
  RAIL_RX_PACKET_ABORT_FILTERED,
  RAIL_RX_PACKET_ABORT_ABORTED,
  RAIL_RX_PACKET_ABORT_OVERFLOW,
  RAIL_RX_PACKET_ABORT_CRC_ERROR,
  RAIL_RX_PACKET_READY_CRC_ERROR,
  RAIL_RX_PACKET_READY_SUCCESS,
  RAIL_RX_PACKET_RECEIVING
}
 The packet status code associated with a packet received or currently being received.

Functions

RAIL_Status_t RAIL_ConfigRxOptions (RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)
 Configures receive options.
 
RAIL_Status_t RAIL_StartRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_SchedulerInfo_t *schedulerInfo)
 Starts the receiver on a specific channel.
 
RAIL_Status_t RAIL_ScheduleRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_ScheduleRxConfig_t *cfg, const RAIL_SchedulerInfo_t *schedulerInfo)
 Schedules a receive window for some future time.
 
RAIL_RxPacketHandle_t RAIL_GetRxPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketInfo_t *pPacketInfo)
 Gets basic information about a pending or received packet.
 
static void RAIL_CopyRxPacket (uint8_t *pDest, const RAIL_RxPacketInfo_t *pPacketInfo)
 Convenience helper function to copy a full packet to a user-specified contiguous buffer.
 
RAIL_Status_t RAIL_GetRxPacketDetails (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)
 Gets detailed information about a ready packet received (one whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set).
 
RAIL_Status_t RAIL_GetRxPacketDetailsAlt (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)
 Get detailed information about a ready packet received (one whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set).
 
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.
 
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.
 
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.
 
RAIL_RxPacketHandle_t RAIL_HoldRxPacket (RAIL_Handle_t railHandle)
 Place a temporary hold on this packet's data and information resources within RAIL.
 
uint16_t RAIL_PeekRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, uint8_t *pDst, uint16_t len, uint16_t offset)
 Copies 'len' bytes of packet data starting from 'offset' from the receive FIFO.
 
RAIL_Status_t RAIL_ReleaseRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)
 Releases RAIL's internal resources for the packet.
 
int16_t RAIL_GetRssi (RAIL_Handle_t railHandle, bool wait)
 Returns the current raw RSSI.
 
RAIL_Status_t RAIL_StartAverageRssi (RAIL_Handle_t railHandle, uint16_t channel, RAIL_Time_t averagingTimeUs, const RAIL_SchedulerInfo_t *schedulerInfo)
 Starts the RSSI averaging over a specified time in us.
 
bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)
 Queries whether the RSSI averaging is done.
 
int16_t RAIL_GetAverageRssi (RAIL_Handle_t railHandle)
 Gets the RSSI averaged over a specified time in us.
 
RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)
 Sets the RSSI offset.
 
int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)
 Gets the RSSI offset.

Detailed Description

APIs related to packet receive.

Macro Definition Documentation

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

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

Definition at line 1787 of file rail_types.h.

#define RAIL_RSSI_INVALID_DBM   (-128)

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

Definition at line 1785 of file rail_types.h.

#define RAIL_RX_OPTION_ANTENNA0   (1UL << RAIL_RX_OPTION_ANTENNA0_SHIFT)

An option to select the use of antenna 0 when doing RX.

If no antenna option is selected, the RX may take place on either antenna depending on the last RX or TX configuration. Defaults to false. This option is only valid on platforms that support antenna selection.

Definition at line 1756 of file rail_types.h.

#define RAIL_RX_OPTION_ANTENNA1   (1UL << RAIL_RX_OPTION_ANTENNA1_SHIFT)

An option to select the use of antenna 1 when doing RX.

If no antenna option is selected, the RX may take place on either antenna depending on the last RX or TX configuration. Defaults to false. This option is only valid on platforms that support antenna selection.

Definition at line 1764 of file rail_types.h.

#define RAIL_RX_OPTION_ANTENNA_AUTO   (RAIL_RX_OPTION_ANTENNA0 | RAIL_RX_OPTION_ANTENNA1)

Am option to automatically choose an antenna.

If both antenna 0 and antenna 1 options are set, the chip will switch between antennas and will automatically choose one.

Definition at line 1771 of file rail_types.h.

#define RAIL_RX_OPTION_DISABLE_FRAME_DETECTION   (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 1779 of file rail_types.h.

#define RAIL_RX_OPTION_ENABLE_DUALSYNC   (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 SYNC0 only. Setting it to 1 causes the receiver to listen for either SYNC0 or SYNC1. 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. See the data sheet or support team for more details.

Definition at line 1735 of file rail_types.h.

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

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

Definition at line 1724 of file rail_types.h.

#define RAIL_RX_OPTION_REMOVE_APPENDED_INFO   (1UL << RAIL_RX_OPTION_REMOVE_APPENDED_INFO_SHIFT)

An option to configure whether the appended information is included after received frames.

Defaults to false.

Definition at line 1748 of file rail_types.h.

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

Defaults to false.

Definition at line 1718 of file rail_types.h.

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

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

Definition at line 1742 of file rail_types.h.

#define RAIL_RX_OPTIONS_ALL   0xFFFFFFFFUL

A value representing all possible options.

Definition at line 1782 of file rail_types.h.

#define RAIL_RX_OPTIONS_DEFAULT   RAIL_RX_OPTIONS_NONE

All options are disabled by default.

Definition at line 1711 of file rail_types.h.

#define RAIL_RX_OPTIONS_NONE   0

A value representing no options enabled.

Definition at line 1709 of file rail_types.h.

#define RAIL_RX_PACKET_HANDLE_INVALID   (NULL)

An invalid RX packet handle value.

Definition at line 1879 of file rail_types.h.

#define RAIL_RX_PACKET_HANDLE_NEWEST   ((RAIL_RxPacketHandle_t) 2)

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 1889 of file rail_types.h.

#define RAIL_RX_PACKET_HANDLE_OLDEST   ((RAIL_RxPacketHandle_t) 1)

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

Definition at line 1881 of file rail_types.h.

Typedef Documentation

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 and RAIL_RX_PACKET_HANDLE_NEWEST.

Definition at line 1876 of file rail_types.h.

Enumeration Type Documentation

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.

Definition at line 1689 of file rail_types.h.

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.
In RX FIFO mode, ABORT statuses imply some packet data may be available, but it's incomplete and not trustworthy.
READY statuses indicate all packet data is available, including packet details (if enabled), but only RAIL_RX_PACKET_READY_SUCCESS indicates the packet data is trustworthy.
Enumerator
RAIL_RX_PACKET_NONE 

The radio is idle or searching for a packet.

RAIL_RX_PACKET_ABORT_FORMAT 

A format/length error.

RAIL_RX_PACKET_ABORT_FILTERED 

A filtering error (address).

RAIL_RX_PACKET_ABORT_ABORTED 

An aborted error.

RAIL_RX_PACKET_ABORT_OVERFLOW 

The receive buffer overflowed.

RAIL_RX_PACKET_ABORT_CRC_ERROR 

A CRC error aborted.

RAIL_RX_PACKET_READY_CRC_ERROR 

A CRC error accepted (details available).

RAIL_RX_PACKET_READY_SUCCESS 

Success (details available).

RAIL_RX_PACKET_RECEIVING 

Receiving in progress.

Definition at line 1857 of file rail_types.h.

Function Documentation

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

Configures receive options.

Parameters
[in]railHandleA RAIL instance handle.
[in]maskA bitmask containing which options should be modified.
[in]optionsA 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.

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

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

Convenience helper function to copy a full packet to a user-specified contiguous buffer.

Parameters
[out]pDestAn 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 Rx FIFO buffer. Exactly pPacketInfo->packetBytes of packet data will be written into it.
[out]pPacketInfoRAIL_RxPacketInfo_t for the requested packet.
Returns
void.
Note
This helper is intended to be expedient. As a result, it does not check the validity of its arguments, so don't pass either as NULL, and don't pass a pDest pointer to a buffer that's too small for the packet's data.
If only a portion of the packet is needed, use RAIL_PeekRxPacket() instead.

Definition at line 2139 of file rail.h.

References RAIL_RxPacketInfo_t::firstPortionBytes, RAIL_RxPacketInfo_t::firstPortionData, RAIL_RxPacketInfo_t::lastPortionData, RAIL_RxPacketInfo_t::packetBytes, RAIL_Calibrate(), RAIL_CancelAutoAck(), RAIL_ConfigAddressFilter(), RAIL_ConfigAutoAck(), RAIL_ConfigCal(), RAIL_ConfigVerification(), RAIL_EnableAddressFilter(), RAIL_EnableAddressFilterAddress(), RAIL_EnableDirectMode(), RAIL_EnablePaCal(), RAIL_GetAverageRssi(), RAIL_GetPendingCal(), RAIL_GetRssi(), RAIL_GetRssiOffset(), RAIL_GetRxFreqOffset(), RAIL_GetRxPacketDetails(), RAIL_GetRxPacketDetailsAlt(), RAIL_GetRxTimeFrameEnd(), RAIL_GetRxTimePreambleStart(), RAIL_GetRxTimeSyncWordEnd(), RAIL_GetSchedulerStatus(), RAIL_GetTune(), RAIL_HoldRxPacket(), RAIL_IsAddressFilterEnabled(), RAIL_IsAutoAckEnabled(), RAIL_IsAutoAckWaitingForAck(), RAIL_IsAverageRssiReady(), RAIL_IsRfSensed(), RAIL_IsRxAutoAckPaused(), RAIL_IsTxAutoAckPaused(), RAIL_PauseRxAutoAck(), RAIL_PauseTxAutoAck(), RAIL_PeekRxPacket(), RAIL_ReleaseRxPacket(), RAIL_ResetAddressFilter(), RAIL_SetAddressFilterAddress(), RAIL_SetFreqOffset(), RAIL_SetRssiOffset(), RAIL_SetTaskPriority(), RAIL_SetTune(), RAIL_StartAverageRssi(), RAIL_StartRfSense(), RAIL_StartTxStream(), RAIL_StopTxStream(), RAIL_UseTxFifoForAutoAck(), RAIL_Verify(), RAIL_WriteAutoAckFifo(), RAIL_YieldRadio(), and RAILCb_AssertFailed().

int16_t RAIL_GetAverageRssi ( RAIL_Handle_t  railHandle)

Gets the RSSI averaged over a specified time in us.

Parameters
[in]railHandleA RAIL instance handle.
Returns
Return RAIL_RSSI_INVALID if the receiver is disabled an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm,dbm*4.

Gets the hardware RSSI average after issuing RAIL_StartAverageRssi. It should be used after RAIL_StartAverageRssi.

Referenced by RAIL_CopyRxPacket().

int16_t RAIL_GetRssi ( RAIL_Handle_t  railHandle,
bool  wait 
)

Returns the current raw RSSI.

Parameters
[in]railHandleA RAIL instance handle.
[in]waitif 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. Users should characterize the RSSI received on their hardware and apply an offset in the application to account for board and PHY parameters. 'Wait' argument doesn't guarantee a valid RSSI reading.'Wait' being true gives assurance that that the RSSI is current and not a stale value from a previous radio state. If GetRssi is called during RX-to-RX, RX-to-IDLE, or RX-to-TX transition, the RSSI is considered stale and RAIL_RSSI_INVALID is returned if wait=true. 'Wait' being false will return either the current RSSI or a stale RSSI measurement (if called during RX-to-RX, RX-to-IDLE, or RX-to-TX transition). RAIL_RSSI_INVALID is returned if radio hasn't been in RX longer than 'idleToRx' time (see RAIL_StateTiming_t), regardless of wait argument.

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.

Referenced by RAIL_CopyRxPacket().

int8_t RAIL_GetRssiOffset ( RAIL_Handle_t  railHandle)

Gets the RSSI offset.

Parameters
[in]railHandlea RAIL instance handle.
Returns
rssiOffset in dBm corresponding to the current handle.

Referenced by RAIL_CopyRxPacket().

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

Gets detailed information about a ready packet received (one whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set).

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

Parameters
[in]railHandleA RAIL instance handle.
[in]packetHandleA 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 or RAIL_RX_PACKET_HANDLE_NEWEST.
[in,out]pPacketDetailsAn application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. The timeReceived fields totalPacketBytes and timePosition must be initialized prior to each call:
  • totalPacketBytes with the total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.
  • timePosition with a RAIL_PacketTimePosition_t value specifying the packet position to put in the timeReceived field on return. This field will also be updated with the actual position corresponding to the timeReceived value filled in.
Returns
RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.
Note
Consider using RAIL_GetRxPacketDetailsAlt for smaller code size.

Referenced by RAIL_CopyRxPacket().

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

Get detailed information about a ready packet received (one whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set).

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

Parameters
[in]railHandleA RAIL instance handle.
[in]packetHandleA 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 or RAIL_RX_PACKET_HANDLE_NEWEST.
[out]pPacketDetailsAn application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. The timeReceived field packetTime will be populated with a timestamp corresponding to an arbitrary location in the packet. Call RAIL_GetRxTimePreambleStart, RAIL_GetRxTimeSyncWordEnd, or RAIL_GetRxTimeFrameEnd to adjust that timestamp for different locations in the packet.
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.

Referenced by RAIL_CopyRxPacket().

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

Gets basic information about a pending or received packet.

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

Parameters
[in]railHandleA RAIL instance handle.
[in]packetHandleA packet handle for the unreleased packet as returned from a previous call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST or RAIL_RX_PACKET_HANDLE_NEWEST.
[out]pPacketInfoAn application-provided pointer to store RAIL_RxPacketInfo_t for the requested packet. Must be non-NULL.
Returns
The packet handle for the requested packet: if packetHandle was one of the sentinel values, returns the actual packet handle for that packet, otherwise returns packetHandle. It may return RAIL_RX_PACKET_HANDLE_INVALID to indicate an error.
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, cancelled, 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.
RAIL_Status_t RAIL_GetRxTimeFrameEnd ( RAIL_Handle_t  railHandle,
uint16_t  totalPacketBytes,
RAIL_Time_t pPacketTime 
)

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

Parameters
[in]railHandleA RAIL instance handle.
[in]totalPacketBytesThe 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.
[in,out]pPacketTimeThe 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.

This API must be called while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.

Referenced by RAIL_CopyRxPacket().

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

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

Parameters
[in]railHandleA RAIL instance handle.
[in]totalPacketBytesThe 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.
[in,out]pPacketTimeThe 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.

This API must be called while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.

Referenced by RAIL_CopyRxPacket().

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

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

Parameters
[in]railHandleA RAIL instance handle.
[in]totalPacketBytesThe 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.
[in,out]pPacketTimeThe 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.

This API must be called while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE.

Referenced by RAIL_CopyRxPacket().

RAIL_RxPacketHandle_t RAIL_HoldRxPacket ( RAIL_Handle_t  railHandle)

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

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

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

Parameters
[in]railHandleA RAIL instance handle.
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.

Referenced by RAIL_CopyRxPacket().

bool RAIL_IsAverageRssiReady ( RAIL_Handle_t  railHandle)

Queries whether the RSSI averaging is done.

Parameters
[in]railHandleA RAIL instance handle.
Returns
Returns true if done and false otherwise.

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

Referenced by RAIL_CopyRxPacket().

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

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

Those bytes remain valid for re-peeking.

Parameters
[in]railHandleA RAIL instance handle.
[in]packetHandleA packet handle as returned from a previous RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST or RAIL_RX_PACKET_HANDLE_NEWEST.
[out]pDstA pointer to the location where the received bytes will be copied. If NULL, no copying occurs.
[in]lenA number of packet data bytes to copy.
[in]offsetA byte offset within remaining packet data from which to copy.
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().

Referenced by RAIL_CopyRxPacket().

RAIL_Status_t RAIL_ReleaseRxPacket ( RAIL_Handle_t  railHandle,
RAIL_RxPacketHandle_t  packetHandle 
)

Releases RAIL's internal resources for the packet.

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.

Parameters
[in]railHandleA RAIL instance handle.
[in]packetHandleA packet handle as returned from a previous RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST 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).
Returns
RAIL_STATUS_NO_ERROR if the held packet was released or an appropriate error code otherwise.

Referenced by RAIL_CopyRxPacket().

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

Schedules a receive window for some future time.

Parameters
[in]railHandleA RAIL instance handle.
[in]channelA channel to listen on.
[in]cfgThe configuration structure to define the receive window.
[in]schedulerInfoInformation 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, aborts any ongoing packet transmission or reception.

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

RAIL_Status_t RAIL_SetRssiOffset ( RAIL_Handle_t  railHandle,
int8_t  rssiOffset 
)

Sets the RSSI offset.

Parameters
[in]railHandlea RAIL instance handle.
[in]rssiOffsetdesired offset to be added to the RSSI measurements.
Returns
Status code indicating success of the function call.

Adds an offset to the RSSI in dBm. This offset affects all functionality that depends on RSSI values, such as CCA fuctions. The offset should not be modified dynamically during the RX of a packet.

Referenced by RAIL_CopyRxPacket().

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

Starts the RSSI averaging over a specified time in us.

Parameters
[in]railHandleA RAIL instance handle.
[in]channelThe physical channel to set.
[in]averagingTimeUsAveraging time in microseconds.
[in]schedulerInfoInformation 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).

Referenced by RAIL_CopyRxPacket().

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

Starts the receiver on a specific channel.

Parameters
[in]railHandleA RAIL instance handle.
[in]channelThe channel to listen on.
[in]schedulerInfoInformation 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.