Added CreditMigrate.ino description

examples/CreditMigrate/CreditMigrate.ino

@@ -23,20 +23,20 @@
  * @param  size  Returns a size of the eeprom partition
  * @return Retrieved data buffered pointer
  */
-uint8_t* retrievePartition(size_t *size) {
-  const esp_partition_t*  eeprom = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "eeprom");
+uint8_t* retrievePartition(const char* name, size_t *size) {
+  const esp_partition_t*  eeprom = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, name);
 
   if (!eeprom) {
-    Serial.println("EEPROM partition not found");
+    Serial.printf("%s partition not found\n", name);
     return nullptr;
   }
   uint8_t*  pBuf = (uint8_t*)malloc(eeprom->size);
   if (!pBuf) {
-    Serial.println("Insufficient memory to retrieve EEPROM partition");
+    Serial.printf("Insufficient memory to retrieve %s partition\n", name);
     return nullptr;
   }
   if (esp_partition_read(eeprom, 0, (void*)pBuf, eeprom->size) != ESP_OK) {
-    Serial.println("Unable to read EEPROM partition");
+    Serial.printf("Unable to read %s partition\n", name);
     free(pBuf);
     return nullptr;
   }
@@ -49,18 +49,18 @@ uint8_t* retrievePartition(size_t *size) {
  * @param  eeprom  Retrieved data buffered pointer
  * @param  size    Retrieved data size
  */
-void convert(uint8_t* eeprom, size_t size) {
+void convert(const uint8_t* eeprom, const size_t size) {
   uint8_t*  ac_credt = (uint8_t*)strstr((const char*)eeprom, "AC_CREDT");
   if (!ac_credt)
-    Serial.println("AC_CREDT identifier not found in EEPROM partition.");
+    Serial.println("AC_CREDT identifier not found in the partition.");
   else {
     AutoConnectCredential credential;
-    uint8_t*  bp = ac_credt + sizeof("AC_CREDT") - 1;
+    uint8_t*  bp = ac_credt + sizeof("AC_CREDT") - sizeof('\0');
     uint8_t*  dp = bp;
     uint8_t   entries = *dp++;
     size_t    dpSize = *dp++;
     dpSize += *dp++ << 8;
-    Serial.printf("%d stored credential(s), size:%d\n", (int)entries, dpSize);
+    Serial.printf("%d stored credential(s),size:%d\n", (int)entries, dpSize);
 
     // Start EEPROM to Preferences migration
     uint8_t*  ep = dp + dpSize - 1;
@@ -92,7 +92,7 @@ void convert(uint8_t* eeprom, size_t size) {
         Serial.printf(":%02x", config.bssid[ei]);
       }
       bool rc = credential.save(&config);
-      Serial.println(rc ? " saved" : " failed to save");
+      Serial.println(rc ? " transferred" : " failed to save Preferences");
     }
   }
 }
@@ -103,11 +103,11 @@ void setup() {
   Serial.println();
 
   size_t    eepromSize;
-  uint8_t*  eepromData = retrievePartition(&eepromSize);
+  uint8_t*  eepromData = retrievePartition("eeprom", &eepromSize);
   if (eepromData) {
-    Serial.println("Start EEPROM migration to Preferences");
+    Serial.println("Start migration to Preferences");
     convert(eepromData, eepromSize);
-    Serial.println("Conversion ended");
+    Serial.println("Transfer ended");
     free(eepromData);
   }
 }

examples/CreditMigrate/CreditMigrate.md

@@ -0,0 +1,24 @@
+## CreditMigrate.ino - A migration tool for the saved credentials
+
+### Description
+
+Since AutoConnect v1.0.0 for ESP32, the storage location in the flash of established credentials has moved from EEPROM to Preferences. After You update AutoConnect to v1.0.0, past credentials saved by v0.9.12 earlier will *not be accessible* from the AutoConnect menu - **Open SSIDs**. You need to transfer once the stored credentials from the EEPROM area to the Preferences area.
+
+**CreditMigrate.ino** transports the credentials stored in EEPROM to the Preferences area to inherit them for AutoConnect v1.0.0 or later.
+
+### Restrictions
+
+- CreditMigrate.ino is only applicable to ESP32 boards. It cannot be executed with a compile error on the ESP8266 boards. (ESP8266 does not require credential migration.)
+- CreditMigrate.ino will work properly with the installed ESP32 core version is 1.0.2 or earlier. (In ESP32 core 1.0.3, EEPROM area has moved from partition to the nvs. CreditMigrate.ino will not work properly with ESP32 core 1.0.3. ESP32 core 1.0.2 is recommended)
+
+### Saved credentials migration procedure on your ESP32 board
+
+1. Connect your host PC and ESP32 module with serial and start Arduino IDE.
+2. Confirm that the version of the ESP32 core currently installed via the board manager of ArduinoIDE is 1.0.2 or earlier.
+3. Open **CreditMigrate.ino** as a sketch in the examples of the AutoConnect library folder.
+4. From the Arduino IDE menu: **Tools > Board:** to select the one that matches your ESP32 board and set it up.
+5. Open the serial monitor of Arduino IDE.
+6. From the Arduino IDE menu: **Sketch > Upload** to compile and upload the sketch.
+7. It will transport the past credentials that had been stored in EEPROM to Preferences. You can confirm the result on the serial monitor.
+
+<img src="../../mkdocs/images/creditmigrate.png">