A class for managing long deep sleep cycles with RTC memory and optimized WiFi reconnection on ESP8266. More...

#include <LongDeepSleep.h>

Public Types
enum	{ DEEP_SLEEP_DONE = 0 , DEEP_SLEEP_UNTIL_DONE = 1 , OTHER_WAKE_UP_REASON = -1 , RTC_MEMORY_CHECK_FAILED = -2 , ABSOLUTE_TIME_CHECK_FAILED = -3 }
	Return codes for checkWakeUp(). More...

enum	{ OK = 0 , NO_TIME_CLIENT = -1 , NO_ABSOLUE_TIME_AVAILABLE = -2 , SPECIFIED_TIME_IN_PAST = 1 }
	Return codes for performLongDeepSleepUntil(int). More...

enum	CloneWorkaround { NO_WORKAROUND = 0 , WEMOS_D1_V3_CLONE = 1 , ESP01_MODULE = 2 , UNKNOWN = 3 }
	Differrent types of workarounds for deepsleep problems with clone modules. More...

Public Member Functions
	LongDeepSleep (CloneWorkaround param_cloneWorkaround, const char ssid=nullptr, const char password=nullptr, NTPClient *ntpClient=nullptr)
	Second constructor for clone modules with deep sleep problems.

	LongDeepSleep (const char ssid=nullptr, const char password=nullptr, NTPClient *ntpClient=nullptr)
	Constructor.

int	checkWakeUp (uint32_t toleranceSec=0, uint16_t failureSleepSecs=0)
	Checks whether the device woke up from deep sleep and handles state.

void	performLongDeepSleep (uint64_t sleepTimeSec)
	Sleep for a relative amount of time (seconds).

int	performLongDeepSleepUntil (uint64_t epocheTime)
	Sleep until an absolute epoch time.

void	restoreWifi (uint16_t failureSleepSecs=0)
	Restores WiFi after wake-up from deep sleep.

void	releaseWifi ()
	Releases WiFi to conserve power.

void	changeWaitCycles (uint16_t quickConnectCycles, uint16_t wifiWaitCycles)
	Customizes connection wait cycles.

uint32_t	rebootCounter ()
	Releases WiFi to conserve power.

void	resetRebootCounter ()
	Releases WiFi to conserve power.

Static Public Member Functions
static uint32_t	UsedRTCDataSize ()
	Releases WiFi to conserve power.

Detailed Description

A class for managing long deep sleep cycles with RTC memory and optimized WiFi reconnection on ESP8266.

This class allows deep sleep durations beyond the hardware-imposed ~3.5-hour limit by using RTC memory to persist sleep state between wake-ups.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Return codes for checkWakeUp().

Enumerator
DEEP_SLEEP_DONE	Wake-up completed, proceed. WiFi not yet restored.
DEEP_SLEEP_UNTIL_DONE	Wake-up completed, WiFi and time server already available.
OTHER_WAKE_UP_REASON	Wake-up due to other reason (reset, power-on, etc.).
RTC_MEMORY_CHECK_FAILED	RTC memory is invalid or corrupted.
ABSOLUTE_TIME_CHECK_FAILED	Wake-up for absolute time failed due to time server/WiFi issues.

◆ anonymous enum

anonymous enum

Return codes for performLongDeepSleepUntil(int).

Enumerator
OK	Will never be seen as then the ESP will go into deep sleep.
NO_TIME_CLIENT	No time client specified when creating class longdeepsleep, hence this function is not available.
NO_ABSOLUE_TIME_AVAILABLE	time client was specified, but it was not possible to determine an absolute time, hence this function is not available.
SPECIFIED_TIME_IN_PAST	The specified until time stamp lies in the past, hence sleep not required, do whatever you want to do then.

◆ CloneWorkaround

enum LongDeepSleep::CloneWorkaround

Differrent types of workarounds for deepsleep problems with clone modules.

Enumerator
NO_WORKAROUND	This is standard solution, no workaround is applied.
WEMOS_D1_V3_CLONE	This worked for my Wemos D1 mini V3 clones.
ESP01_MODULE	esp01 modules, not tested yet. Just copy/pasted code from here: https://github.com/nokxs/esp8266-alternative-deep-sleep
UNKNOWN

Constructor & Destructor Documentation

◆ LongDeepSleep() [1/2]

LongDeepSleep::LongDeepSleep	(	CloneWorkaround	param_cloneWorkaround,
		const char *	ssid = nullptr,
		const char *	password = nullptr,
		NTPClient *	ntpClient = nullptr )

Second constructor for clone modules with deep sleep problems.

Parameters

param_cloneWorkaround.	This is to selected the clone workaround. Use one of the enums form CloneWorkaround.
ssid	WiFi SSID. (optional in case no absolute time for deep sleep is required.)
password	WiFi password. (optional in case no absolute time for deep sleep is required.)
ntpClient	pointer to a configured NTPClient instance. (optional in case no absolute time for deep sleep is rquired.)

