Merge pull request #2812 from facchinm/test_pr2794

EEPROM library V2

8 files changed, 370 insertions, 26 deletions

diff --git a/libraries/EEPROM/examples/eeprom_clear/eeprom_clear.ino b/libraries/EEPROM/examples/eeprom_clear/eeprom_clear.ino
index b18ff2c..49eb5fe 100644
--- a/libraries/EEPROM/examples/eeprom_clear/eeprom_clear.ino
+++ b/libraries/EEPROM/examples/eeprom_clear/eeprom_clear.ino
@@ -2,22 +2,34 @@
  * EEPROM Clear
  *
  * Sets all of the bytes of the EEPROM to 0.
+ * Please see eeprom_iteration for a more in depth
+ * look at how to traverse the EEPROM.
+ *
  * This example code is in the public domain.
-
  */
 
 #include <EEPROM.h>
 
 void setup()
 {
-  // write a 0 to all 512 bytes of the EEPROM
-  for (int i = 0; i < 512; i++)
+
+  /***
+    Iterate through each byte of the EEPROM storage.    
+    
+    Larger AVR processors have larger EEPROM sizes, E.g:
+    - Arduno Duemilanove: 512b EEPROM storage.
+    - Arduino Uno:        1kb EEPROM storage.
+    - Arduino Mega:       4kb EEPROM storage.
+    
+    Rather than hard-coding the length, you should use the pre-provided length function.
+    This will make your code portable to all AVR processors.    
+  ***/
+  
+  for ( int i = 0 ; i < EEPROM.length() ; i++ )
     EEPROM.write(i, 0);
 
   // turn the LED on when we're done
   digitalWrite(13, HIGH);
 }
 
-void loop()
-{
-}
+void loop(){ /** Empty loop. **/ }
diff --git a/libraries/EEPROM/examples/eeprom_crc/eeprom_crc.ino b/libraries/EEPROM/examples/eeprom_crc/eeprom_crc.ino
new file mode 100644
index 0000000..8461d56
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_crc/eeprom_crc.ino
@@ -0,0 +1,50 @@
+/***
+    Written by Christopher Andrews.
+    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 <Arduino.h>
+#include <EEPROM.h>
+
+void setup(){
+  
+  //Start serial
+  Serial.begin(9600);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for Leonardo only
+  }
+
+  //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;
+}
\ No newline at end of file
diff --git a/libraries/EEPROM/examples/eeprom_get/eeprom_get.ino b/libraries/EEPROM/examples/eeprom_get/eeprom_get.ino
new file mode 100644
index 0000000..6620999
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_get/eeprom_get.ino
@@ -0,0 +1,66 @@
+/***
+    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
+    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( 9600 );
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for Leonardo only
+  }
+  Serial.print( "Read float from EEPROM: " );
+
+  //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 */ }
\ No newline at end of file
diff --git a/libraries/EEPROM/examples/eeprom_iteration/eeprom_iteration.ino b/libraries/EEPROM/examples/eeprom_iteration/eeprom_iteration.ino
new file mode 100644
index 0000000..650c90a
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_iteration/eeprom_iteration.ino
@@ -0,0 +1,57 @@
+/***
+    eeprom_iteration example.
+    
+    A set of example snippets highlighting the
+    simplest methods for traversing the EEPROM.
+    
+    Running this sketch is not necessary, this is 
+    simply highlighting certain programming methods.
+    
+    Written by Christopher Andrews 2015
+    Released under MIT licence.
+***/
+
+#include <EEPROM.h>
+
+void setup() {
+
+  /***
+    Iterate the EEPROM using a for loop.
+  ***/
+  
+  for( int index = 0 ; index < EEPROM.length() ; index++ ){
+
+    //Add one to each cell in the EEPROM
+    EEPROM[ index ] += 1;
+  }
+  
+  /***
+    Iterate the EEPROM using a while loop.
+  ***/
+  
+  int index = 0;
+  
+  while( index < EEPROM.length() ){
+  
+    //Add one to each cell in the EEPROM
+    EEPROM[ index ] += 1;  
+    index++;
+  }
+  
+  /***
+    Iterate the EEPROM using a do-while loop.
+  ***/
+  
+  int idx = 0;  //Used 'idx' to avoid name conflict with 'index' above.
+  
+  do{
+  
+    //Add one to each cell in the EEPROM
+    EEPROM[ idx ] += 1;  
+    idx++;
+  }while( idx < EEPROM.length() );
+  
+  
+} //End of setup function.
+
+void loop(){}
\ No newline at end of file
diff --git a/libraries/EEPROM/examples/eeprom_put/eeprom_put.ino b/libraries/EEPROM/examples/eeprom_put/eeprom_put.ino
new file mode 100644
index 0000000..186cf95
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_put/eeprom_put.ino
@@ -0,0 +1,56 @@
+/***
+    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
+    Released under MIT licence.    
+***/
+
+#include <EEPROM.h>
+
+struct MyObject{
+  float field1;
+  byte field2;
+  char name[10];
+};
+
+void setup(){
+
+  Serial.begin(9600);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for Leonardo only
+  }
+
+  float f = 123.456f;  //Variable to store in EEPROM.
+  int eeAddress = 0;   //Location we want the data to be put.
+  
+  
+  //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,
+    65,
+    "Working!"
+  };
+
+  eeAddress += sizeof(float); //Move address to the next byte after float 'f'.
+  
+  EEPROM.put( eeAddress, customVar );
+  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 */ }
\ No newline at end of file
diff --git a/libraries/EEPROM/examples/eeprom_read/eeprom_read.ino b/libraries/EEPROM/examples/eeprom_read/eeprom_read.ino
index ebf79d6..68c4ffc 100644
--- a/libraries/EEPROM/examples/eeprom_read/eeprom_read.ino
+++ b/libraries/EEPROM/examples/eeprom_read/eeprom_read.ino
@@ -31,13 +31,27 @@ void loop()
   Serial.print(value, DEC);
   Serial.println();
 
