proxi-ai/README.md

<div align="center">

<img src="docs/img/proxi.png" width="360" alt="Der Proxi-Roboter">

# Proxi AI

**Einen Spielzeug-Roboter mit natürlicher Sprache steuern.**
Ein Kind sagt „lass ihn tanzen" — eine KI macht daraus Befehle, der Roboter tanzt.

[![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-blue.svg)](LICENSE)
[![micro:bit V1 + V2](https://img.shields.io/badge/micro%3Abit-V1%20%2B%20V2-brightgreen.svg)](#)
[![Bluetooth LE](https://img.shields.io/badge/Bluetooth-LE-blue.svg)](#)

</div>

---

Der [KOSMOS Proxi](https://kosmos.de/proxi) ist ein Bausatz-Roboter mit einem
BBC micro:bit als Kopf. Ab Werk programmiert man ihn mit Blöcken im Browser und
spielt das Ergebnis per USB auf.

Dieses Projekt ersetzt das durch eine Firmware, die **einmal** geflasht wird und
danach über Bluetooth auf Textbefehle hört. Was die Befehle schickt, ist ihr
egal — ein Skript, ein `curl`, oder eben ein KI-Agent, der aus „mach mal was
Lustiges" eine Choreografie baut.

```
   „Proxi, freu dich!"
            │
            ▼
      KI-Agent  ──HTTP──▶  Brücke (Python)  ──Bluetooth LE──▶  Proxi
                            Raspberry Pi
```

## In drei Schritten

```bash
# 1. Firmware aufspielen: firmware/proxi-ai.hex auf das MICROBIT-Laufwerk kopieren

# 2. Brücke starten (irgendein Rechner mit Bluetooth)
pip install bleak
python3 bridge/proxi_bridge.py --serve 8080

# 3. Proxi etwas sagen lassen
curl -X POST localhost:8080/command \
     -H 'Content-Type: application/json' \
     -d '{"command":"DANCE:3"}'
```

> ⚠️ Die Brücke hat **keine Authentifizierung** — wer sie erreicht, fährt den
> Roboter. Im Heimnetz ist das gewollt und unproblematisch; gib den Port aber
> nicht nach außen frei. Details in [docs/SETUP.md](docs/SETUP.md).

Ausführlich: **[docs/SETUP.md](docs/SETUP.md)**

## Was Proxi kann

| | |
|---|---|
| 🚶 **Laufen** | `MOVE:FWD:1200` · `TURN:LEFT:700` — vor, zurück, drehen, Kurven |
| 💃 **Tanzen** | `DANCE:3` · `STAMP:2` · `SHAKE:2` — oder eigene Choreografien |
| 😀 **Gesichter** | `FACE:HAPPY` · `FACE:RAW:0:10:0:17:14` — 34 Symbole oder eigene Pixelbilder |
| 🎵 **Musik** | `MELODY:NYAN` · `TONE:880:200` — 20 Melodien oder Ton für Ton komponiert |
| 📝 **Text** | `TEXT:Hallo Ben` — läuft über das LED-Display |
| 👀 **Sehen** | `SENSOR:ALL` — Infrarot links und rechts, erkennt Hindernisse |
| 🛑 **Not-Stopp** | `STOP` — wirkt auch mitten in einer Bewegung. Taste A am Roboter immer |

Vollständig: **[docs/PROTOCOL.md](docs/PROTOCOL.md)**

## Warum das interessant ist

**Die Bausteine sind fest, das Gebaute nicht.** Eine KI kann keine neuen
Grundbefehle erfinden — aber aus `FACE:RAW` jedes denkbare Gesicht malen, aus
`TONE` eigene Melodien komponieren und aus `MOVE`/`TURN` Choreografien bauen,
die niemand vorgegeben hat. [`agent/proxi-control.md`](agent/proxi-control.md)
ist der fertige Skill dafür.

**Die Pin-Belegung stand nirgends.** Kosmos dokumentiert sie nicht. Sie steckte
in den mitgelieferten `.hex`-Dateien — MakeCode hängt jedes Projekt komprimiert
an die kompilierte Firmware an. [`tools/hex_source.py`](tools/hex_source.py)
holt sie wieder heraus und funktioniert mit jeder micro:bit-`.hex`, nicht nur
mit denen von Proxi.

**Zwei Fallstricke, die je einen Abend gekostet haben.** Die Frequenz für
`music.playTone()` muss ganzzahlig sein — als Kommazahl kracht der Lautsprecher,
der Aufruf hängt und die Bluetooth-Verbindung stirbt. Und der Ton muss
ausdrücklich auf Pin P0 gelegt werden, sonst läuft er über den Audio-Mixer
des micro:bit V2 und lässt den Funk nicht mehr zum Zug kommen. Beides steht mit
Messwerten in [docs/HARDWARE.md](docs/HARDWARE.md).

## Aufbau

| | |
|---|---|
| [`firmware/`](firmware) | MakeCode-Projekt (TypeScript) und fertige `.hex` für V1 und V2 |
| [`bridge/`](bridge) | Bluetooth-Brücke und HTTP-API — nur `bleak` als Abhängigkeit |
| [`agent/`](agent) | Skill-Definition: Alltagssprache → Befehle |
| [`tools/`](tools) | Quelltext aus `.hex` extrahieren, Musik-Tabellen prüfen |
| [`docs/`](docs) | Protokoll, Einrichtung, Hardware, Lizenzen |

## Stand

Am echten Roboter durchgetestet: Verbindung, Sensoren, Display, 41 Sekunden
Musik am Stück, alle Bewegungsrichtungen, Musik und Fahren gleichzeitig,
Tanzfiguren, Not-Stopp mitten in der Bewegung, Autostart nach Neustart.

## Lizenz

MIT — siehe [LICENSE](LICENSE). Die Hardware-Extension und die Notendaten
stammen aus fremden MIT-Projekten, ihre Vermerke stehen in
[THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES).

---

## Wer das gebaut hat

Ich bin **Christian Gärtner**, selbstständiger **KI-Dozent und Berater**. Ich
zeige Unternehmen und Teams, wie künstliche Intelligenz im Alltag tatsächlich
funktioniert — ohne Buzzword-Bingo, dafür an echten Projekten.

Dieses hier ist eins davon, und es zeigt ziemlich genau, was ich meine: Ein
KI-Agent steuert keine Tabellen, sondern einen Roboter, der im Kinderzimmer
herumläuft. Die Bausteine sind fest, was daraus gebaut wird nicht — dieselbe
Frage stellt sich in jedem Unternehmen, das überlegt, wo KI bei ihm konkret
etwas beiträgt. Und die Fallstricke stehen hier dokumentiert statt versteckt,
weil das der Teil ist, an dem Projekte in der Praxis hängenbleiben.

<div align="center">

**KI-Schulungen · KI-Beratung · KI-Projekte**

**[gaertner.onl](https://gaertner.onl)** — Künstliche Intelligenz verständlich gemacht

[**Termin vereinbaren**](https://gaertner.onl/termin/) · [Kontakt](https://gaertner.onl/kontakt/) · [Blog](https://gaertner.onl/blog/)

</div>

<!--
  Dieser Ordner ist in sich geschlossen und lässt sich am Stück in ein
  eigenes Repo kopieren.

  docs/img/proxi.png ist das Produktbild von KOSMOS. Wer das vermeiden will,
  ersetzt es durch ein eigenes Foto — es ist genau diese eine Zeile oben.
-->