sleep() [ Classic API ]

System.sleep, sleep

This API is the previous API for sleep and is less flexible. You should use the newer sleep APIs with Device OS 1.5.0 and later.

System.sleep() can be used to dramatically improve the battery life of a Particle-powered project. There are several variations of System.sleep() based on which arguments are passed.


Gen 3 Devices:

Gen 3 devices (Argon, Boron, B Series SoM, Tracker SoM) only support sleep modes in 0.9.0 and later. Sleep does not function properly in 0.8.0-rc versions of Device OS for Gen 3 devices.

On the Argon, Boron, and Xenon, WKP is pin D8.

On the B Series SoM, WKP is pin A7 in Device OS 1.3.1 and later. In prior versions, it was D8.

On the Tracker SoM WKP is pin A7/D7.

System.sleep(SLEEP_MODE_DEEP) can be used to put the entire device into a deep sleep mode, sometimes referred to as "standby sleep mode." It is not possible to specify a wake time in seconds using SLEEP_MODE_DEEP on Gen 3 devices, however you can use timed wake with ULTRA_LOW_POWER sleep mode.

// SYNTAX
System.sleep(SLEEP_MODE_DEEP);

// EXAMPLE USAGE

// Put the device into deep sleep until wakened by D8.
System.sleep(SLEEP_MODE_DEEP);
// The device LED will shut off during deep sleep

On the Boron, B Series SoM, and Tracker SoM it is not useful to combine SLEEP_MODE_DEEP and SLEEP_NETWORK_STANDBY as the modem will remain on, but also be reset when the device resets, eliminating any advantage of using SLEEP_NETWORK_STANDBY.

The Gen 3 devices (Argon, Boron, Xenon) can only wake from SLEEP_MODE_DEEP by a high level on D8. It's not possible to exit SLEEP_MODE_DEEP based on time because the clock does not run in standby sleep mode on the nRF52. It's possible wake from HIBERNATE mode using other pins; you should use the newer sleep API that supports HIBERNATE if possible.

Also, the real-time-clock (Time class) will not be set when waking up from SLEEP_MODE_DEEP or HIBERNATE. It will get set on after the first cloud connection, but initially it will not be set.


System.sleep(SLEEP_MODE_SOFTPOWEROFF) is just like SLEEP_MODE_DEEP, with the added benefit that it also sleeps the Fuel Gauge. This is the only way to achieve the lowest quiescent current on the device, apart from sleeping the Fuel Gauge before calling SLEEP_MODE_DEEP.

// SYNTAX
System.sleep(SLEEP_MODE_SOFTPOWEROFF);


Gen 2 Devices:

Gen 2 devices (Photon, P1, Electron, E Series):

System.sleep(SLEEP_MODE_DEEP, long seconds) can be used to put the entire device into a deep sleep mode, sometimes referred to as "standby sleep mode."

// SYNTAX
System.sleep(SLEEP_MODE_DEEP, long seconds);

// EXAMPLE USAGE

// Put the device into deep sleep for 60 seconds
System.sleep(SLEEP_MODE_DEEP, 60);
// The device LED will shut off during deep sleep

// Since 0.8.0
// Put the device into deep sleep for 60 seconds and disable WKP pin
System.sleep(SLEEP_MODE_DEEP, 60, SLEEP_DISABLE_WKP_PIN);
// The device LED will shut off during deep sleep
// The device will not wake up if a rising edge signal is applied to WKP

Note: Be sure WKP is LOW before going into SLEEP_MODE_DEEP with a time interval! If WKP is high, even if it falls and rises again the device will not wake up. Additionally, the time limit will not wake the device either, and the device will stay in sleep mode until reset or power cycled.

Since 1.5.0:

You can also specify a value using chrono literals, for example: System.sleep(SLEEP_MODE_DEEP, 2min) for 2 minutes.

The device will automatically wake up after the specified number of seconds or by applying a rising edge signal to the WKP pin.

Since 0.8.0: Wake up by WKP pin may be disabled by passing SLEEP_DISABLE_WKP_PIN option to System.sleep(): System.sleep(SLEEP_MODE_DEEP, long seconds, SLEEP_DISABLE_WKP_PIN).


