Receive#

RAIL_RxOptions_t#

RAIL_RxOptions_t

Receive options, in reality a bitmask.

RAIL_RxPacketStatus_t#

RAIL_RxPacketStatus_t

The packet status code associated with a packet received or currently being received.

Note

• RECEIVING implies some packet data may be available, but is untrustworthy (not CRC-verified) and might disappear if the packet is rolled back on error. No packet details are yet available.

• In RX RAIL_DataMethod_t::FIFO_MODE, ABORT statuses imply some packet data may be available, but it's incomplete and not trustworthy.

RAIL_RxPacketHandle_t#

RAIL_RxPacketHandle_t

A handle used to reference a packet during reception processing.

There are several sentinel handle values that pertain to certain circumstances: RAIL_RX_PACKET_HANDLE_INVALID, RAIL_RX_PACKET_HANDLE_OLDEST, RAIL_RX_PACKET_HANDLE_OLDEST_COMPLETE and RAIL_RX_PACKET_HANDLE_NEWEST.

RAIL_ConvertLqiCallback_t#

RAIL_ConvertLqiCallback_t )(uint8_t lqi, int8_t rssi)

A pointer to a function called before LQI is copied into the RAIL_RxPacketDetails_t structure.

Returns

• uint8_t The converted LQI value that will be loaded into the RAIL_RxPacketDetails_t structure in preparation for application consumption. This value should likewise be in integral units ranging from 0 to 255.

RAIL_ConfigRxOptions#

RAIL_Status_t RAIL_ConfigRxOptions (RAIL_Handle_t railHandle, RAIL_RxOptions_t mask, RAIL_RxOptions_t options)

Configure receive options.

Returns

• Status code indicating success of the function call.

Configure the radio receive flow based on the list of available options. Only the options indicated by the mask parameter will be affected. Pass RAIL_RX_OPTIONS_ALL to set all parameters. The previous settings may affect the current frame if a packet is received during this configuration.

Note

• : On chips where RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING is true, enabling RAIL_RX_OPTION_CHANNEL_SWITCHING without configuring RX channel switching, via RAIL_IEEE802154_ConfigRxChannelSwitching, will return RAIL_STATUS_INVALID_PARAMETER for only this option. Any other RX options (except antenna selection) would still take effect.

RAIL_IncludeFrameTypeLength#

void RAIL_IncludeFrameTypeLength (RAIL_Handle_t railHandle)

Include the code necessary for frame type based length decoding.

This function must be called before RAIL_ConfigChannels to allow configurations using a frame type based length setup. In RAIL 2.x, it is called by default in the RAILCb_ConfigFrameTypeLength API which can be overridden to save code space. In future versions, the user may be required to call this API explicitly.

RAILCb_ConfigFrameTypeLength#

void RAILCb_ConfigFrameTypeLength (RAIL_Handle_t railHandle, const RAIL_FrameType_t * frameType)

Handle frame type length.

This function is implemented in the radio configuration. Currently, the frame type passed in only handles packet length decoding. If NULL is passed into this function, it clears any currently configured frame type settings. This will either be implemented as an empty function in the radio configuration if it is not needed, to assist in dead code elimination.

RAIL_StartRx#

RAIL_Status_t RAIL_StartRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_SchedulerInfo_t * schedulerInfo)

Start the receiver on a specific channel.

Returns

• Status code indicating success of the function call.

This is a non-blocking function. Whenever a packet is received, RAIL_Config_t::eventsCallback will fire with RAIL_EVENT_RX_PACKET_RECEIVED set. If you call this while not idle but with a different channel, any ongoing receive or transmit operation will be aborted.

RAIL_ScheduleRx#

RAIL_Status_t RAIL_ScheduleRx (RAIL_Handle_t railHandle, uint16_t channel, const RAIL_ScheduleRxConfig_t * cfg, const RAIL_SchedulerInfo_t * schedulerInfo)

Schedule a receive window for some future time.

Returns

• Status code indicating success of the function call.

This API immediately changes the channel and schedules receive to start at the specified time and end at the given end time. If you do not specify an end time, you may call this API later with an end time as long as you set the start time to disabled. You can also terminate the receive operation immediately using the RAIL_Idle() function. Note that relative end times are always relative to the start unless no start time is specified. If changing channels, the channel is changed immediately and will abort any ongoing packet transmission or reception.

