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

---

## 🛠️ 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 41
- LRC:  GPIO 42
- DIN:  GPIO 40

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
│
├── main/
│   ├── CMakeLists.txt
│   ├── main.c               # Hauptprogramm
│   └── 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
```

---

## 🚀 Build & Flash

### Voraussetzungen

1. **ESP-IDF v4.4** installiert
2. **Python 3.10** (NICHT 3.12!)
3. **Git**

### Installation

```bash
# 1. Repository klonen
git clone <dein-repo>
cd esp32-s3-gnuboy

# 2. ESP-IDF aktivieren
source ~/esp-idf/export.sh

# 3. Target setzen
idf.py set-target esp32s3

# 4. (Optional) Konfiguration anpassen
idf.py menuconfig

# 5. Bauen
idf.py build

# 6. Flashen
idf.py -p /dev/ttyUSB0 flash

# 7. Monitor
idf.py monitor
```

### Troubleshooting

**Python 3.12 Fehler?**
```bash
# Python 3.10 installieren:
sudo apt-get install python3.10 python3.10-venv
cd ~/esp-idf
python3.10 ./install.sh esp32s3
```

**Build Fehler?**
```bash
# Clean & rebuild:
idf.py fullclean
idf.py build
```

---

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

1. **NFC Tags programmieren** mit ROM-Namen
2. **Tag scannen** → ROM startet automatisch!
3. **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

1. **Zwei GameBoys bauen**
2. **Link Cable verbinden:**
   - SCLK ↔ SCLK
   - SOUT ↔ SIN (gekreuzt!)
   - SIN ↔ SOUT (gekreuzt!)
   - GND ↔ GND
3. **Gleiches ROM laden** auf beiden
4. **Im Spiel:** 2-Player Mode wählen
5. **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

### Nächste Schritte

**Aktueller Status:**
- ✅ Projekt-Struktur fertig
- ✅ CMake Build System
- ✅ Pin-Konfiguration
- ✅ Component-Grundstruktur
- ⏳ 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
- **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

---

## 🎯 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! ❤️*