RX Channel Hopping
Hardware accelerated hopping between channels while waiting for a packet in receive.
Data Structures |
|
struct | RAIL_RxChannelHoppingConfigMultiMode_t |
Structure that parameterizes
RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE
.
|
|
struct | RAIL_RxChannelHoppingConfigEntry_t |
Structure that represents one of the channels that is part of a
RAIL_RxChannelHoppingConfig_t
sequence of channels used in channel hopping.
|
|
struct | RAIL_RxChannelHoppingConfig_t |
Wrapper struct that will contain the sequence of
RAIL_RxChannelHoppingConfigEntry_t
that represents 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_MAX_SENSE_TIME_US 0x08000000UL |
The maximum sense time supported for those
RAIL_RxChannelHoppingMode_t
modes whose parameter(s) specify a sensing time.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE 0U |
A value representing no options enabled.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE |
All options disabled by default.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT |
Deprecated backwards-compatible synonym of
RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT
.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL_SHIFT) |
An option to skip synth calibration while
hopping into
the channel specified in the current entry.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT) |
An option to skip DC calibration while
hopping into
the channel specified in the current entry.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT) |
An option to check RSSI after
hopping into
the channel specified in the current entry and hop if that RSSI is below the threshold specified in
RAIL_RxChannelHoppingConfigEntry_t::rssiThresholdDbm
.
|
|
#define | RAIL_RX_CHANNEL_HOPPING_OPTION_STOP (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT) |
An option to stop the hopping sequence at this entry in the hop table.
|
|
#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.
|
Typedefs |
|
typedef uint32_t | RAIL_RxChannelHoppingParameter_t |
Rx channel hopping on-channel time.
|
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.
|
|
RAIL_Status_t | RAIL_GetDefaultRxDutyCycleConfig ( RAIL_Handle_t railHandle, RAIL_RxDutyCycleConfig_t *config) |
Get the default RX duty cycle configuration.
|
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.
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
979
of file
rail_chip_specific.h
.
◆ RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD
#define RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD (1U << RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT) |
An option to check RSSI after hopping into the channel specified in the current entry and hop if that RSSI is below the threshold specified in RAIL_RxChannelHoppingConfigEntry_t::rssiThresholdDbm .
This check runs in parallel with the RAIL_RxChannelHoppingMode_t specified and may cause a hop sooner than that mode otherwise would.
Definition at line
3894
of file
rail_types.h
.
◆ RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT
#define RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE |
All options disabled by default.
Channel hopping will behave as described by other parameters as it did in RAIL 2.7 and earlier.
Definition at line
3871
of file
rail_types.h
.
◆ RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE
#define RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE 0U |
A value representing no options enabled.
Definition at line
3865
of file
rail_types.h
.
Enumeration Type Documentation
◆ RAIL_RxChannelHoppingDelayMode_t
Deprecated enum.
Set only to RAIL_RX_CHANNEL_DELAY_MODE_STATIC
Definition at line
3826
of file
rail_types.h
.
◆ 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_t::parameter , and must be less than RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US . |
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_t::parameter , and must be less than RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US . |
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_t::parameter , and must be less than RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US . |
RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 |
Placeholder for a reserved hopping mode that is not supported. |
RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE |
A mode that combines modes TIMING_SENSE, PREAMBLE_SENSE, and TIMEOUT (sync detect) all running in parallel. Refer to RAIL_RxChannelHoppingConfigMultiMode_t for further details. A pointer to that structure, allocated in global read-write memory and initialized to the desired configuration values, is specified as the RAIL_RxChannelHoppingConfigEntry_t::parameter or RAIL_RxDutyCycleConfig_t::parameter , cast appropriately:
.parameter = (uint32_t)(
void
*)&hoppingConfigMultiMode,
|
RAIL_RX_CHANNEL_HOPPING_MODE_SQ |
Switch to the next channel based on the demodulation settings in the PHY config. This mode is PHY and chip dependent. The RAIL_RxChannelHoppingConfigEntry_t::parameter is ignored, and should be set to 0 for future compatibility. |
RAIL_RX_CHANNEL_HOPPING_MODE_CONC |
Marks that the channel is concurrent with another channel, and otherwise behaves identically to RAIL_RX_CHANNEL_HOPPING_MODE_SQ . |
RAIL_RX_CHANNEL_HOPPING_MODE_VT |
Indicates that this channel is a virtual channel that is concurrently detected with the channel indicated by the RAIL_RxChannelHoppingConfigEntry_t::parameter . Otherwise behaves identically to RAIL_RX_CHANNEL_HOPPING_MODE_SQ . |
RAIL_RX_CHANNEL_HOPPING_MODE_TX |
This is the transmit channel used for auto-ACK if the regular channel, specified in RAIL_RxChannelHoppingConfigEntry::parameter, is optimized for RX which may degrade some TX performance. |
RAIL_RX_CHANNEL_HOPPING_MODES_COUNT |
A count of the basic choices in this enumeration. |
RAIL_RX_CHANNEL_HOPPING_MODES_WITH_OPTIONS_BASE |
The start of equivalent modes requiring non-default RAIL_RxDutyCycleConfig_t::options , needed for backwards-compatibility with earlier RAIL_RxDutyCycleConfig_t format. Non-default options are supported with RAIL_RxChannelHoppingConfigEntry_t in all modes. |
RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_MANUAL with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_TIMEOUT with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_TIMING_SENSE with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_RESERVED1 with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_MULTI_SENSE with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_SQ_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_SQ with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_CONC_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_CONC with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_VT_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_VT with options. |
RAIL_RX_CHANNEL_HOPPING_MODE_TX_WITH_OPTIONS |
Variant of RAIL_RX_CHANNEL_HOPPING_MODE_TX with options. |
Definition at line
3672
of file
rail_types.h
.
◆ 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 |
Shift position of RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL bit. |
RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL_SHIFT |
Shift position of RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL bit. |
RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD_SHIFT |
Shift position of RAIL_RX_CHANNEL_HOPPING_OPTION_RSSI_THRESHOLD bit. |
RAIL_RX_CHANNEL_HOPPING_OPTION_STOP_SHIFT |
Stop hopping on this hop. |
RAIL_RX_CHANNEL_HOPPING_OPTIONS_COUNT |
A count of the choices in this enumeration. |
Definition at line
3851
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_EnableRxChannelHopping() . 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. Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
- 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. For short delays (in the order of microseconds), RAIL_RxDutyCycleConfig_t::delay , this can be used to save receive current while having little impact on the radio performance, for protocols with long preambles. For long delays (in the order of milliseconds or higher) the chip can be put into EM2 energy mode before re-entering RX, to save extra power, with some application hooks as shown below.
- Note
- This feature/API is not supported on the EFR32XG1 family of chips. Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
- Calling this function will overwrite any settings configured with RAIL_ConfigRxChannelHopping .
◆ 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_ConfigRxChannelHopping must be called successfully before this API is called.
- Note
- This feature/API is not supported on the EFR32XG1 family of chips. Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
- 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. Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
- Calling this function will overwrite any settings configured with RAIL_EnableRxChannelHopping .
◆ 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. Use the compile time symbol RAIL_SUPPORTS_CHANNEL_HOPPING or the runtime call RAIL_SupportsChannelHopping() to check whether the platform supports this feature.
- In multiprotocol, this function returns RAIL_RSSI_INVALID immediately if railHandle is not the current active RAIL_Handle_t .
- RAIL_ConfigRxChannelHopping must be called successfully before this API is called.
- When the Z-Wave protocol is active, it is expected that after RAIL_ConfigRxChannelHopping is called successfully on EFR32XG1 family of chips, running RAIL_GetChannelHoppingRssi() on a 40kbps PHY will not work well. Plan to use the 9.6kbps PHY for estimating channel noise instead. On EFR32XG2 family of chips, running RAIL_GetChannelHoppingRssi() on the 9.6kbps PHY returns the RSSI measurement of the 40kpbs PHY. This is because the 9.6kbps PHY has trouble with RSSI measurements on EFR32XG2 family of chips.
◆ RAIL_GetDefaultRxDutyCycleConfig()
RAIL_Status_t RAIL_GetDefaultRxDutyCycleConfig | ( | RAIL_Handle_t |
railHandle,
|
RAIL_RxDutyCycleConfig_t * |
config
|
||
) |
Get the default RX duty cycle configuration.
- Parameters
-
[in] railHandle
A RAIL instance handle. [out] config
An application-provided non-NULL pointer to store the default RX duty cycle configuration.
- Returns
- Status code indicating success of the function call. Note that RAIL_STATUS_INVALID_PARAMETER will be returned if the current channel's radio configuration does not support the requested information.
To save power during RX, an application may want to go to low power as long as possible by periodically waking up and trying to "sense" if there are any incoming packets. This API returns the recommended RX duty cycle configuration, so the application can enter low power mode periodically without missing packets. To wake up earlier, the application can reduce the delay parameter. Note that these value might be different if any configuration / channel has changed.