System.sleep(SLEEP_MODE_SOFTPOWEROFF, long seconds) is just like SLEEP_MODE_DEEP, with the added benefit that it also sleeps the Fuel Gauge. This is the only way to achieve the lowest quiescent current on the device, apart from sleeping the Fuel Gauge before calling SLEEP_MODE_DEEP. This is also the same net result as used in the user-activated Soft Power Down feature when you double-tap the Mode button and the Electron powers down.

// SYNTAX
System.sleep(SLEEP_MODE_SOFTPOWEROFF, long seconds);

In this particular mode, the device shuts down the network subsystem and puts the microcontroller in a standby mode.

When the device awakens from deep sleep, it will reset and run all user code from the beginning with no values being maintained in memory from before the deep sleep.

The standby mode is used to achieve the lowest power consumption. After entering standby mode, the RAM and register contents are lost except for retained memory.

For cellular devices, reconnecting to cellular after SLEEP_MODE_DEEP will generally use more power than using SLEEP_NETWORK_STANDBY for periods less than 15 minutes. You should definitely avoid using SLEEP_MODE_DEEP on cellular devices for periods less than 10 minutes. Your SIM can be blocked by your mobile carrier for aggressive reconnection if you reconnect to cellular very frequently.


System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode) can be used to put the entire device into a stop mode with wakeup on interrupt. In this particular mode, the device shuts down the network and puts the microcontroller in a stop mode with configurable wakeup pin and edge triggered interrupt. When the specific interrupt arrives, the device awakens from stop mode.

The device will not reset before going into stop mode so all the application variables are preserved after waking up from this mode. This mode achieves the lowest power consumption while retaining the contents of RAM and registers.

// SYNTAX
System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode);
System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode, SLEEP_NETWORK_STANDBY);

// EXAMPLE USAGE

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 pin
System.sleep(D1,RISING);
// The device LED will shut off during sleep

The Electron and Boron maintain the cellular connection for the duration of the sleep when SLEEP_NETWORK_STANDBY is given as the last parameter value. On wakeup, the device is able to reconnect to the cloud much quicker, at the expense of increased power consumption during sleep. Roughly speaking, for sleep periods of less than 15 minutes, SLEEP_NETWORK_STANDBY uses less power.

For sleep periods of less than 10 minutes you must use SLEEP_NETWORK_STANDBY. Your SIM can be blocked by your mobile carrier for aggressive reconnection if you reconnect to cellular very frequently. Using SLEEP_NETWORK_STANDBY keeps the connection up and prevents your SIM from being blocked.

Parameters:

  • wakeUpPin: the wakeup pin number. supports external interrupts on the following pins:
    • supports external interrupts on the following pins:
  • edgeTriggerMode: defines when the interrupt should be triggered. Three constants are predefined as valid values:
    • CHANGE to trigger the interrupt whenever the pin changes value,
    • RISING to trigger when the pin goes from low to high,
    • FALLING for when the pin goes from high to low.
  • Cellular devices: SLEEP_NETWORK_STANDBY: optional - keeps the cellular modem in a standby state while the device is sleeping..

The device will automatically reconnect to the cloud if the cloud was connected when sleep was entered. If disconnected prior to sleep, it will stay disconnected on wake.

Since 0.8.0:

// SYNTAX
System.sleep(std::initializer_list<pin_t> wakeUpPins, InterruptMode edgeTriggerMode);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, InterruptMode edgeTriggerMode);

System.sleep(std::initializer_list<pin_t> wakeUpPins, std::initializer_list<InterruptMode> edgeTriggerModes);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, const InterruptMode* edgeTriggerModes, size_t edgeTriggerModesCount);

System.sleep(std::initializer_list<pin_t> wakeUpPins, InterruptMode edgeTriggerMode, SLEEP_NETWORK_STANDBY);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, InterruptMode edgeTriggerMode, SLEEP_NETWORK_STANDBY);

System.sleep(std::initializer_list<pin_t> wakeUpPins, std::initializer_list<InterruptMode> edgeTriggerModes, SLEEP_NETWORK_STANDBY);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, const InterruptMode* edgeTriggerModes, size_t edgeTriggerModesCount, SLEEP_NETWORK_STANDBY);

