ESP32 Storage programming

Понятие хранения в программировании хранения включает в себя методы хранения данных для последующего использования. ESP32 имеет ОЗУ, но когда ESP32 выключен, содержимое ОЗУ теряется. Таким образом, нам нужен механизм, чтобы сделать это хранилище более постоянным. ESP32 обычно имеет доступ к флэш-памяти, которая электрически подключается через специальную шину SPI. Обычно размер флеш-памяти составляет 4 Мбайт. Мы можем получить доступ к флэш-памяти через SPI Flash API.

Partition table

Архитектура ESP32 представляет собой концепцию, называемую таблицей разделов, которая в основном представляет собой «карту» или «Макет» того, что содержится во флэш-памяти. Таблица разделов находится в 0x8000 во флэш-памяти и имеет длину 0xC00 байт, что обеспечивает пространство для около 95 отдельных таблиц записей. Каждая запись в таблице имеет структуру записи, которая логически содержит:

• type – The type of the partition. One of:
  • data
  • app
• subtype – The sub-type of the partition. One of:
  • nvs – Used for non volatile storage.
  • phy
  • factory
  • coredump – Used to hold core dumps.
  • ota
  • fat – Used for the FAT file system.
• address – The offset address (flash) of the start of the partition.
• size – The size of the partition in bytes.
• label – An optional null terminated string (max 16 characters + NULL)
• encrypted – Is the partition encrypted.

Таблица разделов доступна для наших приложений только для чтения и может получена с помощью API ESP-IDF. Таблица записывается во флэш-память при прошивке.

Размер смещения является необязательным. Пустые смещения будут размещены смежно после предыдущих данных. Смещения выравниваются по 64 КБ.

Инструмент под названием «gen_esp32part.py» доступен как часть инструментария для построения двоичных представлений таблицы. Мы можем построить двоичную таблицу из файла значений, разделенных запятыми, используя: $ Gen_esp32part.py -verify input_partitions.csv binary_partitions.bin

Мы можем преобразовать двоичный файл обратно в CSV, используя:

$ Gen_esp32part.py --verify binary_partitions.bin input_partitions.csv

И мы можем перечислить содержимое двоичного файла, используя: $ Gen_esp32part.py binary_partitions.bin

Таблица разделов, используемая вашим приложением, определяется командой make menuconfig в разделе Partition Table

See also: • Partition API • esp_vfs_fat_spiflash_mount • esp_vfs_fat_register

Non Volatile Storage

Энергонезависимое хранилище - это память, которая может быть записана так, чтобы после выключения или перезапуска, те же данные могут быть прочитаны из него снова без потерь. В рамках этих данных мы можем хранить конфигурационные и эксплуатационные значения для наших приложений. Например, мы можем сохранить сетевой SSID и пароль таким образом, чтобы когда устройство перезапускается, он знает, к какой сети подключиться, и пароль для представления.

Хранилище разделено на именованные области. Для данной именованной области мы можем сохранить и прочитать пару имя / значение в хранилище. Существуют функции getter / setter для большинства типов данных, включая целые числа с знаком и без знака, строки и двоичные данные.

Именованная область открывается для доступа вызовом nvs_open (). Имя области передается как параметр. Нам возвращен логический «дескриптор», который мы впоследствии можем использовать для ссылки на эту область хранения. Как только мы получим дескриптор, мы можем записать и прочитать элементы именованных данных. Элементы данных ссылаются на имя ключа эффективно превращая область хранения в хэш-карту. Если мы изменим данные, выполнив функцию set, это не приведет к тому, что данные будут записаны в энергонезависимое хранилище. Вместо этого хранилище обновляется, когда мы вызываем nvs_commit (). Это зависит от внутренней реализации того, когда выполняется фактическое обновление, и это может произойти до nvs_commit (). Контракт заключается в том, что, когда мы возвращаемся из nvs_commit (), мы уверены, что все обновления обработаны. Когда мы выполнили все наши наборы и получили, мы должны вызвать nvs_close (), чтобы объявить, что мы больше не будем работать с хранилищем в это время, чтобы время выполнения могло очистить любые ресурсы, которые он мог открыть.

