Receive

RAIL API

The value returned by RAIL for an invalid RSSI: in quarter dBm.

Definition at line 2233 of file rail_types.h .

The value returned by RAIL for an invalid RSSI, in dBm.

Definition at line 2231 of file rail_types.h .

An option to select the use of antenna 0 during receive (including Auto-ACK receive).

If no antenna option is selected, the packet will be received on the last antenna used for receive or transmit. Defaults to false. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna() .

Definition at line 2196 of file rail_types.h .

An option to select the use of antenna 1 during receive (including Auto-ACK receive).

If no antenna option is selected, the packet will be received on the last antenna used for receive or transmit. Defaults to false. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna() .

Definition at line 2205 of file rail_types.h .

An option combination to automatically choose an antenna during receive (including Auto-ACK receive).

If both antenna 0 and antenna 1 options are set, the radio will dynamically switch between antennas during packet detection and choose the best one for completing the reception. This option is only valid when the antenna diversity field is properly configured via Simplicity Studio. This option is only valid on platforms that support Antenna Control and have been configured via RAIL_ConfigAntenna() .

Definition at line 2217 of file rail_types.h .

An option to disable frame detection.

This can be useful for doing energy detection without risking packet reception. Enabling this will abort any frame currently being received in addition to preventing further frames from being received. Defaults to false.

Definition at line 2225 of file rail_types.h .

An option to control which sync words will be accepted.

Setting it to 0 (default) will cause the receiver to listen for SYNC1 only. Setting it to 1 causes the receiver to listen for either SYNC1 or SYNC2. RX appended info will contain which sync word was detected. Note, this only affects which sync word(s) are received, but not what each of the sync words actually are. This feature may not be available on some combinations of chips, PHYs, and protocols. See the data sheet or support team for more details.

Definition at line 2171 of file rail_types.h .

An option to configure whether CRC errors will be ignored.

If this is set, RX will still be successful, even if the CRC does not pass the check. Defaults to false.

Definition at line 2160 of file rail_types.h .

An option to suppress capturing the appended information after received frames.

Defaults to false. When suppressed, certain RAIL_RxPacketDetails_t details will not be available for received packets whose RAIL_RxPacketStatus_t is among the RAIL_RX_PACKET_READY_ set.

Definition at line 2187 of file rail_types.h .

An option to configure whether the CRC portion of the packet is included in the packet payload exposed to the app on packet reception.

Defaults to false.

Definition at line 2154 of file rail_types.h .

An option to configure whether frames which are aborted during reception should continue to be tracked.

Setting this option allows viewing Packet Trace information for frames which get discarded. Defaults to false.

Definition at line 2178 of file rail_types.h .

A value representing all possible options.

Definition at line 2228 of file rail_types.h .

All options are disabled by default.

Definition at line 2147 of file rail_types.h .

A value representing no options enabled.

Definition at line 2145 of file rail_types.h .

An invalid RX packet handle value.

Definition at line 2387 of file rail_types.h .

A special RX packet handle to refer to the newest unreleased packet when in callback context.

For a callback involving a completed receive event, this refers to the packet just completed. For other callback events, this refers to the next packet to be completed, which might be in-progress or might not have even started yet.

Definition at line 2397 of file rail_types.h .

A special RX packet handle to refer to the oldest unreleased packet.

Definition at line 2389 of file rail_types.h .

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

Parameters

[in]	lqi	The LQI value obtained by hardware and being readied for application consumption. This LQI value is in integral units ranging from 0 to 255.
[in]	rssi	The RSSI value corresponding to the packet from which the hardware LQI value was obtained. This RSSI value is in integral dBm units.

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.

Definition at line 2679 of file rail_types.h .

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 and RAIL_RX_PACKET_HANDLE_NEWEST .

Definition at line 2384 of file rail_types.h .

Receive options, in reality a bitmask.

Definition at line 2125 of file rail_types.h .

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.

Definition at line 2300 of file rail_types.h .

Configures receive options.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	mask	A bitmask containing which options should be modified.
[in]	options	A bitmask containing desired configuration settings. Bit positions for each option are found in the RAIL_RxOptions_t .

