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

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

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.

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


Definition at line 3537 of file common/rail.h

RAIL_GetRxIncomingPacketInfo#

void RAIL_GetRxIncomingPacketInfo (RAIL_Handle_t railHandle, RAIL_RxPacketInfo_t *pPacketInfo)

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

Parameters
[in]railHandle

A RAIL instance handle.

[out]pPacketInfo

Application provided 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.

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.


Definition at line 3570 of file common/rail.h

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
[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 3592 of file common/rail.h

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
[in]railHandle

A RAIL instance handle.

[in]packetHandle

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

[inout]pPacketDetails

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

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

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

Returns

Note


Definition at line 3638 of file common/rail.h

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
[in]railHandle

A RAIL instance handle.

[in]packetHandle

A packet handle for the unreleased packet as returned from a previous call to RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket(), or sentinel values RAIL_RX_PACKET_HANDLE_OLDESTRAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE or RAIL_RX_PACKET_HANDLE_NEWEST.

[out]pPacketDetails

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.

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

Returns

This alternative API allows for smaller code size by deadstripping the timestamp adjustment algorithms which are not in use.

Note


Definition at line 3675 of file common/rail.h

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.

[inout]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. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 3702 of file common/rail.h

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.

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


Definition at line 3724 of file common/rail.h

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.

[inout]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. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 3750 of file common/rail.h

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.

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


Definition at line 3772 of file common/rail.h

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.

[inout]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. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.


Definition at line 3798 of file common/rail.h

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.

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


Definition at line 3820 of file common/rail.h