Детали алгоритмов, используемых для управления NVS, раскрываются в документации. Цель NVS на высоком уровне - хранить простые строки и целые числа и другие флаги, а не быть богатой структурой «файловой системы». В настоящее время дефрагментация не выполняется в хранилище.

See also: • nvs_open • nvs_commit • nvs_close

Virtual File System

Виртуальная файловая система (VFS) - это архитектура, предоставляемая ESP-IDF, которая дает нам возможность сохранять и загружать данные из наших приложений с использованием ввода-вывода файловой системы.

VFS не привязан к какой-либо одной конкретной технологии, а вместо этого является архитектурной абстракцией, используемой для обеспечения интерфейса ввода-вывода для множества различных реализаций.

Ключом к VFS является тип данных, называемый esp_vfs_t. Эта структура содержит следующее:

• fd_offset –
• flags – Operational flags. Use ESP_VFS_FLAG_DEFAULT.
• close/close_p – Close a previously opened file.
• closedir/closedir_p – Close a previously opened directory.
• fstat/fstat_p – Get stats/details of a file.
• link/link_p – Create a new link to a file.
• lseek/lseek_p – Change the data pointer within a file.
• mkdir/mkdir_p – Create a new directory entry.
• open/open_p – Open a named file.
• opendir/opendir_p – Open a directory for reading.
• read/read_p – Read the contents of a file.
• readdir/readdir_p – Read a record from a directory.
• rename/rename_p – Rename a file.
• rmdir/rmdir_p – Delete a directory entry.
• seekdir/seekdir_p – Set the position of the next readdir().
• stat/stat_p – Get stats/details of a file.
• telldir/telldir_p – Return the current direction stream.
• unlink/unlink_p – Remove a file.
• write/write_p – Write into a file.

После заполнения структуры нам необходимо зарегистрировать нашу новую виртуальную файловую систему с вызовом esp_vfs_register ().

Нам нужно знать, что предполагаемый вызывающий файл ввода-вывода ожидает среду, похожую на POSIX.

See also: • esp_vfs_register • Virtual filesystem componen t

VFS Implementations

Поскольку VFS предоставляет архитектурную модель, нам необходимо рассмотреть ее фактические реализации. По состоянию на 2016-11 реализаций пока нет. Первыми ожидаемыми реализациями будут файловые системы, хранящиеся во флэш-памяти. Они будут обеспечивать постоянное хранение данных через API файлов. Первыми кандидатами на реализацию являются FAT и/или SPIFFS.

Мы также можем создавать собственные специализированные реализации. Одной из интересных идей - позволить ESP32 быть сетевым клиентом внешних файловых систем. Например для:

• NFS
• SSH
• FTP
• TFTP
• HTTP servers
• Google Drive
• Other cloud based systems

Может показаться странным иметь доступ к данным сетевого устройства через файловый механизм только для того, чтобы он затем обрабатывал запросы в качестве другого сетевого вызова ... однако могут быть преимущества. ESP32 может кэшировать полученные данные либо в ОЗУ, либо в локальной флэш-памяти и выполнять только внешние сетевые запросы, если запрашиваемые данные недоступны в другом месте.

При работе с файловыми вводами-выводами мы можем использовать механизмы файлов потоков, импортированные через «stdio.h», или использовать ввод / вывод файлов нижнего уровня, импортированных через «fcntl.h».

See also:

• VFS mapping to SPIFFS

FATFS File System

Файловая система FatFs представляет собой реализацию файловой системы FAT / exFAT, как показано в более ранних операционных системах ПК, таких как MS-DOS и ранние версии Windows (до FAT32 и NTFS).

Реализация является открытым исходным кодом и поставляется «предварительно перенесенной» в ESP32 как часть дистрибутива ESP-IDF. Отображение ESP-IDF для FATFS сопоставляет файловую систему с функциями posix IO. Это означает, что нам не нужно изучать какие-либо специальные API-интерфейсы для чтения и записи файлов. Мы можем использовать функции open (), close (), read (), write () и другие методы, открытые через виртуальную файловую систему.

