# 🚀 Quickstart Guide - ESP32-S3 GNUBoy

**Von 0 zu einem laufenden GameBoy Emulator in 10 Minuten!**

---

## ⚡ Schnellstart

### 1️⃣ Voraussetzungen prüfen

```bash
# ESP-IDF installiert?
idf.py --version

# Python Version (sollte 3.10 sein)?
python --version

# Git installiert?
git --version
```

**Wenn etwas fehlt, siehe weiter unten!**

---

### 2️⃣ Projekt klonen

```bash
cd ~/Arduino/gameboy/
git clone <dein-repo> esp32-s3-gnuboy
cd esp32-s3-gnuboy
```

---

### 3️⃣ ESP-IDF aktivieren

```bash
source ~/esp-idf/export.sh
```

**Wichtig:** Das musst du **jedes Mal** machen wenn du ein neues Terminal öffnest!

---

### 4️⃣ Target setzen

```bash
idf.py set-target esp32s3
```

---

### 5️⃣ Bauen

```bash
idf.py build
```

**Dauer:** ~2-5 Minuten beim ersten Build

---

### 6️⃣ Flashen

```bash
# Board anschließen via USB
# Dann:
idf.py -p /dev/ttyUSB0 flash
```

**Port finden:**
```bash
ls /dev/ttyUSB*
# oder
ls /dev/ttyACM*
```

---

### 7️⃣ Monitor starten

```bash
idf.py monitor
```

**Beenden:** `Ctrl+]`

---

## ✅ Fertig!

Du solltest jetzt sehen:

```
╔════════════════════════════════════════════════════════╗
║                                                        ║
║       ESP32-S3 GNUBoy LEGO GameBoy Emulator           ║
║                                                        ║
╚════════════════════════════════════════════════════════╝

Hardware: Waveshare ESP32-S3-Touch-LCD-2
Display:  ST7789 2.0" 240x320
Flash:    16 MB
PSRAM:    8 MB
```

---

## 🔧 Fehlerbehebung

### Problem: Python 3.12 Fehler

```bash
# Python 3.10 installieren:
sudo apt-get install python3.10 python3.10-venv python3.10-dev

# Alte ESP-IDF Umgebung löschen:
rm -rf ~/.espressif/python_env/idf4.4_py3.12_env

# ESP-IDF neu installieren:
cd ~/esp-idf
python3.10 ./install.sh esp32s3
```

---

### Problem: Port nicht gefunden

```bash
# USB Ports checken:
ls -la /dev/ttyUSB*
ls -la /dev/ttyACM*

# Berechtigungen setzen:
sudo usermod -a -G dialout $USER
# Dann neu einloggen!
```

---

### Problem: Build Fehler

```bash
# Alles löschen und neu:
idf.py fullclean
idf.py build
```

---

### Problem: Flash Fehler

```bash
# Board in Download Mode bringen:
# 1. BOOT Button drücken und halten
# 2. RESET Button kurz drücken
# 3. BOOT loslassen
# 4. Nochmal flashen versuchen
```

---

## 📱 Nächste Schritte

### SD-Karte vorbereiten

1. **Formatieren:** FAT32
2. **Verzeichnis:** `/roms/gb/`
3. **ROMs kopieren:** `tetris.gb`, etc.

### Hardware verbinden

- **Display:** Sollte schon integriert sein!
- **Buttons:** Nach Pin-Plan verlöten
- **Audio:** MAX98357A anschließen
- **NFC:** PN532 via I2C
- **SD-Karte:** Einlegen

### Code anpassen

1. **Pins prüfen:** `main/hardware_config.h`
2. **Features aktivieren:** `main/main.c`

---

## 🎮 Test-Workflow

### Minimaler Test (ohne ROMs):

```bash
# Build & Flash
idf.py build flash monitor

# Erwartung:
# - System startet
# - PSRAM erkannt
# - Display initialisiert
# - Keine Errors
```

### Mit ROM testen:

```bash
# 1. ROM auf SD-Karte: /roms/gb/tetris.gb
# 2. SD-Karte einlegen
# 3. Neustarten
# 4. ROM sollte laden
```

---

## 💡 Tipps

### Schneller entwickeln:

```bash
# Nur App flashen (schneller):
idf.py app-flash

# Monitor ohne Flash:
idf.py monitor

# Build + Flash + Monitor in einem:
idf.py build flash monitor
```

### Debug aktivieren:

```bash
idf.py menuconfig

# Dann:
# Component config → Log output
# → Default log verbosity → Verbose
```

### Pin-Check:

Alle Pins sind in **einer** Datei:
```bash
cat main/hardware_config.h
```

---

## 📊 Checkliste

Nach erfolgreichem Build solltest du haben:

- ✅ ESP-IDF v4.4 aktiv
- ✅ Python 3.10 (nicht 3.12!)
- ✅ Projekt kompiliert ohne Fehler
- ✅ Board erkannt auf `/dev/ttyUSB0`
- ✅ Flash erfolgreich
- ✅ Serial Monitor zeigt Boot-Messages
- ✅ PSRAM wird erkannt (8 MB)
- ✅ Display wird initialisiert

---

## 🎯 Wenn alles läuft:

**Glückwunsch!** 🎉

Jetzt kannst du:
1. Hardware zusammenbauen
2. GNUBoy Core integrieren
3. ROMs testen
4. NFC implementieren
5. Link Cable bauen

---

## 📞 Hilfe

**Serial Monitor zeigt nichts?**
→ Richtigen Port? Richtige Baud-Rate (115200)?

**Build dauert ewig?**
→ Beim ersten Mal normal (5-10 Min), danach schneller

**Flash schlägt fehl?**
→ Boot Mode? USB-Kabel OK? Treiber installiert?

---

**Viel Erfolg!** 🚀

*Für Stefan's LEGO GameBoy Projekt*