RX Channel Hopping#

RAIL_RxChannelHoppingMode_t#

RAIL_RxChannelHoppingMode_t

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

RAIL_RxChannelHoppingDelayMode_t#

RAIL_RxChannelHoppingDelayMode_t

DeprecatedSet only to RAIL_RX_CHANNEL_DELAY_MODE_STATIC.

RAIL_RxChannelHoppingOptions_t#

RAIL_RxChannelHoppingOptions_t

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

RAIL_RxChannelHoppingParameter_t#

RAIL_RxChannelHoppingParameter_t

Rx channel hopping on-channel time.

RAIL_ConfigRxChannelHopping#

RAIL_Status_t RAIL_ConfigRxChannelHopping (RAIL_Handle_t railHandle, RAIL_RxChannelHoppingConfig_t * config)

Configure 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

• 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_EnableRxChannelHopping#

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

Enable RX channel hopping.

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 first channel index, 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

• 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_GetChannelHoppingRssi#

int16_t RAIL_GetChannelHoppingRssi (RAIL_Handle_t railHandle, uint8_t channelIndex)

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

Returns

• Latest RSSI in deci-dBm for the channel at the specified index.

Note

• 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, 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_ConfigRxDutyCycle#

RAIL_Status_t RAIL_ConfigRxDutyCycle (RAIL_Handle_t railHandle, const RAIL_RxDutyCycleConfig_t * config)

Configure RX duty cycle mode.

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.

#include "rail.h"

extern RAIL_Handle_t railHandle;
RAIL_Time_t periodicWakeupUs;

volatile bool dutyCycleEnd = true;

void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
  // Omitting other event handlers
  if (events & RAIL_EVENT_RX_DUTY_CYCLE_RX_END) {
    dutyCycleEnd = true;
  }
}

void main(void)
{
  RAIL_Status_t status;
  bool shouldSleep = false;

  initializeRail(); // Call RAIL_Init() and such

  // This function depends on your board/chip but it must enable the LFCLK
  // you intend to use for RTCC sync before we configure sleep as that
  // function will attempt to auto detect the clock.
  BoardSetupLFCLK();
  // Initialize Power Manager module
  sl_power_manager_init();
  // Initialize RAIL Power Manager
  RAIL_InitPowerManager();

  // Configure sleep for timer synchronization
  RAIL_TimerSyncConfig_t timerSyncConfig = RAIL_TIMER_SYNC_DEFAULT;
  status = RAIL_ConfigSleep(railHandle, &timerSyncConfig);
  assert(status == RAIL_STATUS_NO_ERROR);

  // Configure RX duty-cycling
  RAIL_RxDutyCycleConfig_t duty_cycle_config = {
    .mode = RAIL_RX_CHANNEL_HOPPING_MODE_PREAMBLE_SENSE,
    .parameter = DUTY_CYCLE_ON_TIME,
    .delay_us = DUTY_CYCLE_OFF_TIME,
    .delay_mode = RAIL_RX_CHANNEL_HOPPING_DELAY_MODE_STATIC,
    .options = RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE,
  };
  status = RAIL_ConfigRxDutyCycle(rail_handle, &duty_cycle_config);
  assert(status == RAIL_STATUS_NO_ERROR);
  status = RAIL_EnableRxDutyCycle(rail_handle, true);
  assert(status == RAIL_STATUS_NO_ERROR);

  // Application main loop
  while (1) {
    if (dutyCycleEnd) {
      dutyCycleEnd = false;
      // Schedule the next receive.
      RAIL_ScheduleRxConfig_t rxConfig = {
        .start = periodicWakeupUs,
        .startMode = RAIL_TIME_DELAY,
        .end = 0U,
        .endMode = RAIL_TIME_DISABLED,
        .rxTransitionEndSchedule = 0U,
        .hardWindowEnd = 0U
      };
      RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true);
      RAIL_StartScheduledRx(railHandle, channel, &rxConfig, NULL);
    }
    // ... do normal app stuff and set shouldSleep when we want to sleep
    if (shouldSleep) {
      // Let the CPU go to sleep if the system allows it.
      sl_power_manager_sleep();
    }
  }
}

Note

• 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_EnableRxDutyCycle#

RAIL_Status_t RAIL_EnableRxDutyCycle (RAIL_Handle_t railHandle, bool enable)

Enable RX duty cycle mode.

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

• 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_GetDefaultRxDutyCycleConfig#

RAIL_Status_t RAIL_GetDefaultRxDutyCycleConfig (RAIL_Handle_t railHandle, RAIL_RxDutyCycleConfig_t * config)

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

RAIL_RX_CHANNEL_HOPPING_MAX_SENSE_TIME_US#

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

RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE#

#define RAIL_RX_CHANNEL_HOPPING_OPTIONS_NONE

0U

A value representing no options enabled.

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.

RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT#

#define RAIL_RX_CHANNEL_HOPPING_OPTION_DEFAULT

RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT

DeprecatedPlease use RAIL_RX_CHANNEL_HOPPING_OPTIONS_DEFAULT instead.

RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_SYNTH_CAL#

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

RAIL_RX_CHANNEL_HOPPING_OPTION_SKIP_DC_CAL#

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

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.

RAIL_RX_CHANNEL_HOPPING_OPTION_STOP#

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

RAIL_CHANNEL_HOPPING_INVALID_INDEX#

#define RAIL_CHANNEL_HOPPING_INVALID_INDEX

(0xFEU)

A sentinel value to flag an invalid channel hopping index.