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#
Get basic information about a pending or received packet.
Get information about the live incoming packet (if any).
Copy a full packet to a user-specified contiguous buffer.
Get detailed information about a received packet.
Get detailed information about a received packet.
Adjust a RAIL RX timestamp to refer to the start of the preamble.
Adjust a RAIL RX timestamp to refer to the start of the preamble.
Adjust a RAIL RX timestamp to refer to the end of the sync word.
Adjust a RAIL RX timestamp to refer to the end of the sync word.
Adjust a RAIL RX timestamp to refer to the end of frame.
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.
[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.
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).
[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.
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.
[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.
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.
[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:
|
This function can be used in any RX mode; it does not free up any internal 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_tRAIL_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.
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.
[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
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_tRAIL_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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
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.
[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.
3820
of file common/rail.h