Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pkarsy/nonvolatile

Arduino persistent variables (int uint etc). A special EEPROM wear leveling counter is also included.
https://github.com/pkarsy/nonvolatile

arduino counter eeprom leveling variable wear

Last synced: about 1 month ago
JSON representation

Arduino persistent variables (int uint etc). A special EEPROM wear leveling counter is also included.

Awesome Lists containing this project

README 

        
# NonVolatile (Non Volatile Variable)

Arduino persistent bool and numeric variables. They can be used like

global variables, but underneath all changes are saved to EEPROM



In global section:



```C++

#include 

// WARNING : NonVolatile can only be GLOBAL variables

NonVolatile counter;      // Uses EEPROM addreeses 0-1

NonVolatile elevation[10];     // Uses addresses 3-22

```

Now in the code

```C++

// = ++v v++ --v v-- += -= *= /= etc are supported, chaining non tested

counter++; // The change is written to EEPROM

elevation[5]=100; // Immediatelly writen to EEPROM

elevation[5]=100; // The changes are NOT saved again to reduce EEPROM wear

Serial.print(elevation[5]++);   // postfix

Serial.print(++elevation[5]);   // prefix

for (int i=0;i<10;i++) elevation[i]=0;

```

### Installation

Put the directory "NonVolatile" in the Arduino "libraries" location.

Or you can put the "NonVolatile.h" file in the same location as the .ino file



### Types

- **NonVolatile\** The most importand type this library offers. **T** can be bool,char,int,long

and the unsigned counterparts.

- **NvCounter\** usually **T** is uint32_t(unsigned long). This special type

is usefull only as counter (++ is the only operator working), and uses more EEPROM bytes

but spreads the writes across the N extra bytes doind EEPROM wear leveling. So if every

EEPROM cell withands 100000 writes, the counter can be incremented about 100000*N times.

See NvCounter Example.



The next 2 types are not variables but can be used to set the eeprom address used by the variables. Ususally they are

not needed and can lead to hard to examine bugs, in case you set the EEPROM location wrong.



- **NvAddress _dummy_var(addr)** Sets the EEPROM location of the next NonVolatile or NvCounter

variable to **addr**. See NvExample.

- **NvSpace _dummy_var2(no_of_bytes)** Reserves some space in EEPROM, in case you need it for other purpose.

The next defined variable, will point to the next byte after the reserved space. See NvExample.



### Intended use

NonVolatile has a very specific purpose. To make it easier to store and use, the (usually few)

settings an Arduino project needs. It is unsuitable for data logging. Generally if there

is a need to use a significant percentage of the EEPROM, you have to use another method.



### Caveats

Although NonVolatile variables look and feel just like normal variables,

there are some things to keep in mind:

- **You must declare them as global variables.** The eeprom location is

determined at runtime. If they are local, they point to elevated EEPROM

location every time. **There are no boundary checks in the code**.

Declare all of them one after another,

like the example above.

- The location in EEPROM is determined at runtime. **If the order of the

declarations change, the values of NonVolatile variables

can change to different and unexpected values.** If you change the order

during development, you must also reset all NonVolatile variables. See

"guard variable" below.

- **You must make sure you are not modify them too often** or the EEPROM

will wear soon (about 100000 writes).

- In contrast to normal global variables, they are not get 0 at boot.

This is the purpose of their existence.

- In contrast with avr-libc EEMEM variables they are not updated with

code upload. If the initial value is important (and usually is) you can

use a "guard" variable (see below).

- Reading a NonVolatile should be fast, but writing is slow

(about 3ms/byte), due to EEPROM write. This can be important in time

critical code.

- Every NonVolatile variable eats some RAM, in addition to the EEPROM space

it uses. sizeof(var) returns the RAM usage of the object, and not the RAM of

the basetype.

- Do not change NonVolatile variables by direct EEPROM manipulations.

- If you feel a NonVolatile looks like a normal variable more than it

should, you can prefix it with something meaningful like **nv_elevation**

- Large arrays are RAM hungry. sizeof(arr) gives the RAM they use.



### Guard variabe



This fragment of code inside setup() contains all the NonVolatile variables we need

```C++

#define GUARD_SIGN 12345

if (eeprom_guard!=GUARD_SIGN) {

    // NonVolatile variables are set to 0

    counter=0;

    longvar=0;

    for (int i=0;i<5;i++) arr[i]=0;

    float1=0;

    float2=0;

    eeprom_guard=GUARD_SIGN;

}



```



and runs only once. If we change the declarations, most likely

the code will run again (due to eeprom_guard misaligment) but

to be sure we can change the GUARD_SIGN to 12340.

Note that "eeprom_guard" must be itself an NonVolatile. See the examples.