{"id":19028565,"url":"https://github.com/pkarsy/nonvolatile","last_synced_at":"2025-09-02T20:43:50.164Z","repository":{"id":202091758,"uuid":"87357530","full_name":"pkarsy/NonVolatile","owner":"pkarsy","description":"Arduino persistent variables (int uint etc). A  special EEPROM wear leveling counter is also included.","archived":false,"fork":false,"pushed_at":"2017-09-25T08:12:56.000Z","size":60,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-01-02T03:25:12.326Z","etag":null,"topics":["arduino","counter","eeprom","leveling","variable","wear"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkarsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-04-05T21:19:31.000Z","updated_at":"2024-02-03T05:08:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"c6e6afbd-12c1-4c5f-a098-c43a4a913974","html_url":"https://github.com/pkarsy/NonVolatile","commit_stats":null,"previous_names":["pkarsy/nonvolatile"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2FNonVolatile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2FNonVolatile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2FNonVolatile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2FNonVolatile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkarsy","download_url":"https://codeload.github.com/pkarsy/NonVolatile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240079621,"owners_count":19744721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","counter","eeprom","leveling","variable","wear"],"created_at":"2024-11-08T21:11:33.860Z","updated_at":"2025-02-21T19:44:07.602Z","avatar_url":"https://github.com/pkarsy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NonVolatile (Non Volatile Variable)\nArduino persistent bool and numeric variables. They can be used like\nglobal variables, but underneath all changes are saved to EEPROM\n\nIn global section:\n\n```C++\n#include \u003cNonVolatile.h\u003e\n// WARNING : NonVolatile can only be GLOBAL variables\nNonVolatile\u003cuint16_t\u003e counter;      // Uses EEPROM addreeses 0-1\nNonVolatile\u003cint\u003e elevation[10];     // Uses addresses 3-22\n```\nNow in the code\n```C++\n// = ++v v++ --v v-- += -= *= /= etc are supported, chaining non tested\ncounter++; // The change is written to EEPROM\nelevation[5]=100; // Immediatelly writen to EEPROM\nelevation[5]=100; // The changes are NOT saved again to reduce EEPROM wear\nSerial.print(elevation[5]++);   // postfix\nSerial.print(++elevation[5]);   // prefix\nfor (int i=0;i\u003c10;i++) elevation[i]=0;\n```\n### Installation\nPut the directory \"NonVolatile\" in the Arduino \"libraries\" location.\nOr you can put the \"NonVolatile.h\" file in the same location as the .ino file\n\n### Types\n- **NonVolatile\\\u003cT\\\u003e** The most importand type this library offers. **T** can be bool,char,int,long\nand the unsigned counterparts.\n- **NvCounter\\\u003cT,N\\\u003e** usually **T** is uint32_t(unsigned long). This special type\nis usefull only as counter (++ is the only operator working), and uses more EEPROM bytes\nbut spreads the writes across the N extra bytes doind EEPROM wear leveling. So if every\nEEPROM cell withands 100000 writes, the counter can be incremented about 100000*N times.\nSee NvCounter Example.\n\nThe next 2 types are not variables but can be used to set the eeprom address used by the variables. Ususally they are\nnot needed and can lead to hard to examine bugs, in case you set the EEPROM location wrong.\n\n- **NvAddress _dummy_var(addr)** Sets the EEPROM location of the next NonVolatile or NvCounter\nvariable to **addr**. See NvExample.\n- **NvSpace _dummy_var2(no_of_bytes)** Reserves some space in EEPROM, in case you need it for other purpose.\nThe next defined variable, will point to the next byte after the reserved space. See NvExample.\n\n### Intended use\nNonVolatile has a very specific purpose. To make it easier to store and use, the (usually few)\nsettings an Arduino project needs. It is unsuitable for data logging. Generally if there\nis a need to use a significant percentage of the EEPROM, you have to use another method.\n\n### Caveats\nAlthough NonVolatile variables look and feel just like normal variables,\nthere are some things to keep in mind:\n- **You must declare them as global variables.** The eeprom location is\ndetermined at runtime. If they are local, they point to elevated EEPROM\nlocation every time. **There are no boundary checks in the code**.\nDeclare all of them one after another,\nlike the example above.\n- The location in EEPROM is determined at runtime. **If the order of the\ndeclarations change, the values of NonVolatile variables\ncan change to different and unexpected values.** If you change the order\nduring development, you must also reset all NonVolatile variables. See\n\"guard variable\" below.\n- **You must make sure you are not modify them too often** or the EEPROM\nwill wear soon (about 100000 writes).\n- In contrast to normal global variables, they are not get 0 at boot.\nThis is the purpose of their existence.\n- In contrast with avr-libc EEMEM variables they are not updated with\ncode upload. If the initial value is important (and usually is) you can\nuse a \"guard\" variable (see below).\n- Reading a NonVolatile should be fast, but writing is slow\n(about 3ms/byte), due to EEPROM write. This can be important in time\ncritical code.\n- Every NonVolatile variable eats some RAM, in addition to the EEPROM space\nit uses. sizeof(var) returns the RAM usage of the object, and not the RAM of\nthe basetype.\n- Do not change NonVolatile variables by direct EEPROM manipulations.\n- If you feel a NonVolatile looks like a normal variable more than it\nshould, you can prefix it with something meaningful like **nv_elevation**\n- Large arrays are RAM hungry. sizeof(arr) gives the RAM they use.\n\n\n### Guard variabe\n\nThis fragment of code inside setup() contains all the NonVolatile variables we need\n```C++\n#define GUARD_SIGN 12345\nif (eeprom_guard!=GUARD_SIGN) {\n    // NonVolatile variables are set to 0\n    counter=0;\n    longvar=0;\n    for (int i=0;i\u003c5;i++) arr[i]=0;\n    float1=0;\n    float2=0;\n    eeprom_guard=GUARD_SIGN;\n}\n\n```\n\nand runs only once. If we change the declarations, most likely\nthe code will run again (due to eeprom_guard misaligment) but\nto be sure we can change the GUARD_SIGN to 12340.\nNote that \"eeprom_guard\" must be itself an NonVolatile. See the examples.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkarsy%2Fnonvolatile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkarsy%2Fnonvolatile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkarsy%2Fnonvolatile/lists"}