From b356d07422a7fdefb1d8dad3522c72424eec8ed9 Mon Sep 17 00:00:00 2001
From: Mateusz Zakarczemny <m.zakarczemny@gmail.com>
Date: Tue, 19 Jul 2022 13:45:11 +0200
Subject: [PATCH] Update System.h with info about the deep sleep mode. (#2526)

* Update System.h

* Check documentation output, revise

* Fix comments indentation.

Co-authored-by: mikee47 <mike@sillyhouse.net>
Co-authored-by: Slavey Karadzhov <slav@attachix.com>
---
 Sming/Platform/System.h | 47 +++++++++++++++++++++++++----------------
 1 file changed, 29 insertions(+), 18 deletions(-)

diff --git a/Sming/Platform/System.h b/Sming/Platform/System.h
index 562e5d5074..ac5467527b 100644
--- a/Sming/Platform/System.h
+++ b/Sming/Platform/System.h
@@ -60,7 +60,7 @@ class ISystemReadyHandler
 	}
 
 	/** @brief  Handle <i>system ready</i> events
-    */
+	 */
 	virtual void onSystemReady() = 0;
 };
 
@@ -112,8 +112,8 @@ class SystemClass
 	static bool initialize();
 
 	/** @brief  Check if system ready
-     *  @retval bool True if system initialisation is complete and system is now ready
-     */
+	 *  @retval bool True if system initialisation is complete and system is now ready
+	 */
 	bool isReady()
 	{
 		return state == eSS_Ready;
@@ -124,45 +124,56 @@ class SystemClass
 	 *  @note A delay is often required to allow network callback code to complete correctly.
 	 *  The restart is always deferred, either using the task queue (if deferMillis == 0)
 	 *  or using a timer. This method always returns immediately.
-     */
+	 */
 	void restart(unsigned deferMillis = 0);
 
 	/** @brief  Set the CPU frequency
-     *  @param  freq Frequency to set CPU
+	 *  @param  freq Frequency to set CPU
 	 *  @retval bool true on success
-     */
+	 */
 	bool setCpuFrequency(CpuFrequency freq)
 	{
 		return system_update_cpu_freq(freq);
 	}
 
 	/** @brief  Get the CPU frequency
-     *  @retval CpuFrequency The frequency of the CPU
-     */
+	 *  @retval CpuFrequency The frequency of the CPU
+	 */
 	CpuFrequency getCpuFrequency()
 	{
 		return static_cast<CpuFrequency>(system_get_cpu_freq());
 	}
 
-	/** @brief  Enter deep sleep mode
-     *  @param  timeMilliseconds Quantity of milliseconds to remain in deep sleep mode
-     *  @param  options Deep sleep options
-     */
+	/** @brief  Enter deep sleep mode.
+	 *  Deep sleep turns off processor and keeps only the RTC memory active.
+	 *  @param  timeMilliseconds Quantity of milliseconds to remain in deep sleep mode
+	 *  @param  options Deep sleep options
+	 *
+	 *  @note Determine reset cause like this:
+	 *
+	 * 		auto info = system_get_rst_info();
+	 *  	if(info->reason == REASON_DEEP_SLEEP_AWAKE) {
+	 *    		// ...
+	 *  	}
+	 *
+	 * 	@note ESP8266: Ensure GPIO 16 (XPD_DCDC) is connected to RST (EXT_RSTB).
+	 *  and call pinMode(16, WAKEUP_PULLUP) to enable wakeup from deep sleep.
+	 */
 	bool deepSleep(uint32_t timeMilliseconds, DeepSleepOptions options = eDSO_RF_CAL_BY_INIT_DATA);
 
 	/** @brief  Set handler for <i>system ready</i> event
-     *  @param  readyHandler Function to handle event
-     *  @note if system is ready, callback is executed immediately without deferral
-     */
+	 *  @param  readyHandler Function to handle event
+	 *  @note if system is ready, callback is executed immediately without deferral
+	 */
 	void onReady(SystemReadyDelegate readyHandler)
 	{
 		queueCallback(readyHandler);
 	}
 
 	/** @brief  Set handler for <i>system ready</i> event
-     *  @param  readyHandler Function to handle event
-     *  @note if system is ready, callback is executed immediately without deferral
-     */
+	 *  @param  readyHandler Function to handle event
+	 *  @note if system is ready, callback is executed immediately without deferral
+	 */
 	void onReady(ISystemReadyHandler* readyHandler)
 	{
 		if(readyHandler != nullptr) {