APIs to get information about received packets.

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

void	RAIL_GetRxIncomingPacketInfo ( RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t *pPacketInfo)
	Get information about the live incoming packet (if any).

static void	RAIL_CopyRxPacket (uint8_t pDest, const RAIL_RxPacketInfo_t pPacketInfo)
	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)
	Get detailed information about a received packet.

RAIL_Status_t	RAIL_GetRxPacketDetailsAlt ( RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, RAIL_RxPacketDetails_t *pPacketDetails)
	Get detailed information about a received packet.

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_GetRxTimePreambleStartAlt ( RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)
	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_GetRxTimeSyncWordEndAlt ( RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)
	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_Status_t	RAIL_GetRxTimeFrameEndAlt ( RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)
	Adjust a RAIL RX timestamp to refer to the end of frame.

Detailed Description

APIs to get information about received packets.

After receiving a packet, RAIL will trigger a RAIL_EVENT_RX_PACKET_RECEIVED event. At that point, there is a variety of information available to the application about the received packet. The following example code assumes that the RAIL_RX_OPTION_REMOVE_APPENDED_INFO is not used, and the application wants as much data about the packet as possible.

       
        // Get all information about a received packet.
       
        RAIL_Status_t
       
       status;
      
        RAIL_RxPacketInfo_t
       
       rxInfo;
      
        RAIL_RxPacketDetails_t
       
       rxDetails;
      
        RAIL_RxPacketHandle_t
       
       rxHandle
      
       =
       
        RAIL_GetRxPacketInfo
       
       (railHandle,
       
        RAIL_RX_PACKET_HANDLE_NEWEST
       
       , &rxInfo);
      
       assert(rxHandle !=
       
        RAIL_RX_PACKET_HANDLE_INVALID
       
       );
      
       status =
       
        RAIL_GetRxPacketDetailsAlt
       
       (railHandle, rxHandle, &rxDetails);
      
       assert(status ==
       
        RAIL_STATUS_NO_ERROR
       
       );
      
        if
       
       (rxDetails.
       
        timeReceived
       
       .
       
        timePosition
       
       ==
       
        RAIL_PACKET_TIME_INVALID
       
       ) {
      
        return
       
       ;
       
        // No timestamp available for this packet
       
       }
      
        // CRC_BYTES only needs to be added when not using RAIL_RX_OPTION_STORE_CRC
       
       rxDetails.
       
        timeReceived
       
       .
       
        totalPacketBytes
       
       = rxInfo.
       
        packetBytes
       
       + CRC_BYTES;
      
        // Choose the function which gives the desired timestamp
       
       status =
       
        RAIL_GetRxTimeFrameEndAlt
       
       (railHandle, &rxDetails);
      
       assert(status ==
       
        RAIL_STATUS_NO_ERROR
       
       );
      
        // Now all fields of rxInfo and rxDetails have been populated correctly

Function Documentation

◆ RAIL_CopyRxPacket()

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

inline static

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

Parameters

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

Note: This is a convenience helper function, which is intended to be expedient. As a result, it does not check the validity of its arguments, so don't pass either as NULL, and don't pass a pDest pointer to a buffer that's too small for the packet's data.; If only a portion of the packet is needed, use RAIL_PeekRxPacket() instead.

Definition at line 3004 of file rail.h .

◆ RAIL_GetRxIncomingPacketInfo()

void RAIL_GetRxIncomingPacketInfo	(	RAIL_Handle_t	`railHandle,`
		RAIL_RxPacketInfo_t *	`pPacketInfo`
	)

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

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.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[out]	`pPacketInfo`	Application provided pointer to store RAIL_RxPacketInfo_t for the incoming packet.

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.

◆ RAIL_GetRxPacketDetails()

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

Get detailed information about a received packet.

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

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`packetHandle`	A packet handle for the unreleased packet as returned from a previous call to RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() , or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST , RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST .
[in,out]	`pPacketDetails`	An application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived 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: Certain details are always available, while others are only available if the RAIL_RxOptions_t RAIL_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.

◆ RAIL_GetRxPacketDetailsAlt()

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

