8000 add · GyverLibs/FileData@ef874e3 · GitHub
[go: up one dir, main page]
Skip to content

Commit ef874e3

Browse files
GyverLibsGyverLibs
committed
add
1 parent 006ed48 commit ef874e3

File tree

4 files changed

+465
-1
lines changed

4 files changed

+465
-1
lines changed

‎README.md

Lines changed: 242 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,243 @@
1+
[![latest](https://img.shields.io/github/v/release/GyverLibs/FileData.svg?color=brightgreen)](https://github.com/GyverLibs/FileData/releases/latest/download/FileData.zip)
2+
[![Foo](https://img.shields.io/badge/Website-AlexGyver.ru-blue.svg?style=flat-square)](https://alexgyver.ru/)
3+
[![Foo](https://img.shields.io/badge/%E2%82%BD$%E2%82%AC%20%D0%9D%D0%B0%20%D0%BF%D0%B8%D0%B2%D0%BE-%D1%81%20%D1%80%D1%8B%D0%B1%D0%BA%D0%BE%D0%B9-orange.svg?style=flat-square)](https://alexgyver.ru/support_alex/)
4+
[![Foo](https://img.shields.io/badge/README-ENGLISH-blueviolet.svg?style=flat-square)](https://github-com.translate.goog/GyverLibs/FileData?_x_tr_sl=ru&_x_tr_tl=en)
5+
6+
[![Foo](https://img.shields.io/badge/ПОДПИСАТЬСЯ-НА%20ОБНОВЛЕНИЯ-brightgreen.svg?style=social&logo=telegram&color=blue)](https://t.me/GyverLibs)
7+
18
# FileData
2-
Замена EEPROM для ESP8266/32 для хранения любых данных в файлах
9+
Замена EEPROM для ESP8266/32 для хранения любых данных в файлах
10+
- Механизм автоматического "флага" первой записи
11+
- Поддержка всех файловых систем (LittleFS, SPIFFS, SDFS)
12+
- Поддержка любых типов статических данных
13+
- Отложенная запись по таймауту
14+
- "Обновление" данных - файл не перезапишется, если данные не изменились
15+
16+
### Совместимость
17+
ESP8266, ESP32
18+
19+
## Содержание
20+
- [Установка](#install)
21+
- [Инициализация](#init)
22+
- [Использование](#usage)
23+
- [Пример](#example)
24+
- [Версии](#versions)
25+
- [Баги и обратная связь](#feedback)
26+
27+
<a id="install"></a>
28+
## Установка
29+
- Библиотеку можно найти по названи 10000 ю **FileData** и установить через менеджер библиотек в:
30+
- Arduino IDE
31+
- Arduino IDE v2
32+
- PlatformIO
33+
- [Скачать библиотеку](https://github.com/GyverLibs/FileData/archive/refs/heads/main.zip) .zip архивом для ручной установки:
34+
- Распаковать и положить в *C:\Program Files (x86)\Arduino\libraries* (Windows x64)
35+
- Распаковать и положить в *C:\Program Files\Arduino\libraries* (Windows x32)
36+
- Распаковать и положить в *Документы/Arduino/libraries/*
37+
- (Arduino IDE) автоматическая установка из .zip: *Скетч/Подключить библиотеку/Добавить .ZIP библиотеку…* и указать скачанный архив
38+
- Читай более подробную инструкцию по установке библиотек [здесь](https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
39+
### Обновление
40+
- Рекомендую всегда обновлять библиотеку: в новых версиях исправляются ошибки и баги, а также проводится оптимизация и добавляются новые фичи
41+
- Через менеджер библиотек IDE: найти библиотеку как при установке и нажать "Обновить"
42+
- Вручную: **удалить папку со старой версией**, а затем положить на её место новую. "Замену" делать нельзя: иногда в новых версиях удаляются файлы, которые останутся при замене и могут привести к ошибкам!
43+
44+
<a id="init"></a>
45+
## Инициализация
46+
47+
```cpp
48+
FileData;
49+
FileData(fs::FS* fs);
50+
FileData(fs::FS* fs, const char* path);
51+
FileData(fs::FS* fs, const char* path, uint8_t key);
52+
FileData(fs::FS* fs, const char* path, uint8_t key, void* data, uint16_t size);
53+
FileData(fs::FS* fs, const char* path, uint8_t key, void* data, uint16_t size, uint16_t tout);
54+
55+
// fs - файловая система, адрес (&LittleFS, &SDFS..)
56+
// path - путь (имя) файла. Может быть любым, как и расширение ("/myData", "/data/settings.dat")
57+
// key - ключ первой записи. Не рекомендуется задавать 0 и 255. Рекомендуется использовать символы ('A', 'F')
58+
// data - ссылка на переменную (массив, структуру, класс)
59+
// size - размер переменной, можно передать как sizeof(переменная)
60+
// tout - таймаут обновления в миллисекундах (умолч 5000)
61+
```
62+
63+
<a id="usage"></a>
64+
## Использование
65+
66+
В ESP8266/32 EEPROM память эмулируется из Flash памяти, реализация EEPROM во встроенной библиотеке имеет следующие минусы:
67+
- Размер ограничен 4 кБ
68+
- Весь указанный в `EEPROM.begin()` объём памяти дублируется в оперативной памяти до вызова `EEPROM.end()`
69+
- При любом изменении в "EEPROM" памяти (даже 1-го байта) и вызове `EEPROM.commit()` полностью стирается и перезаписывается весь сектор 4 кБ. То есть износ памяти происходит не по ячейкам, а полностью всей EEPROM области! Около 10-20 тысяч перезаписей данных и EEPROM памяти больше нет
70+
71+
Предлагается использовать для хранения данных файловую систему (например встроенную LittleFS), которая сама заботится о перезаписи памяти и занимается ротацией файлов по отведённой области, что многократно увеличивает ресурс памяти и надёжность хранения данных. Также это позволит "скачивать" сохранённые данные, делать бэкапы и так далее. Данная библиотека является аналогом [EEManager](https://github.com/GyverLibs/EEManager) и имеет схожие с ней механизмы и возможности:
72+
- "Подключение" статических переменных любого типа, библиотека сама будет читать и писать их содержимое в файл
73+
- Механизм "ключа первого запуска" - если файл не существует или не содержит указанный ключ - в файл будут записаны данные "по умолчанию"
74+
- Механизм отложенной записи по таймауту - после изменения данных достаточно дать библиотеке команду на обновление, и она обновит данные по истечению таймаута
75+
76+
```cpp
77+
// установить файловую систему и путь к файлу
78+
void setFS(fs::FS* nfs, const char* path);
79+
80+
// установить ключ
81+
void setKey(uint8_t key);
82+
83+
// подключить данные (переменную)
84+
void setData(void* data, uint16_t size);
85+
86+
// установить таймаут записи
87+
void setTimeout(uint16_t tout);
88+
89+
// прочитать файл в переменную
90+
// возврат: FD_FS_ERR/FD_FILE_ERR/FD_WRITE/FD_ADD/FD_READ
91+
FDstat_t read();
92+
93+
// обновить сейчас
94+
// возврат: FD_FS_ERR/FD_FILE_ERR/FD_WRITE/FD_NO_DIF
95+
FDstat_t updateNow();
96+
97+
// отложить обновление на заданный таймаут
98+
void update();
99+
100+
// тикер, обновит данные по таймауту
101+
// возврат: FD_FS_ERR/FD_FILE_ERR/FD_WRITE/FD_NO_DIF/FD_WAIT/FD_IDLE
102+
FDstat_t tick();
103+
104+
// записать данные в файл
105+
// возврат: FD_FS_ERR/FD_FILE_ERR/FD_WRITE
106+
FDstat_t write();
107+
108+
// сбросить ключ
109+
// возврат: FD_FS_ERR/FD_FILE_ERR/FD_RESET
110+
FDstat_t reset();
111+
112+
// включить режим увеличения данных с добавлением в файл без очистки
113+
void addWithoutWipe(bool addw);
114+
115+
// ============== СТАТУСЫ ==============
116+
FD_IDLE // 0 - холостая работа
117+
FD_WAIT // 1 - ожидание таймаута
118+
FD_FS_ERR // 2 - ошибка файловой системы
119+
FD_FILE_ERR // 3 - ошибка открытия файла
120+
FD_WRITE // 4 - запись данных в файл
121+
FD_READ // 5 - чтение данных из файла
122+
FD_ADD // 6 - добавление данных в файл
123+
FD_NO_DIF // 7 - данные не отличаются (не записаны)
124+
FD_RESET // 8 - произведён сброс ключа
125+
```
126+
127+
### Порядок действий (глобальные данные)
128+
Для хранения "настроек" программы в глобальной области, чтобы всегда иметь к ним доступ:
129+
1. Создать глобальную переменную и объект `FileData`
130+
2. Передать переменную в объект
131+
3. Прочитать данные `read()` при запуске
132+
4. Вызывать `tick()` в `loop()`
133+
5. После изменения данных вызвать `update()`
134+
6. По истечению таймаута данные сами запишутся в файл
135+
136+
> Таким образом безопасно вызывать `update()` несколько раз подряд, например при изменении "настройки" кнопками - данные обновятся только после окончания ввода и таймаута
137+
138+
### Порядок действий (локальные данные)
139+
Для хранения настроек в файле и чтении/изменении внутри функций в программе:
140+
1. Создать переменную и объект `FileData`
141+
2. Передать переменную в объект
142+
3. Прочитать данные `read()`
143+
4. Если данные изменились и их нужно сохранить - вызвать `updateNow()`
144+
145+
```cpp
146+
void func() {
147+
Data mydata;
148+
FileData data(&LittleFS, "/data.dat", 'A', &mydata, sizeof(mydata));
149+
data.read();
150+
// ...
151+
data.updateNow();
152+
}
153+
```
154+
155+
<a id="example"></a>
156+
## Пример
157+
158+
```cpp
159+
#include <Arduino.h>
160+
#include <FileData.h>
161+
#include <LittleFS.h>
162+
163+
struct Data {
164+
uint8_t val8;
165+
uint16_t val16;
166+
uint32_t val32 = 12345;
167+
char str[20];
168+
};
169+
Data mydata;
170+
171+
FileData data(&LittleFS, "/data.dat", 'B', &mydata, sizeof(mydata));
172+
173+
void setup() {
174+
Serial.begin(115200);
175+
delay(1000);
176+
Serial.println();
177+
178+
LittleFS.begin();
179+
180+
// прочитать данные из файла в переменную
181+
// при первом запуске в файл запишутся данные из структуры
182+
FDstat_t stat = data.read();
183+
184+
switch (stat) {
185+
case FD_FS_ERR: Serial.println("FS Error");
186+
break;
187+
case FD_FILE_ERR: Serial.println("Error");
188+
break;
189+
case FD_WRITE: Serial.println("Data Write");
190+
break;
191+
case FD_ADD: Serial.println("Data Add");
192+
break;
193+
case FD_READ: Serial.println("Data Read");
194+
break;
195+
default:
196+
break;
197+
}
198+
199+
Serial.println("Data read:");
200+
Serial.println(mydata.val8);
201+
Serial.println(mydata.val16);
202+
Serial.println(mydata.val32);
203+
Serial.println(mydata.str);
204+
}
205+
206+
void loop() {
207+
// data.tick(); // вызывать тикер в loop
208+
209+
// можно отловить момент записи
210+
if (data.tick() == FD_WRITE) Serial.println("Data updated!");
211+
212+
// запишем в данные строку из монитора порта
213+
// а также присвоим остальным переменным случайные значения
214+
if (Serial.available()) {
215+
int len = Serial.readBytes(mydata.str, 20);
216+
mydata.str[len] = '\0';
217+
mydata.val8 = random(255);
218+
mydata.val16 = random(65000);
219+
Serial.println("Update");
220+
221+
// отложить обновление
222+
data.update();
223+
}
224+
}
225+
```
226+
227+
<a id="versions"></a>
228+
## Версии
229+
- v1.0
230+
231+
<a id="feedback"></a>
232+
## Баги и обратная связь
233+
При нахождении багов создавайте **Issue**, а лучше сразу пишите на почту [alex@alexgyver.ru](mailto:alex@alexgyver.ru)
234+
Библиотека открыта для доработки и ваших **Pull Request**'ов!
235+
236+
При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать:
237+
- Версия библиотеки
238+
- Какой используется МК
239+
- Версия SDK (для ESP)
240+
- Версия Arduino IDE
241+
- Корректно ли работают ли встроенные примеры, в которых используются функции и конструкции, приводящие к багу в вашем коде
242+
- Какой код загружался, какая работа от него ожидалась и как он работает в реальности
243+
- В идеале приложить минимальный код, в котором наблюдается баг. Не полотно из тысячи строк, а минимальный код

‎keywords.txt

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
#######################################
2+
# Syntax Coloring Map For FileData
3+
#######################################
4+
5+
#######################################
6+
# Datatypes (KEYWORD1)
7+
#######################################
8+
FileData KEYWORD1
9+
10+
#######################################
11+
# Methods and Functions (KEYWORD2)
12+
#######################################
13+
setFS KEYWORD2
14+
setKey KEYWORD2
15+
setData KEYWORD2
16+
setTimeout KEYWORD2
17+
read KEYWORD2
18+
updateNow KEYWORD2
19+
update KEYWORD2
20+
tick KEYWORD2
21+
write KEYWORD2
22+
addWithoutWipe KEYWORD2
23+
24+
#######################################
25+
# Constants (LITERAL1)
26+
#######################################
27+
FD_IDLE LITERAL1
28+
FD_WAIT LITERAL1
29+
FD_FS_ERR LITERAL1
30+
FD_FILE_ERR LITERAL1
31+
FD_WRITE LITERAL1
32+
FD_READ LITERAL1
33+
FD_ADD LITERAL1
34+
FD_NO_DIF LITERAL1
35+
FD_RESET LITERAL1

‎library.properties

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name=FileData
2+
version=1.0
3+
author=AlexGyver <alex@alexgyver.ru>
4+
maintainer=AlexGyver <alex@alexgyver.ru>
5+
sentence=Simple library for storing any data in file
6+
paragraph=Simple library for storing any data in file
7+
category=Data Storage
8+
url=https://github.com/GyverLibs/FileData
9+
architectures=ESP8266, ESP32

0 commit comments

Comments
 (0)
0