Returns an error if a CSMA or LBT transmit is still in progress.

In multiprotocol, ensure that you properly yield the radio after this call. See Yielding the Radio for more details.

RAIL_HoldRxPacket#

RAIL_RxPacketHandle_t RAIL_HoldRxPacket (RAIL_Handle_t railHandle)

Place a temporary hold on this packet's data and information resources within RAIL.

This function can only be called from within RAIL callback context. It can be used in any RX mode.

Normally, when RAIL issues its callback indicating a packet is ready or aborted, it expects the application's callback to retrieve and copy (or discard) the packet's information and data, and will free up its internal packet data after the callback returns. This function tells RAIL to hold onto those resources after the callback returns in case the application wants to defer processing the packet to a later time, e.g., outside of callback context.

Returns

• The packet handle for the packet associated with the callback, RAIL_RX_PACKET_HANDLE_INVALID if no such packet yet exists or railHandle is not active.

Note

• When using multiprotocol the receive FIFO is reset during protocol switches so any packets held with RAIL_HoldRxPacket() will be lost. It is best to avoid using this in DMP or to at least reset any internal held packet information when the RAIL_EVENT_CONFIG_UNSCHEDULED occurs.

RAIL_PeekRxPacket#

uint16_t RAIL_PeekRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle, uint8_t * pDst, uint16_t len, uint16_t offset)

Copy 'len' bytes of packet data starting from 'offset' from the receive FIFO.

Those bytes remain valid for re-peeking.

Returns

• Number of packet bytes copied.

Note

• Peek does not permit peeking beyond the requested packet's available packet data (though there is a small chance it might for a RAIL_RX_PACKET_HANDLE_NEWEST packet at the very end of still being received). Nor can one peek into already-consumed data read by RAIL_ReadRxFifo(). len and offset are relative to the remaining data available in the packet, if any was already consumed by RAIL_ReadRxFifo().

RAIL_ReleaseRxPacket#

RAIL_Status_t RAIL_ReleaseRxPacket (RAIL_Handle_t railHandle, RAIL_RxPacketHandle_t packetHandle)

Release RAIL's internal resources for the packet.

This function must be called for any packet previously held via RAIL_HoldRxPacket(). It may optionally be called within a callback context to release RAIL resources sooner than at callback completion time when not holding the packet. This function can be used in any RX mode.

Returns

• RAIL_STATUS_NO_ERROR if the held packet was released or an appropriate error code otherwise.

RAIL_GetRssi#

int16_t RAIL_GetRssi (RAIL_Handle_t railHandle, bool wait)

Return the current raw RSSI.

Returns

• RAIL_RSSI_INVALID if the receiver is disabled and an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm, dbm*4.

Gets the current RSSI value. This value represents the current energy of the channel. It can change rapidly and will be low if no RF energy is in the current channel. The function from the value reported to dBm is an offset dependent on the PHY and the PCB layout. Characterize the RSSI received on your hardware and apply an offset in the application to account for board and PHY parameters. When 'wait' is false, the radio needs to be currently in RX and have been in there for a sufficient amount of time for a fresh RSSI value to be read and returned. Otherwise, the RSSI is considered stale and RAIL_RSSI_INVALID is returned instead. When 'wait' is true, if the radio is transitioning to or already in RX, this function will wait for a valid RSSI to be read and return it. Otherwise, if the radio is in or transitions to IDLE or TX, RAIL_RSSI_INVALID will be returned. On low datarate PHYs, this function can take a significantly longer time when wait is true.

In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t. Additionally, 'wait' should never be set 'true' in multiprotocol as the wait time is not consistent, so scheduling a scheduler slot cannot be done accurately. Rather if waiting for a valid RSSI is desired, use RAIL_GetRssiAlt instead to apply a bounded time period.

Note

• If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), pass true for the wait parameter otherwise it's very likely RAIL_RSSI_INVALID will be returned.

• If RX channel hopping is turned on, do not use this API. Instead, see RAIL_GetChannelHoppingRssi().

