Added additional examples to EEPROM lib

7 files changed, 455 insertions, 0 deletions

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..40b08bd
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_crc/eeprom_crc.ino
@@ -0,0 +1,47 @@
+/***
+    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);
+  
+  //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 < 32  ; ++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..58475fd
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_get/eeprom_get.ino
@@ -0,0 +1,63 @@
+/***
+    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; //Location of the IP address inside the class.
+  
+  Serial.begin( 9600 );
+  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..34071fc
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_iteration/eeprom_iteration.ino
@@ -0,0 +1,73 @@
+/***
+    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;
+  
+  do{
+  
+    //Add one to each cell in the EEPROM
+    EEPROM[ index ] += 1;  
+    index++;
+  }while( index < EEPROM.length() );
+  
+  /***
+    Iterate the EEPROM using a C++11 ranged for loop.
+    
+    This version of the loop is best explained in the example 'eeprom_pointer'
+    as this kind of iteration uses pointers rather than an index/integer.
+    
+    !! Note: C++11 is not yet enabled by default in any IDE version.
+       Unless you manually enable it, this sketch will not compile.
+       You can comment the loop below to verify the non C++11 content.
+  ***/
+  
+  for( auto cell : EEPROM ){
+
+    //Add one to each cell in the EEPROM
+    cell += 1;
+  }
+  
+} //End of setup function.
+
+void loop(){}
\ No newline at end of file
diff --git a/libraries/EEPROM/examples/eeprom_pointer/eeprom_pointer.ino b/libraries/EEPROM/examples/eeprom_pointer/eeprom_pointer.ino
new file mode 100644
index 0000000..b56b681
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_pointer/eeprom_pointer.ino
@@ -0,0 +1,74 @@
+/***
+    eeprom_pointer example.
+    
+    This example shows how the built-in EEPtr
+    object can be used to manipulate the EEPROM
+    using standard pointer arithmetic.
+    
+    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() {
+
+  Serial.begin(9600);
+
+  /***
+    In this example, we will iterate forward over the EEPROM,
+    starting at the 10th cell (remember indices are zero based).
+  ***/
+  
+  EEPtr ptr = 9;
+  
+  //Rather than hard coding a length, we can use the provided .length() function.
+
+  while( ptr < EEPROM.length() ){
+  
+    Serial.print( *ptr, HEX );  //Print out hex value of the EEPROM cell pointed to by 'ptr'
+    Serial.print( ", " );       //Separate values with a comma.
+    ptr++;                      //Move to next cell
+  }
+
+  /***
+    In this example, we will iterate backwards over the EEPROM,
+    starting at the last cell.
+  ***/
+  
+  ptr = EEPROM.length() - 1;
+  
+  do{
+    
+    Serial.print( *ptr, HEX );
+    Serial.print( ", " );
+    
+  }while( ptr-- ); //When the pointer reaches zero the loop will end as zero is considered 'false'.
+  
+  
+  /***
+    And just for clarity, the loop below is an equivalent implementation
+    of the C++11 ranged for loop.
+  ***/
+  
+  for( EEPtr ptr = EEPROM.begin() ; item != EEPROM.end() ; ++item ){
+    Serial.print( *ptr, HEX );
+    Serial.print( ", " );
+  }
+  
+  /*** 
+    The actual C++11 version:
+  
+    for( auto ptr : EEPROM ){
+      Serial.print( *ptr, HEX );
+      Serial.print( ", " );
+    }
+  ***/
+  
+
+}
+
+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..7575768
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_put/eeprom_put.ino
@@ -0,0 +1,53 @@
+/***
+    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>
+
+void setup(){
+
+  Serial.begin(9600);
+  
+  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. **/
+  
+  struct MyObject{
+    float field1;
+    byte field2;
+    char name[10];
+  };
+  
+  //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_reference/eeprom_reference.ino b/libraries/EEPROM/examples/eeprom_reference/eeprom_reference.ino
new file mode 100644
index 0000000..bcf84d6
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_reference/eeprom_reference.ino
@@ -0,0 +1,93 @@
+/***
+    eeprom_reference example.
+    
+    This example shows how to use the EEPROM
+    reference object EERef, which allows usage
+    similar to using a simple char (uint8_t in this case).
+    
+    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() {
+
+
+  /***
+    To create a reference to an EEPROM cell, simply create an EERef variable.
+    To let it know which cell you want to reference, you can simply assign the
+    address when you create it.
+  ***/
+  
+  EERef ref = 0;
+  
+  /***
+    An equivalent way is by calling the constructor directly:
+    EERef ref( 0 );
+  ***/
+  
+  /** Using the reference **/
+  
+  /*** 
+    Updating cell data.
+    To prevent unnecessary wear on the EEPROM cells
+    this function will only write the data when it
+    is different to what is already stored. 
+  ***/
+  
+  ref.update( 44 ); //May write 44 if not present.
+  ref.update( 44 ); //This second call will not write anything.
+  
+  /*** 
+    Assign values directly to the EEPROM cell. 
+    
+    You can use any form of assignment that would otherwise be available
+    to a standard uint8_t:
+    
+    *=
+    /=
+    +=
+    -=
+    ^=
+    %=
+    &=
+    |=
+    <<=
+    >>=
+    
+  ***/
+  
+  ref = 4;  /*** 
+                Take care to notice, this changes the EEPROM cell data, it does not 
+                change the index of the cell referenced by 'ref'.
+                
+                Only the initial declaration like 'EERef ref = 0;' will set the address.
+                Using an assignment anywhere else modifies the referenced cell.
+                To modify the referenced address after declaring your variable see below.
+            ***/
+
+  /***
+    Changing the referenced object. 
+    The class has a member named 'index' which is an integer you can modify.
+  ***/
+  
+  ref.index++; //Move reference to the next cell.
+  
+  
+  /***
+    Grouping of references.
+    
+    Using EERef objects you can create a contiguous array referencing
+    non-contiguous EEPROM cells.
+  ***/
+  
+  EERef array[] = { 0, 20, 40, 60, 80 };
+
+
+} //End of setup function.
+
+void loop(){}
\ No newline at end of file
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..e0e18d8
--- /dev/null
+++ b/libraries/EEPROM/examples/eeprom_update/eeprom_update.ino
@@ -0,0 +1,52 @@
+/***
+   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 addr = 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(addr, val);
+  
+  /***
+    The function EEPROM.update(addr, val) is equivalent to the following:
+  
+    if( EEPROM.read(addr) != val ){
+	  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. **/
+  addr = addr + 1;
+  if (addr == 512)
+    addr = 0;
+
+  delay(100);
+}