Hardware accelerated hopping between channels while waiting for a packet in receive.

Data Structures
struct	RAIL_RxChannelHoppingConfigEntry_t
	Structure that represents one of the channels that is part of a sequence of channels used in channel hopping.

struct	RAIL_RxChannelHoppingConfig_t
	Wrapper struct that will contain the sequence of RAIL_RxChannelHoppingConfig_t that represent the channel sequence to use during RX Channel Hopping.

struct	RAIL_RxDutyCycleConfig_t
	Structure to configure duty cycled receive mode.

Macros
#define	RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT (0UL)
	Options mask to specify no additional options.

#define	RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL (1UL << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT)
	Mask that corresponds with RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT.

#define	RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL (1UL << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT)
	Mask that corresponds with RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT.

#define	RAIL_CHANNEL_HOPPING_INVALID_INDEX (0xFEU)
	A sentinel value to flag an invalid channel hopping index.

#define	RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL (25U)
	The static amount of memory needed per channel for channel hopping, regardless of the size of radio configuration structures.

Enumerations
enum	RAIL_RxChannelHoppingMode_t { RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL, RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT, RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE, RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE }
	Modes by which RAIL can determine when to proceed to the next channel during channel hopping.

enum	RAIL_RxChannelHoppingDelayMode_t { RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC }
	Modes by which RAIL_RxChannelHoppingConfigEntry_t::delay timing can be applied to the time gap between channels.

enum	RAIL_RxChannelHoppingOptions_t { RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT, RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT }
	Options that can customize channel hopping behavior on a per-hop basis.

Functions
RAIL_Status_t	RAIL_ConfigRxChannelHopping (RAIL_Handle_t railHandle, RAIL_RxChannelHoppingConfig_t *config)
	Configure RX Channel Hopping.

RAIL_Status_t	RAIL_EnableRxChannelHopping (RAIL_Handle_t railHandle, bool enable, bool reset)
	Enable RX Channel Hopping.

int16_t	RAIL_GetChannelHoppingRssi (RAIL_Handle_t railHandle, uint8_t channelIndex)
	Get RSSI of one channel in the channel hopping sequence, during channel hopping.

RAIL_Status_t	RAIL_ConfigRxDutyCycle (RAIL_Handle_t railHandle, const RAIL_RxDutyCycleConfig_t *config)
	Configure RX duty cycle mode.

RAIL_Status_t	RAIL_EnableRxDutyCycle (RAIL_Handle_t railHandle, bool enable)
	Enable RX duty cycle mode.

Detailed Description

Hardware accelerated hopping between channels while waiting for a packet in receive.

Channel hopping provides a hardware accelerated method for scanning across multiple channels quickly, as part of a receive protocol. While it is possible to call RAIL_StartRx on different channels, back to back, and listen on many channels sequentially in that way, the time it takes to switch channels with that method may be too long for some protocols. This API pre-computes necessary channel change operations for a given list of channels, so that the radio can move from channel to channel much faster. Additionally, it leads to more succinct code as channel changes will be done implicitly, without requiring numerous calls to RAIL_StartRx. Currently, while this feature is enabled, the radio will hop channels in the given sequence each time it enters RX.

The following code gives an example of how to use the RX Channel Hopping API.

