Packet Information#

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 time stamp 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 time stamp
status = RAIL_GetRxTimeFrameEndAlt(railHandle, &rxDetails);
assert(status == RAIL_STATUS_NO_ERROR);
// Now all fields of rxInfo and rxDetails have been populated correctly

After receiving a packet, RAIL will trigger a SL_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 SL_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.
sl_rail_status_t status;
sl_rail_rx_packet_info_t rx_info;
sl_rail_rx_packet_details_t rx_details;
sl_rail_rx_packet_handle_t rx_handle
  = sl_rail_get_rx_packet_info(rail_handle, SL_RAIL_RX_PACKET_HANDLE_NEWEST, &rx_info);
assert(rx_handle != SL_RAIL_RX_PACKET_HANDLE_INVALID);
status = sl_rail_get_rx_packet_details(rail_handle, rx_handle, &rx_details);
assert(status == SL_RAIL_STATUS_NO_ERROR);
if (rx_details.time_received.time_position == SL_RAIL_PACKET_TIME_INVALID) {
  return; // No time stamp available for this packet
}
// CRC_BYTES only needs to be added when not using SL_RAIL_RX_OPTION_STORE_CRC
rx_details.time_received.total_packet_bytes = rx_info.packet_bytes + CRC_BYTES;
// Choose the function which gives the desired time stamp
status = sl_rail_get_rx_time_frame_end(rail_handle, &rx_details);
assert(status == SL_RAIL_STATUS_NO_ERROR);
// Now all fields of rx_info and rx_details have been populated correctly

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.

RAIL_Status_t

RAIL_GetRxIncomingPacketInfo(RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t *pPacketInfo)

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

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 time stamp 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 time stamp 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 time stamp 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 time stamp 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 time stamp to refer to the end of frame.

RAIL_Status_t

RAIL_GetRxTimeFrameEndAlt(RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t *pPacketDetails)

Adjust a RAIL RX time stamp to refer to the end of frame.

sl_rail_rx_packet_handle_t

sl_rail_get_rx_packet_info(sl_rail_handle_t rail_handle, sl_rail_rx_packet_handle_t packet_handle, sl_rail_rx_packet_info_t *p_packet_info)

Get basic information about a pending or received packet.

sl_rail_status_t

sl_rail_get_rx_incoming_packet_info(sl_rail_handle_t rail_handle, sl_rail_rx_packet_info_t *p_packet_info)

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

sl_rail_status_t

sl_rail_abort_rx_incoming_packet(sl_rail_handle_t rail_handle)

Abort an incoming packet actively being received.

sl_rail_status_t

sl_rail_copy_rx_packet(sl_rail_handle_t rail_handle, uint8_t *p_dest, const sl_rail_rx_packet_info_t *p_packet_info)

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

sl_rail_status_t

sl_rail_get_rx_packet_details(sl_rail_handle_t rail_handle, sl_rail_rx_packet_handle_t packet_handle, sl_rail_rx_packet_details_t *p_packet_details)

Get detailed information about a received packet.

sl_rail_status_t

sl_rail_get_rx_time_preamble_start(sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t *p_packet_details)

Adjust a RAIL RX time stamp to refer to the start of the preamble.

sl_rail_status_t

sl_rail_get_rx_time_sync_word_end(sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t *p_packet_details)

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

sl_rail_status_t

sl_rail_get_rx_time_frame_end(sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t *p_packet_details)

Adjust a RAIL RX time stamp to refer to the end of frame.

Function Documentation#

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

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketHandle_t	[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.
RAIL_RxPacketInfo_t *	[out]	pPacketInfo	A non-NULL pointer to a RAIL_RxPacketInfo_t to store info for the requested packet.

Returns

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

This function can be used in any RX mode. It does not free any receive FIFO or internal receive resources. If used in receive RAIL_DataMethod_t::FIFO_MODE, the value in RAIL_RxPacketInfo_t::packetBytes will only return the data remaining in the FIFO. Any data read via earlier calls to RAIL_ReadRxFifo() is not included.

Note

When getting information about an arriving packet that is not yet complete, (i.e., pPacketInfo->packetStatus == RAIL_RX_PACKET_RECEIVING), keep in mind its data is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_packet_info().

RAIL_GetRxIncomingPacketInfo#

RAIL_Status_t RAIL_GetRxIncomingPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t * pPacketInfo)

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

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketInfo_t *	[out]	pPacketInfo	A non-NULL pointer to store RAIL_RxPacketInfo_t for the incoming packet.

