452 lines
10 KiB
Markdown
452 lines
10 KiB
Markdown
# 🎮 ESP32-S3 GNUBoy - LEGO GameBoy Emulator
|
||
|
||
**GameBoy/GameBoy Color Emulator für Waveshare ESP32-S3-Touch-LCD-2**
|
||
|
||
---
|
||
|
||
## 📋 Projekt-Übersicht
|
||
|
||
Dieses Projekt ist ein kompletter GameBoy Emulator für das **Waveshare ESP32-S3-Touch-LCD-2** Board.
|
||
|
||
### ✨ Features
|
||
|
||
- ✅ **GameBoy & GameBoy Color Emulation** (GNUBoy Core)
|
||
- ✅ **ST7789 Display** (2.0", 240x320, optimiert)
|
||
- ✅ **NFC ROM-Auswahl** (PN532, einfach Tag scannen!)
|
||
- ✅ **Potentiometer Controls** (Volume & Brightness)
|
||
- ✅ **Link Cable 2-Player** (Tetris, Pokemon, etc.)
|
||
- ✅ **SD Card ROM Loading** (alle deine ROMs)
|
||
- ✅ **I2S Audio** (MAX98357A, klarer Sound)
|
||
- ✅ **8 GameBoy Buttons** (Original Layout)
|
||
|
||
---
|
||
|
||
## 🚀 Schnellstart - Build & Flash
|
||
|
||
### Voraussetzungen
|
||
|
||
- **ESP-IDF v4.4** installiert
|
||
- **Python 3.10** (NICHT 3.12!)
|
||
- **Git**
|
||
- **pyenv** (für Python-Version Management)
|
||
|
||
### ⚙️ Installation & Build
|
||
|
||
#### 1️⃣ Original GNUBoy Repository klonen
|
||
|
||
```bash
|
||
# Erstelle Arbeitsverzeichnis
|
||
mkdir -p ~/Arduino/gameboy
|
||
cd ~/Arduino/gameboy
|
||
|
||
# Clone das Original MCH2022 GNUBoy Projekt
|
||
git clone -b v4.4 --recursive https://github.com/badgeteam/mch2022-esp32-app-gnuboy.git gnuboy
|
||
cd gnuboy
|
||
```
|
||
|
||
#### 2️⃣ Unser angepasstes Projekt darüber kopieren
|
||
|
||
```bash
|
||
# Clone unser LEGO GameBoy Projekt
|
||
cd ~/Arduino/gameboy
|
||
git clone https://git.hacker-net.de/Hacker-Software/lego-esp32s3-gameboy.git
|
||
|
||
# Kopiere alle Dateien über das Original-Projekt
|
||
cp -r lego-esp32s3-gameboy/* gnuboy/
|
||
cd gnuboy
|
||
```
|
||
|
||
#### 3️⃣ ESP-IDF v4.4 Setup
|
||
|
||
```bash
|
||
# Abhängigkeiten installieren
|
||
sudo apt install python3-gevent python3-virtualenv git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 curl
|
||
sudo apt-get install -y \
|
||
build-essential \
|
||
libssl-dev \
|
||
zlib1g-dev \
|
||
libbz2-dev \
|
||
libreadline-dev \
|
||
libsqlite3-dev \
|
||
wget \
|
||
curl \
|
||
llvm \
|
||
libncurses5-dev \
|
||
libncursesw5-dev \
|
||
xz-utils \
|
||
tk-dev \
|
||
libffi-dev \
|
||
liblzma-dev \
|
||
python3-openssl \
|
||
git
|
||
|
||
|
||
# pyenv installieren (falls noch nicht vorhanden)
|
||
curl https://pyenv.run | bash
|
||
|
||
# Zu ~/.bashrc hinzufügen:
|
||
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
|
||
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
|
||
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
|
||
# Python 3.10 installieren und aktivieren
|
||
pyenv install 3.10.13
|
||
pyenv local 3.10.13
|
||
|
||
# ESP-IDF v4.4 installieren
|
||
git clone -b v4.4 --recursive https://github.com/espressif/esp-idf.git ~/esp-idf
|
||
cd ~/esp-idf
|
||
./install.sh esp32s3
|
||
source ./export.sh
|
||
```
|
||
|
||
#### 4️⃣ **WICHTIG: Fix-Scripts ausführen!**
|
||
|
||
⚠️ **Vor dem Kompilieren müssen zwingend diese beiden Scripts ausgeführt werden:**
|
||
|
||
```bash
|
||
cd ~/Arduino/gameboy/gnuboy
|
||
|
||
# 1. PSRAM-Kompatibilität für ESP-IDF v4.4 herstellen
|
||
chmod +x fix_psram.sh
|
||
./fix_psram.sh
|
||
|
||
# 2. Komponenten-Abhängigkeiten fixen (Potentiometer, NFC, JSON)
|
||
chmod +x fix_poti_manager_nfc_json.sh
|
||
./fix_poti_manager_nfc_json.sh
|
||
```
|
||
|
||
**Was machen diese Scripts?**
|
||
- `fix_psram.sh`: Ersetzt `esp_psram` mit `esp_hw_support` (ESP-IDF v4.4 API-Änderung)
|
||
- `fix_poti_manager_nfc_json.sh`:
|
||
- Fügt fehlende Komponenten-Abhängigkeiten hinzu (json, fatfs, st7789)
|
||
- Kopiert `hardware_config.h` an die richtigen Stellen
|
||
- Passt ADC-API für Potentiometer an (entfernt deprecated `esp_adc_cal`)
|
||
|
||
#### 5️⃣ Projekt konfigurieren & bauen
|
||
|
||
```bash
|
||
cd ~/Arduino/gameboy/gnuboy
|
||
|
||
# ESP-IDF Environment laden
|
||
source ~/esp-idf/export.sh
|
||
|
||
# Target setzen
|
||
idf.py set-target esp32s3
|
||
|
||
# (Optional) Konfiguration anpassen, wird schon durch script fix_psram.sh gemacht
|
||
idf.py menuconfig
|
||
# → Component config → ESP32S3-Specific → PSRAM auf "Octal Mode" setzen
|
||
|
||
# Projekt bauen
|
||
idf.py build
|
||
```
|
||
|
||
#### 6️⃣ Flashen
|
||
|
||
```bash
|
||
# USB-Port finden (meist /dev/ttyUSB0 oder /dev/ttyACM0)
|
||
ls /dev/ttyUSB* /dev/ttyACM*
|
||
|
||
# Flashen (ggf. BOOT-Button beim Verbinden gedrückt halten)
|
||
idf.py -p /dev/ttyUSB0 flash
|
||
|
||
# Mit Monitor (zum Debuggen)
|
||
idf.py -p /dev/ttyUSB0 flash monitor
|
||
|
||
# Monitor beenden: Ctrl + ]
|
||
#Einfach nur monitor
|
||
#idf.py -p /dev/ttyUSB0 monitor
|
||
```
|
||
|
||
### 🐛 Troubleshooting
|
||
|
||
#### Python 3.12 Fehler?
|
||
```bash
|
||
# Python 3.10 installieren:
|
||
siehe anfang 3️⃣ ESP-IDF v4.4 Setup
|
||
```
|
||
|
||
#### Build Fehler?
|
||
```bash
|
||
# Clean & rebuild:
|
||
idf.py fullclean
|
||
idf.py build
|
||
```
|
||
|
||
#### PSRAM nicht erkannt?
|
||
```bash
|
||
# Octal PSRAM aktivieren:
|
||
idf.py menuconfig
|
||
# → Component config → ESP32S3-Specific
|
||
# → [*] Support for external, SPI-connected RAM
|
||
# → SPI RAM config → Mode: Octal Mode PSRAM
|
||
```
|
||
|
||
#### Board kommt nicht in Flash-Modus?
|
||
```
|
||
1. BOOT-Button gedrückt halten
|
||
2. RESET-Button kurz drücken
|
||
3. BOOT-Button loslassen
|
||
4. Flash-Befehl ausführen
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ Hardware
|
||
|
||
### Hauptkomponenten
|
||
|
||
| Component | Model | Notes |
|
||
|-----------|-------|-------|
|
||
| **MCU Board** | Waveshare ESP32-S3-Touch-LCD-2 | 16MB Flash, 8MB PSRAM |
|
||
| **Display** | ST7789 2.0" | 240x320, integriert |
|
||
| **Audio** | MAX98357A | I2S Amplifier |
|
||
| **NFC Reader** | PN532 | I2C mode |
|
||
| **Storage** | MicroSD Card | FAT32, via SPI |
|
||
|
||
### Pin-Belegung
|
||
|
||
> **Siehe `main/hardware_config.h` für alle Pin-Definitionen!**
|
||
|
||
**Wichtigste Pins:**
|
||
|
||
**Display (ST7789):**
|
||
- MOSI: GPIO 11
|
||
- SCLK: GPIO 12
|
||
- CS: GPIO 10
|
||
- DC: GPIO 8
|
||
- RST: GPIO 14
|
||
- BL: GPIO 9
|
||
|
||
**Audio (I2S):**
|
||
- BCLK: GPIO 35
|
||
- LRC: GPIO 36
|
||
- DIN: GPIO 37
|
||
|
||
**NFC (PN532):**
|
||
- SCL: GPIO 16
|
||
- SDA: GPIO 15
|
||
|
||
**Buttons:**
|
||
- UP: GPIO 1, DOWN: GPIO 2
|
||
- LEFT: GPIO 42, RIGHT: GPIO 41
|
||
- A: GPIO 21, B: GPIO 47
|
||
- START: GPIO 48, SELECT: GPIO 45
|
||
|
||
**Link Cable:**
|
||
- SCLK: GPIO 17
|
||
- SOUT: GPIO 18
|
||
- SIN: GPIO 38
|
||
|
||
---
|
||
|
||
## 📦 Projekt-Struktur
|
||
|
||
```
|
||
esp32-s3-gnuboy/
|
||
├── CMakeLists.txt # Root CMake
|
||
├── sdkconfig.defaults # ESP-IDF config
|
||
├── partitions.csv # Flash partitions
|
||
├── README.md # Diese Datei
|
||
├── fix_psram.sh # ⚠️ WICHTIG: Vor Build ausführen!
|
||
├── fix_poti_manager_nfc_json.sh # ⚠️ WICHTIG: Vor Build ausführen!
|
||
│
|
||
├── main/
|
||
│ ├── CMakeLists.txt
|
||
│ ├── main.c # Hauptprogramm
|
||
│ └── include/
|
||
│ └── hardware_config.h # Pin-Definitionen
|
||
│
|
||
└── components/
|
||
├── gnuboy/ # GNUBoy Emulator Core
|
||
│ ├── CMakeLists.txt
|
||
│ ├── include/gnuboy.h
|
||
│ └── gnuboy_placeholder.c
|
||
│
|
||
├── st7789/ # Display Driver
|
||
│ ├── CMakeLists.txt
|
||
│ ├── include/st7789.h
|
||
│ └── st7789.c
|
||
│
|
||
├── nfc_manager/ # NFC ROM Selection
|
||
│ ├── CMakeLists.txt
|
||
│ ├── include/nfc_manager.h
|
||
│ └── nfc_manager.c
|
||
│
|
||
├── link_cable/ # 2-Player Support
|
||
│ ├── CMakeLists.txt
|
||
│ ├── include/link_cable.h
|
||
│ └── link_cable.c
|
||
│
|
||
└── potentiometer_manager/ # Volume/Brightness Control
|
||
├── CMakeLists.txt
|
||
├── include/potentiometer_manager.h
|
||
└── potentiometer_manager.c
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 Benutzung
|
||
|
||
### ROMs laden
|
||
|
||
1. SD-Karte formatieren (FAT32)
|
||
2. Verzeichnis erstellen: `/roms/gb/`
|
||
3. ROMs kopieren (.gb oder .gbc Dateien)
|
||
4. SD-Karte einlegen
|
||
|
||
### NFC ROM-Auswahl
|
||
|
||
- NFC Tags programmieren mit ROM-Namen
|
||
- Tag scannen → ROM startet automatisch!
|
||
- Mapping-File: `/sd/nfc_roms.json`
|
||
|
||
**Beispiel `nfc_roms.json`:**
|
||
```json
|
||
{
|
||
"mappings": [
|
||
{
|
||
"tag_uid": "04:12:34:56:78:9A:B0",
|
||
"rom_path": "/roms/gb/tetris.gb"
|
||
},
|
||
{
|
||
"tag_uid": "04:AB:CD:EF:12:34:56",
|
||
"rom_path": "/roms/gb/pokemon_red.gb"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Link Cable 2-Player
|
||
|
||
- Zwei GameBoys bauen
|
||
- Link Cable verbinden:
|
||
- SCLK ↔ SCLK
|
||
- SOUT ↔ SIN (gekreuzt!)
|
||
- SIN ↔ SOUT (gekreuzt!)
|
||
- GND ↔ GND
|
||
- Gleiches ROM laden auf beiden
|
||
- Im Spiel: 2-Player Mode wählen
|
||
- Spielen! 🎮🔗🎮
|
||
|
||
### Buttons
|
||
|
||
GameBoy Layout:
|
||
```
|
||
┌─────┐
|
||
←→↑↓ B A
|
||
SELECT START
|
||
```
|
||
|
||
- **D-Pad:** Bewegung
|
||
- **A/B:** Aktion
|
||
- **START:** Menü/Start
|
||
- **SELECT:** Auswahl
|
||
|
||
### Potentiometer
|
||
|
||
- **Links:** Volume (0-100%)
|
||
- **Rechts:** Brightness (10-100%)
|
||
|
||
---
|
||
|
||
## 🔧 Entwicklung
|
||
|
||
### Aktueller Status
|
||
|
||
- ✅ Projekt-Struktur fertig
|
||
- ✅ CMake Build System
|
||
- ✅ Pin-Konfiguration
|
||
- ✅ Component-Grundstruktur
|
||
- ✅ ESP-IDF v4.4 Kompatibilität
|
||
- ✅ PSRAM Support (8MB Octal)
|
||
- ⏳ GNUBoy Core Integration
|
||
- ⏳ ST7789 Driver fertigstellen
|
||
- ⏳ NFC Implementation
|
||
- ⏳ Link Cable Implementation
|
||
|
||
### TODO
|
||
|
||
1. **GNUBoy Core integrieren:**
|
||
- Quellcode von esplay-gb portieren
|
||
- Für ESP32-S3 anpassen
|
||
- Serial/Link Interface implementieren
|
||
|
||
2. **ST7789 Driver fertigstellen:**
|
||
- Init-Sequenz ergänzen
|
||
- Framebuffer-Rendering optimieren
|
||
- GameBoy→Display Mapping
|
||
|
||
3. **NFC Manager implementieren:**
|
||
- PN532 I2C Treiber
|
||
- Tag UID auslesen
|
||
- JSON Mapping parsen
|
||
|
||
4. **Link Cable fertigstellen:**
|
||
- GPIO Bit-Transfer
|
||
- Master/Slave Negotiation
|
||
- GNUBoy Serial Hook
|
||
|
||
5. **Audio implementieren:**
|
||
- I2S Konfiguration
|
||
- GameBoy→I2S Buffer
|
||
- Volume Control
|
||
|
||
### Code-Richtlinien
|
||
|
||
- **Zentralisierte Konfiguration:** Alle Pins in `hardware_config.h`
|
||
- **ESP-IDF Stil:** `ESP_LOG` statt `printf`
|
||
- **Fehlerbehandlung:** Immer `ESP_ERROR_CHECK` nutzen
|
||
- **Dokumentation:** Doxygen-Kommentare
|
||
|
||
---
|
||
|
||
## 📝 Lizenz
|
||
|
||
- **GNUBoy:** GPL v2.0
|
||
- **Projekt-spezifischer Code:** MIT (oder nach Wahl)
|
||
|
||
---
|
||
|
||
## 🙏 Credits
|
||
|
||
- **GNUBoy:** Original GameBoy Emulator
|
||
- **esplay-gb:** ESP32 Port von pebri86
|
||
- **MCH2022 Badge Team:** ESP32 GNUBoy App
|
||
- **Waveshare:** Hardware Board
|
||
- **Stefan:** LEGO GameBoy Projekt! 🎮
|
||
|
||
---
|
||
|
||
## 📞 Support
|
||
|
||
Bei Fragen oder Problemen:
|
||
|
||
1. Hardware-Config prüfen (`hardware_config.h`)
|
||
2. Serial Monitor checken (`idf.py monitor`)
|
||
3. Build-Log lesen
|
||
4. Pin-Konflikte überprüfen
|
||
5. Fix-Scripts ausgeführt? (`fix_psram.sh` & `fix_poti_manager_nfc_json.sh`)
|
||
|
||
---
|
||
|
||
## 🎯 Vision
|
||
|
||
**Ziel:** Der ultimative LEGO GameBoy Emulator!
|
||
|
||
- Zwei baugleiche Geräte
|
||
- Link Cable Multiplayer
|
||
- NFC ROM-Auswahl
|
||
- Professionelle Qualität
|
||
- Open Source
|
||
|
||
**Let's build it! 🚀🎮**
|
||
|
||
---
|
||
|
||
*Erstellt für Stefan's LEGO GameBoy Projekt*
|
||
*Hardware: Waveshare ESP32-S3-Touch-LCD-2*
|
||
*Mit Liebe zum Detail gebaut! ❤️*
|