Прежде чем мы сможем использовать эти API, нам нужно выполнить предварительную настройку.

1. Вызовите esp_vfs_fat_register
2. Вызовите ff_diskio_register
3. Вызовите f_mount

Отменить регистрацию

1. Закройте все открытые файлы
2. Вызвать f_mount с помощью NULL
3. Вызовите ff_diskio_register с помощью NULL
4. Вызовите esp_vfs_fat_unregister

По умолчанию имена файлов ограничены старым форматом 8.3 (короткие имена), однако, если мы выберем, мы можем включить длительное управление именами файлов в настройках make menuconfig.

См. Также:

• FatFS – Generic FAT File System Module
• Virtual File System
• FatFs file system

Spiffs File System

Файловая система SPI (SPIFFS) - это механизм файловой системы, предназначенный для встроенных устройств. Чтобы настроить SPIFF, нам нужно определить некоторые числа. Во-первых, это размер физической страницы. Далее следует размер физического блока. Затем мы определяем размер логического блока. Это будет некоторый целочисленный множитель размера физического блока.

Вся файловая система SPIFFS должна быть кратной размеру логического блока. Далее следует размер логической страницы, который является некоторым множителем размера логического блока.

Общий размер ESP32 составляет 64 КБ для размера логического блока и 256 для размера логической страницы.

Чтобы было ясно, 1 блок - это n x страниц.

Когда выполняется вызов API SPIFFS, нулевой или положительный ответ указывает на успех, а значение <0 указывает на ошибку. Характер ошибки можно получить через вызов SPIFFS_errno (). Реализация SPIFFS не обеспечивает прямой доступ к флэш-памяти. Вместо этого функциональная область, называемая уровнем абстракции оборудования («hal»), предоставляет эту услугу. Для интеграции SPIFFS необходимо создать три функции, которые имеют следующие заголовки:

s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst)
s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src)
s32_t (*spiffs_erase)(u32_t addr, u32_t size)

В случае успешного выполнения, код возврата SPIFFS_OK (0). На ESP32 они будут сопоставляться с API-интерфейсами SPI.

Чтобы использовать файловую систему SPIFFS, мы должны выполнить вызов SPIFFS_mount (). В результате создается структура конфигурации, которая сообщает SPIFFS, сколько флэш-памяти доступно и множество других свойств. Кроме того, некоторые рабочие хранилища должны быть выделены для различных внутренних операций. Эти размеры могут быть настроены. Ниже приведен пример конфигурации для установки файловых систем:

#define LOG_PAGE_SIZE 256

static uint8_t spiffs_work_buf[LOG_PAGE_SIZE*2];
static uint8_t spiffs_fds[32*sizeof(uint32_t)];
static uint8_t spiffs_cache_buf[(LOG_PAGE_SIZE+32)*4];

spiffs fs;
spiffs_config cfg;
cfg.phys_size = 512*1024; // use 512K
cfg.phys_addr = 2*1024*1024 - cfg.phys_size; // start spiffs at 2MB - 512K
cfg.phys_erase_block = 65536; // according to datasheet
cfg.log_block_size = 65536; // let us not complicate things
cfg.log_page_size = LOG_PAGE_SIZE; // as we said

cfg.hal_read_f = esp32_spi_flash_read;
cfg.hal_write_f = esp32_spi_flash_write;
cfg.hal_erase_f = esp32_spi_flash_erase;
int res = SPIFFS_mount(&fs, &cfg, spiffs_work_buf, spiffs_fds, sizeof(spiffs_fds), spiffs_cache_buf, sizeof(spiffs_cache_buf), 0);

После того, как мы установили файловую систему, мы можем открыть файл, записать в него контент и закрыть его. Например:

char *fileName = "/f1/my_file";
spiffs_file fd = SPIFFS_open(&fs, fileName,
SPIFFS_CREAT | SPIFFS_TRUNC | SPIFFS_RDWR, 0);
SPIFFS_write(&fs, fd, (u8_t *)"Hello world", 12);
SPIFFS_close(&fs, fd);

Аналогично, если мы хотим прочитать данные из файла, мы можем выполнить следующее:

