From 17b0421aaf903a2cb493173ed51f6c23f9c10dbd Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 14 Sep 2026 16:03:56 +0300 Subject: [PATCH] Translate READMEs to Russian Co-Authored-By: Claude Sonnet 5 --- README.md | 88 ++++++++++++------------ firmware/README.md | 166 +++++++++++++++++++++++---------------------- 2 files changed, 129 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index 2ff71d8..77f8604 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,59 @@ -# ZIFI32 — ESP32 WiFi/SPI module for ZX Evolution +# ZIFI32 — модуль ESP32 WiFi/SPI для ZX Evolution -Firmware and hardware for the ESP32-S3-based WiFi/SPI module ("ZiFi32") used -by the ZX Evolution / TS-Conf ("Pentevo") retro-computer platform. Adds -WiFi, a WAV/XM/MOD/S3M audio tracker, and (new in this fork, work in -progress) an SMB2/3 network share that exposes the machine's real SD card -to any Windows/macOS/Linux client. +Прошивка и аппаратная часть модуля ESP32-S3 (WiFi/SPI, "ZiFi32") для +ретро-компьютера ZX Evolution / TS-Conf ("Pentevo"). Даёт WiFi, +аудио-трекер (WAV/XM/MOD/S3M), а также (новое в этом форке, в разработке) +сетевую шару по SMB2/3, открывающую доступ к реальной SD-карте машины с +любого клиента Windows/macOS/Linux. -**Base source**: [tslabs/zx-evo](https://github.com/tslabs/zx-evo/tree/master/pentevo/esp32). -See [`firmware/README.md`](firmware/README.md) for the full list of changes -made in this fork and their current status. +**Исходная база**: [tslabs/zx-evo](https://github.com/tslabs/zx-evo/tree/master/pentevo/esp32). +Полный список изменений этого форка и их текущий статус — в +[`firmware/README.md`](firmware/README.md). -## Requirements +## Требования -- The ZX Evolution/TS-Conf board's own **core firmware must be built with - VDAC2 and ESP32 (ZiFi32) peripheral support enabled** - without both, the - core won't recognize this module on the SPI bus at all, and won't drive - the FT8xx video chip either. -- The **RESET jumper on the IDE connector must be installed** - see +- Прошивка ядра платы ZX Evolution/TS-Conf **должна быть собрана с + поддержкой VDAC2 и ESP32 (ZiFi32)** — без этого ядро вообще не увидит + модуль на шине SPI, а видеочип FT8xx работать не будет. +- **Перемычка RESET на разъёме IDE должна быть установлена** — см. [`hardware/connection_diagram.webp`](hardware/connection_diagram.webp). -## Repository layout +## Структура репозитория -| Path | What's there | +| Путь | Что там | |---------------------|--------------| -| `src/` | ESP32 firmware source (ESP-IDF project) | -| `firmware/` | Ready-to-flash compiled binaries + flashing instructions + changelog | -| `hardware/` | Adapter board connection diagram, PCB photo, Gerber files | -| `doc/` | Protocol/design notes | -| `test/` | Original upstream SPI protocol test scripts (Python, Raspberry Pi) | -| `spi_gpio_probe/` | Standalone diagnostic firmware - logs raw SPI pin edges, used for bring-up debugging, NOT the main firmware | +| `src/` | Исходный код прошивки ESP32 (проект ESP-IDF) | +| `firmware/` | Готовые к прошивке скомпилированные файлы + инструкция по прошивке + список изменений | +| `hardware/` | Схема подключения переходной платы, фото платы, Gerber-файлы | +| `doc/` | Заметки по протоколу/архитектуре | +| `test/` | Оригинальные тестовые скрипты протокола SPI из апстрима (Python, Raspberry Pi) | +| `spi_gpio_probe/` | Отдельная диагностическая прошивка — логирует сырые фронты на пинах SPI, использовалась для отладки при разработке; НЕ основная прошивка | -## Quick start +## Быстрый старт -1. Flash `firmware/esp-spi.bin` (+ bootloader/partition table) to the ESP32-S3 - module - see [`firmware/README.md`](firmware/README.md#flashing) for the - exact `esptool.py` command. -2. Wire it up per [`hardware/connection_diagram.webp`](hardware/connection_diagram.webp) - (adapter PCB Gerbers are in [`hardware/gerber/`](hardware/gerber/) if you're - making your own board - see the photo in [`hardware/pcb_photo.jpg`](hardware/pcb_photo.jpg)). -3. Make sure the ZX Evolution core firmware requirement above is met. -4. Build from source instead of flashing the prebuilt binary: ESP-IDF - **v6.1** (not `v6.1-rc1`), `idf.py build flash`. +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`. -## Status +## Статус -WiFi, audio tracker playback, and the SMB2/3 VFS bridge (browse, download, -upload, delete over a real SD card) all work against real hardware. The VFS -bridge is still **actively being developed** - directory creation, in-place -file truncation on overwrite, and live directory-change notifications aren't -implemented yet. Full details in [`firmware/README.md`](firmware/README.md). +WiFi, воспроизведение аудио-трекера и SMB2/3-мост (просмотр, скачивание, +загрузка, удаление на реальной SD-карте) — всё работает на реальном +железе. Мост к SMB всё ещё **активно дорабатывается** — пока не реализовано +создание директорий, обрезка файла при перезаписи более коротким +содержимым и уведомления об изменениях в реальном времени. Подробности — +в [`firmware/README.md`](firmware/README.md). -## License +## Лицензия -This repository vendors [libsmb2](https://github.com/sahlberg/libsmb2) -(LGPL-2.1) under `src/third_party/libsmb2` - see its own `COPYING` and -`LICENCE-LGPL-2.1.txt` there. +В этом репозитории вендорится [libsmb2](https://github.com/sahlberg/libsmb2) +(LGPL-2.1) в каталоге `src/third_party/libsmb2` — см. его собственные файлы +`COPYING` и `LICENCE-LGPL-2.1.txt`. diff --git a/firmware/README.md b/firmware/README.md index 3e59ede..48ed0ad 100644 --- a/firmware/README.md +++ b/firmware/README.md @@ -1,92 +1,93 @@ -# ESP32 firmware (ZX Evolution / TS-Conf ZiFi32 module) +# Прошивка ESP32 (модуль ZiFi32 для ZX Evolution / TS-Conf) -Compiled firmware for the ESP32-S3-based WiFi/SPI module used by the ZX -Evolution / TS-Conf ("Pentevo") platform. +Скомпилированная прошивка для WiFi/SPI-модуля на базе ESP32-S3, +используемого платформой ZX Evolution / TS-Conf ("Pentevo"). -**Base source**: this firmware is based on +**Исходная база**: этот форк основан на [tslabs/zx-evo](https://github.com/tslabs/zx-evo/tree/master/pentevo/esp32) — -full source for this fork lives in `pentevo/esp32/src` alongside this folder; -this `firmware/` directory only holds ready-to-flash binaries. +полный исходный код лежит в `pentevo/esp32/src` рядом с этой папкой; в +`firmware/` — только готовые к прошивке бинарники. -## Requirements +## Требования -The ZX Evolution/TS-Conf board's own core firmware must be built with -**VDAC2** and **ESP32 (ZiFi32)** peripheral support enabled - without both, -the core won't recognize the ESP32 module on the SPI bus at all (no matter -how correct this ESP32-side firmware is), and won't drive the FT8xx video -chip either. Check this before assuming a connection problem is on the -ESP32 side. +Прошивка ядра платы ZX Evolution/TS-Conf должна быть собрана с поддержкой +**VDAC2** и **ESP32 (ZiFi32)** — без этого ядро вообще не увидит модуль +ESP32 на шине SPI (независимо от того, насколько корректна прошивка самого +ESP32), а видеочип FT8xx работать не будет. Проверьте это, прежде чем +считать проблему подключения проблемой стороны ESP32. -The **RESET jumper on the IDE connector must be installed** as well - see +**Перемычка RESET на разъёме IDE тоже должна быть установлена** — см. `../hardware/connection_diagram.webp`. -## What's changed vs. the upstream source +## Что изменено относительно апстрима -Most of the work in this fork is a **VFS bridge that exposes the ZX -Evolution's real SD card as a network share over SMB2/3**, so any Windows/ -macOS/Linux SMB client can browse, download, upload to, and delete files on -the real Wild Commander filesystem without pulling the card. This is still -**actively being worked on** — see "Status" below. +Основная часть работы в этом форке — **мост VFS, открывающий реальную +SD-карту ZX Evolution как сетевую шару по SMB2/3**, чтобы любой клиент +Windows/macOS/Linux мог просматривать, скачивать, загружать и удалять +файлы на реальной файловой системе Wild Commander без извлечения карты. +Эта часть всё ещё **активно дорабатывается** — см. раздел "Статус" ниже. -Changes so far, roughly in the order they were made: +Изменения, примерно в порядке внесения: -- **Real filesystem wired up.** `vfs_bridge.cpp`'s SMB2 handlers - (CREATE/READ/WRITE/CLOSE/QUERY_DIRECTORY/QUERY_INFO/etc.) now talk to the - real filesystem via a small request/response bridge (`vfs_request.cpp`) - over the existing SPI link to the Z80 side, instead of the original - hardcoded demo filesystem. -- **Upload (WRITE) and delete support** for files and empty directories, - including proper `FILE_DELETE_ON_CLOSE` handling and a - `SMB2_STATUS_DIRECTORY_NOT_EMPTY` reply when a non-empty directory delete - is rejected. -- **Directory listing fixes**: `SMB2_RETURN_SINGLE_ENTRY` pagination support - (needed by `cmd.exe`'s own SMB2 client, not just Explorer), the missing - non-"ID" directory info classes, synthesized `.`/`..` entries, and a - `NextEntryOffset` encoding bug in the vendored `libsmb2` that silently - corrupted any listing past the second entry. -- **`srvsvc` share-enumeration fix**: the RPC pipe used to always report the - Phase-1 placeholder share name `"test"` regardless of what a client had - actually connected to — fixed to report the real share name. -- **Added `SMB2_FILE_FS_VOLUME_INFORMATION`** support (a bare `dir`/`net use` - needs it; Explorer doesn't ask for it, which is why this was missed at - first). -- **Stability fixes**: a NULL-pointer crash in the named-pipe RPC transceive - path, and a 0-length SPI DMA transaction that could wedge the whole SPI - channel to the Z80 side. -- **`libsmb2` (vendored, `src/third_party/libsmb2`) patches**: - - `SMB2_FSCTL_DFS_GET_REFERRALS` now answers `STATUS_OBJECT_PATH_NOT_FOUND` - instead of `STATUS_NOT_IMPLEMENTED` — the wrong status code was sending - Windows Explorer into a retry storm before it would even attempt to - connect to the share. - - `SET_INFO` parsing is now permissive for info classes this server - doesn't specifically implement (passes the raw buffer through instead of - failing to parse) — a hard parse failure here used to tear down the - *entire* TCP connection instead of just failing that one request, which - showed up as Explorer aborting mid file-copy with a generic error. - - A `close_cmd` return value of `-2` now maps to - `SMB2_STATUS_DIRECTORY_NOT_EMPTY` in the CLOSE reply instead of a generic +- **Подключена реальная файловая система.** 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. +- **Патчи `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`. -- **Auth simplified** to plain guest/anonymous sessions (`authorize_handler` - always succeeds) — an earlier attempt at forcing NTLMv2 + SMB2 signing - turned out to be unrelated to a since-fixed listing bug, so it was backed - out rather than kept as unnecessary complexity. -- Removed high-frequency per-request debug logging that was originally added - to chase the above bugs, replaced with a single per-connection summary - line. +- **Упрощена авторизация** до обычных гостевых/анонимных сессий + (`authorize_handler` всегда успешен) — более ранняя попытка + принудительной NTLMv2 + подписи SMB2 оказалась не связана с уже + исправленным багом листинга, поэтому убрана как лишняя сложность. +- Убрано частое отладочное логирование каждого запроса, добавленное для + отлова описанных выше багов, заменено одной итоговой строкой на + соединение. -## Status +## Статус -The SMB2/3 server (read, browse, upload, delete) works against real Windows/ -Samba clients. **This is still in-progress work** — directory/file creation -(`MKDIR`) isn't implemented yet, overwriting an existing file with shorter -content doesn't truncate the old tail, and there's no live-update -(`change_notify`) support, so Explorer can show a stale listing for a moment -after a change until it's refreshed. See the source tree's own code comments -for the current state of any specific handler. +SMB2/3-сервер (чтение, просмотр, загрузка, удаление) работает с реальными +клиентами Windows/Samba. **Работа всё ещё продолжается** — создание +директорий (`MKDIR`) пока не реализовано, перезапись существующего файла +более коротким содержимым не обрезает старый хвост, и нет поддержки +уведомлений об изменениях в реальном времени (`change_notify`), поэтому +Проводник может на мгновение показывать устаревший листинг до обновления. +Актуальное состояние конкретных обработчиков — в комментариях исходного +кода. -## Flashing +## Прошивка -Target chip: **ESP32-S3**. Using `esptool.py` directly: +Целевой чип: **ESP32-S3**. Через `esptool.py` напрямую: ```bash esptool.py --chip esp32s3 -p COM5 -b 460800 write_flash \ @@ -96,16 +97,17 @@ esptool.py --chip esp32s3 -p COM5 -b 460800 write_flash \ 0x10000 esp-spi.bin ``` -(replace `COM5` with the actual port; `flasher_args.json` in this folder has -the same offsets in `idf.py`'s own JSON format, for reference or scripting.) +(замените `COM5` на реальный порт; `flasher_args.json` в этой папке +содержит те же смещения в собственном JSON-формате `idf.py` — для справки +или скриптов.) -If you're building from source instead: ESP-IDF **v6.1** (not `v6.1-rc1`) — +Если собираете из исходников: ESP-IDF **v6.1** (не `v6.1-rc1`) — `idf.py build flash`. -## Hardware +## Аппаратная часть -See `../hardware/` for: -- `connection_diagram.webp` — how this module wires up to a ZX Evolution - board. -- `pcb_photo.jpg` — a photo of the adapter board. -- `gerber/` — Gerber files for the adapter PCB. +См. `../hardware/`: +- `connection_diagram.webp` — как этот модуль подключается к плате ZX + Evolution. +- `pcb_photo.jpg` — фото переходной платы. +- `gerber/` — Gerber-файлы переходной платы.