ZIFI32--ESP32-/firmware/README.md

# Прошивка ESP32 (модуль ZiFi32 для ZX Evolution / TS-Conf)

Скомпилированная прошивка для WiFi/SPI-модуля на базе ESP32-S3,
используемого платформой ZX Evolution / TS-Conf ("Pentevo").

**Исходная база**: этот форк основан на
[tslabs/zx-evo](https://github.com/tslabs/zx-evo/tree/master/pentevo/esp32) —
полный исходный код лежит в `pentevo/esp32/src` рядом с этой папкой; в
`firmware/` — только готовые к прошивке бинарники.

## Требования

Прошивка ядра платы ZX Evolution/TS-Conf должна быть собрана с поддержкой
**VDAC2** и **ESP32 (ZiFi32)** — без этого ядро вообще не увидит модуль
ESP32 на шине SPI (независимо от того, насколько корректна прошивка самого
ESP32), а видеочип FT8xx работать не будет. Проверьте это, прежде чем
считать проблему подключения проблемой стороны ESP32.

**Перемычка RESET на разъёме IDE тоже должна быть установлена** — см.
`../hardware/connection_diagram.webp`.

## Что изменено относительно апстрима

Основная часть работы в этом форке — **мост VFS, открывающий реальную
SD-карту ZX Evolution как сетевую шару по SMB2/3**, чтобы любой клиент
Windows/macOS/Linux мог просматривать, скачивать, загружать и удалять
файлы на реальной файловой системе Wild Commander без извлечения карты.
Эта часть всё ещё **активно дорабатывается** — см. раздел "Статус" ниже.

Изменения, примерно в порядке внесения:

- **Подключена реальная файловая система.** SMB2-обработчики в
  `vfs_bridge.cpp` (CREATE/READ/WRITE/CLOSE/QUERY_DIRECTORY/QUERY_INFO и
  т.д.) теперь общаются с реальной файловой системой через небольшой мост
  запрос/ответ (`vfs_request.cpp`) поверх существующей SPI-связи со
  стороной Z80, вместо оригинальной захардкоженной демо-файловой системы.
- **Поддержка загрузки файлов (WRITE) и удаления** файлов и пустых
  директорий, включая корректную обработку `FILE_DELETE_ON_CLOSE` и ответ
  `SMB2_STATUS_DIRECTORY_NOT_EMPTY` при попытке удалить непустую
  директорию.
- **Исправления листинга директорий**: поддержка пагинации
  `SMB2_RETURN_SINGLE_ENTRY` (нужна собственному SMB2-клиенту `cmd.exe`, не
  только Проводнику), недостающие не-"ID" классы информации о директории,
  синтезированные записи `.`/`..`, и баг кодирования `NextEntryOffset` в
  вендоренном `libsmb2`, молча портивший любой листинг длиннее двух
  записей.
- **Исправление перечисления шар в `srvsvc`**: RPC-канал всегда сообщал
  заглушку-имя шары `"test"` из Фазы 1 независимо от того, к чему реально
  подключился клиент — исправлено на реальное имя шары.
- **Добавлена поддержка `SMB2_FILE_FS_VOLUME_INFORMATION`** (нужна голому
  `dir`/`net use`; Проводник её не запрашивает, поэтому пропустили
  изначально).
- **Исправления стабильности**: падение по нулевому указателю в обработке
  named-pipe RPC transceive, и нулевая по длине SPI DMA-транзакция, которая
  могла подвесить весь SPI-канал к стороне Z80.
- **Исправления в интерфейсе AT-команд** (`at_uart.cpp`/`at_cip.cpp`,
  не связаны с VFS/SMB, но тоже часть этого форка):
  - `AT+CIPSTART` (и любая другая первая после загрузки сетевая AT-команда)
    падал, если стек WiFi ещё не был поднят (мьютекс `tcpip_task` ещё не
    создан) — исправлено ленивой инициализацией WiFi перед первой сетевой
    командой.
  - Ответ на `AT+GMR` добавлял `vTaskDelay(500ms)` перед содержимым — без
    этой паузы реальный ZiFi-клиент на ZX Evolution иногда не успевал
    захватить баннер на экран.
  - Собственная нестандартная команда `AT+NET_NTP` заменена на реальные
    команды спецификации ESP-AT `AT+CIPSNTPCFG`/`AT+CIPSNTPTIME`.
- **Патчи `libsmb2`** (вендорено в `src/third_party/libsmb2`):
  - `SMB2_FSCTL_DFS_GET_REFERRALS` теперь отвечает
    `STATUS_OBJECT_PATH_NOT_FOUND` вместо `STATUS_NOT_IMPLEMENTED` —
    неверный код статуса отправлял Проводник Windows в шторм повторных
    запросов ещё до попытки подключения к шаре.
  - Разбор `SET_INFO` стал терпимым к классам информации, которые сервер
    отдельно не реализует (пропускает сырой буфер вместо ошибки разбора) —
    раньше жёсткая ошибка разбора здесь рвала *всё* TCP-соединение вместо
    отказа только в этом одном запросе, что проявлялось как обрыв
    Проводником копирования файла посередине с общей ошибкой.
  - Возврат `-2` из `close_cmd` теперь отображается в ответе CLOSE как
    `SMB2_STATUS_DIRECTORY_NOT_EMPTY` вместо общего
    `STATUS_NOT_IMPLEMENTED`.
- **Упрощена авторизация** до обычных гостевых/анонимных сессий
  (`authorize_handler` всегда успешен) — более ранняя попытка
  принудительной NTLMv2 + подписи SMB2 оказалась не связана с уже
  исправленным багом листинга, поэтому убрана как лишняя сложность.
- Убрано частое отладочное логирование каждого запроса, добавленное для
  отлова описанных выше багов, заменено одной итоговой строкой на
  соединение.

## Статус

SMB2/3-сервер (чтение, просмотр, загрузка, удаление) работает с реальными
клиентами Windows/Samba. **Работа всё ещё продолжается** — создание
директорий (`MKDIR`) пока не реализовано, перезапись существующего файла
более коротким содержимым не обрезает старый хвост, и нет поддержки
уведомлений об изменениях в реальном времени (`change_notify`), поэтому
Проводник может на мгновение показывать устаревший листинг до обновления.
Актуальное состояние конкретных обработчиков — в комментариях исходного
кода.

## Прошивка

Целевой чип: **ESP32-S3**. Через `esptool.py` напрямую:

```bash
esptool.py --chip esp32s3 -p COM5 -b 460800 write_flash \
  --flash-mode dio --flash-freq 80m --flash-size detect \
  0x0     bootloader.bin \
  0x8000  partition-table.bin \
  0x10000 esp-spi.bin
```

(замените `COM5` на реальный порт; `flasher_args.json` в этой папке
содержит те же смещения в собственном JSON-формате `idf.py` — для справки
или скриптов.)

Если собираете из исходников: ESP-IDF **v6.1** (не `v6.1-rc1`) —
`idf.py build flash`.

## Аппаратная часть

См. `../hardware/`:
- `connection_diagram.webp` — как этот модуль подключается к плате ZX
  Evolution.
- `pcb_photo.jpg` — фото переходной платы.
- `gerber/` — Gerber-файлы переходной платы.