// EXAMPLE USAGE

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and A4 pins
// Specify the pins in-place (using std::initializer_list)
System.sleep({D1, A4}, RISING);
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and FALLING edge interrupt on A4 pin
// Specify the pins and edge trigger mode in-place (using std::initializer_list)
System.sleep({D1, A4}, {RISING, FALLING});
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and A4 pins
// Specify the pins in an array
pin_t wakeUpPins[2] = {D1, A4};
System.sleep(wakeUpPins, 2, RISING);
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and FALLING edge interrupt on A4 pin
// Specify the pins and edge trigger modes in an array
pin_t wakeUpPins[2] = {D1, A4};
InterruptMode edgeTriggerModes[2] = {RISING, FALLING};
System.sleep(wakeUpPins, 2, edgeTriggerModes, 2);
// The device LED will shut off during sleep

Multiple wakeup pins may be specified for this mode.

Parameters:

  • wakeUpPins: a list of wakeup pins:

    • std::initializer_list<pin_t>: e.g. {D1, D2, D3}
    • a pin_t array. The length of the array needs to be provided in wakeUpPinsCount argument
    • supports external interrupts on the following pins:
  • wakeUpPinsCount: the length of the list of wakeup pins provided in wakeUpPins argument. This argument should only be specified if wakeUpPins is an array of pins and not an std::initializer_list.

  • edgeTriggerMode: defines when the interrupt should be triggered. Three constants are predefined as valid values:
    • CHANGE to trigger the interrupt whenever the pin changes value,
    • RISING to trigger when the pin goes from low to high,
    • FALLING for when the pin goes from high to low.
  • edgeTriggerModes: defines when the interrupt should be triggered on a specific pin from wakeUpPins list:
    • std::initializer_list<InterruptMode>: e.g. {RISING, FALLING, CHANGE}
    • an InterruptMode array. The length of the array needs to be provided in edgeTriggerModesCount argument
  • edgeTriggerModesCount: the length of the edge trigger modes provided in edgeTriggerModes argument. This argument should only be specified if edgeTriggerModes is an array of modes and not an std::initializer_list.
  • Cellular devices: SLEEP_NETWORK_STANDBY: optional - keeps the cellular modem in a standby state while the device is sleeping..
// SYNTAX
System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode, long seconds);
System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode, SLEEP_NETWORK_STANDBY, long seconds);

// EXAMPLE USAGE

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 pin or wakeup after 60 seconds whichever comes first
System.sleep(D1,RISING,60);
// The device LED will shut off during sleep

System.sleep(uint16_t wakeUpPin, uint16_t edgeTriggerMode, long seconds) can be used to put the entire device into a stop mode with wakeup on interrupt or wakeup after specified seconds. In this particular mode, the device shuts network subsystem and puts the microcontroller in a stop mode with configurable wakeup pin and edge triggered interrupt or wakeup after the specified seconds. When the specific interrupt arrives or upon reaching the configured timeout, the device awakens from stop mode. The device will not reset before going into stop mode so all the application variables are preserved after waking up from this mode. The voltage regulator is put in low-power mode. This mode achieves the lowest power consumption while retaining the contents of RAM and registers.

Parameters:

  • wakeUpPin: the wakeup pin number. supports external interrupts on the following pins:
    • supports external interrupts on the following pins:
  • edgeTriggerMode: defines when the interrupt should be triggered. Three constants are predefined as valid values:
    • CHANGE to trigger the interrupt whenever the pin changes value,
    • RISING to trigger when the pin goes from low to high,
    • FALLING for when the pin goes from high to low.
  • seconds: wakeup after the specified number of seconds (0 = no alarm is set). On Gen 3 devices, the maximum sleep time is approximately 24 days.
  • Cellular devices: SLEEP_NETWORK_STANDBY: optional - keeps the cellular modem in a standby state while the device is sleeping..

Since 1.5.0:

You can also specify a value using chrono literals, for example: System.sleep(D1, RISING, 2min) for 2 minutes.

Since 0.8.0:

// SYNTAX
System.sleep(std::initializer_list<pin_t> wakeUpPins, InterruptMode edgeTriggerMode, long seconds);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, InterruptMode edgeTriggerMode, long seconds);

System.sleep(std::initializer_list<pin_t> wakeUpPins, std::initializer_list<InterruptMode> edgeTriggerModes, long seconds);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, const InterruptMode* edgeTriggerModes, size_t edgeTriggerModesCount, long seconds);

System.sleep(std::initializer_list<pin_t> wakeUpPins, InterruptMode edgeTriggerMode, SLEEP_NETWORK_STANDBY, long seconds);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, InterruptMode edgeTriggerMode, SLEEP_NETWORK_STANDBY, long seconds);

