# ZIFI32 — модуль ESP32 WiFi/SPI для ZX Evolution

Прошивка и аппаратная часть модуля ESP32-S3 (WiFi/SPI, "ZiFi32") для
ретро-компьютера ZX Evolution / TS-Conf ("Pentevo"). Даёт WiFi,
аудио-трекер (WAV/XM/MOD/S3M), а также (новое в этом форке, в разработке)
сетевую шару по SMB2/3, открывающую доступ к реальной SD-карте машины с
любого клиента Windows/macOS/Linux.

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

## Интерфейсы

Модулем можно управлять двумя способами:

- **Родной SPI-протокол** (`esp_spi_defs.h`) — основной, быстрый способ
  связи с Z80-стороной (используется, в частности, VFS/SMB-мостом).
- **AT-команды по UART** (`at_uart.cpp`) — добавлены в этом форке для
  обратной совместимости с программами, написанными под старые ZiFi-модули
  на реальном ESP8266 с оригинальной прошивкой Espressif AT. Поддерживаются
  кратко: `AT+RST` (сброс), `AT+GMR` (версия), `AT+CWJAP` (подключение к
  WiFi), `AT+CWLAP` (сканирование точек доступа), `AT+CIPSTART`/`AT+CIPSEND`
  (TCP-соединение и отправка данных), `AT+CIPSNTPCFG`/`AT+CIPSNTPTIME`
  (настройка и получение времени по NTP).

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

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

## Структура репозитория

| Путь                | Что там |
|---------------------|--------------|
| `src/`               | Исходный код прошивки ESP32 (проект ESP-IDF) |
| `firmware/`          | Готовые к прошивке скомпилированные файлы + инструкция по прошивке + список изменений |
| `hardware/`          | Схема подключения переходной платы, фото платы, Gerber-файлы |
| `doc/`               | Заметки по протоколу/архитектуре |
| `test/`              | Оригинальные тестовые скрипты протокола SPI из апстрима (Python, Raspberry Pi) |
| `spi_gpio_probe/`    | Отдельная диагностическая прошивка — логирует сырые фронты на пинах SPI, использовалась для отладки при разработке; НЕ основная прошивка |

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

1. Прошейте `firmware/esp-spi.bin` (+ bootloader/таблицу разделов) в модуль
   ESP32-S3 — точная команда `esptool.py` в
   [`firmware/README.md`](firmware/README.md#Прошивка).
2. Подключите по схеме
   [`hardware/connection_diagram.webp`](hardware/connection_diagram.webp)
   (Gerber-файлы переходной платы — в [`hardware/gerber/`](hardware/gerber/),
   если делаете свою плату; фото платы —
   [`hardware/pcb_photo.jpg`](hardware/pcb_photo.jpg)).
3. Убедитесь, что выполнено требование по ядру ZX Evolution (см. выше).
4. Собрать из исходников вместо прошивки готового бинарника: ESP-IDF
   **v6.1** (не `v6.1-rc1`), `idf.py build flash`.

## Статус

WiFi, воспроизведение аудио-трекера и SMB2/3-мост (просмотр, скачивание,
загрузка, удаление на реальной SD-карте) — всё работает на реальном
железе. Мост к SMB всё ещё **активно дорабатывается** — пока не реализовано
создание директорий, обрезка файла при перезаписи более коротким
содержимым и уведомления об изменениях в реальном времени. Подробности —
в [`firmware/README.md`](firmware/README.md).

## Лицензия

В этом репозитории вендорится [libsmb2](https://github.com/sahlberg/libsmb2)
(LGPL-2.1) в каталоге `src/third_party/libsmb2` — см. его собственные файлы
`COPYING` и `LICENCE-LGPL-2.1.txt`.