From 2a4081b079f05df5f44bee1333c048393d99c66f Mon Sep 17 00:00:00 2001
From: Macro Yau <MacroYau@users.noreply.github.com>
Date: Wed, 1 Jun 2016 11:13:33 +0800
Subject: [PATCH] Added support for RTC user memory in ESP-specific APIs.
 (#1836)

---
 cores/esp8266/Esp.cpp                         | 18 +++++++
 cores/esp8266/Esp.h                           |  3 ++
 doc/libraries.md                              |  2 +
 .../examples/RTCUserMemory/RTCUserMemory.ino  | 52 +++++++++++++++++++
 4 files changed, 75 insertions(+)
 create mode 100644 libraries/esp8266/examples/RTCUserMemory/RTCUserMemory.ino

diff --git a/cores/esp8266/Esp.cpp b/cores/esp8266/Esp.cpp
index 3416c9b91..bd0c5c6d3 100644
--- a/cores/esp8266/Esp.cpp
+++ b/cores/esp8266/Esp.cpp
@@ -112,6 +112,24 @@ void EspClass::deepSleep(uint32_t time_us, WakeMode mode)
     esp_yield();
 }
 
+bool EspClass::rtcUserMemoryRead(uint32_t *data, size_t size)
+{
+    if (size > 512) {
+        return false;
+    } else {
+        return system_rtc_mem_read(64, data, size);
+    }
+}
+
+bool EspClass::rtcUserMemoryWrite(uint32_t *data, size_t size)
+{
+    if (size > 512) {
+        return false;
+    } else {
+        return system_rtc_mem_write(64, data, size);
+    }
+}
+
 extern "C" void __real_system_restart_local();
 void EspClass::reset(void)
 {
diff --git a/cores/esp8266/Esp.h b/cores/esp8266/Esp.h
index 80b041196..b6914cdd7 100644
--- a/cores/esp8266/Esp.h
+++ b/cores/esp8266/Esp.h
@@ -94,6 +94,9 @@ class EspClass {
 
         void deepSleep(uint32_t time_us, RFMode mode = RF_DEFAULT);
 
+        bool rtcUserMemoryRead(uint32_t *data, size_t size);
+        bool rtcUserMemoryWrite(uint32_t *data, size_t size);
+
         void reset();
         void restart();
 
diff --git a/doc/libraries.md b/doc/libraries.md
index d3cda54fb..ae0e9f0de 100644
--- a/doc/libraries.md
+++ b/doc/libraries.md
@@ -83,6 +83,8 @@ APIs related to deep sleep and watchdog timer are available in the `ESP` object,
 
 `ESP.deepSleep(microseconds, mode)` will put the chip into deep sleep. `mode` is one of `WAKE_RF_DEFAULT`, `WAKE_RFCAL`, `WAKE_NO_RFCAL`, `WAKE_RF_DISABLED`. (GPIO16 needs to be tied to RST to wake from deepSleep.)
 
+`ESP.rtcUserMemoryWrite(&data, sizeof(data))` and `ESP.rtcUserMemoryRead(&data, sizeof(data))` allow struct data with the maximum size of 512 bytes to be stored and retrieved from the RTC user memory of the chip respectively. The stored data can be retained between deep sleep cycles. However, the data might be lost after power cycling the chip.
+
 `ESP.restart()` restarts the CPU.
 
 `ESP.getResetReason()` returns String containing the last reset resaon in human readable format.
diff --git a/libraries/esp8266/examples/RTCUserMemory/RTCUserMemory.ino b/libraries/esp8266/examples/RTCUserMemory/RTCUserMemory.ino
new file mode 100644
index 000000000..6506ffd05
--- /dev/null
+++ b/libraries/esp8266/examples/RTCUserMemory/RTCUserMemory.ino
@@ -0,0 +1,52 @@
+// Example: Storing struct data in RTC user memory
+//
+// Struct data with the maximum size of 512 bytes can be stored in the RTC user memory using the ESP-specifc APIs.
+// The stored data can be retained between deep sleep cycles. However, the data might be lost after power cycling the ESP8266.
+//
+// Created Mar 30, 2016 by Macro Yau.
+//
+// This example code is in the public domain.
+
+typedef struct {
+  byte data[512];
+} rtcUserMemory;
+
+rtcUserMemory mem;
+
+void printMemory(bool readFromRtc) {
+  char buf[3];
+  Serial.print(readFromRtc ? "Read:  " : "Write: ");
+  for (int i = 0; i < sizeof(mem); i++) {
+    sprintf(buf, "%02X", mem.data[i]);
+    Serial.print(buf);
+    Serial.print(" ");
+  }
+  Serial.println();
+}
+
+void setup() {
+  Serial.begin(115200);
+  Serial.println();
+
+  // Read struct from RTC user memory
+  if (ESP.rtcUserMemoryRead((uint32_t*) &mem, sizeof(mem))) {
+    printMemory(true);
+  }
+
+  // Generate new data set for the struct
+  for (int i = 0; i < sizeof(mem); i++) {
+    mem.data[i] = random(0, 128);
+  }
+
+  // Write struct to RTC user memory
+  if (ESP.rtcUserMemoryWrite((uint32_t*) &mem, sizeof(mem))) {
+    printMemory(false);
+  }
+  
+  // Enter deep sleep mode for 10 seconds
+  ESP.deepSleep(10e6);
+}
+
+void loop() {
+  
+}