◆ LongDeepSleep() [2/2]

LongDeepSleep::LongDeepSleep	(	const char *	ssid = nullptr,
		const char *	password = nullptr,
		NTPClient *	ntpClient = nullptr )

inline

Constructor.

Parameters

ssid	WiFi SSID. (optional in case no absolute time for deep sleep is required.)
password	WiFi password. (optional in case no absolute time for deep sleep is required.)
ntpClient	pointer to a configured NTPClient instance. (optional in case no absolute time for deep sleep is rquired.)

Member Function Documentation

◆ changeWaitCycles()

void LongDeepSleep::changeWaitCycles	(	uint16_t	quickConnectCycles,
		uint16_t	wifiWaitCycles )

inline

Customizes connection wait cycles.

One cycle is 10 ms. Default is 20/2000 = 200ms/20s. It's not recommended to change these values, but funciton is provided for completeness.

Parameters

quickConnectCycles	Max cycles to reconnect via saved BSSID/channel.
wifiWaitCycles	Max cycles to establish normal WiFi.

◆ checkWakeUp()

int LongDeepSleep::checkWakeUp	(	uint32_t	toleranceSec = 0,
		uint16_t	failureSleepSecs = 0 )

Checks whether the device woke up from deep sleep and handles state.

Depending on prior sleep configuration, may re-enter deep sleep if targeted sleep time is not elapsed (relative) or reached (absolute).

Parameters

toleranceSec	Allowed wake-up deviation in seconds (in case woke up a little bit earlier.)
failureSleepSecs	If >0, sleep this long again when wifi connection or time server (only if specified) update fails. This parameter is only relevant in case we got with performLongDeepSleepUntil method into deep sleep and woke up to get into this function.

Returns: One of the enum codes above.

◆ performLongDeepSleep()

void LongDeepSleep::performLongDeepSleep ( uint64_t sleepTimeSec )

Sleep for a relative amount of time (seconds).

Deep sleep is broken into cycles of up to ~3.5 hours.

Parameters

sleepTimeSec Time to sleep in seconds.

◆ performLongDeepSleepUntil()

int LongDeepSleep::performLongDeepSleepUntil ( uint64_t epocheTime )

Sleep until an absolute epoch time.

Requires a wifi connection and an updated NTPClient with valid time.

Parameters

epocheTime Target epoch time (in seconds).

◆ rebootCounter()

uint32_t LongDeepSleep::rebootCounter ( )

inline

Releases WiFi to conserve power.

In case you want to know how often the ESP reboots until you manually reset the counter, you can get the current value via this function. The counter is increased by one every time the constructor of this class is called after the value was restored from RTC memory. Please note that you need to manually reset the value by function resetRebootCounter() whenever you need to.

◆ releaseWifi()

void LongDeepSleep::releaseWifi ( )

Releases WiFi to conserve power.

Saves connection state to RTC for fast reconnect. Might be used by users in their part, when a larger part might be executed without WiFi and energy consumption is really critical. Otherwise this is called automatically within the performLongDeepSleep-functions.

◆ resetRebootCounter()

void LongDeepSleep::resetRebootCounter ( )

inline

Releases WiFi to conserve power.

This function resets an internal counter to zero. The counter is increased by one every time the constructor of this class is called after the value was restored from RTC memory.

◆ restoreWifi()

void LongDeepSleep::restoreWifi ( uint16_t failureSleepSecs = 0 )

Restores WiFi after wake-up from deep sleep.

Optimizes for minimal connection time. Falls back to deep sleep if reconnect fails.

Parameters

failureSleepSecs If >0, sleep this long again when wifi connection or time server (only if specified) update fails. Users might need to call this as it's only automatically called when woken up the last time after the system went into deep sleep via function performLongDeepSleepUntil.

◆ UsedRTCDataSize()

static uint32_t LongDeepSleep::UsedRTCDataSize ( )

inlinestatic

Releases WiFi to conserve power.

Returns the size of the RTC memory that is used internally. You can use this to offset your own RTC memory usage in case you need to store something else to survive reboots. Be aware that the workarounds for weak ESP8266 modules need another 4 bytes of memory. They are using the same function as well. You might have a look into file CloneDeepSleepWorkaround.cpp for a hint how to use it.

The documentation for this class was generated from the following files:

src/LongDeepSleep.h
src/LongDeepSleep.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ CloneWorkaround

Constructor & Destructor Documentation

◆ LongDeepSleep() [1/2]

◆ LongDeepSleep() [2/2]

Member Function Documentation

◆ changeWaitCycles()

◆ checkWakeUp()

◆ performLongDeepSleep()

◆ performLongDeepSleepUntil()

◆ rebootCounter()

◆ releaseWifi()

◆ resetRebootCounter()

◆ restoreWifi()

◆ UsedRTCDataSize()