-  // advance to the next address of the EEPROM
+  /***
+    Advance to the next address, when at the end restart at the beginning.    
+    
+    Larger AVR processors have larger EEPROM sizes, E.g:
+    - Arduno Duemilanove: 512b EEPROM storage.
+    - Arduino Uno:        1kb EEPROM storage.
+    - Arduino Mega:       4kb EEPROM storage.
+    
+    Rather than hard-coding the length, you should use the pre-provided length function.
+    This will make your code portable to all AVR processors.    
+  ***/
   address = address + 1;
-
-  // there are only 512 bytes of EEPROM, from 0 to 511, so if we're
-  // on address 512, wrap around to address 0
-  if (address == 512)
+  if(address == EEPROM.length())
     address = 0;
+    
+  /***
+    As the EEPROM sizes are powers of two, wrapping (preventing overflow) of an 
+    EEPROM address is also doable by a bitwise and of the length - 1.
+    
+    ++address &= EEPROM.length() - 1;
+  ***/
 
   delay(500);
 }
diff --git a/libraries/EEPROM/examples/eeprom_update/eeprom_update.ino b/libraries/EEPROM/examples/eeprom_update/eeprom_update.ino
new file mode 100644
index 0000000..831056f
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_update/eeprom_update.ino
@@ -0,0 +1,69 @@
+/***
+   EEPROM Update method
+  
+   Stores values read from analog input 0 into the EEPROM.
+   These values will stay in the EEPROM when the board is
+   turned off and may be retrieved later by another sketch.
+  
+   If a value has not changed in the EEPROM, it is not overwritten
+   which would reduce the life span of the EEPROM unnecessarily.
+   
+   Released using MIT licence.
+ ***/
+
+#include <EEPROM.h>
+
+/** the current address in the EEPROM (i.e. which byte we're going to write to next) **/
+int address = 0;
+
+void setup(){ /** EMpty setup **/ }
+
+void loop()
+{
+  /***
+    need to divide by 4 because analog inputs range from
+    0 to 1023 and each byte of the EEPROM can only hold a
+    value from 0 to 255.
+  ***/
+  int val = analogRead(0) / 4;
+
+  /***
+    Update the particular EEPROM cell.
+    these values will remain there when the board is
+    turned off.
+  ***/
+  EEPROM.update(address, val);
+  
+  /***
+    The function EEPROM.update(address, val) is equivalent to the following:
+  
+    if( EEPROM.read(address) != val ){
+      EEPROM.write(address, val);
+    }
+  ***/
+  
+
+  /***
+    Advance to the next address, when at the end restart at the beginning.    
+    
+    Larger AVR processors have larger EEPROM sizes, E.g:
+    - Arduno Duemilanove: 512b EEPROM storage.
+    - Arduino Uno:        1kb EEPROM storage.
+    - Arduino Mega:       4kb EEPROM storage.
+    
+    Rather than hard-coding the length, you should use the pre-provided length function.
+    This will make your code portable to all AVR processors.    
+  ***/
+  address = address + 1;
+  if(address == EEPROM.length())
+    address = 0;
+    
+  /***
+    As the EEPROM sizes are powers of two, wrapping (preventing overflow) of an 
+    EEPROM address is also doable by a bitwise and of the length - 1.
+    
+    ++address &= EEPROM.length() - 1;
+  ***/
+
+  delay(100);
+}
diff --git a/libraries/EEPROM/examples/eeprom_write/eeprom_write.ino b/libraries/EEPROM/examples/eeprom_write/eeprom_write.ino
index c047887..f07446c 100644
--- a/libraries/EEPROM/examples/eeprom_write/eeprom_write.ino
+++ b/libraries/EEPROM/examples/eeprom_write/eeprom_write.ino
@@ -8,31 +8,51 @@
 
 #include <EEPROM.h>
 
