8000 english readme · GyverLibs/FileData@157ab71 · GitHub
[go: up one dir, main page]
Skip to content

Commit 157ab71

Browse files
GyverLibsGyverLibs
committed
english readme
1 parent e6650d5 commit 157ab71

File tree

1 file changed

+242
-0
lines changed

1 file changed

+242
-0
lines changed

‎README_EN.md

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
This is an automatic translation, may be incorrect in some places. See sources and examples!
2+
3+
# FILEDATA
4+
Replacing EEPROM for ESP8266/32 for storing any data in files
5+
- the mechanism of the automatic "flag" of the first record
6+
- Support for all file systems (Littlefs, Spiffs, SDFS)
7+
- support for any type of static data
8+
- Putting an entry by timeout
9+
- "Update" data - the file will not be rewritten if the data has not changed
10+
11+
## compatibility
12+
ESP8266, ESP32
13+
14+
## Content
15+
- [installation] (# Install)
16+
- [initialization] (#init)
17+
- [use] (#usage)
18+
- [Example] (# Example)
19+
- [versions] (#varsions)
20+
- [bugs and feedback] (#fedback)
21+
22+
<a id="install"> </a>
23+
## Installation
24+
- The library can be found by the name ** filleda ** and installed through the library manager in:
25+
- Arduino ide
26+
- Arduino ide v2
27+
- Platformio
28+
- [download the library] (https://github.com/gyverlibs/filedata/archive/refs/heads/main.zip). Zip archive for manual installation:
29+
- unpack and put in * C: \ Program Files (X86) \ Arduino \ Libraries * (Windows X64)
30+
- unpack and put in * C: \ Program Files \ Arduino \ Libraries * (Windows X32)
31+
- unpack and put in *documents/arduino/libraries/ *
32+
- (Arduino id) Automatic installation from. Zip: * sketch/connect the library/add .Zip library ... * and specify downloaded archive
33+
- Read more detailed instructions for installing libraries [here] (https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%BD%D0%BE%BE%BE%BED0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
34+
### Update
35+
- I recommend always updating the library: errors and bugs are corrected in the new versions, as well as optimization and new features are added
36+
- through the IDE library manager: find the library how to install and click "update"
37+
- Manually: ** remove the folder with the old version **, and then put a new one in its place.“Replacement” cannot be done: sometimes in new versions, files that remain when replacing are deleted and can lead to errors!
38+
39+
<a id="init"> </a>
40+
## initialization
41+
42+
`` `CPP
43+
FILEDATA;
44+
FILEDATA (fs :: fs* fs);
45+
FILEDATA (fs :: fs* fs, const char* Path);
46+
FILEDATA (fs :: fs* fs, const char* Path, uint8_t key);
47+
FILEDATA (FS :: fs* fs, const char* Path, Uint8_t Key, Void* Data, Uint16_T SIZE);
48+
FILEDATA (FS :: fs* fs, const chaar* Path, Uint8_t Key, Void* Data, Uint16_T Size, Uint16_T Tout);
49+
50+
// fs - file system, address (& littlefs, & sdfs ..)
51+
// Path - the path (name) of the file.It can be any, as well as the extension ("/mydata", "/data/settings.dat")
52+
// Key - the key of the first record.It is not recommended to set 0 and 255. It is recommended to use the characters ('a', 'f')
53+
// DATA - link to a variable (array, structure, class)
54+
// size - the size of the variable, can be conveyed as sizeof (variable)
55+
// Tout - Timesout updates in milliseconds (silent 5000)
56+
`` `
57+
58+
<a id="usage"> </a>
59+
## Usage
60+
61+
In ESP8266/32 EEPROM, memory is emulated from Flash memory, the implementation of Eeprom in the built -in library has the following disadvantages:
62+
- size is limited 4 kb
63+
- all indicated in `eeprom.begin ()` Memory volume is duplicated in RAM before the call `eeprom.end ()` ``
64+
- In case of any change in the "eeprom" memory (even the 1st byte) and the call `eeprom.commit ()` the entire sector 4 KB is completely erased and rewritten.That is, memory wear does not occur in the cells, but completely the entire EEPROM region!About 10-20 thousandCranberries of data from data counts and eeprom memory no longer
65+
66+
It is proposed to use the file system (for example, built -in Littlefs), which itself takes care of the rewriting of memory and is engaged in the rotation of files in the designated area, which repeatedly increases the memory resource and the reliability of data storage.It will also allow you to "download" saved data, make backups and so on.This library is an analogue [eemanager] (https://github.com/gyverlibs/eemanager) and has similar mechanisms and opportunities:
67+
- "Connection" of static variables of any type, the library itself will read and write their contents to the file
68+
- the “first launch key” mechanism - if the file does not exist or does not contain the specified key - the “default” data will be written into the file
69+
- the mechanism of the postponed record by timeout - after changing the data, it is enough to give the library the command to update, and it will update the data after the time of the timeout
70+
71+
`` `CPP
72+
// install the file system and the path to the file
73+
VOID setfs (fs :: fs* nfs, const char* Path);
74+
75+
// set the key
76+
VOID Setkey (Uint8_t Key);
77+
78+
// connect data (variable)
79+
VOID Setdata (Void* Data, Uint16_T Size);
80+
81+
// Install the timing of records
82+
VOID settimeout (uint16_t tout);
83+
84+
// Read the file in the variable
85+
// Return: fd_fs_err/fd_file_err/fd_write/fd_add/fd_read
86+
Fdstat_t read ();
87+
88+
// update now
89+
// Return: fd_fs_err/fd_file_err/fd_write/fd_no_dif
90+
Fdstat_t updatatenow ();
91+
92+
// postpone the update for a given timaut
93+
VOID update ();
94+
95+
// ticker, upgrade data by timeout
96+
// Return: fd_fs_err/fd_file_err/fd_write/fd_no_dif/fd_wait/fd_idle
97+
Fdstat_t tick ();
98+
99+
// write data to the file
100+
// Return: fd_fs_err/fd_file_err/fd_write
101+
FDSTAT_T WRITE ();
102+
103+
// Reset the key
104+
// Return: fd_fs_err/fd_file_err/fd_reset
105+
Fdstat_t reset ();
106+
107+
// enable the data increase mode with the addition to the file without cleaning
108+
VOID Addwithoutwipe (Bool Addw);
109+
110+
// ======================================
111+
Fd_idle // 0 - idle work
112+
Fd_wait // 1 - expectation of a timeout
113+
Fd_fs_err // 2 - file system error
114+
Fd_file_err // 3 - file opening error
115+
FD_WRITE // 4 - Write data to the file
116+
Fd_read // 5 - reading data from a file
117+
Fd_add // 6 - Adding data to the file
118+
FD_NO_DIF // 7 - data do not differ (not recorded)
119+
FD_Reset // 8 - the key is discharged
120+
`` `
121+
122+
### Procedure (global data)
123+
To store the "settings" of the program in the global region, to always have access to them:
124+
1. Create a global variable and object `filledata`
125+
2. Pass the variable to the object
126+
3. Read the data `read ()` when starting
127+
4. Call `tick ()` in `loop ()`
128+
5. After changing the data, call `update ()`
129+
6. At the expiration of the timeout, the data themselves will be written to the file
130+
131+
> Thus, it is safe to call `update ()` several times in a row, for example, when the "configuration" changes "buttons - the data will be updated only after the input and the timeage is completed
132+
133+
### Procedure (local data)
134+
To store settings in the file and reading/changing the functions in the program:
135+
1. Create a variable and object `filledata`
136+
2. Pass the variable to the object
137+
3. Read the data `read ()`
138+
4. If the data has changed and they need to be saved - call `updatenow ()`
139+
140+
`` `CPP
141+
VOID FUNC () {
142+
Data Mydata;
143+
Finedata Data (& Littlefs, "/data.dat", 'a', & mydata, sizeof (mydata));
144+
Data.read ();
145+
// ...
146+
Data.updatatenow ();
147+
}
148+
`` `
149+
150+
### data change
151+
- when changing the size of the data (when changing the number of fields in the structure), a discharge will be carried out when reading - a new structure will be written into the file
152+
- When installing the flag `Addwithoutwipe (True)` and with ** increasing ** data size: the data of the old size will be read from the file, then new data will be added to the file (the difference with the old size).This is convenient when developing a project - adding new "settings" will not discard the old
153+
154+
<a id="EXAMPLE"> </a>
155+
## Example
156+
157+
`` `CPP
158+
#include <arduino.h>
159+
#incLude <filleda.h>
160+
#include <Littlefs.h>
161+
162+
Struct Data {
163+
uint8_t val8;
164+
uint16_t val16;
165+
uint32_t val32 = 12345;
166+
Chard [20];
167+
};
168+
Data Mydata;
169+
170+
Finedata Data (& LittlefsCranberry, "/data.dat", 'b', & mydata, sizeof (mydata));
171+
172+
VOID setup () {
173+
Serial.Begin (115200);
174+
DELAY (1000);
175+
Serial.println ();
176+
177+
Littlefs.Begin ();
178+
179+
// Read the data from the file to the variable
180+
// at the first launch to the file, data from the structure will be written
181+
Fdstat_t stat = data.read ();
182+
183+
Switch (stat) {
184+
Case fd_fs_err: serial.println ("fs error");
185+
Break;
186+
Case fd_file_err: serial.println ("error");
187+
Break;
1 10000 88+
Case fd_write: serial.println ("Data Write");
189+
Break;
190+
Case fd_add: serial.println ("Data Add");
191+
Break;
192+
Case fd_read: serial.println ("Data Read");
193+
Break;
194+
Default:
195+
Break;
196+
}
197+
198+
Serial.println ("Data Read:");
199+
Serial.println (mydata.val8);
200+
Serial.println (mydata.val16);
201+
Serial.println (mydata.val32);
202+
Serial.println (mydata.str);
203+
}
204+
205+
VOID loop () {
206+
// DATA.Tick ();// call a ticker in look
207+
208+
// you can catch the moment of recording
209+
if (Data.tick () == fd_write) serial.println ("Data updated!");
210+
211+
// write to the data from the port monitor
212+
// and also assign the rest of the variable random values
213+
if (serial.available ()) {
214+
int len = serial.Readbytes (mydata.str, 20);
215+
mydata.str [len] = '\ 0';
216+
MyData.val8 = Random (255);
217+
MyData.val16 = Random (65000);
218+
Serial.println ("update");
219+
220+
// postpone the update
221+
Data.update ();
222+
}
223+
}
224+
`` `
225+
226+
<a id="versions"> </a>
227+
## versions
228+
- V1.0
229+
230+
<a id="feedback"> </a>
231+
## bugs and feedback
232+
Create ** Issue ** when you find the bugs, and better immediately write to the mail [alex@alexgyver.ru] (mailto: alex@alexgyver.ru)
233+
The library is open for refinement and your ** pull Request ** 'ow!
234+
235+
When reporting about bugs or incorrect work of the library, it is necessary to indicate:
236+
- The version of the library
237+
- What is MK used
238+
- SDK version (for ESP)
239+
- version of Arduino ide
240+
- whether the built -in examples work correctly, in which the functions and designs are used, leading to a bug in your code
241+
- what code has been loaded, what work was expected from it and how it works in reality
242+
- Ideally, attach the minimum code in which the bug is observed.Not a canvas of a thousand lines, but a minimum code

0 commit comments

Comments
 (0)
0