A Python-based, open-source, platform-independent serial utility for programming the Papilio Retrocade Board with FPGA bitstreams via its ESP32-S3 module. This is a modified version of Espressif's esptool, customized for programming Tang Primer 20K FPGA modules on the Papilio Retrocade hardware.
The Papilio Retrocade 20K is a retro computing and gaming FPGA development board featuring:
- FPGA: Gowin GW2A-LV18PG256C8/I7 (Tang Primer 20K core module)
- ESP32-S3 SuperMini: For wireless connectivity and FPGA programming
- HDMI video output
- 128MB DDR3 SDRAM on Tang module + dedicated SDRAM on expansion board
- Audio, USB-C, PMOD expansion, and RGB LED
This tool enables programming FPGA bitstreams (.bin files from Gowin EDA) to the Tang Primer 20K module via the ESP32-S3's SPI connection.
Important: Before using pesptool, the Tang Primer 20K FPGA must be programmed with the Papilio Tang Bootloader. This bootloader is a small FPGA design that:
- Uses Gowin's multi-boot feature to load from address 0x00 on startup
- Connects the ESP32-S3's SPI pins to the Tang Primer's flash chip via the FPGA fabric
- Provides a configurable timeout window (default 5 seconds) for programming operations
- Automatically boots to your FPGA design at address 0x100000 after the timeout expires
- Allows pesptool to directly access the FPGA's flash memory
Without this bootloader at address 0x00, pesptool cannot communicate with the FPGA flash chip. The bootloader must be programmed once via JTAG, and your FPGA designs will then be written to address 0x100000.
The tool is pre-configured with default SPI pins for the Papilio Retrocade Board's ESP32-S3 to Tang Primer 20K connection:
- CLK: GPIO 12
- Q (MISO): GPIO 9
- D (MOSI): GPIO 11
- HD: GPIO 26
- CS: GPIO 10
These pins match the hardware connections between the ESP32-S3 SuperMini and the Tang Primer 20K FPGA module.
Quick Programming - Just specify the bitstream file:
pesptool your_bitstream.binThis automatically writes to flash address 0x100000 (1MB), which is the bootloader-protected FPGA bitstream storage region.
Explicit Programming - Specify address and file:
pesptool write-flash 0x100000 your_bitstream.binThe tool protects the ESP32-S3 bootloader region (0x0 to 0xFFFFF) by default. The Papilio Tang Bootloader resides at address 0x00 and uses Gowin's multi-boot feature to automatically load your FPGA designs from address 0x100000 after a configurable timeout. This ensures the bootloader is never overwritten during normal operation.
Using uv (fast):
uv pip install git+https://github.com/Papilio-Labs/pesptool.gitUsing pip:
pip install git+https://github.com/Papilio-Labs/pesptool.gitClone and install:
git clone https://github.com/Papilio-Labs/pesptool.git
cd pesptool
# Using uv
uv pip install --extra-index-url https://dl.espressif.com/pypi -e .
# Or using pip
pip install --extra-index-url https://dl.espressif.com/pypi -e .# Simple - just provide the .bin file
pesptool mydesign.bin
# Explicit - specify flash address
pesptool write-flash 0x100000 mydesign.bin
# Specify serial port
pesptool --port COM3 mydesign.bin# Check ESP32-S3 chip info
pesptool chip-id
# Read flash ID
pesptool flash-id
# Erase specific region
pesptool erase-region 0x100000 0x400000
# Custom SPI connection (if needed)
pesptool --spi-connection 12,9,11,26,10 write-flash 0x100000 design.binFor comprehensive esptool functionality documentation, visit the original documentation or run pesptool -h.
Papilio Modifications: Adapted for Papilio Retrocade Board by Jack Gassett (@Papilio-Labs)
Original esptool: Created by Fredrik Ahlberg (@themadinventor), maintained by Angus Gratton (@projectgus), and supported by Espressif Systems.
- Papilio Retrocade Hardware Repository - Schematics, pin assignments, and hardware documentation
- Tang Primer 20K Documentation
- Gowin EDA - FPGA development tools
- Original esptool
This document and the attached source code are released as Free Software under GNU General Public License Version 2 or later. See the accompanying LICENSE file for a copy.