Skip to content

Commit 24d3ea8

Browse files
porreyporrey
authored
Merge pull request #4 from porrey/v1.0.2
V1.0.2
2 parents 90ae8fe + ea4122c commit 24d3ea8

File tree

11 files changed

+661
-632
lines changed

11 files changed

+661
-632
lines changed

‎README.md

Lines changed: 52 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,42 @@
11
# EEPROM-Storage Library
2-
## Overview
3-
This library is designed to work on both the **Particle** and the **Arduino** platforms.
4-
5-
The EEPROM Storage library provides the ability to access variables stored in EEPROM just as if they were stored in normal RAM. This makes it easy to create static variables that must be restored after a reboot and manage them in your code just like any other variable.
6-
7-
8-
Once defined, a variable can be used in the same manner as its underlying type. For example, a variable defined as an integer (int) would be defined as shown below.
9-
10-
11-
// ***
12-
// *** Define i as an int with the default value of 0;
13-
// ***
14-
int i = 0;
15-
16-
// ***
17-
// *** Set i to 12.
18-
// ***
19-
i = 12;
20-
21-
// ***
22-
// *** Increment i.
23-
// ***
24-
i++;
25-
26-
// ***
27-
// *** Set the value of a to the current value of i.
28-
// ***
29-
int a = i;
30-
31-
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 and used in code as shown below.
32-
33-
// ***
34-
// *** Define i as an int with a default value of 10 at EEPROM address 0.
35-
// ***
36-
EEPROMStorage<int> i(0, 10);
37-
38-
// ***
39-
// *** Set i to 12.
40-
// ***
41-
i = 12;
42-
43-
// ***
44-
// *** Increment i.
45-
// ***
46-
i++;
47-
48-
// ***
49-
// *** Set the value of 'a' to the current value of i.
50-
// ***
51-
int a = i;
52-
53-
The first parameter of the constructor defines the address of the variable in EEPROM and the second parameter defines the default value when the EEPROM has been initialized or erased.
54-
55-
After the definition, the variable `i` can be used in the same way as before, but now the value is stored and retrieved to and from EEPROM.
56-
## EEPROM Performance
57-
### Write Limits
58-
True EEPROM chips have write limits. The ATmega328P specifies a 100,000 write limit per address location. Other microcontrollers may have different limits. The Particle Photon implements its EEPROM (for compatibility with existing Arduino code) in static RAM and therefore does not have any write limits. It is good to know your microcontroller specifications when using the EEPROM.
59-
### Flash Memory vs. EEPROM Memory
60-
The read and write speed of EEPROM is much slower than flash memory. When using these EEPROM variables, take note where and when you are reading them and also where and when you are writing them.
61-
### Writing Values
62-
If you attempt to write the current value back to EEPROM, the library will not perform a write. Keep in mind there is extra code to perform this check which can cause some performance issues in your application.
63-
### Reading Values
64-
Reading a value from EEPROM is faster than writing a value to EEPROM, but the read from EEPROM is slower than a variable read from flash memory.
65-
### Tips
66-
The following are recommendations:
67-
68-
1. Avoid excessive writes to a variable
69-
2. Avoid writes in loops where the same variable is updated several times. Instead save the value once at the end of the loop.
70-
3. Avoid reading or writing an EEPROM variable in time sensitive code.
71-
4. Know the write limits for your particular platform/microcontroller. Write your code in such a way that you will not exceed the limit in the lifetime of your application.
72-
73-
## EEPROM Address
74-
### Memory Requirement
2+
## Overview ##
3+
The EEPROM Storage library provides the ability to access variables stored in EEPROM just as if they would stored in normal RAM.
4+
5+
Once defined, a variable can be used in in the same manner as it's underlying type. For example, a variable defined as an integer (int) would be defined as follows:
6+
7+
int i = 0;
8+
9+
Throughout the code this variable can be read and written in various ways. For example, to increment the variable, we would use the statement
10+
11+
i++;
12+
13+
To set the value to a specific value we would, for example, use the statement
14+
15+
i = 12;
16+
17+
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:
18+
19+
EEPROMStorage<int> i(0, 0);
20+
21+
where the first parameter of the constructor defines the address of the variable in EEPROM and the second parameter defines the default value.
22+
23+
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.
24+
25+
## EEPROM Address ##
26+
### Memory Requirement ###
7527
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.
7628

7729
Each variable requires enough memory to store the underlying type plus one additional byte for a checksum.
7830

7931
Consider the following variable definitions.
8032

