source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/libraries/EEPROM/README.md @ 46

Last change on this file since 46 was 46, checked in by jrpelegrina, 4 years ago

First release to Xenial

File size: 5.0 KB
Line 
1## **EEPROM Library V2.0** for Arduino
2
3**Written by:** _Christopher Andrews_. 
4
5### **What is the EEPROM library.**
6
7Th EEPROM library provides an easy to use interface to interact with the internal non-volatile storage found in AVR based Arduino boards. This library will work on many AVR devices like ATtiny and ATmega chips.
8
9### **How to use it**
10The EEPROM library is included in your IDE download. To add its functionality to 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.
11
12```Arduino
13#include <EEPROM.h>
14
15void setup(){
16
17}
18
19void loop(){
20
21}
22
23```
24
25The library provides a global variable named `EEPROM`, you use this variable to access the library functions. The methods provided in the EEPROM class are listed below.
26
27You can view all the examples [here](examples/).
28
29### **Library functions**
30
31#### **`EEPROM.read( address )`** [[_example_]](examples/eeprom_read/eeprom_read.ino)
32
33This function allows you to read a single byte of data from the eeprom.
34Its only parameter is an `int` which should be set to the address you wish to read.
35
36The function returns an `unsigned char` containing the value read.
37
38#### **`EEPROM.write( address, value )`** [[_example_]](examples/eeprom_write/eeprom_write.ino)
39
40The `write()` method allows you to write a single byte of data to the EEPROM.
41Two parameters are needed. The first is an `int` containing the address that is to be written, and the second is a the data to be written (`unsigned char`).
42
43This function does not return any value.
44
45#### **`EEPROM.update( address, value )`** [[_example_]](examples/eeprom_update/eeprom_update.ino)
46
47This function is similar to `EEPROM.write()` however this method will only write data if the cell contents pointed to by `address` is different to `value`. This method can help prevent unnecessary wear on the EEPROM cells.
48
49This function does not return any value.
50
51#### **`EEPROM.get( address, object )`** [[_example_]](examples/eeprom_get/eeprom_get.ino)
52
53This function will retrieve any object from the EEPROM.
54Two parameters are needed to call this function. The first is an `int` containing the address that is to be written, and the second is the object you would like to read.
55
56This function returns a reference to the `object` passed in. It does not need to be used and is only returned for conveience.
57
58#### **`EEPROM.put( address, object )`** [[_example_]](examples/eeprom_put/eeprom_put.ino)
59
60This function will write any object to the EEPROM.
61Two parameters are needed to call this function. The first is an `int` containing the address that is to be written, and the second is the object you would like to write.
62
63This function uses the _update_ method to write its data, and therefore only rewrites changed cells.
64
65This function returns a reference to the `object` passed in. It does not need to be used and is only returned for conveience.
66
67#### **Subscript operator: `EEPROM[address]`** [[_example_]](examples/eeprom_crc/eeprom_crc.ino)
68
69This operator allows using the identifier `EEPROM` like an array. 
70EEPROM cells can be read _and_ **_written_** directly using this method.
71
72This operator returns a reference to the EEPROM cell.
73
74```c++
75unsigned char val;
76
77//Read first EEPROM cell.
78val = EEPROM[ 0 ];
79
80//Write first EEPROM cell.
81EEPROM[ 0 ] = val;
82
83//Compare contents
84if( val == EEPROM[ 0 ] ){
85  //Do something...
86}
87```
88
89#### **`EEPROM.length()`**
90
91This function returns an `unsigned int` containing the number of cells in the EEPROM.
92
93---
94
95### **Advanced features**
96
97This library uses a component based approach to provide its functionality. This means you can also use these components to design a customized approach. Two background classes are available for use: `EERef` & `EEPtr`.
98
99#### **`EERef` class**
100
101This object references an EEPROM cell.
102Its purpose is to mimic a typical byte of RAM, however its storage is the EEPROM.
103This class has an overhead of two bytes, similar to storing a pointer to an EEPROM cell.
104
105```C++
106EERef ref = EEPROM[ 10 ]; //Create a reference to 11th cell.
107
108ref = 4; //write to EEPROM cell.
109
110unsigned char val = ref; //Read referenced cell.
111```
112
113#### **`EEPtr` class**
114
115This object is a bidirectional pointer to EEPROM cells represented by `EERef` objects.
116Just like a normal pointer type, this type can be dereferenced and repositioned using
117increment/decrement operators.
118
119```C++
120EEPtr ptr = 10; //Create a pointer to 11th cell.
121
122*ptr = 4; //dereference and write to EEPROM cell.
123
124unsigned char val = *ptr; //dereference and read.
125
126ptr++; //Move to next EEPROM cell.
127```
128
129#### **`EEPROM.begin()`**
130
131This function returns an `EEPtr` pointing to the first cell in the EEPROM. 
132This is useful for STL objects, custom iteration and C++11 style ranged for loops.
133
134#### **`EEPROM.end()`**
135
136This function returns an `EEPtr` pointing at the location after the last EEPROM cell. 
137Used with `begin()` to provide custom iteration.
138
139**Note:** The `EEPtr` returned is invalid as it is out of range. Infact the hardware causes wrapping of the address (overflow) and `EEPROM.end()` actually references the first EEPROM cell.
Note: See TracBrowser for help on using the repository browser.