LFSManager

LFSManager

LFSManager — легковесная C++ библиотека для управления файловой системой LittleFS на ESP8266/ESP32 через UART. Оптимизирована для экономии памяти (без использования String), обеспечивает передачу файлов с проверкой CRC32. Подойдет для загрузки файлов конфигураций, веб-страниц (HTML/JS/CSS) или картинок во Flash-память микроконтроллера напрямую по USB-кабелю без использования Wi-Fi.

Особенности

• Никаких String - Библиотека использует исключительно C-строки
• Расчет контрольной суммы CRC32 "на лету". Файл сохраняется во временный буфер и заменяет оригинал только при 100% совпадении CRC32.
• Работает с любым объектом
  Stream
  (Serial, Serial1, SoftwareSerial).

Программа для ПК

LittleFS Desktop Manager - файловый менеджер на Python (Tkinter). Позволяет загружать, скачивать, удалять, переименовывать файлы и форматировать память LittleFS прямо через COM-порт. Или уже собранную в exe - LittleFS Desktop Manager

Установка (PlatformIO)

Убедитесь, что в вашем файле

Быстрый старт

Важно: Конфликты UART и совместная работа с вашим кодом

• ❌ Чтение (
  Serial.read
  ) — Вызывает конфликт. Библиотека непрерывно прослушивает входящие данные в функции
  tick()
  . Если в вашем цикле
  loop()
  вы тоже начнете вызывать
  Serial.read()
  , возникнет путаница в чтении данных и файл будет загружен с ошибкой.
• ⚠️ Запись (
  Serial.print
  ) — Почти не мешает. Python-программа на ПК игнорирует любой текст, который не соответствует её протоколу. Вы можете выводить отладочную информацию (например,
  Serial.println("Temp: 25");
  ). Избегайте сильного "спама" в порт во время загрузки/скачивания файлов, чтобы не переполнить буфер и не вызвать таймаут передачи.

Как правильно интегрировать библиотеку?

Вариант 1: Использование разных портов (Рекомендуемый)

Если микроконтроллер поддерживает несколько аппаратных UART (ESP32) или вы используете

Конструктор библиотеки принимает любой объект класса

Вариант 2: Добавление пользовательских команд в библиотеку

Если доступен только один USB-порт, и вы хотите управлять устройством по тому же кабелю, добавьте обработку своих команд напрямую в парсер библиотеки LFSManager.cpp (в метод processCommand):

Вариант 3: Режим "Сервисного обслуживания" (Переключатель)

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

Нужно одновременное, независимое чтение — используйте Вариант 1. Связь идет только через один кабель — используйте Вариант 2 или 3.

Протокол связи

Приложение общается с микроконтроллером по кастомному протоколу, разделенному двоеточиями (например, UPL_START:/index.html:1024:A1B2C3D4).

• Разделитель: Команды и параметры разделяются символом " : " (двоеточие).
• Окончание команды: Символ \n (перевод строки). Символы \r игнорируются. Менеджер может находиться в одном из состояний: ожидание (IDLE), прием файла (RECEIVING_FILE), отправка файла (SENDING_FILE). В состояниях приема/передачи файла другие команды не обрабатываются (кроме DWN_NEXT во время отправки).

Команды управления (Состояние IDLE)

PING Проверка связи.

• Запрос: PING\n
• Ответ: PONG:LFS_FM\n

INFO Получить информацию о размере файловой системы.

• Запрос: INFO\n
• Ответ: INFO:<total_bytes>:<used_bytes>\n
• total_bytes – общий объем ФС в байтах.
• used_bytes – занятое место в байтах.

LIST Получить список файлов в корневой директории.

• Запрос: LIST\n
• Ответ: Одна или несколько строк формата FILE::\n, за которыми следует строка LIST_END\n.
• – путь к файлу (начинается с /).
• – размер файла в байтах.

DEL Удалить файл.

• Запрос: DEL:\n
• Ответ:
• OK\n – в случае успеха.
• ERR:REMOVE\n – если не удалось удалить (файл не найден, ошибка ФС).

REN Переименовать/переместить файл.

• Запрос: REN:<old_path>:<new_path>\n
• Ответ:
• OK\n – в случае успеха.
• ERR:RENAME\n – если операция не удалась.

FMT Отформатировать файловую систему (удалить все файлы).

• Запрос: FMT\n
• Ответ:
• OK\n – в случае успеха.
• ERR:FORMAT\n – если форматирование не удалось.

Загрузка файла на устройство (UPLOAD)

Процесс загрузки состоит из трех этапов: инициация, передача данных чанками, завершение.

• Инициация (Host -> Device)
• Ответ устройства (Device -> Host)
• Передача данных (Host -> Device)
• Подтверждение (Device -> Host) Завершение:
• SUCCESS:CRC_OK\n – CRC совпала.
• ERR:CRC_MISMATCH\n – CRC не совпала.

H -> D: UPL_START:/data.bin:1024:3EE52B4F\n
D -> H: READY\n
H -> D: [256 байт данных]
D -> H: ACK\n
H -> D: [256 байт данных]
D -> H: ACK\n
...
H -> D: [последние N байт данных, N <= 256]
D -> H: ACK\n
D -> H: SUCCESS:CRC_OK\n

Скачивание файла с устройства (DOWNLOAD)

Процесс скачивания управляется хостом.

• Инициация (Host -> Device)
• Ответ устройства (Device -> Host)
• Передача данных (Host -> Device)
• Подтверждение (Device -> Host) Завершение: Когда весь файл отправлен (после отправки последнего чанка), устройство отправляет строку \nSUCCESS:DWN_OK\n. Важно: Обратите внимание на предшествующий символ новой строки (\n). Это сделано для того, чтобы отделить бинарные данные последнего чанка от текстового сообщения об успехе. Хост должен быть готов к этому.

H -> D: DWN_START:/data.bin\n
D -> H: DWN_HDR:1024\n
H -> D: DWN_NEXT\n
D -> H: [до 256 байт данных]
H -> D: DWN_NEXT\n
D -> H: [до 256 байт данных]
...
H -> D: DWN_NEXT\n
D -> H: [последние N байт данных, N <= 256]
D -> H: \nSUCCESS:DWN_OK\n

Коды ошибок

• ERR:FS_OPEN – Ошибка открытия файла (для чтения или записи).
• ERR:REMOVE – Ошибка удаления файла.
• ERR:RENAME – Ошибка переименования.
• ERR:FORMAT – Ошибка форматирования.
• ERR:TIMEOUT – Таймаут приема данных (UPLOAD).
• ERR:CRC_MISMATCH – Контрольная сумма не совпала (UPLOAD).

Отладка библиотеки

Для вывода отладочных сообщений библиотеки в Serial, раскомментируйте строку #define LFS_DEBUG в файле LFSManager.h.