• When 'wait' is false, this API is equivalent to RAIL_GetRssiAlt with 'waitTimeout' set to RAIL_GET_RSSI_NO_WAIT. When 'wait' is true, this API is equivalent to RAIL_GetRssiAlt with 'waitTimeout' set to RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT. Consider using RAIL_GetRssiAlt if a bounded maximum wait timeout is desired.

RAIL_GetRssiAlt#

int16_t RAIL_GetRssiAlt (RAIL_Handle_t railHandle, RAIL_Time_t waitTimeout)

Return the current raw RSSI within a definitive time period.

Returns

• RAIL_RSSI_INVALID if the receiver is disabled and an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm, dbm*4.

Gets the current RSSI value. This value represents the current energy of the channel. It can change rapidly, and will be low if no RF energy is in the current channel. The function from the value reported to dBm is an offset dependent on the PHY and the PCB layout. Characterize the RSSI received on your hardware and apply an offset in the application to account for board and PHY parameters. If a value of RAIL_GET_RSSI_NO_WAIT is given for waitTimeout, the radio needs to be currently in RX and have been in there for a sufficient amount of time for a fresh RSSI value to be read and returned. Otherwise the RSSI is considered stale and RAIL_RSSI_INVALID is returned instead. For non-zero values of waitTimeout, if the radio is transitioning to or already in RX, this function will wait a maximum time equal to waitTimeout (or indefinitely if waitTimeout is set to RAIL_GET_RSSI_WAIT_WITHOUT_TIMEOUT) for a valid RSSI to be read and return it. Otherwise, if the waitTimeout is reached, or the radio is in or transitions to IDLE or TX, RAIL_RSSI_INVALID will be returned. On low datarate PHYs, this function can take a significantly longer time when waitTimeout is non-zero.

In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t. Additionally, 'waitTimeout' should never be set to a value other than RAIL_GET_RSSI_NO_WAIT in multiprotocol as the integration between this feature and the radio scheduler has not been implemented.

Note

• If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), pass true for the wait parameter otherwise it's very likely RAIL_RSSI_INVALID will be returned.

• If RX Antenna Diversity is enabled via RAIL_ConfigRxOptions(), the RSSI value returned could come from either antenna and vary between antennas.

• If RX channel hopping is turned on, do not use this API. Instead, see RAIL_GetChannelHoppingRssi().

RAIL_StartAverageRssi#

RAIL_Status_t RAIL_StartAverageRssi (RAIL_Handle_t railHandle, uint16_t channel, RAIL_Time_t averagingTimeUs, const RAIL_SchedulerInfo_t * schedulerInfo)

Start the RSSI averaging over a specified time in us.

Returns

• Status code indicating success of the function call.

Starts a non-blocking hardware-based RSSI averaging mechanism. Only a single instance of RSSI averaging can be run at any time and the radio must be idle to start.

In multiprotocol, this is a scheduled event. It will start when railHandle becomes active. railHandle needs to stay active until the averaging completes. If the averaging is interrupted, calls to RAIL_GetAverageRssi will return RAIL_RSSI_INVALID.

Also in multiprotocol, the user is required to call RAIL_YieldRadio after this event completes (i.e., when RAIL_EVENT_RSSI_AVERAGE_DONE occurs).

Note

• If the radio is idled while RSSI averaging is still in effect, a RAIL_EVENT_RSSI_AVERAGE_DONE event may not occur and RAIL_IsAverageRssiReady may never return true.

RAIL_IsAverageRssiReady#

bool RAIL_IsAverageRssiReady (RAIL_Handle_t railHandle)

Query whether the RSSI averaging is done.

Returns

• Returns true if done and false otherwise.

This function can be used to poll for completion of the RSSI averaging to avoid relying on an interrupt-based callback.

Note

• If the radio is idled while RSSI averaging is still in effect, this function may never return true.

RAIL_GetAverageRssi#

int16_t RAIL_GetAverageRssi (RAIL_Handle_t railHandle)

Get the RSSI averaged over a specified time in us.

Returns

• Return RAIL_RSSI_INVALID if the receiver is disabled an RSSI value can't be obtained. Otherwise, return the RSSI in quarter dBm,dbm*4.

Gets the hardware RSSI average after issuing RAIL_StartAverageRssi. Use after RAIL_StartAverageRssi.