char buf[12];
spiffs_file fd = SPIFFS_open(&fs, fileName, SPIFFS_RDWR, 0);
SPIFFS_read(&fs, fd, (u8_t *)buf, 12);
SPIFFS_close(&fs, fd);

Использование файловой системы SPIFFS может быть иерархической по своей природе, так что она содержит как каталоги, так и файлы, но, похоже, на самом деле это не так. Существует только один каталог с именем root. Корневой каталог - «/». Чтобы определить членов каталога, мы можем открыть каталог для чтения с помощью API SPIFFS_opendir (), и, когда мы закончим, закройте операцию чтения с помощью вызова API SPIFFS_closedir (). Мы можем пройти через записи каталога с вызовами SPIFFS_readdir ().

Например:

spiffs_DIR spiffsDir;
SPIFFS_opendir(&fs, "/", &spiffsDir);
struct spiffs_dirent spiffsDirEnt;
while(SPIFFS_readdir(&spiffsDir, &spiffsDirEnt) != 0) {
   printf("Got a directory entry: %s\n", spiffsDirEnt.name);
}
SPIFFS_closedir(&spiffsDir);

Чтобы это стало ясно, в Linux, если мы создали «/a/b/c.txt», это обычно создало бы файл c.txt в каталоге с именем «b» в каталоге с именем «a». В SPIFFS это фактически создает один файл с именем «/a/b/c.txt», где символы «/» являются просто частью имени файла. Когда мы выполняем SPIFFS_opendir (), на самом деле нет структуры каталогов, а всего лишь один плоский список ВСЕХ файлов, которые могут иметь или не иметь «слэши» в их именах. Чтобы создать файл, мы можем использовать API SPIFFS_open (), предоставив флаг SPIFFS_CREAT.

See also:

• SPIFFs API
• Github: pellepl/spiffs
• Github: igrr/mkspiffs – The mkspiffs tool.
• SPI Flash
• Virtual File System mapping to SPIFFS

Building SPIFFs for the ESP32

Под заголовком «"let's build on each other» была проделана отличная работа портирования SPIFF в ESP32 командой LUA (Jaume Olivé Petrus). Исходный код можно найти на github. Они упаковали его как компонент ESP-IDF.

mkspiffs tool

В дополнение к фантастической библиотеке SPIFF существует также инструмент под названием «mkspiffs», который может принимать структуру каталогов в вашей файловой системе и создавать из него образ SPIFF, который затем может быть загружен во флэш-память для предоставления предварительно загруженных данных.

Можно скачать репозиторий Git для mkspiffs и скомпилировать его. Я не обнаружил проблем и скомпилировал их с первого раза.

Пример:

mkspiffs { -c <packdir> | -u <destdir>|-l|-i} \
-b <number> -p <number> -s <number>

One of:

• -c <directory to pack>
• -u <dest to unpack into>
• -l – list content
• -i – visualize content

and

• -b <number> – Block size in bytes (for example 65536)
• -p <number> – Page size in bytes (for example 256)
• -s <number> – fs image size in bytes.

В результате получим файл образа:

0 idid___________ era_cnt: 0

1 _______________ era_cnt: 0

2 _______________ era_cnt: 0

3 _______________ era_cnt: 0

4 _______________ era_cnt: 0

5 _______________ era_cnt: 0

6 _______________ era_cnt: 0

7 _______________ era_cnt: 0

8 _______________ era_cnt: 0

9 _______________ era_cnt: 0

10 _______________ era_cnt: 0

11 _______________ era_cnt: 0

12 _______________ era_cnt: 0

13 _______________ era_cnt: 0

14 _______________ era_cnt: 0

15 _______________ era_cnt: 0

era_cnt_max: 1

last_errno: 0

blocks: 16

free_blocks: 15

page_alloc: 4

page_delet: 0

used: 1004 of 52961

total: 52961

used: 1004

Когда у нас есть файл образа, чтобы его загрузить выполняем:

esptool.py --chip esp32 --port "/dev/ttyUSB0" --baud 115200 write_flash -z
--flash_mode "dio" --flash_freq "40m" <address> <file>

