# ZIFI32 — ESP32 WiFi/SPI module for 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.

**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.

## 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
  [`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 |

## 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`.

## 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).

## 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.