// The channel hopping buffer requires RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL
// number of 32-bit words of overhead per channel, plus 3 words overall plus the
// twice the size of the radioConfigDeltaSubtract of the whole radio configuration,
// plus the twice the sum of the sizes of all the radioConfigDeltaAdds of
// all the channel hopping channels.
#define CHANNEL_HOPPING_NUMBER_OF_CHANNELS 4
#define CHANNEL_HOPPING_BUFFER_SIZE do {        \
  3 +                                           \
  (RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL \
   * CHANNEL_HOPPING_NUMBER_OF_CHANNELS) +      \
  2 * (SIZEOF_UINT32_DELTA_SUBTRACT +           \
  SIZEOF_UINT32_DELTA_ADD_0 +                   \
  SIZEOF_UINT32_DELTA_ADD_1 +                   \
  SIZEOF_UINT32_DELTA_ADD_2 +                   \
  SIZEOF_UINT32_DELTA_ADD_3)                    \
} while (0)
RAIL_RxChannelHoppingConfigEntry_t channelHoppingEntries[CHANNEL_HOPPING_NUMBER_OF_CHANNELS];
uint32_t channelHoppingBuffer[CHANNEL_HOPPING_BUFFER_SIZE];
RAIL_RxChannelHoppingConfig_t channelHoppingConfig = {
  .buffer = channelHoppingBuffer,
  .bufferLength = CHANNEL_HOPPING_BUFFER_SIZE,
  .numberOfChannels = CHANNEL_HOPPING_NUMBER_OF_CHANNELS,
  .entries = channelHoppingEntries
};
channelHoppingEntries[0].channel = 1;
channelHoppingEntries[1].channel = 2;
channelHoppingEntries[2].channel = 3;
RAIL_ConfigRxChannelHopping(railHandle, &channelHoppingConfig);
RAIL_EnableRxChannelHopping(railHandle, true, true)

Macro Definition Documentation

◆ RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL

#define RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL (25U)

The static amount of memory needed per channel for channel hopping, regardless of the size of radio configuration structures.

Definition at line 737 of file rail_chip_specific.h.

◆ RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT

#define RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT (0UL)

Options mask to specify no additional options.

Channel hopping will behave as described by other paramters as it did in RAIL 2.7 and earlier.

Definition at line 3079 of file rail_types.h.

Enumeration Type Documentation

◆ RAIL_RxChannelHoppingDelayMode_t

enum RAIL_RxChannelHoppingDelayMode_t

Modes by which RAIL_RxChannelHoppingConfigEntry_t::delay timing can be applied to the time gap between channels.

Enumerator
RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC	Always delay for exactly the amount of time specified in the delay parameter, regardless of how other channel hopping channels were extended via preamble sense or other means.

Definition at line 3041 of file rail_types.h.

◆ RAIL_RxChannelHoppingMode_t

enum RAIL_RxChannelHoppingMode_t

Modes by which RAIL can determine when to proceed to the next channel during channel hopping.

Enumerator
RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL	Switch to the next channel each time the radio enters RX.
RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT	Switch to the next channel after a certain amount of time passes. The time should be specified in microseconds in RAIL_RxChannelHoppingConfigEntry::parameter.
RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE	Listen in receive RX for at least a specified timeout. If, by the end of the timeout, the radio has packet timing, remain in the current channel until the radio loses it. The timeout should be specified in microseconds in RAIL_RxChannelHoppingConfigEntry::parameter.
RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE	Listen in receive RX for at least a specified timeout. If, by the end of the timeout, the radio has a packet preamble, remain in the current channel until the radio loses it. The timeout should be specified in microseconds in RAIL_RxChannelHoppingConfigEntry::parameter.

Definition at line 2999 of file rail_types.h.

◆ RAIL_RxChannelHoppingOptions_t

enum RAIL_RxChannelHoppingOptions_t

Options that can customize channel hopping behavior on a per-hop basis.

Enumerator
RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT	Optionally skip synth calibration while hopping into the channel specified in the current entry.
RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT	Optionally skip DC calibration while hopping into the channel specified in the current entry.

Definition at line 3060 of file rail_types.h.

Function Documentation

◆ RAIL_ConfigRxChannelHopping()

RAIL_Status_t RAIL_ConfigRxChannelHopping	(	RAIL_Handle_t	`railHandle,`
		RAIL_RxChannelHoppingConfig_t *	`config`
	)

Configure RX Channel Hopping.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`config`	Configuration parameters for RX Channel Hopping.

Returns: Status code indicating success of the function call.

Configure Channel Hopping channels, conditions, and parameters. This API must be called before RAIL_EnableChannelHopping. This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled.

Note: This feature/API is not supported on the EFR32XG1 family of chips.; This feature/API is currently not supported in multiprotocol.; Calling this function will overwrite any settings configured with RAIL_ConfigRxDutyCycle.