Differs from RAIL_GetRxPacketInfo() by only returning information about a packet actively being received, something which even the RAIL_RX_PACKET_HANDLE_NEWEST may not represent if there are completed but unprocessed packets in the receive FIFO.

Returns

Status code indicating success of the function call.

This function can only be called from callback context, e.g., when handling RAIL_EVENT_RX_FILTER_PASSED or RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND. It must not be used with receive RAIL_DataMethod_t::FIFO_MODE if any portion of an incoming packet has already been extracted from the receive FIFO.

Note

The incomplete data of an arriving packet is highly suspect because it has not yet passed any CRC integrity checking. Also note that the packet could be aborted, canceled, or fail momentarily, invalidating its data in Packet mode. Furthermore, there is a small chance towards the end of packet reception that the filled-in RAIL_RxPacketInfo_t could include not only packet data received so far, but also some raw radio-appended info detail bytes that RAIL's packet-completion processing will subsequently deal with. It's up to the application to know its packet format well enough to avoid confusing such info as packet data.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_incoming_packet_info().

RAIL_CopyRxPacket#

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

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

Parameters

Type	Direction	Argument Name	Description
uint8_t *	[out]	pDest	A non-NULL application-provided pointer to a buffer of at least pPacketInfo->packetBytes in size to store the packet data contiguously. This buffer must never overlay RAIL's receive FIFO buffer. Exactly pPacketInfo->packetBytes of packet data will be written into it.
const RAIL_RxPacketInfo_t *	[in]	pPacketInfo	A non-NULL pointer to the RAIL_RxPacketInfo_t for the requested packet.

Note

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

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_copy_rx_packet() with an additional sl_rail_handle_t parameter.

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.

Parameters

Type Direction Argument Name Description

RAIL_Handle_t

[in]

railHandle

A RAIL instance handle.

RAIL_RxPacketHandle_t

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

RAIL_RxPacketDetails_t *

[inout]

pPacketDetails

An application-provided non-NULL pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived fields totalPacketBytes and timePosition must be initialized prior to each call:

totalPacketBytes with the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. 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.

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

Returns

RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

Note