81-
EEPROMStorage<uint8_t> v1(0, 0); // 2 bytes (1 + 1 checksum), positions 0 and 1
82-
EEPROMStorage<uint16_t> v2(2, 0); // 3 bytes (2 + 1 checksum), positions 2, 3 and 4
83-
EEPROMStorage<uint32_t> v3(5, 0); // 5 bytes (4 + 1 checksum), positions 5, 6, 6, 8 and 9
84-
EEPROMStorage<float> v4(10, 0.0); // 5 bytes (4 + 1 checksum), positions 10, 11, 12, 13 and 14
85-
EEPROMStorage<bool> v5(15, false); // 2 bytes (1 + 1 checksum), positions 15, 16, 17, 18 and 19
33+
EEPROMStorage<uint8_t> v1(0, 0); // 2 bytes (1 + 1 checksum), positions 0 and 1
34+
EEPROMStorage<uint16_t> v2(2, 0); // 3 bytes (2 + 1 checksum), positions 2, 3 and 4
35+
EEPROMStorage<uint32_t> v3(5, 0); // 5 bytes (4 + 1 checksum), positions 5, 6, 6, 8 and 9
36+
EEPROMStorage<float> v4(10, 0.0); // 5 bytes (4 + 1 checksum), positions 10, 11, 12, 13 and 14
37+
EEPROMStorage<bool> v5(15, false); // 2 bytes (1 + 1 checksum), positions 15, 16, 17, 18 and 19
8638

87-
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 constructs access to EEPROM in this manner.
39+
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.
8840

8941
In the above definitions, `v1` is stored at position 0 and occupies two bytes. The first byte is for the data type and the second byte is for the one byte checksum. The variable `v1` requires two bytes and thus occupies EEPROM memory locations 0 and 1,
9042

