По состоянию на 2024 год, в проектах ESP32 на базе IDF и Arduino обычно используются три файловые системы: LittleFS, FAT и SPIFFS (последняя скоро будет устаревшей). Все три файловые системы поддерживаются в мини-файловом менеджере ESPShell.
Для тестирования доступен пример файла "partitions.csv", в котором описаны все три файловые системы. Этот файл, если он находится в каталоге проекта, будет использоваться при загрузке прошивки.
Поддерживаются следующие типы носителей:
SDMMC с полноценной 4-битной шиной данных — самый быстрый способ чтения/записи на SD-карты. Однако на многих отладочных платах подключена только одна линия данных (например, у ESP32Cam). Тем не менее, даже SDMMC в 1-битном режиме быстрее, чем SD по SPI.
Основная цель файлового менеджера ESPShell — копирование, перемещение, переименование и удаление файлов и каталогов, которые могут использоваться в прошивке. Это, например, конфигурационные файлы, изображения с камеры, страницы веб-сервера, логи и т.д.
ESPShell позволяет выполнять операции копирования и перемещения между разными файловыми системами. Например, файл можно переместить из FAT в LittleFS.
Поддерживаются SD-карты, подключенные по шине SPI.
Кроме того, ESPShell предоставляет базовые функции редактирования бинарных и текстовых файлов. Пользователь может создавать файлы, дописывать строки или байты, вставлять или удалять строки в текстовых файлах.
Чтобы войти в режим файлового менеджера, введите "files" и нажмите <Enter>:
esp32#>files % Entering filesystem configuration mode. Ctrl+Z or "exit" to return % Main commands are still avaiable (but not visible in "?" command list) esp32#(/)>
Теперь в командной строке отображается текущий рабочий каталог в скобках. Это называется корневым каталогом. Он виртуальный и не может использоваться как обычный каталог: нельзя создать в нём файлы или папки. Он используется исключительно для хранения точек монтирования.
Точка монтирования — это каталог, имя которого начинается с "/", например, "/wwwroot", где размещается реальная файловая система.
ПРИМЕЧАНИЕ: если вы хотите использовать пробелы (" ") в пути, то просто напишите ваш путь в двойных кавычках. А можно использовать вместо пробелов звёздочку "*". ESPShell автоматически заменит звёздочки на пробелы. ESPShell не поддерживает:
Теперь давайте рассмотрим команды файлового менеджера (выйти из режима можно нажатием Ctrl+Z или вводом "exit" + Enter):
esp32#(/)>? % Enter "? command" to get details about specific command. % Enter "? keys" to display the espshell keyboard help page % % "?" : Список команд и помощь % "mount" : Смонтировать раздел / Показать таблицу разделов % "unmount" : Размонтировать раздел % "ls" : Список каталога % "pwd" : Показать текущий каталог % "cd" : Сменить каталог % "rm" : Удалить файлы % "mv" : Переместить/переименовать файлы % "cp" : Копировать файлы % "write" : Записать байты % "append" : Дописать байты % "insert" : Вставить байты % "delete" : Удалить строки % "mkdir" : Создать каталог % "cat" : Показать текстовый/бинарный файл % "touch" : Обновить метку времени / создать файл % "format" : Стереть старую и создать новую файловую систему % "exit" : Выйти esp32#(/)>
Команда без аргументов отображает таблицу разделов и информацию о смонтированных файловых системах (команда "mount" сокращена до "m"):
esp32#(/)>m % Partition label | Type | Size | Mounted on |Total(Kb)|Free(Kb) % -----------------+-----------+---------+------------------+---------+-------- % nvs | NVStorage | 20Kb | | | % otadata | OTA data | 8Kb | | | % wwwroot | FAT/exFAT | 960Kb | /wwwroot| 920 | 920 % pr0n | SPIFFS | 480Kb | | | % logs | LittleFS | 480Kb | /logs| 480 | 464 % coredump | Core dump | 64Kb | | | % % 3 mountable partitions found esp32#(/)>Вывод выше показывает, что есть 3 различных раздела, два из которых смонтированы по путям "/wwwroot" и "/logs". Столбец "Size" показывает размер файловой системы на флеш-памяти. Столбцы "Total" и "Free" показывают общий и свободный объём файловой системы соответственно.
Эта команда с одним или двумя аргументами монтирует файловую систему, находящуюся на разделе с указанной меткой LABEL, в указанный путь /PATH. Если /PATH (точка монтирования) не задан, он автоматически формируется путём объединения "/" и имени метки раздела (как показано выше).
Если файловая система не монтируется, она будет отформатирована, после чего монтирование будет повторено.
LABEL можно указывать укороченно, но это не влияет на итоговую точку монтирования — она всё равно формируется по полному имени метки:
esp32#(/)>mount www % FAT/exFAT on partition "wwwroot" is mounted under "/wwwroot" esp32#(/)>Здесь мы использовали укороченную метку ("www" вместо "wwwroot"), но она была распознана как полное имя. Путь монтирования был опущен, поэтому он сгенерирован автоматически из имени метки.
После монтирования файловая система становится доступной по пути /PATH (в данном случае — /wwwroot): пользователь может выполнить "cd /wwwroot" и исследовать/изменять содержимое.
Пример: смонтировать файловую систему с раздела "wwwroot" в точку "/my/point":
esp32#(/)>mount wwwroot /my/point % FAT/exFAT on partition "wwwroot" is mounted under "/my/point" esp32#(/)>
"mount spi1|spi2|spi3|hspi|fspi|vspi MOSI MISO CLK CS [FREQ_KHZ] [/PATH]"
SD-карта может быть смонтирована по SPI-шине с помощью приведённой выше команды. Первый аргумент указывает, какой SPI-интерфейс использовать. Самый безопасный выбор — "hspi", он работает на всех моделях ESP32. Поддерживаются оба соглашения об именовании SPI-интерфейсов: Arduino (hspi, vspi) и ESP-IDF (spi1, spi2 и т. д.).
MOSI, MISO, CLK и CS — это пины SPI-шины (GPIO, к которым подключена SD-карта).
FREQ_KHZ — необязательный параметр, определяющий частоту SPI-шины. По умолчанию SD-карты работают на частоте 20 МГц. Однако при использовании длинных проводов (например, на макетных платах) рекомендуется понижать частоту (вплоть до 400 кГц) для предотвращения ошибок передачи данных.
Противоположность команде "mount": выполняет размонтирование файловой системы. Принимает один необязательный аргумент — путь монтирования. Если путь не указан, он определяется из текущей рабочей директории:
esp32#(/wwwroot/1/2/)>unmount % Unmounted FAT/exFAT partition "/wwwroot" esp32#(/)>Также доступна команда "umount", являющаяся алиасом для "unmount".
Команда "format" используется для форматирования раздела, указанного по LABEL. Если LABEL не указан, ESPShell определяет метку раздела по текущей директории:
esp32#(/wwwroot/)>format % Formatting partition "wwwroot", file system type is " FAT/exFAT " % done esp32#(/wwwroot/)>Тип файловой системы определяется в файле partitions.csv и не может быть изменён во время выполнения. Для FAT выполняется быстрое форматирование (таблицы размещения очищаются, данные не затираются).
Команда "ls" отображает содержимое директории. Если PATH не указан, используется текущая директория:
esp32#(/wwwroot/)>ls % Size Modified * Name % -- level up -- DIR [..] % 171 1980-01-01 01:43:26 DIR [index] % 146 1980-01-01 01:43:26 DIR [logs] % 0 1980-01-01 01:43:26 DIR [uphp] % 0 1980-01-01 01:43:26 DIR [tmp] % 57 1980-01-01 01:46:18 index.html % % 4 directories, 1 file, 374 bytes esp32#(/wwwroot/)>Выводимые данные включают: время последнего изменения, размер файла в байтах, тип (директории помечены как DIR, файлы — нет) и имя.
Подробности:
Size: размер файла или директории в байтах
Modified: дата и время последнего изменения
Type: директории помечаются как DIR, файлы — без пометок
Name: имя файла или директории (имена директорий отображаются в квадратных скобках)
Специальный каталог [..] означает «на уровень выше»
Файлы отображаются в порядке создания, без сортировки.
Пример: вывод содержимого директории /wwwroot/index/:
esp32#(/)>ls wwwroot/index % Size Modified * Name % -- level up -- DIR [..] % 57 1980-01-01 01:45:00 index.php % 57 1980-01-01 01:45:16 index_old.php % 57 1980-01-01 01:45:26 index_html % % 0 directories, 3 files, 171 bytes esp32#(/)>Путь (PATH) должен указывать на директорию, с / или без него на конце.
Важно: по умолчанию ls рекурсивно вычисляет общий размер директорий. Это может замедлить выполнение и потреблять память. Чтобы отключить это поведение, выполните:
var ls_show_dir_size 0
Команда "cd" поддерживает три варианта:
1. "cd" — без параметров: перейти в корень текущей смонтированной ФС (не путать с глобальным "/"):
esp32#(/wwwroot/1/2/)>cd
esp32#(/wwwroot/)>
2. "cd .." — перейти на уровень вверх. Путь вроде "../../" не поддерживается. Если родительской директории не существует, переход осуществляется к ближайшей существующей:
esp32#(/)>mount wwwroot /a/mount/point
% FAT/exFAT on partition "wwwroot" is mounted under "/a/mount/point"
esp32#(/)>cd /a/mount/point
esp32#(/a/mount/point/)>cd ..
esp32#(/)>
В данном случае команда возвращает нас в "/", так как путь монтирования рассматривается как единый виртуальный путь.
3. "cd PATH" — перейти в директорию PATH. Абсолютные пути начинаются с точки монтирования.
Относительные пути задаются от текущей директории.
esp32#(/wwwroot/)>cd test_dir/dir2
esp32#(/wwwroot/test_dir/dir2/)>cd
esp32#(/wwwroot/)>cd ..
esp32#(/)>
Удаляет указанный файл или директорию:
esp32#(/)>ls wwwroot/test_dir % Size/Used Modified * Name % -- level up -- DIR [..] % 1980-01-01 01:00:24 DIR [dir2] % 4 1980-01-01 01:16:20 test.cfg % 1 directory, 1 file, 4 bytes esp32#(/)>rm wwwroot/test_dir % Directory removed: "/wwwroot/test_dir/dir2/" % File removed: "/wwwroot/test_dir/test.cfg" % Directory removed: "/wwwroot/test_dir/" % 3 files/directories were deleted esp32#(/)>Удаление директорий из корня "/" (виртуальный корень всех точек монтирования) невозможно: например, "rm /wwwroot" не сработает. Используйте для этого команду unmount.
Записывает строку байтов или символов в файл. Если файл не существует — создаётся. Если существует — содержимое перезаписывается полностью.
Чтобы дописать или изменить данные без перезаписи, используйте команды "append", "insert" или "delete".
Аргумент TEXT может содержать:
обычные символы, пробелы, escape-последовательности:
\\ = обратный слэш
\n = перевод строки
\r = возврат каретки
\t = табуляция
\AB = байт с шестнадцатеричным значением AB
Если TEXT опущен, записывается перевод строки (\n).
Пример 1: создать или перезаписать test.cfg с "Hello World!" и строкой байт 61 62 63 64 65 \n:
esp32#(/wwwroot/)>write test.cfg Hello World\n\61\62\63\64\65\n % 18 bytes written esp32#(/wwwroot/)>Если в пути указаны несуществующие директории, они будут созданы автоматически.
Добавляет данные в конец существующего файла. Работает как write, но не затирает данные:
esp32#(/wwwroot/)>append test.cfg \nNew line % 9 bytes written esp32#(/wwwroot/)>Используйте "write" для перезаписи файла, "insert"/"delete" — для изменения строк.
Вставляет TEXT (который может содержать несколько строк, разделённых символами \n) перед строкой с номером LINE_NUM в файле по пути PATH.
Примечание: В конец каждой вставляемой строки автоматически добавляется символ новой строки (\n) — нет необходимости вручную добавлять \n в конец каждой строки, если только вы не вставляете несколько строк.
Пример: Отобразить файл и вставить в него многострочную строку:
esp32#(/wwwroot/)>cat -n index.html
1:
2:
3:
4: Hello World!
5:
6:
7:
esp32#(/wwwroot/)>insert index.html 4 Hey! This line was inserted!\nAnd this line also!
%% Line inserted
esp32#(/wwwroot/)>cat -n index.html
1:
2:
3:
4: Hey! This line was inserted!
5: And this line also!
6: Hello World!
7:
8:
9:
esp32#(/wwwroot/)>
Как и в команде write, поддерживаются escape-последовательности, такие как \n, \r, \t и \XX (шестнадцатеричный байт).esp32#(/wwwroot/)>cat -n index.html 1: 2: 3: 4: Hey! This line was inserted! 5: And this line also! 6: Hello World! 7: 8: 9: esp32#(/wwwroot/)>delete index.html 4 2 % 2 lines deleted starting at line 4 esp32#(/wwwroot/)>cat -n index.html 1: 2: 3: 4: Hello World! 5: 6: 7:
Создаёт один или несколько каталогов. Поддерживается создание вложенных путей — например, команда "mkdir 1/2/3/4" создаст все отсутствующие промежуточные каталоги.
Пример 1: Создание нескольких каталогов в /wwwroot
esp32#(/)>cd wwwroot esp32#(/wwwroot/)>mkdir 1 2 3 % Directory created: "/wwwroot/1/" % Directory created: "/wwwroot/2/" % Directory created: "/wwwroot/3/" esp32#(/wwwroot/)>Эта команда не может создавать каталоги напрямую в корневом каталоге / — используйте команду "mount" для создания или определения новых точек монтирования в /.
ПРИМЕЧАНИЕ по путям с пробелами:
Если вам нужно использовать пробелы в именах файлов или каталогов, можно написать тмя в двойных кавычках: "Program Files", а можно - используовать вместо пробела символ звёздочки (*).
ESPShell автоматически заменит звёздочки на пробелы при обработке пути.
Пример:
esp32#(/wwwroot/)>mkdir My*Documents % Directory created: "/wwwroot/My Documents/" esp32#(/wwwroot/)>mkdir "Program Files" % Directory created: "/wwwroot/Program Files/"
Эта команда работает аналогично команде `touch` в Linux:
Создаёт пустые файлы, если они не существуют.
Обновляет метку времени изменения для существующих файлов.
Если указанный путь включает подкаталоги, ESPShell автоматически создаст все необходимые каталоги.
Пример 1: Создание нескольких новых файлов в текущем каталоге
esp32#(/wwwroot/)>touch file1.txt file2.txt file3.txt % File created: "/wwwroot/file1.txt" % File created: "/wwwroot/file2.txt" % File created: "/wwwroot/file3.txt" esp32#(/wwwroot/)>Пример 2: Обновление времени последнего изменения существующего файла
esp32#(/wwwroot/)>touch file1.txt esp32#(/wwwroot/)>Пример 3: Создание файла во вложенном каталоге (с автосозданием недостающих папок)
esp32#(/wwwroot/)>touch dir1/dir2/config.json % Directory created: "/wwwroot/dir1/" % Directory created: "/wwwroot/dir1/dir2/" % File created: "/wwwroot/dir1/dir2/config.json" esp32#(/wwwroot/)>
ОСНОВНОЕ ИСПОЛЬЗОВАНИЕ
Чтобы вывести файл как обычный текст:
esp32#(/wwwroot/)>cat index.html Hey! This line was inserted! And this line also! Hello World! esp32#(/wwwroot/)>
ОТОБРАЖЕНИЕ ОПРЕДЕЛЁННЫХ СТРОК
Можно использовать аргументы LINE_NUM и COUNT, чтобы вывести только часть файла:
esp32#(/wwwroot/)>cat index.html 4 2 Hey! This line was inserted! And this line also! esp32#(/wwwroot/)>ПОКАЗ НОМЕРОВ СТРОК
Используйте флаг -n для вывода номеров строк. Полезно при работе с insert и delete:
esp32#(/wwwroot/)>cat -n index.html 1: 2: 3: 4: Hey! This line was inserted! 5: And this line also! 6: Hello World! 7: 8: esp32#(/wwwroot/)>ОТОБРАЖЕНИЕ ФАЙЛА В ВИДЕ ДВОИЧНОГО (HEX + ASCII)
Флаг -b интерпретирует содержимое как бинарные данные и отображает их в виде hex-дампа:
esp32#(/wwwroot/)>cat -b index.html
0 1 2 3 4 5 6 7 8 9 A B C D E F |0123456789ABCDEF
----------------------------------------------------------+----------------
0000: 3c 68 74 6d 6c 3e 0a 3c 68 65 61 64 3e 3c 2f 68 |...Hey!
0020: 20 54 68 69 73 20 6c 69 6e 65 20 77 61 73 20 69 | This line was i
0030: 6e 73 65 72 74 65 64 21 0a 41 6e 64 20 74 68 69 |nserted!.And thi
0040: 73 20 6c 69 6e 65 20 61 6c 73 6f 21 0a 48 65 6c |s line also!.Hel
0050: 6c 6f 20 57 6f 72 6c 64 21 0a 0a 0a 3c 2f 62 6f |lo World!......
% EOF (109 bytes)
esp32#(/wwwroot/)>
ПЕРЕДАЧА ФАЙЛА ПО UART
Команда cat также может использоваться для передачи содержимого файла по инициализированному UART-интерфейсу.
При использовании флага -b файл передаётся как есть (в бинарном виде), без форматирования или номеров строк.
Это особенно полезно для передачи файлов на устройства, подключённые по UART. Например, модуль SIM7600 LTE с 64 ГБ встроенной памяти может использоваться для отправки больших файлов по LTE. Передача обрабатывается самим модулем, снижая нагрузку на основной процессор.
esp32#(/wwwroot/)>cat -b firmware.bin uart 2 % Binary file sent over UART2 (14832 bytes) esp32#(/wwwroot/)>
"show mount [/PATH]"
Команда "show mount" выводит информацию о смонтированных файловых системах.
Без аргументов показывает список доступных разделов и точек монтирования для уже смонтированных разделов:
esp32#>sh mount
% Disk partition |M|File system| Size on | Mounted on |Capacity | Free
% label |?| type | flash | | total | space
% ---------------+-+-----------+---------+------------------+---------+---------
% nvs| | NVStorage | 20K | | |
% otadata| | OTA data | 8K | | |
% wwwroot|+| FAT/exFAT | 960K | /wwwroot | 916K | 916K
% pr0n|+| SPIFFS | 480K | | |
% logs|+| LittleFS | 480K | | |
% coredump| | Core dump | 64K | | |
%
% 3 mountable partitions found. (+) - mountable partition
esp32#>
Эта команда является псевдонимом для команды "mount", работающей с файловыми системами.
При использовании с аргументом (путь к каталогу) отображает информацию о конкретной точке монтирования:
esp32#>sh mount /w
% Mount point "/wwwroot", FAT/exFAT , (partition label is "wwwroot")
% Wear-levelling layer is active on this media
% Filesystem is located on internal SPI FLASH
esp32#>