-// the current address in the EEPROM (i.e. which byte
-// we're going to write to next)
-int addr = 0;
+/** the current address in the EEPROM (i.e. which byte we're going to write to next) **/
+int addr = 0; 
 
-void setup()
-{
-}
+void setup(){ /** Empty setup. **/}
 
 void loop()
 {
-  // need to divide by 4 because analog inputs range from
-  // 0 to 1023 and each byte of the EEPROM can only hold a
-  // value from 0 to 255.
+  /***
+    Need to divide by 4 because analog inputs range from
+    0 to 1023 and each byte of the EEPROM can only hold a
+    value from 0 to 255.
+  ***/
+  
   int val = analogRead(0) / 4;
 
-  // write the value to the appropriate byte of the EEPROM.
-  // these values will remain there when the board is
-  // turned off.
+  /***
+    Write the value to the appropriate byte of the EEPROM.
+    these values will remain there when the board is
+    turned off.
+  ***/
+  
   EEPROM.write(addr, val);
 
-  // advance to the next address.  there are 512 bytes in
-  // the EEPROM, so go back to 0 when we hit 512.
+  /***
+    Advance to the next address, when at the end restart at the beginning.    
+    
+    Larger AVR processors have larger EEPROM sizes, E.g:
+    - Arduno Duemilanove: 512b EEPROM storage.
+    - Arduino Uno:        1kb EEPROM storage.
+    - Arduino Mega:       4kb EEPROM storage.
+    
+    Rather than hard-coding the length, you should use the pre-provided length function.
+    This will make your code portable to all AVR processors.    
+  ***/
   addr = addr + 1;
-  if (addr == 512)
+  if(addr == EEPROM.length())
     addr = 0;
+    
+  /***
+    As the EEPROM sizes are powers of two, wrapping (preventing overflow) of an 
+    EEPROM address is also doable by a bitwise and of the length - 1.
+    
+    ++addr &= EEPROM.length() - 1;
+  ***/
+
 
   delay(100);
 }