See also: • Github: igrr/mkspiffs – The mkspiffs tool.

The ESP File System – EspFs

Part of the Github project known as "Spritetm/libesphttpd" is a module called "espfs" which is the "ESP File System". What this module does is allow one to make an image from a set of files on your PC and store that combined image in flash memory. From there, a set of APIs are provided to read and access those files and their content. It is vital to note that the data in these files is read-only. There is no API to update the content of the files. Only the data that is initially written to flash is available to be read. As part of the project there is a utility called "mkespfsimage" that takes as input a set of file names and streams as output the image data that should be flashed. For example: find | ./mkespfsimage [-c compressor] [-l compression_level] > out.espfs (Note that the project has compression capabilities that I am ignoring at this point).

Once the data is in flash, we can then use the APIs supplied by the component to perform the underlying data access.

They are: • EspFsInitResult espFsInit(void *flashAddress) • int espFsFlags(EspFsFile *fh) • EspFsFile *espFsOpen(char *fileName) • int espFsRead(EspFsFile *fh, char *buff, int len) • void espFsClose(EspFsFile *fh) An attempt to port the code to utilize ESP32 technologies was undertaken and can be found here: https://github.com/nkolban/esp32-snippets/tree/master/filesystems/espfs

This adds a new function called: • int espFsAccess(EspFsFile *fh, void **buf, size_t *len) This function returns a pointer to the whole content of the file which is stored in buf. The length of the file is stored in len and also returned from the function as a whole. The data is accessed directly from flash without any RAM copies. In addition, the function called: • EspFsInitResult espFsInit(void *flashAddress, size_t size) was augmented to include the size of the flash storage to map. Here is an example application: ESP_LOGD(tag, "Flash address is 0x%x", (int)flashAddress); if (espFsInit(flashAddress, 64*1024) != ESPFS_INIT_RESULT_OK) { ESP_LOGD(tag, "Failed to initialize espfs"); return; } EspFsFile *fh = espFsOpen("files/test3.txt"); if (fh != NULL) { int sizeRead = 0; char buff[5*1024]; sizeRead = espFsRead(fh, buff, sizeof(buff)); ESP_LOGD(tag, "Result: %.*s", sizeRead, buff); size_t fileSize; char *data; sizeRead = espFsAccess(fh, (void **)&data, &fileSize); ESP_LOGD(tag, "Result from access: %.*s", fileSize, data); espFsClose(fh); } SD, MMC and SDIO interfacing Secure Digital (SD) is a standard for removable media. These devices are also known as "flash cards" or "SD cards". The idea is that an SD card contains data that can be both read and written. The SD cards store the data as raw memory and it is common to create a file system that lives on top of the data. The FAT16 and FAT32 file system formats are commonly used. SD cards come in a variety of physical dimensions and with a variety of capacities and speeds. For the physical dimensions there are three distinct types known as "SD", "miniSD" and "microSD" ranging from largest to smallest. For capacity, there are again three distinct types known as "SD", "SDHC" and "SDXC". SD SDHC SDXC Capacity x <= 2GB 2GB <= x <=32GB 32GB <= x <= 2TB File system FAT12, FAT16 FAT32 exFAT For our story, we will ignore SDXC. An additional characteristic of SD cards is their rated speed. The common speeds are: Class 2 2MB/s Class 4 4MB/s Class 6 6MB/s Class 10 10MB/s The SD specification is large and comprehensive. If we were to try and implement the SD specification ourselves we would be delving down into a whole host of puzzles. As such, it is common to leverage pre-existing implementations of the specification and, thankfully, the ESP-IDF provides us with exactly that. There is also an excellent example application provide in the examples/storage/sd_card directory of the ESP-IDF. The SD card can be used to hold data but can not be used to hold instruction code for execution. As such, the SD card shouldn't be considered as an alternative to the flash memory accessible via SPI for code storage. The SD card should be used to store application data that can be read by or written by running applications. See also: Page 404 • Wikipedia: Multi Media Card • Wikipedia: Secure Digita l • SD Association Charting data Consider some of the sensors