RAIL_SetRssiOffset#

RAIL_Status_t RAIL_SetRssiOffset (RAIL_Handle_t railHandle, int8_t rssiOffset)

Set the RSSI offset.

Returns

• Status code indicating success of the function call. RAIL_STATUS_INVALID_CALL if called with chip-specific handle, such as RAIL_EFR32_HANDLE, after RAIL initialization. RAIL_STATUS_INVALID_PARAMETER if the RSSI offset is deemed large enough to cause the RSSI readings to underflow or overflow.

Adds an offset to the RSSI in dBm. This offset affects all functionality that depends on RSSI values, such as CCA functions. Do not modify the offset dynamically during packet reception. This function can only be called while the radio is off, or in the case of multiprotocol, on an inactive protocol.

Note

• : If RAIL has not been initialized, a chip-specific handle, such as RAIL_EFR32_HANDLE, can be used to set a chip level RSSI offset.

• : Setting a large rssiOffset may still cause the RSSI readings to underflow. If that happens, the RSSI value returned by RAIL_GetRssi, RAIL_GetAverageRssi, RAIL_GetChannelHoppingRssi etc. will be RAIL_RSSI_LOWEST

• : During RX Channel Hopping this API will not update the RSSI offset immediately if channel hopping has already been configured. A subsequent call to RAIL_ZWAVE_ConfigRxChannelHopping or RAIL_ConfigRxChannelHopping is required for the new RSSI offset to take effect.

RAIL_GetRssiOffset#

int8_t RAIL_GetRssiOffset (RAIL_Handle_t railHandle)

Get the RSSI offset.

Returns

• rssiOffset in dBm corresponding to the current handle.

Note

• : A chip-specific handle, such as RAIL_EFR32_HANDLE, can be used to get the chip level RSSI offset otherwise this will return the RSSI offset value associated with the RAIL instance handle, exclusive of any chip level RSSI offset correction, if any.

RAIL_SetRssiDetectThreshold#

RAIL_Status_t RAIL_SetRssiDetectThreshold (RAIL_Handle_t railHandle, int8_t rssiThresholdDbm)

Set the RSSI detection threshold(in dBm) to trigger RAIL_EVENT_DETECT_RSSI_THRESHOLD.

Returns

• Status code indicating success of the function call. Returns RAIL_STATUS_INVALID_STATE in multiprotocol, if the requested RAIL_Handle_t is not active. Returns RAIL_STATUS_INVALID_CALL if called on parts on which this function is not supported.

When in receive, RSSI is sampled and if it exceeds the threshold, RAIL_EVENT_DETECT_RSSI_THRESHOLD is triggered.

Note

• : If the radio is idled or this function is called with rssiThresholdDbm as RAIL_RSSI_INVALID_DBM while RSSI detect is still in effect, a RAIL_EVENT_DETECT_RSSI_THRESHOLD may not occur and the detection is disabled. If the RSSI is already above threshold when this function is called then RAIL_EVENT_DETECT_RSSI_THRESHOLD will occur. Once the RSSI goes over the configured threshold and RAIL_EVENT_DETECT_RSSI_THRESHOLD occurs, this function needs to be called again to reactivate the RSSI threshold detection. This function is only available on series-2 Sub-GHz parts EFR32XG23 and EFR32XG25.

RAIL_GetRssiDetectThreshold#

int8_t RAIL_GetRssiDetectThreshold (RAIL_Handle_t railHandle)

Get the RSSI detection threshold(in dBm).

Returns

• rssiThreshold (in dBm) corresponding to the current handle.

Note

• : The function returns RAIL_RSSI_INVALID_DBM when RAIL_SetRssiDetectThreshold is not supported or disabled. In multiprotocol, the function returns RAIL_RSSI_INVALID_DBM if railHandle is not active. This function is only available on series-2 Sub-GHz parts EFR32XG23 and EFR32XG25.

RAIL_ConvertLqi#

RAIL_Status_t RAIL_ConvertLqi (RAIL_Handle_t railHandle, RAIL_ConvertLqiCallback_t cb)

Set up a callback function capable of converting a RX packet's LQI value before being consumed by application code.

Returns

• Status code indicating success of the function call.