Sleep#

These APIs help when putting the system to an EM2/EM3/EM4 sleep states where the high frequency clock is disabled.

The RAIL library has its own timebase and the ability to schedule operations into the future. When going to any power mode that disables the HF clock used for the radio (EM2/EM3/EM4), it is important that this timebase is synchronized to a running LFCLK and the chip is set to wake up before the next scheduled event. If RAIL has not been configured to use the power manager, RAIL_Sleep and RAIL_Wake must be called for performing this synchronization. If RAIL has been configured to use the power manager, RAIL_InitPowerManager, it will automatically perform timer synchronization based on the selected RAIL_TimerSyncConfig_t. Calls to RAIL_Sleep and RAIL_Wake are unsupported in such a scenario.

Following example code snippets demonstrate synchronizing the timebase with and without timer synchronization:

Sleep with timer synchronization:

When sleeping with timer synchronization, you must first get the required LFCLK up and running and leave it running across sleep so that the high frequency clock that drives the RAIL time base can be synchronized to it. The RAIL_Sleep() API will also set up a wake event on the timer to wake up wakeupTime before the next timer event so that it can run successfully. See the EFR32 sections on Low-Frequency Clocks and RAIL Timer Synchronization for more setup details.

This is useful when maintaining packet timestamps across sleep or use the scheduled RX/TX APIs while sleeping in between. It does take more time and code to do the synchronization. If your application does not need this, it should be avoided.

Example (without Power Manager):

#include "rail.h"

extern RAIL_Handle_t railHandle;
// Wakeup time for your crystal/board/chip combination
extern uint32_t wakeupTime;

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

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

  // Configure sleep for timer synchronization
  status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED);
  assert(status == RAIL_STATUS_NO_ERROR);

  // Application main loop
  while(1) {
    // ... do normal app stuff and set shouldSleep to true when we want to
    // sleep
    if (shouldSleep) {
      bool sleepAllowed = false;

      // Go critical to assess sleep decisions
      CORE_ENTER_CRITICAL();
      if (RAIL_Sleep(wakeupTime, &sleepAllowed) != RAIL_STATUS_NO_ERROR) {
        printf("Error trying to go to sleep!");
        CORE_EXIT_CRITICAL();
        continue;
      }
      if (sleepAllowed) {
        // Go to sleep
      }
      // Wakeup and sync the RAIL timebase back up
      RAIL_Wake(0);
      CORE_EXIT_CRITICAL();
    }
  }
}

Example (with Power Manager):

#include "rail.h"
#include "sl_power_manager.h"

extern RAIL_Handle_t railHandle;

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

  // 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();
  // Configure sleep for timer synchronization
  status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED);
  assert(status == RAIL_STATUS_NO_ERROR);
  // Initialize application-level power manager service
  sl_power_manager_init();
  // Initialize RAIL library's use of the power manager
  RAIL_InitPowerManager();

  // Application main loop
  while(1) {
    // ... do normal app stuff and set shouldSleep to true when we want to
    // sleep
    if (shouldSleep) {
      // Let the CPU go to sleep if the system allows it.
      sl_power_manager_sleep();
    }
  }
}

RAIL APIs such as, RAIL_StartScheduledTx, RAIL_ScheduleRx, RAIL_SetTimer, RAIL_SetMultiTimer can be used to schedule periodic wakeups to perform a scheduled operation. The call to sl_power_manager_sleep() in the main loop ensures that the device sleeps until the scheduled operation is due. Upon completion, each instantaneous or scheduled RX/TX operation will indicate radio busy to the power manager to allow the application to service the RAIL event and perform subsequent operations before going to sleep. Therefore, it is important that the application idle the radio by either calling RAIL_Idle or RAIL_YieldRadio. If the radio transitions to RX after an RX or TX operation, always call RAIL_Idle in order transition to a lower sleep state. If the radio transitions to idle after an RX or TX operation, RAIL_YieldRadio should suffice in indicating to the power manager that the radio is no longer busy and the device can sleep.

The following example shows scheduling periodic TX on getting a TX completion event:

void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
  // Omitting other event handlers
  if (events & RAIL_EVENTS_TX_COMPLETION) {
    // Schedule the next TX.
    RAIL_ScheduleTxConfig_t config = {
      .when = (RAIL_Time_t)parameters->startTime,
      .mode = (RAIL_TimeMode_t)parameters->startTimeMode
    };
    (void)RAIL_StartScheduledTx(railHandle, channel, 0, &config, NULL);
  }
}

Note

• The above code assumes that RAIL automatic state transitions after TX are idle. Set RAIL_SetTxTransitions to ensure the right state transitions. Radio must be idle for the device to enter EM2 or lower energy mode.

• When using the power manager, usage of RAIL_YieldRadio in single protocol RAIL is similar to its usage in multiprotocol RAIL. See Yielding the Radio for more details.

• Back to back scheduled operations do not require an explicit call to RAIL_YieldRadio if the radio transitions to idle.

Sleep without timer synchronization:

When sleeping without timer synchronization, you are free to enable only the LFCLKs and wake sources required by the application. RAIL will not attempt to configure any wake events and may miss anything that occurs over sleep.

This is useful when your application does not care about packet timestamps or scheduling operations accurately over sleep.

Example (without Power Manager):

#include "rail.h"

extern RAIL_Handle_t railHandle;

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

  // Configure sleep for timer synchronization
  status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED);
  assert(status == RAIL_STATUS_NO_ERROR);

  // Application main loop
  while(1) {
    // ... do normal app stuff and set shouldSleep to true when we want to
    // sleep
    if (shouldSleep) {
      bool sleepAllowed = false;
      uint32_t sleepTime = 0;

      // Go critical to assess sleep decisions
      CORE_ENTER_CRITICAL();
      if (RAIL_Sleep(0, &sleepAllowed) != RAIL_STATUS_NO_ERROR) {
        printf("Error trying to go to sleep!");
        CORE_EXIT_CRITICAL();
        continue;
      }
      if (sleepAllowed) {
        // Go to sleep and optionally update sleepTime to the correct value
        // in microseconds
      }
      // Wakeup and sync the RAIL timebase back up
      RAIL_Wake(sleepTime);
      CORE_EXIT_CRITICAL();
    }
  }
}

Example (with Power Manager):

#include "rail.h"
#include "sl_power_manager.h"

extern RAIL_Handle_t railHandle;

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

  // 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();
  // Configure sleep for timer synchronization
  status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED);
  assert(status == RAIL_STATUS_NO_ERROR);
  // Initialize application-level power manager service
  sl_power_manager_init();
  // Initialize RAIL library's use of the power manager
  RAIL_InitPowerManager();

  // Application main loop
  while(1) {
    // ... do normal app stuff and set shouldSleep to true when we want to
    // sleep
    if (shouldSleep) {
      // Let the CPU go to sleep if the system allows it.
      sl_power_manager_sleep();
    }
  }
}

Modules#

RAIL_TimerSyncConfig_t

EFR32XG2X

void RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)
{
  timerSyncConfig->prsChannel = MY_TIMERSYNC_PRS_CHANNEL;
  timerSyncConfig->rtccChannel = MY_TIMERSYNC_RTCC_CHANNEL;
}