◆ RAIL_ConfigRxDutyCycle()

RAIL_Status_t RAIL_ConfigRxDutyCycle	(	RAIL_Handle_t	`railHandle,`
		const RAIL_RxDutyCycleConfig_t *	`config`
	)

Configure RX duty cycle mode.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`config`	Configuration structure to specify duty cycle parameters.

Returns: Status code indicating success of the function call.

Configure RX duty cycle mode. With this mode enabled, every time the radio enters RX, it will duty cycle on and off to save power. The duty cycle ratio can be altered dynamically and intelligently by the hardware by staying on longer if a preamble or other packet segments are detected in the air. This API must never be called while the radio is on with RX Duty Cycle or Channel Hopping enabled.

Note: This feature/API is not supported on the EFR32XG1 family of chips.; Calling this function will overwrite any settings configured with RAIL_ConfigRxChannelHopping.; This feature/API is currently not supported in multiprotocol.

◆ RAIL_EnableRxChannelHopping()

RAIL_Status_t RAIL_EnableRxChannelHopping	(	RAIL_Handle_t	`railHandle,`
		bool	`enable,`
		bool	`reset`
	)

Enable RX Channel Hopping.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`enable`	Enable (true) or disable (false) RX Channel Hopping.
[in]	`reset`	Start from the first channel of the channel hopping sequence (true) or from wherever hopping left off last time the code left RX.

Returns: Status code indicating success of the function call.

Enable or disable Channel Hopping. Additionally, specify whether hopping should be reset to start from the channel at index zero, or continue from the channel last hopped to. The radio should not be on when this API is called. RAIL_ConfigChannelHopping must be called before this API is called.

Note: This feature/API is not supported on the EFR32XG1 family of chips.; This feature/API is currently not supported in multiprotocol.; RX Channel Hopping may not be enabled while auto-ACKing is enabled.; Calling this function will overwrite any settings configured with RAIL_EnableRxDutyCycle.

◆ RAIL_EnableRxDutyCycle()

RAIL_Status_t RAIL_EnableRxDutyCycle	(	RAIL_Handle_t	`railHandle,`
		bool	`enable`
	)

Enable RX duty cycle mode.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`enable`	Enable (true) or disable (false) RX Duty Cycling.

Returns: Status code indicating success of the function call.

Enable or disable RX duty cycle mode. After this is called, the radio will begin duty cycling each time it enters RX, based on the configuration passed to RAIL_ConfigRxDutyCycle. This API must not be called while the radio is on.

Note: This feature/API is not supported on the EFR32XG1 family of chips.; Calling this function will overwrite any settings configured with RAIL_EnableRxChannelHopping.; This feature/API is currently not supported in multiprotocol.

◆ RAIL_GetChannelHoppingRssi()

int16_t RAIL_GetChannelHoppingRssi	(	RAIL_Handle_t	`railHandle,`
		uint8_t	`channelIndex`
	)

Get RSSI of one channel in the channel hopping sequence, during channel hopping.

Parameters

[in]	`railHandle`	A RAIL instance handle.
[in]	`channelIndex`	Index in the channel hopping sequence of the channel of interest

Returns: Latest RSSI for the channel at the specified index.

Note: This feature/API is not supported on the EFR32XG1 family of chips.; This feature/API is currently not supported in multiprotocol.; RAIL_ConfigRxChannelHopping must be called successfully before this API is called.

RX Channel HoppingRAIL API

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RAIL_CHANNEL_HOPPING_BUFFER_SIZE_PER_CHANNEL

◆ RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT

Enumeration Type Documentation

◆ RAIL_RxChannelHoppingDelayMode_t

◆ RAIL_RxChannelHoppingMode_t

◆ RAIL_RxChannelHoppingOptions_t

Function Documentation

◆ RAIL_ConfigRxChannelHopping()

◆ RAIL_ConfigRxDutyCycle()

◆ RAIL_EnableRxChannelHopping()

◆ RAIL_EnableRxDutyCycle()

◆ RAIL_GetChannelHoppingRssi()

RX Channel Hopping
RAIL API