EEPROM library - emulated EEPROM in user option bytes (#103)

* Emulate EEPROM using the user select word storage area. Tested on CH32V003.

* Added more info, styling.

* Updated wording, typos and styling

* Updated some more wording and typos

* fixed typo

Author: maxint-rd

libraries/EEPROM/README.md

@@ -0,0 +1,158 @@
+## **EEPROM Library** for Arduino CH32
+
+### **What is the EEPROM library**
+
+The EEPROM library provides an easy to use interface to interact with the internal non-volatile storage found in Arduino boards. 
+This CH32 version of the library provides a familiar API to emulated EEPROM using the Option bytes area in flash memory.
+
+Ported to CH32 by Maxint R&D, based on multiple sources:
+- Code from the Option Data example of CH32V003fun by @CNLOHR.
+- Arduino original copyright (c) 2006 David A. Mellis.  All right reserved. New version by Christopher Andrews 2015.
+- ESP8266 version copyright (c) 2014 Ivan Grokhotkov. All rights reserved.
+
+## Table of contents
+- [CH32V003 emulated EEPROM](#ch32v003-emulated-eeprom)
+- [How to use this library](#how-to-use-this-library)
+- [Library functions](#library-functions)
+- [Features & limitations](#features--limitations)
+- [Disclaimer](#disclaimer)
+
+### CH32V003 emulated EEPROM 
+On the CH32V003 there are 2+24 bytes available. The first two bytes are Option bytes data0 and data1.
+All bytes are copied to a 26-byte long byte array in RAM. After changing a value the commit() method is used to write flash.
+
+From the CH32V003 Data Sheet:
+>  "Built-in 1920 bytes of system storage (System FLASH) for system bootloader storage (factory-cured
+  bootloader) 64 bytes are used for the system non-volatile configuration information storage area and 64 bytes
+  are used for the user select word storage area."
+
+So next to 16kB of Code FLASH, the chip features 2kB Flash for boot, configuration and storage. That 64 bytes
+user select word storage area is the area we can use to emulate on chip EEPROM memory.
+
+From the CH32V003 Reference Manual:
+>  "The user-option bytes is solidified in FLASH and will be reloaded into the corresponding register after system
+  reset, and can be erased and programmed by the user at will. The user option bytes information block has a
+  total of 8 bytes (4 bytes for write protection, 1 byte for read protection, 1 byte for configuration options, and
+  2 bytes for storing user data), and each bit has its inverse code bit for checksum during loading."
+
+These 8 bytes and their inverse use 16 bytes of flash. The total storage area page is 64 bytes, leaving 48 bytes available, 
+(including required inverse values). This gives 24 bytes that can be used plus the two data0 and data1 bytes. 
+Layout for uint8_t _data[26]: { ob[4], ob[6], ob[16...62] ].
+
+The first release of this library was made for the CH32V003 and only uses the user select word storage area. 
+It was tested using Arduino IDE 2.3.2 and OpenWCH core 1.0.4. 
+Future releases of this library may support other CH32 processors and allow for larger memory sizes.
+
+### **How to use this library**
+To use the library in your sketch you'll need to reference the library header file. You do this by adding an include directive to the top of your sketch. The library provides a global object variable named `EEPROM`. You use this object to access the library functions that are listed below.
+This EEPROM library requires you to call EEPROM.begin() to initialize the object.
+
+```Arduino
+#include <EEPROM.h>
+
+void setup(){
+  EEPROM.begin();
+}
+
+void loop(){
+
+}
+
+```
+You can find complete examples [here](examples/).
+
+---
+
+
+### **Library functions**
+
+#### **`EEPROM.begin()`** 
+
+This method initializes the EEPROM object. It reads the current data from permanent storage into a RAM memory buffer to allow speedy access. After writing data to memory, EEPROM.commit() needs to be called to save the data into permanent storage.
+
+This method does not return any value.
+
+#### **`EEPROM.erase()`** 
+
+This method erases the RAM memory of the EEPROM object. Erased bytes have a default value of 255 (0xFF). After erasing the RAM memory, EEPROM.commit() needs to be called to erase the permanent storage.
+
+This method does not return any value.
+
+#### **`EEPROM.commit()`** [[_example_]](examples/eeprom_counter/eeprom_counter.ino)
+
+The EEPROM object uses a RAM memory buffer to allow speedy access to its data. After writing data to memory, EEPROM.commit() needs to be called to save the data into permanent storage. 
+
+This method returns the `bool` true value to indicate success. The current implementations uses loops to wait for success.
+
+#### **`EEPROM.length()`** [[_example_]](examples/eeprom_counter/eeprom_counter.ino)
+
+This method returns an `size_t` containing the number of elements in the emulated EEPROM. On the CH32V003 there are 2+24 bytes available. _Future releases of this library may allow the begin() method to specify a larger size._
+
+#### **`EEPROM.read( address )`** [[_example_]](examples/eeprom_read/eeprom_read.ino)
+
+This method allows you to read a single byte of data from the EEPROM.
+Its only parameter is an `int` which should be set to the address you wish to read.
+
+The method returns the byte (`unsigned char` / `uint8_t`) containing the value read.
+
+#### **`EEPROM.write( address, value )`** [[_example_]](examples/eeprom_write/eeprom_write.ino)
+
+The `write()` method allows you to write a single byte of data to the EEPROM.
+Two parameters are needed. The first is an `int` containing the address that is to be written, and the second is a the byte to be written (`unsigned char` / `uint8_t`). After writing data to memory, EEPROM.commit() needs to be called to save the data into permanent storage.
+
+This method does not return any value.
+
+#### **`EEPROM.get( address, variable )`** [[_example_]](examples/eeprom_get/eeprom_get.ino)
+
+This method will retrieve any type of data from the EEPROM.
+Two parameters are needed to call this method. The first is an `int` containing the address that is to be written, and the second is the variable you would like to read.
+
+This method returns a reference to the `variable` passed in. It does not need to be used and is only returned for convenience.
+
+#### **`EEPROM.put( address, variable )`** [[_example_]](examples/eeprom_put/eeprom_put.ino)
+
+This method will write any type of data to the EEPROM.
+Two parameters are needed to call this method. The first is an `int` containing the address that is to be written, and the second is the variable you would like to write. After writing data to memory, EEPROM.commit() needs to be called to save the data into permanent storage.
+
+This method returns a reference to the `variable` passed in. It does not need to be used and is only returned for convenience.
+
+#### **Subscript operator: `EEPROM[address]`** [[_example_]](examples/eeprom_crc/eeprom_crc.ino)
+
+This operator allows using the `EEPROM` object like an array.  
+EEPROM RAM elements can be read _and_ **_written_** directly using this method. After writing data to memory, EEPROM.commit() needs to be called to save the data into permanent storage.
+
+This operator returns a reference to the EEPROM RAM elements.
+
+```c++
+uint8_t val;
+
+//Read first EEPROM RAM element.
+val = EEPROM[ 0 ];
+
+//Write first EEPROM RAM element.
+EEPROM[ 0 ] = val;
+
+//Compare contents
+if( val == EEPROM[ 0 ] ){
+  //Do something...
+}
+```
+
+#### **`EEPROM.ReadOptionBytes()`** [[_example_]](examples/eeprom_counter/eeprom_counter.ino)
+
+This method is made available to show how the CH32 stores data in the user select word storage area.
+The 8 words in the user option bytes information block are reloaded into their corresponding register after system reset.
+For this reason the data0 and data1 bytes within that block can be read even before EEPROM.begin() is called.
+After calling EEPROM.begin() these data0 and data1 bytes are copied into addresses 0 and 1 of the EEPROM RAM buffer.
+
+The method returns a `uint32_t` value, containing the data0 and data1 bytes and their inversed values.
+
+---
+
+## Features & limitations
+- The first release of this library was made only for the CH32V003 and has been tested on that MCU only. Other members of the CH32 may behave incorrectly or not work at all. 
+- This EEPROM implementation for the CH32V003 has only 26 bytes available. When addressing more, things are likely to go wrong. A future release may allow using more pages from the flash memory.
+- Most CH32 EEPROM methods are the same as their equivalent on regular Arduino's. BEWARE: The begin() and end() methods are like their counterparts for ESP8266/ESP32, but are very different from the begin() and end() methods of EEPROM v2.0 by Christopher Andrews, who introduced them to support C++ iterators. This library follows the begin() convention introduced by the Serial and Wire classes, i.e. to initialize the object.
+
+## Disclaimer
+- All code on this GitHub account, including this library is provided to you on an as-is basis without guarantees and with all liability dismissed. It may be used at your own risk. Unfortunately I have no means to provide support.

libraries/EEPROM/examples/eeprom_counter/eeprom_counter.ino

@@ -0,0 +1,40 @@
+/***
+  eeprom_counter example.
+  Written by by Maxint R&D for CH32.
+
+	The purpose of this example is to demonstrate non-volatile storage of a simple counter that counts
+  the times that the setup() function was called. It also shows the entire contents of the EEPROM.
+***/
+#include <EEPROM.h>
+
+void setup()
+{
+  Serial.begin(115200);
+  delay(2000);   // allow some time for Arduino IDE v2 serial console to show after recompiling
+  Serial.println("\n--- EEPROM COUNTER EXAMPLE ---");
+  Serial.printf("Option bytes: 0x%08x\r\n", EEPROM.ReadOptionBytes()); //  usually FF FF to start with
+  EEPROM.begin();
+
+  // Read the counter at EEPROM address 0, increment and write it back.
+  uint8_t bootcnt=EEPROM.read(0);
+	bootcnt++;
+  EEPROM.write(0, bootcnt);
+	Serial.printf("Boot count is %d [0x%02X]\n",bootcnt, bootcnt);
+
+  // Use EEPROM.commit() to write data to permanent storage
+  EEPROM.commit();
+
+  // Show the contents of the entire EEPROM memory
+  Serial.print("EEPROM contents:");
+  for(int n=0; n<EEPROM.length(); n++)
+  {
+    if(n%8==0) Serial.println("");
+	  Serial.printf("%02X ", EEPROM[n]);
+  }
+  Serial.println(".");
+}
+
+void loop()
+{   // nothing to do
+
+}

libraries/EEPROM/examples/eeprom_crc/eeprom_crc.ino

@@ -0,0 +1,54 @@
+/***
+  eeprom_crc example.
+  Written by Christopher Andrews. Modified by Maxint R&D for CH32.
+  CRC algorithm generated by pycrc, MIT licence ( https://github.com/tpircher/pycrc ).
+
+	A CRC is a simple way of checking whether data has changed or become corrupted.
+	This example calculates a CRC value directly on the EEPROM values.
+	The purpose of this example is to highlight how the EEPROM object can be used just like an array.
+***/
+
+#include <EEPROM.h>
+
+void setup() {
+  // Initialize serial and wait for port to open:
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+  
+  // Initialize EEPROM object
+  EEPROM.begin();
+
+  //Print length of data to run CRC on.
+  Serial.print("EEPROM length: ");
+  Serial.println(EEPROM.length());
+
+  //Print the result of calling eeprom_crc()
+  Serial.print("CRC32 of EEPROM data: 0x");
+  Serial.println(eeprom_crc(), HEX);
+  Serial.print("\n\nDone!");
+}
+
+void loop() {
+  /* Empty loop */
+}
+
+unsigned long eeprom_crc(void) {
+
+  const unsigned long crc_table[16] = {
+    0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac,
+    0x76dc4190, 0x6b6b51f4, 0x4db26158, 0x5005713c,
+    0xedb88320, 0xf00f9344, 0xd6d6a3e8, 0xcb61b38c,
+    0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c
+  };
+
+  unsigned long crc = ~0L;
+
+  for (int index = 0 ; index < EEPROM.length()  ; ++index) {
+    crc = crc_table[(crc ^ EEPROM[index]) & 0x0f] ^ (crc >> 4);
+    crc = crc_table[(crc ^ (EEPROM[index] >> 4)) & 0x0f] ^ (crc >> 4);
+    crc = ~crc;
+  }
+  return crc;
+}

libraries/EEPROM/examples/eeprom_get/eeprom_get.ino

@@ -0,0 +1,71 @@
+/***
+    eeprom_get example.
+
+    This shows how to use the EEPROM.get() method.
+
+    To pre-set the EEPROM data, run the example sketch eeprom_put.
+    This sketch will run without it, however, the values shown
+    will be shown from what ever is already on the EEPROM.
+
+    This may cause the serial object to print out a large string
+    of garbage if there is no null character inside one of the strings
+    loaded.
+
+    Written by Christopher Andrews 2015. Modified by Maxint R&D for CH32.
+    Released under MIT licence.
+***/
+
+#include <EEPROM.h>
+
+void setup() {
+
+  float f = 0.00f;   //Variable to store data read from EEPROM.
+  int eeAddress = 0; //EEPROM address to start reading from
+
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+  Serial.print("Read float from EEPROM: ");
+
+  // initialize EEPROM object
+  EEPROM.begin();
+
+  //Get the float data from the EEPROM at position 'eeAddress'
+  EEPROM.get(eeAddress, f);
+  Serial.println(f, 3);    //This may print 'ovf, nan' if the data inside the EEPROM is not a valid float.
+
+  /***
+    As get also returns a reference to 'f', you can use it inline.
+    E.g: Serial.print( EEPROM.get( eeAddress, f ) );
+  ***/
+
+  /***
+    Get can be used with custom structures too.
+    I have separated this into an extra function.
+  ***/
+
+  secondTest(); //Run the next test.
+}
+
+struct MyObject {
+  float field1;
+  byte field2;
+  char name[10];
+};
+
+void secondTest() {
+  int eeAddress = sizeof(float); //Move address to the next byte after float 'f'.
+
+  MyObject customVar; //Variable to store custom object read from EEPROM.
+  EEPROM.get(eeAddress, customVar);
+
+  Serial.println("Read custom object from EEPROM: ");
+  Serial.println(customVar.field1);
+  Serial.println(customVar.field2);
+  Serial.println(customVar.name);
+}
+
+void loop() {
+  /* Empty loop */
+}

libraries/EEPROM/examples/eeprom_put/eeprom_put.ino

@@ -0,0 +1,63 @@
+/***
+    eeprom_put example.
+
+    This shows how to use the EEPROM.put() method.
+    Also, this sketch will pre-set the EEPROM data for the
+    example sketch eeprom_get.
+
+    Note, unlike the single byte version EEPROM.write(),
+    the put method will use update semantics. As in a byte
+    will only be written to the EEPROM if the data is actually
+    different.
+
+    Written by Christopher Andrews 2015. Modified by Maxint R&D for CH32.
+    Released under MIT licence.
+***/
+
+#include <EEPROM.h>
+
+struct MyObject {
+  float field1;
+  byte field2;
+  char name[10];
+};
+
+void setup() {
+  float f = 123.456f;  //Variable to store in EEPROM.
+  int eeAddress = 0;   //Location we want the data to be put.
+
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+
+  // initialize EEPROM object
+  EEPROM.begin();
+
+  //One simple call, with the address first and the object second.
+  EEPROM.put(eeAddress, f);
+
+  Serial.println("Written float data type!");
+
+  /** Put is designed for use with custom structures also. **/
+
+  //Data to store.
+  MyObject customVar = {
+    3.14f,
+    42,
+    "Working!"
+  };
+
+  eeAddress += sizeof(float); //Move address to the next byte after float 'f'.
+
+  EEPROM.put(eeAddress, customVar);
+
+  // Use EEPROM.commit() to write data to permanent storage
+  EEPROM.commit();
+
+  Serial.print("Written custom data type! \n\nView the example sketch eeprom_get to see how you can retrieve the values!");
+}
+
+void loop() {
+  /* Empty loop */
+}