# Hinweise für KI-Assistenten (Codex, Claude Code und andere)

Die Sketches in diesem Ordner sind für den **PicoBoy Color Plus** (PBC+) und
die **Arduino IDE 2**. Sie stammen aus dem Buch „Programmieren mit Arduino –
PicoBoy Color Plus“. Der Mensch am anderen Ende lernt gerade programmieren:
Erkläre Änderungen in einfachen Worten.

## Hardware und Board

- Mikrocontroller **RP2350** (wie Raspberry Pi Pico 2), 2 Kerne, 150 MHz,
  520 KB RAM, 16 MB Flash. **Kein** AVR, **kein** Arduino Uno, **kein** ESP32.
- Kern „Raspberry Pi Pico/RP2040/RP2350“ von Earle Philhower (arduino-pico),
  Board **Generic RP2350**, Flash Size **16MB (Sketch: 8MB, FS: 8MB)**.
  FQBN: `rp2040:rp2040:generic_rp2350:flash=16777216_8388608`
- Display ST7789, **240 × 280 Pixel**, (0, 0) oben links, runde Ecken
  (etwa 20 Pixel Rand freilassen).
- Joystick (hoch, runter, links, rechts, Mitte), Tasten A und B, LEDs
  rot/gelb/grün, eine RGB-LED (für Adafruit NeoPixel), Lautsprecher, Beschleunigungssensor
  STK8BA58, zwei AAA-Batterien.

## Pins (immer diese Namen und Nummern)

```cpp
#define TFT_CS 10
#define TFT_DC 8
#define TFT_RST 9
#define TFT_LICHT 26      // Hintergrundlicht
#define LAUTSPRECHER 15
#define LED_ROT 14
#define LED_GELB 13
#define LED_GRUEN 12
#define RGB_LED 11
#define TASTE_HOCH 4
#define TASTE_RUNTER 2
#define TASTE_LINKS 3
#define TASTE_RECHTS 1
#define TASTE_MITTE 0
#define TASTE_A 27
#define TASTE_B 28
#define BATTERIE A3       // Batteriespannung, Spannungsteiler 1:3
```

Benutze nur diese Pins. `LED_BUILTIN` (GP25) ist keine der LEDs.

## Bibliotheken

Nur diese, nichts anderes installieren oder einbinden:

Installation (einmal):

- Adafruit ST7735 and ST7789 und Adafruit NeoPixel aus dem Bibliotheksverwalter
  (`arduino-cli lib install "Adafruit ST7735 and ST7789 Library" "Adafruit NeoPixel"`,
  Adafruit GFX kommt als Abhängigkeit mit).
- STK8BA58 gibt es nicht im Bibliotheksverwalter. Herunterladen:
  https://pbcplus.de/downloads/STK8BA58.zip – in der IDE über
  „Sketch → Bibliothek einbinden → .ZIP-Bibliothek hinzufügen…“, mit arduino-cli:
  `arduino-cli config set library.enable_unsafe_install true` und
  `arduino-cli lib install --zip-path STK8BA58.zip`.

- **Adafruit ST7735 and ST7789** (mit Adafruit GFX): `#include <Adafruit_ST7789.h>`,
  `Adafruit_ST7789 tft(TFT_CS, TFT_DC, TFT_RST);`, `tft.init(240, 280);`
- **Adafruit NeoPixel**: `Adafruit_NeoPixel rgb(1, RGB_LED, NEO_GRB + NEO_KHZ800);`,
  nach `setPixelColor` immer `rgb.show()`.
- **STK8BA58** (Beschleunigungssensor): `sensor.begin(20, 21);` und
  `sensor.setOrientation(STK8BA58::PICOBOY_COLOR_PLUS);`,
  dann `sensor.readAcceleration(x, y, z)` in g.
- Aus dem Kern: `Wire`, `EEPROM`, `LittleFS`, `tone`, `analogRead` usw.

Erfinde keine Funktionen. Wenn du nicht sicher bist, ob es eine Funktion
gibt, lies die Header-Datei der Bibliothek (z. B. `Adafruit_GFX.h`) oder
sag, dass du es nicht weißt.

## Regeln für jeden Sketch

- Arduino-Aufbau: `setup()` und `loop()`, kein eigenes `main()`.
- Display: nach `tft.init(240, 280);` immer das Hintergrundlicht einschalten:
  `pinMode(TFT_LICHT, OUTPUT); digitalWrite(TFT_LICHT, HIGH);` – sonst
  bleibt alles schwarz.
- Flimmerfrei mit `GFXcanvas16 bild(240, 280);` zeichnen und mit
  `tft.drawRGBBitmap(0, 0, bild.getBuffer(), 240, 280);` zeigen.
- Tasten: `pinMode(…, INPUT_PULLUP)`, gedrückt ist `LOW`. Entprellen selbst
  machen.
- I2C: **niemals** `Wire.begin()` ohne vorher die Pins zu setzen. Die
  Standard-Pins GP4/GP5 sind Joystick-Hoch und ein freier Pin. Richtig:
  `Wire.setSDA(20); Wire.setSCL(21); Wire.begin();` oder einfach
  `sensor.begin(20, 21)`. Der Sensor hat die Adresse 0x18.
- **`Serial1` nie benutzen** (liegt auf GP0/GP1 = Joystick Mitte/Rechts),
  `Serial2` auch nicht (GP8/GP9 = Display). Ausgaben über `Serial` (USB),
  `Serial.begin(115200);` als erste Zeile in `setup()`.
- **Keine AVR-Register** wie `PORTB`, `DDRB`, `PIND`, kein `_delay_ms`,
  keine `avr/…`-Header außer dem, was der Kern selbst mitbringt.
- Interrupts (`attachInterrupt`): Die Routine ist kurz, setzt nur
  `volatile`-Variablen. **Kein `delay`, kein `Serial`, kein `tone`, kein
  Zeichnen in einer ISR.**
- Zweiter Kern: `setup1()`/`loop1()`. Nur ein Kern zeichnet auf dem Display.
  Daten zwischen den Kernen über `volatile`-Variablen oder `rp2040.fifo`.
- Texte auf dem Display und im seriellen Monitor ohne Umlaute und ß
  („Schoen“, „Gruesse“).
- Zufall: `randomSeed(rp2040.hwrand32());` in `setup()`.
- Flash schonen: `EEPROM.commit()` und Dateien in `LittleFS` nur schreiben,
  wenn sich etwas geändert hat, nicht in jedem `loop()`-Durchlauf.
- Namen deutsch, klein, ohne Umlaute; 4 Leerzeichen Einrückung; immer
  geschweifte Klammern.

## Prüfen

Der Sketch muss **ohne Fehler und ohne Warnungen** übersetzen. Wenn
`arduino-cli` installiert ist:

```
arduino-cli compile -b rp2040:rp2040:generic_rp2350:flash=16777216_8388608 --warnings all <Sketchordner>
```

Mit `--output-dir build` legt arduino-cli dort auch die fertige `.uf2` ab. Hochladen macht der Mensch (Arduino IDE: **Hochladen**, oder die `.uf2` im Bootmodus aufs Laufwerk ziehen). Was du nicht selbst
testen konntest (Display, Ton, Tasten), nenne ausdrücklich, damit es am Gerät
geprüft wird.