Added support for RTC user memory in ESP-specific APIs. (#1836)

Author: MacroYau

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)
 {

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

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.

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() {
+  
+}