@@ -93,6 +45,7 @@ The next variable, `v2`, is located in the position 2, immediately following `v1
9345
> Aligning variables at the beginning of memory or aligning them in a contiguous nature is not required. This just makes it easier, in my opinion, to keep track. You are free to arrange them in any manner that suits your needs.
9446
9547
If you need help determining the proper address for your `EEPROMStorage` instances, open the example sketch called **address.ino** and follow the instructions.
48+
9649
### Determining Data Type Size ###
9750
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.
9851

@@ -101,49 +54,49 @@ If you are not sure of the memory requirement for a given data type, you can use
10154
When using the `sizeof` operator to determine the number of bytes to preserve remember to add one extra byte for the **checksum**.
10255

10356
To see a full demonstration of this, open the example sketch called **sizeof.ino**.
104-
## EEPROM Storage Initialization
105-
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 or not the instance has been initialized.
10657

107-
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 explicitly written. The first time a value is written, the variable is initialized and its checksum is calculated. Each write operation to EEPROM will update the checksum.
108-
## Scope
109-
It is important to note that since `EEPROMStorage` variables are 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. Both instances will share the same value keeping the two instances in sync.
58+
## EEPROM Storage Initialization ##
59+
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 your define a variable and fail to detect whether or not the instance has been initialized.
11060

111-
This behavior can be good and bad depending on your scenario. If two instances are created with a different base type, the result may be unexpected.
61+
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.
11262

113-
> The **EEPROMStorage** variable never caches the value internally and will read the value from EEPROM each time it is requested.
114-
>
115-
> Similarly, each time the instance value is updated it is written directly to EEPROM.
63+
## Scope ##
64+
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.
11665

117-
# Usage
118-
## Declaration
66+
> 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.
67+
68+
# Usage #
69+
## Declaration ##
11970
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.
12071

12172
The syntax for declaration is as follows:
12273

12374
EEPROMStorage<data type> variableName(address, default value);
12475

125-
### Data Type
76+
### Data Type ###
12677
Specifies the underlying data type for the given instance.
12778

128-
### Address
79+
### Address ###
12980
Specifies the starting index in EEPROM where the value will be stored.
13081

131-
### Default Value
82+
### Default Value ###
13283
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).
13384

134-
### Example
85+
### Example ###
13586
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:
13687

13788
EEPROMStorage<int> myInt(50, 10);
138-
## Assignment
89+
90+
## Assignment ##
13991
Using the previous example, assigning a value to the instance is as simple as the assignment shown here.
14092

14193
myInt = 100;
14294

14395
The `EEPROMStorage` class also defines a `set()` method that can be used.
14496

14597
myInt.set(100);
146-
## Retrieving
98+
99+
## Retrieving ##
147100
To get the instance value, simply assign it to a variable, as shown below,
148101

149102
int x = myInt;
@@ -155,7 +108,8 @@ or pass it as an argument in any function that takes an int argument as shown be
155108
The `EEPROMStorage` class also defines a `get()` method that can be used.
156109

157110
int x = myInt.get();
111+
158112
## LICENSE
159-
*Copyright 2017-2020 Daniel Porrey*
113+
*Copyright 2017-2025 Daniel Porrey*
160114

161-
*Licensed under the LGPL-3.0 license*
115+
*Licensed under the GPL-3.0 license*

‎examples/address/address.ino

Lines changed: 49 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright © 2017-2020 Daniel Porrey. All Rights Reserved.
1+
// Copyright © 2017-2025 Daniel Porrey. All Rights Reserved.
22
//
33
// This file is part of the EEPROM-Storage library.
44
//
@@ -17,20 +17,18 @@
1717
// see http://www.gnu.org/licenses/.
1818
//
1919

20-
// ******************************************************************************************
21-
// *** This example will calculate the address and
22-
// *** create initialization code for one or more
23-
// *** EEPROM-Storage variables. Just follow the steps
24-
// *** outlined below.
25-
// ******************************************************************************************
26-
27-
// ******************************************************************************************
28-
// ******************************************************************************************
29-
// ***
30-
// *** Complete Steps 1 through 3 (below) for your project.
31-
// ***
32-
// ******************************************************************************************
33-
// ******************************************************************************************
20+
// ***************************************************************************************
21+
// This example will calculate the address and
22+
// create initialization code for one or more
23+
// EEPROM-Storage variables. Just follow the steps
24+
// outlined below.
25+
// ***************************************************************************************
26+
27+
// ***************************************************************************************
28+
//
29+
// Complete Steps 1 through 3 (below) for your project.
30+
//
31+
// ***************************************************************************************
3432

3533
#if defined(SPARK)
3634
#define word short
@@ -87,22 +85,22 @@ struct definition
8785

8886
void setup()
8987
{
90-
// ***
91-
// *** Initialize the serial port.
92-
// ***
88+
//
89+
// Initialize the serial port.
90+
//
9391
Serial.begin(115200);
9492

95-
// ***
96-
// *** Wait for serial port to connect. Needed
97-
// *** for native USB port only
98-
// ***
93+
//
94+
// Wait for serial port to connect. Needed
95+
// for native USB port only
96+
//
9997
while (!Serial);
10098

101-
// ***
102-
// *** STEP 1 of 3:
103-
// ***
104-
// *** Create a list of definitions that each contain the data type and the default value.
105-
// ***
99+
//
100+
// STEP 1 of 3:
101+
//
102+
// Create a list of definitions that each contain the data type and the default value.
103+
//
106104
definition myDefinitions[] =
107105
{
108106
{ DT_INT, 0 },
@@ -113,28 +111,28 @@ void setup()
113111
{ DT_INT, 10 }
114112
};
115113

116-
// ***
117-
// *** STEP 2 of 3:
118-
// ***
119-
// *** Define the starting address in EEPROM. If you are manually string other data in EEPROM this
120-
// *** address could be defined at the end of that data.
121-
// ***
114+
//
115+
// STEP 2 of 3:
116+
//
117+
// Define the starting address in EEPROM. If you are manually string other data in EEPROM this
118+
// address could be defined at the end of that data.
119+
//
122120
int myFirstAddress = 0;
123121

124-
// ***
125-
// *** STEP 3 of 3:
126-
// ***
127-
// *** Set the value below to true to display comments and false to hide the comments.
128-
// ***
122+
//
123+
// STEP 3 of 3:
124+
//
125+
// Set the value below to true to display comments and false to hide the comments.
126+
//
129127
bool showComments = true;
130128

131-
// ******************************************************************************************
132-
// ******************************************************************************************
133-
// ***
134-
// *** This will output declarations through the serial port.
135-
// ***
136-
// ******************************************************************************************
137-
// ******************************************************************************************
129+
//***************************************************************************************
130+
//***************************************************************************************
131+
//
132+
// This will output declarations through the serial port.
133+
//
134+
//***************************************************************************************
135+
//***************************************************************************************
138136
int items = sizeof(myDefinitions) / sizeof(definition);
139137
Serial.print("The number of declarations defined is "); Serial.println(items);
140138
Serial.println();
@@ -144,9 +142,9 @@ void setup()
144142
{
145143
if (showComments)
146144
{
147-
Serial.println("// ***");
148-
Serial.print("// *** Total length = "); Serial.print(_size[myDefinitions[i].type] + 1); Serial.print(" [Addresses "); Serial.print(nextAddress); Serial.print(" through "); Serial.print(nextAddress + _size[myDefinitions[i].type]); Serial.println("]");
149-
Serial.println("// ***");
145+
Serial.println("//");
146+
Serial.print("// Total length = "); Serial.print(_size[myDefinitions[i].type] + 1); Serial.print(" [Addresses "); Serial.print(nextAddress); Serial.print(" through "); Serial.print(nextAddress + _size[myDefinitions[i].type]); Serial.println("]");
147+
Serial.println("//");
150148
}
151149

152150
Serial.print("EEPROMStorage<"); Serial.print(_name[myDefinitions[i].type]); Serial.print(">("); Serial.print(nextAddress); Serial.print(", "); Serial.print(myDefinitions[i].defaultValue); Serial.println(");");
@@ -158,8 +156,8 @@ void setup()
158156

159157
void loop()
160158
{
161-
// ***
162-
// *** Delay 2 seconds.
163-
// ***
159+
//
160+
// Delay 2 seconds.
161+
//
164162
delay(2000);
165163
}

0 commit comments

Comments
 (0)