You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The EEPROM Storage library provides the ability to access variables stored in EEPROM just as if they were stored in normal RAM.
7
8
9
+
## EEPROMStorage\<T\> vs EEPROMCache\<T\>
10
+
There are two classes that provide the similar access to EEEPROM. The first is the Direct Storage class which reads and writes to directly to and from EEPROM. The second is the Cache Access whichs reads and writes from memory and writes to the EEPROM when directed.
11
+
12
+
Other than the `restore()` and `commit()` (*see description below*) methods on the cache based class, these objects can be used interchangably.
13
+
14
+
### Direct Storage (EEPROMStorage\<T\>)
15
+
This class writes directly to the EEPROM whenever the variable value is updated and reads directly from EEPROM when the variable value is accessed.
16
+
17
+
Within the library, examples of how to use this type of access can be found in the **Storage** folder under **Examples**.
18
+
19
+
### Cached Access (EEPROMCache\<T\>)
20
+
This class reads and writes the variable value from RAM and only updates the value from EEPROM when `restore()` is called. Subsequently it only writes to EEPROM when `commit()` is called.
21
+
22
+
Within the library, examples of how to use this type of access can be found in the **Cache** folder under **Examples**.
23
+
24
+
## General Usage
8
25
Once defined, a variable can be used in in the same manner as its underlying type. For example, a variable defined as an integer (int) would be defined as follows:
9
26
10
27
int i = 0;
@@ -17,27 +34,32 @@ To set the value to a specific value we would, for example, use the statement
17
34
18
35
i = 12;
19
36
20
-
This is all very obvious to even the novice programmer but is used here to show the simplicity of the EEPROM Storage class. An integer variable stored in EEPROM would be defined in the following manner:
37
+
This is all standard coding to even the novice programmer but is used here to show the simplicity of the EEPROM Storage/Cache class. An integer variable stored in EEPROM would be defined in the following manner:
21
38
22
39
EEPROMStorage<int> i(0, 0);
40
+
41
+
or
42
+
43
+
EEPROMCache<int> i(0, 0);
23
44
24
45
where the first parameter of the constructor defines the address of the variable in EEPROM, and the second parameter defines the default value.
25
46
26
47
After the definition, the variable `i` can be used in the same manner, `i++` and `i = 12` will work the same way they did before, but now the value is stored and retrieved to and from EEPROM.
27
48
28
-
## EEPROM Address ##
29
-
### Memory Requirement ###
49
+
## EEPROM Address
50
+
### Memory Requirement
51
+
---
30
52
When defining an EEPROM Storage variable, it is important to understand the number of bytes required for the underlying type and ensuring that the variables are spaced appropriately so they do not collide.
31
53
32
54
Each variable requires enough memory to store the underlying type plus one additional byte for a checksum.
The best way to think about EEPROM memory is to think about it as a large byte array with a base index of 0. In fact, the Arduino libraries construct access to EEPROM in this manner.
43
65
@@ -53,52 +75,57 @@ Using the nextAddress() method will make it easier to align your variables in me
If you are not sure of the memory requirement for a given data type, you can use the `sizeof` operator. User the Serial port to display the size of any data type.
62
85
63
-
Serial.print("The size of int is "); Serial.print(sizeof(int)); Serial.println(".");
86
+
Serial.print("The size of int is "); Serial.print(sizeof(int)); DEBUG_INFO(".");
64
87
65
88
When using the `sizeof` operator to determine the number of bytes to preserve remember to add one extra byte for the **checksum**.
66
89
67
90
To see a full demonstration of this, open the example sketch called **sizeof.ino**.
68
91
69
-
## EEPROM Storage Initialization ##
92
+
## EEPROM Storage Initialization
70
93
When data has never been stored EEPROM on a micro-controller the memory is in an uninitialized state. Since each byte of memory must have a value between 0 and 255, it is not always possible to detect an uninitialized byte. This behavior could have unexpected side effects if you define a variable and fail to detect whether the instance has been initialized.
71
94
72
95
For this reason, the EEPROM Storage library uses a one-byte checksum to determine if the instance has been initialized or not. When an instance is constructed, a default value is specified. This default value is always returned until a value is set thus initializing the location. Each write operation to EEPROM will update the checksum.
73
96
74
-
## Scope ##
97
+
## Scope
75
98
It is important to note that since `EEPROMStorage` variables are in fact, stored in the Micro-controllers EEPROM, the scope of these variables is always global. In fact it is possible to instantiate more than one instance using the same address that as a result will keep the two instances in sync.
76
99
77
100
> The `EEPROMStorage` variable never caches the value internally and will read the value from EEPROM each time it is requested. Similarly, each time the instance value is updated it is written directly to EEPROM.
78
101
79
-
# Usage #
80
-
## Declaration ##
102
+
# Usage
103
+
## Declaration
81
104
An instance of `EEPROMStorage` can be declared globally, within a class or within a function keeping in mind, as stated previously, that the address controls whether two or more instances share the same value.
Specifies the underlying data type for the given instance.
89
113
90
-
### Address ###
114
+
### Address
115
+
---
91
116
Specifies the starting index in EEPROM where the value will be stored.
92
117
93
-
### Default Value ###
118
+
### Default Value
119
+
---
94
120
Specifies the value that will be returned by the instance when the EEPROM memory location has not been initialized (initialization is determined by the checksum).
95
121
96
-
### Example ###
122
+
### Example
123
+
---
97
124
To initialize an instance with an underlying data type of int located in position 50 of the EEPROM and a default value of 10, the syntax would be as follows:
98
125
99
126
EEPROMStorage<int> myInt(50, 10);
100
127
101
-
## Assignment ##
128
+
## Assignment
102
129
Using the previous example, assigning a value to the instance is as simple as the assignment shown here.
103
130
104
131
myInt = 100;
@@ -107,20 +134,27 @@ The `EEPROMStorage` class also defines a `set()` method that can be used.
107
134
108
135
myInt.set(100);
109
136
110
-
## Retrieving ##
137
+
## Retrieving
111
138
To get the instance value, simply assign it to a variable, as shown below,
112
139
113
140
int x = myInt;
114
141
115
142
or pass it as an argument in any function that takes an int argument as shown below.
116
143
117
-
Serial.print("myInt = "); Serial.println(myInt);
144
+
Serial.print("myInt = "); DEBUG_INFO(myInt);
118
145
119
146
The `EEPROMStorage` class also defines a `get()` method that can be used.
0 commit comments