Certain details are always available, while others are only available if the RAIL_RxOptions_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.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_rx_packet_details() with different parameter semantics - the last parameter is solely an output parameter where any time-received time position passed in is ignored.

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.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketHandle_t	[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.
RAIL_RxPacketDetails_t *	[out]	pPacketDetails	A non-NULL application-provided pointer to store RAIL_RxPacketDetails_t for the requested packet. For RAIL_RxPacketStatus_t RAIL_RX_PACKET_READY_ packets, the timeReceived field packetTime will be populated with a time stamp 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 time stamp for different locations in the packet.

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

Returns

RAIL_STATUS_NO_ERROR if pPacketDetails was filled in, or an appropriate error code otherwise.

This alternative API allows for smaller code size by deadstripping the time stamp 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.
This function should be called soon (no more than a minute) after packet reception for the packet time stamp information to be valid.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_packet_details().

RAIL_GetRxTimePreambleStart#

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

Adjust a RAIL RX time stamp to refer to the start of the preamble.

Parameters

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

Returns

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

Call this API while the given railHandle is active, or it will return an error code of RAIL_STATUS_INVALID_STATE. Note that this API may return incorrect time stamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_rx_time_preamble_start() with different parameters.

RAIL_GetRxTimePreambleStartAlt#

RAIL_Status_t RAIL_GetRxTimePreambleStartAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Adjust a RAIL RX time stamp to refer to the start of the preamble.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketDetails_t *	[inout]	pPacketDetails	A non-NULL pointer to the details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt() for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. 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.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_time_preamble_start().

RAIL_GetRxTimeSyncWordEnd#

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

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

Parameters

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

Returns

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

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_rx_time_sync_word_end() with different parameters.

RAIL_GetRxTimeSyncWordEndAlt#

RAIL_Status_t RAIL_GetRxTimeSyncWordEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

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

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketDetails_t *	[inout]	pPacketDetails	A non-NULL pointer to the details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt() for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. 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.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_time_sync_word_end().

RAIL_GetRxTimeFrameEnd#

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

Adjust a RAIL RX time stamp to refer to the end of frame.

Parameters

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

Returns

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

DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_rx_time_frame_end() with different parameters.

RAIL_GetRxTimeFrameEndAlt#

RAIL_Status_t RAIL_GetRxTimeFrameEndAlt (RAIL_Handle_t railHandle, RAIL_RxPacketDetails_t * pPacketDetails)

Adjust a RAIL RX time stamp to refer to the end of frame.

Parameters

Type	Direction	Argument Name	Description
RAIL_Handle_t	[in]	railHandle	A RAIL instance handle.
RAIL_RxPacketDetails_t *	[inout]	pPacketDetails	A non-NULL pointer to the details that were returned from a previous call to RAIL_GetRxPacketDetailsAlt() for this same packet. The application must update the timeReceived field totalPacketBytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. 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.

DeprecatedRAIL 2.x synonym of sl_rail_get_rx_time_frame_end().

sl_rail_get_rx_packet_info#

sl_rail_rx_packet_handle_t sl_rail_get_rx_packet_info (sl_rail_handle_t rail_handle, sl_rail_rx_packet_handle_t packet_handle, sl_rail_rx_packet_info_t * p_packet_info)

Get basic information about a pending or received packet.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_handle_t	[in]	packet_handle	A packet handle for the unreleased packet as returned from a previous call, or sentinel values SL_RAIL_RX_PACKET_HANDLE_OLDEST, SL_RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or SL_RAIL_RX_PACKET_HANDLE_NEWEST.
sl_rail_rx_packet_info_t *	[out]	p_packet_info	A non-NULL pointer to a sl_rail_rx_packet_info_t to store info for the requested packet.

Returns

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

This function can be used in any RX mode. It does not free any receive FIFO or receive Packet Queue resources. If used in receive sl_rail_data_method_t::SL_RAIL_DATA_METHOD_FIFO_MODE, the value in sl_rail_rx_packet_info_t::packet_bytes will only return the data remaining in the FIFO. Any data read via earlier calls to sl_rail_read_rx_fifo() is not included.

Note

When getting information about an arriving packet that is not yet complete, (i.e., p_packet_info->packet_status == SL_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 sl_rail_rx_packet_info_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.

sl_rail_get_rx_incoming_packet_info#

sl_rail_status_t sl_rail_get_rx_incoming_packet_info (sl_rail_handle_t rail_handle, sl_rail_rx_packet_info_t * p_packet_info)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_info_t *	[out]	p_packet_info	A non-NULL pointer to store sl_rail_rx_packet_info_t for the incoming packet.

Differs from sl_rail_get_rx_packet_info() by only returning information about a packet actively being received, something which even the SL_RAIL_RX_PACKET_HANDLE_NEWEST may not represent if there are completed but unprocessed packets in the receive FIFO.

Returns

Status code indicating success of the function call.

This function can only be called from callback context, e.g., when handling SL_RAIL_EVENT_RX_FILTER_PASSED or SL_RAIL_EVENT_IEEE802154_DATA_REQUEST_COMMAND. It must not be used with receive sl_rail_data_method_t::SL_RAIL_DATA_METHOD_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 sl_rail_rx_packet_info_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.

sl_rail_abort_rx_incoming_packet#

sl_rail_status_t sl_rail_abort_rx_incoming_packet (sl_rail_handle_t rail_handle)

Abort an incoming packet actively being received.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.

Returns

Status code indicating success of the function call. SL_RAIL_STATUS_INVALID_STATE would be returned when the radio is not actively receiving a packet or when the inactive protocol. It may be possible that SL_RAIL_STATUS_NO_ERROR will be returned yet the abort attempt was too late to actually abort the packet.

If an incoming packet does get aborted, RAIL will issue SL_RAIL_EVENT_RX_PACKET_ABORTED and the radio would respect the current SL_RAIL_RX_OPTION_TRACK_ABORTED_FRAMES setting and follow the current RX sl_rail_state_transitions_t::error state transition.

sl_rail_copy_rx_packet#

sl_rail_status_t sl_rail_copy_rx_packet (sl_rail_handle_t rail_handle, uint8_t * p_dest, const sl_rail_rx_packet_info_t * p_packet_info)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
uint8_t *	[out]	p_dest	A non-NULL application-provided pointer to a buffer of at least p_packet_info->packet_bytes in size to store the packet data contiguously. This buffer must never overlay RAIL's receive FIFO buffer. Exactly p_packet_info->packet_bytes of packet data will be written into it.
const sl_rail_rx_packet_info_t *	[in]	p_packet_info	A non-NULL pointer to the sl_rail_rx_packet_info_t for the requested packet.

Returns

Status code indicating success of the function call.

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 p_dest pointer to a buffer that's too small for the packet's data.
If only a portion of the packet is needed, use sl_rail_peek_rx_packet() instead.

sl_rail_get_rx_packet_details#

sl_rail_status_t sl_rail_get_rx_packet_details (sl_rail_handle_t rail_handle, sl_rail_rx_packet_handle_t packet_handle, sl_rail_rx_packet_details_t * p_packet_details)

Get detailed information about a received packet.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_handle_t	[in]	packet_handle	A packet handle for the unreleased packet as returned from a previous call to sl_rail_get_rx_packet_info() or sl_rail_hold_rx_packet(), or sentinel values SL_RAIL_RX_PACKET_HANDLE_OLDEST SL_RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or SL_RAIL_RX_PACKET_HANDLE_NEWEST.
sl_rail_rx_packet_details_t *	[out]	p_packet_details	A non-NULL application-provided pointer to store sl_rail_rx_packet_details_t for the requested packet. For sl_rail_rx_packet_status_t SL_RAIL_RX_PACKET_READY_ packets, the time_received field packet_time will be populated with a time stamp corresponding to a default location in the packet. The time_received field time_position will be populated with a sl_rail_packet_time_position_t value specifying that default packet location. Call sl_rail_get_rx_time_preamble_start(), sl_rail_get_rx_time_sync_word_end(), or sl_rail_get_rx_time_frame_end() to adjust that time stamp for different locations in the packet.

This function can be used in any RX mode; it does not free any receive FIFO or receive Packet Queue resources.

Returns

SL_RAIL_STATUS_NO_ERROR if p_packet_details was filled in, or an appropriate error code otherwise.

Note

Certain details are always available, while others are only available if the sl_rail_rx_options_t SL_RAIL_RX_OPTION_REMOVE_APPENDED_INFO option is not in effect and the received packet's sl_rail_rx_packet_status_t is among the SL_RAIL_RX_PACKET_READY_ set. See sl_rail_rx_packet_details_t for clarification.
This function should be called soon (no more than a minute) after packet reception for the packet time stamp information to be valid.

sl_rail_get_rx_time_preamble_start#

sl_rail_status_t sl_rail_get_rx_time_preamble_start (sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t * p_packet_details)

Adjust a RAIL RX time stamp to refer to the start of the preamble.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_details_t *	[inout]	p_packet_details	A non-NULL pointer to the details that were returned from a previous call to sl_rail_get_rx_packet_details() for this same packet. The application must update the time_received field total_packet_bytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the time_received field packet_time will be updated with the time that the preamble for this packet started on air.

Returns

SL_RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

sl_rail_get_rx_time_sync_word_end#

sl_rail_status_t sl_rail_get_rx_time_sync_word_end (sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t * p_packet_details)

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

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_details_t *	[inout]	p_packet_details	A non-NULL pointer to the details that were returned from a previous call to sl_rail_get_rx_packet_details() for this same packet. The application must update the time_received field total_packet_bytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the time_received field packet_time will be updated with the time that the sync word for this packet finished on air.

Returns

SL_RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.

sl_rail_get_rx_time_frame_end#

sl_rail_status_t sl_rail_get_rx_time_frame_end (sl_rail_handle_t rail_handle, sl_rail_rx_packet_details_t * p_packet_details)

Adjust a RAIL RX time stamp to refer to the end of frame.

Parameters

Type	Direction	Argument Name	Description
sl_rail_handle_t	[in]	rail_handle	A real RAIL instance handle.
sl_rail_rx_packet_details_t *	[inout]	p_packet_details	A non-NULL pointer to the details that were returned from a previous call to sl_rail_get_rx_packet_details() for this same packet. The application must update the time_received field total_packet_bytes to be the total number of bytes of the received packet for RAIL to use when calculating the specified time stamp. This should account for all bytes received over the air after the Preamble and Sync word(s), including CRC bytes. After this function, the time_received field packet_time will be updated with the time that the packet finished on air.

Returns

SL_RAIL_STATUS_NO_ERROR if the packet time was successfully calculated, or an appropriate error code otherwise.