Get detailed information about a received packet.

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

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`packetHandle`	A packet handle for the unreleased packet as returned from a previous call to RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() , or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST .
[out]	`pPacketDetails`	An application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived field packetTime will be populated with a timestamp corresponding to a default location in the packet. The timeReceived field timePosition will be populated with a RAIL_PacketTimePosition_t value specifying that default packet location. Call RAIL_GetRxTimePreambleStart , RAIL_GetRxTimeSyncWordEnd , or RAIL_GetRxTimeFrameEnd to adjust that timestamp for different locations in the packet.

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

◆ RAIL_GetRxPacketInfo()

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

Get basic information about a pending or received packet.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`packetHandle`	A packet handle for the unreleased packet as returned from a previous call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST , RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST .
[out]	`pPacketInfo`	An application-provided pointer to store RAIL_RxPacketInfo_t for the requested packet. Must be non-NULL.

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

This function can be used in any RX mode. It does not free up any internal resources. If used in RX RAIL_DataMethod_t::FIFO_MODE , the value in RAIL_RxPacketInfo_t::packetBytes will only return the data remaining in the FIFO. Any data read via earlier 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.

◆ RAIL_GetRxTimeFrameEnd()

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

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

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.
[in,out]	`pPacketTime`	The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that this packet finished on air. Must be non-NULL.

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

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE . Note that this API may return incorrect timestamps when sub-phys are in use, as in the BLE Coded PHY. Prefer RAIL_GetRxTimeFrameEndAlt in those situations.

◆ RAIL_GetRxTimeFrameEndAlt()

RAIL_Status_t RAIL_GetRxTimeFrameEndAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_RxPacketDetails_t *	`pPacketDetails`
	)

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

Parameters

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

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

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

◆ RAIL_GetRxTimePreambleStart()

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

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

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.
[in,out]	`pPacketTime`	The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the preamble for this packet started on air. Must be non-NULL.

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

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE . Note that this API may return incorrect timestamps when sub-phys are in use, as in the BLE Coded PHY. Prefer RAIL_GetRxTimePreambleStartAlt in those situations.

◆ RAIL_GetRxTimePreambleStartAlt()

RAIL_Status_t RAIL_GetRxTimePreambleStartAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_RxPacketDetails_t *	`pPacketDetails`
	)

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

Parameters

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

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

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

◆ RAIL_GetRxTimeSyncWordEnd()

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

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

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`totalPacketBytes`	The total number of bytes of the received packet for RAIL to use when calculating the specified timestamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes.
[in,out]	`pPacketTime`	The time that was returned in the RAIL_PacketTimeStamp_t::packetTime field of RAIL_RxPacketDetails_t::timeReceived from a previous call to RAIL_GetRxPacketDetailsAlt for this same packet. After this function, the time at that location will be updated with the time that the sync word for this packet finished on air. Must be non-NULL.

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

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE . Note that this API may return incorrect timestamps when sub-phys are in use, as in the BLE Coded PHY. Prefer RAIL_GetRxTimeSyncWordEndAlt in those situations.

◆ RAIL_GetRxTimeSyncWordEndAlt()

RAIL_Status_t RAIL_GetRxTimeSyncWordEndAlt	(	RAIL_Handle_t	`railHandle,`
		RAIL_RxPacketDetails_t *	`pPacketDetails`
	)

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

Parameters

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

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

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

Packet Information RAIL API > Receive

Functions

Detailed Description

Function Documentation

◆ RAIL_CopyRxPacket()

◆ RAIL_GetRxIncomingPacketInfo()

◆ RAIL_GetRxPacketDetails()

◆ RAIL_GetRxPacketDetailsAlt()

◆ RAIL_GetRxPacketInfo()

◆ RAIL_GetRxTimeFrameEnd()

◆ RAIL_GetRxTimeFrameEndAlt()

◆ RAIL_GetRxTimePreambleStart()

◆ RAIL_GetRxTimePreambleStartAlt()

◆ RAIL_GetRxTimeSyncWordEnd()

◆ RAIL_GetRxTimeSyncWordEndAlt()

Packet Information
RAIL API > Receive