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 | 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.
3797 of file common/rail.hRAIL_GetRxIncomingPacketInfo#
RAIL_Status_t 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 | 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.
3831 of file common/rail.hRAIL_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 | 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. |
| [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.
3853 of file common/rail.hRAIL_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 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_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.
3899 of file common/rail.hRAIL_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 | 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 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 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 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.
This function should be called soon (no more than a minute) after packet reception for the packet timestamp information to be valid.
3939 of file common/rail.hRAIL_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 | 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 timestamps when sub-phys are in use. Prefer RAIL_GetRxTimePreambleStartAlt in those situations. See RAIL_RxPacketDetails_t::subPhyId for more details.
3966 of file common/rail.hRAIL_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 | 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 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.
3988 of file common/rail.hRAIL_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 | 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.
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.
4014 of file common/rail.hRAIL_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 | 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 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.
4036 of file common/rail.hRAIL_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 | 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.
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.
4062 of file common/rail.hRAIL_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 | 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 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.
4084 of file common/rail.h