System.sleep(std::initializer_list<pin_t> wakeUpPins, std::initializer_list<InterruptMode> edgeTriggerModes, SLEEP_NETWORK_STANDBY, long seconds);
System.sleep(const pin_t* wakeUpPins, size_t wakeUpPinsCount, const InterruptMode* edgeTriggerModes, size_t edgeTriggerModesCount, SLEEP_NETWORK_STANDBY, long seconds);

// EXAMPLE USAGE

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and A4 pins or wakeup after 60 seconds whichever comes first
// Specify the pins in-place (using std::initializer_list)
System.sleep({D1, A4}, RISING, 60);
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and FALLING edge interrupt on A4 pin or wakeup after 60 seconds whichever comes first
// Specify the pins and edge trigger mode in-place (using std::initializer_list)
System.sleep({D1, A4}, {RISING, FALLING}, 60);
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and A4 pins or wakeup after 60 seconds whichever comes first
// Specify the pins in an array
pin_t wakeUpPins[2] = {D1, A4};
System.sleep(wakeUpPins, 2, RISING, 60);
// The device LED will shut off during sleep

// Put the device into stop mode with wakeup using RISING edge interrupt on D1 and FALLING edge interrupt on A4 pin or wakeup after 60 seconds whichever comes first
// Specify the pins and edge trigger modes in an array
pin_t wakeUpPins[2] = {D1, A4};
InterruptMode edgeTriggerModes[2] = {RISING, FALLING};
System.sleep(wakeUpPins, 2, edgeTriggerModes, 2, 60);
// The device LED will shut off during sleep

Multiple wakeup pins may be specified for this mode.

Parameters:

  • wakeUpPins: a list of wakeup pins:
    • std::initializer_list<pin_t>: e.g. {D1, D2, D3}
    • a pin_t array. The length of the array needs to be provided in wakeUpPinsCount argument
    • supports external interrupts on the following pins:
  • wakeUpPinsCount: the length of the list of wakeup pins provided in wakeUpPins argument. This argument should only be specified if wakeUpPins is an array of pins and not an std::initializer_list.
  • edgeTriggerMode: defines when the interrupt should be triggered. Three constants are predefined as valid values:
    • CHANGE to trigger the interrupt whenever the pin changes value,
    • RISING to trigger when the pin goes from low to high,
    • FALLING for when the pin goes from high to low.
  • edgeTriggerModes: defines when the interrupt should be triggered on a specific pin from wakeUpPins list:
    • std::initializer_list<InterruptMode>: e.g. {RISING, FALLING, CHANGE}
    • an InterruptMode array. The length of the array needs to be provided in edgeTriggerModesCount argument
  • edgeTriggerModesCount: the length of the edge trigger modes provided in edgeTriggerModes argument. This argument should only be specified if edgeTriggerModes is an array of modes and not an std::initializer_list.
  • seconds: wakeup after the specified number of seconds (0 = no alarm is set). On Gen 3 devices, the maximum sleep time is approximately 24 days.
  • Cellular devices: SLEEP_NETWORK_STANDBY: optional - keeps the cellular modem in a standby state while the device is sleeping..

Since 0.4.5. The state of the network and Cloud connections is restored when the system wakes up from sleep. So if the device was connected to the cloud before sleeping, then the cloud connection is automatically resumed on waking up.

Since 0.5.0 In automatic modes, the sleep() function doesn't return until the cloud connection has been established. This means that application code can use the cloud connection as soon as sleep() returns. In previous versions, it was necessary to call Particle.process() to have the cloud reconnected by the system in the background.

Since 0.8.0 All System.sleep() variants return an instance of SleepResult class that can be queried on the result of System.sleep() execution.

Since 0.8.0 An application may check the information about the latest sleep by using System.sleepResult() or additional accessor methods:


System.sleep(long seconds) does NOT stop the execution of application code (non-blocking call). Application code will continue running while the network module is in this mode.

This mode is not recommended; it is better to manually control the network connection using SYSTEM_MODE(SEMI_AUTOMATIC) instead.

// SYNTAX
System.sleep(long seconds);

// EXAMPLE USAGE

// Put the Wi-Fi module in standby (low power) for 5 seconds
System.sleep(5);
// The device LED will breathe white during sleep

Since 1.5.0:

You can also specify a value using chrono literals, for example: System.sleep(2min) for 2 minutes.