Returns

Status code indicating success of the function call.

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

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

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	cb	A callback of type RAIL_ConvertLqiCallback_t that is called before the RX packet LQI value is loaded into the RAIL_RxPacketDetails_t structure for application consumption.

Returns

Status code indicating success of the function call.

Gets the RSSI averaged over a specified time in us.

Parameters

[in]

railHandle

A RAIL instance handle.

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. It should be used after RAIL_StartAverageRssi .

Returns the current raw RSSI.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	wait	if false returns instant RSSI with no checks.

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. Users should characterize the RSSI received on their hardware and apply an offset in the application to account for board and PHY parameters. 'Wait' argument doesn't guarantee a valid RSSI reading.'Wait' being true gives assurance that that the RSSI is current and not a stale value from a previous radio state. If GetRssi is called during RX-to-RX, RX-to-IDLE, or RX-to-TX transition, the RSSI is considered stale and RAIL_RSSI_INVALID is returned if wait=true. 'Wait' being false will return either the current RSSI or a stale RSSI measurement (if called during RX-to-RX, RX-to-IDLE, or RX-to-TX transition). RAIL_RSSI_INVALID is returned if radio hasn't been in RX longer than 'idleToRx' time (see RAIL_StateTiming_t ), regardless of wait argument.

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.

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, this API should not be used. Instead see RAIL_GetChannelHoppingRssi() .

Gets the RSSI offset.

Parameters

[in]

railHandle

a RAIL instance handle.

Returns

rssiOffset in dBm corresponding to the current handle.

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.

Parameters

[in]

railHandle

A RAIL instance handle.

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.

Function to include the code necessary for frame type based length decoding.

Parameters

[in]

railHandle

A RAIL instance handle.

Returns

void.

This must be called before RAIL_ConfigChannels to allow configurations using a frame type based length setup. In RAIL 2.x this 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.

Queries whether the RSSI averaging is done.

Parameters

[in]

railHandle

A RAIL instance handle.

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.

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

Those bytes remain valid for re-peeking.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	packetHandle	A packet handle as returned from a previous RAIL_GetRxPacketInfo() or RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST or RAIL_RX_PACKET_HANDLE_NEWEST .
[out]	pDst	A pointer to the location where the received bytes will be copied. If NULL, no copying occurs.
[in]	len	A number of packet data bytes to copy.
[in]	offset	A byte offset within remaining packet data from which to copy.

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

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

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	packetHandle	A packet handle as returned from a previous RAIL_HoldRxPacket() call, or sentinel values RAIL_RX_PACKET_HANDLE_OLDEST or RAIL_RX_PACKET_HANDLE_NEWEST . The latter might be used within RAIL callback context to explicitly release the packet associated with the callback early, before it's released automatically by RAIL on callback return (unless explicitly held).

Returns

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

Schedules a receive window for some future time.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	channel	A channel to listen on.
[in]	cfg	The configuration structure to define the receive window.
[in]	schedulerInfo	Information to allow the radio scheduler to place this receive appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

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, aborts any ongoing packet transmission or reception.

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

Sets the RSSI offset.

Parameters

[in]	railHandle	a RAIL instance handle.
[in]	rssiOffset	desired offset to be added to the RSSI measurements.

Returns

Status code indicating success of the function call.

Adds an offset to the RSSI in dBm. This offset affects all functionality that depends on RSSI values, such as CCA functions. The offset should not be modified dynamically during the RX of a packet.

Starts the RSSI averaging over a specified time in us.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	channel	The physical channel to set.
[in]	averagingTimeUs	Averaging time in microseconds.
[in]	schedulerInfo	Information to allow the radio scheduler to place this operation appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

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

Starts the receiver on a specific channel.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	channel	The channel to listen on.
[in]	schedulerInfo	Information to allow the radio scheduler to place this receive appropriately. This is only used in multiprotocol version of RAIL and may be set to NULL in all other versions.

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.

Function implemented in the radio config for frame type length handling.

Parameters

[in]	railHandle	A RAIL instance handle.
[in]	frameType	A frame type configuration structure.

Returns

void.

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.