Here you go — a clean, vector-friendly MD you can drop straight into the repo.

---

# Beardyman-Prinzip → ESP-Wald

**Ein Sound-Broker als Lern- und Bühnen-Setup (Clock, Control, Care)**

**Stand:** v1
**Kontext:** 4 iPads steuern via MQTT eine „Aurora“-Kernuhr (Clock) und Module (LEDs, Seifenblasen, Prompts). Broker läuft lokal/statisch, MikroTik segmentiert (ESP-VLAN isoliert, Crew-Pads separat).
**Ziel:** Ein robustes, kindertaugliches Set-up, das im **Learn-Modus** ruhig und nachvollziehbar ist und im **Stage-Modus** Show kann—ohne je die **Nullfeld-Sicherheiten** (CUT, Watchdogs, Logs) zu verlieren.

---

## 1) Architektur (kurz)

* **Netz**

  * MikroTik: `VLAN50 = ESP_WALD`, `VLAN20 = CREWPADS` (oder vorhandenes Crew-WLAN).
  * Broker (RasPi/Jetson) **per LAN**, feste IP (z. B. `192.168.50.10`), nur Control-Daten über MQTT.
* **Rollen**

  * **Clock/Conductor:** zentrale BPM & Tick.
  * **Controller (4 iPads):** Beat, Lights/Bubbles, FX/Prompts, Scene/CUT.
  * **Acts:** ESP-LEDs, Seifenblasen-ESP, OpenMV (Heartbeat/Events), optional Audio-Host (Ableton/Logic).

---

## 2) MQTT-Topics (minimal & robust)

```text
# Zeitbasis
crumb/clock/bpm            int      # z.B. 120
crumb/clock/tick           int      # 0..7 (8er Raster)

# Global Commands
crumb/cmd/cut              "NOW"    # harter Not-Aus für alles
crumb/cmd/scene            "A"|"B"|"C"

# Musik / Visual Control (klein halten!)
crumb/stem/beat            "k:1,5|h:3,7"         # Mini-Pattern
crumb/stem/melody          "C4:1,C5:5"           # Note events
crumb/stem/light/<zone>    JSON {"mode":"pulse","h":210,"s":80,"v":60}

# Telemetrie / Logs
crumb/esp/<id>/heartbeat   JSON {"rssi":-57,"lat":42}
crumb/log/<device>         string   # Plain debug for Node-RED pane
```

**Prinzip:** Nur wenige, sinnvolle Messages. **Clock zuerst**, alles andere folgt.

---

## 3) Zwei Betriebsarten

### Learn (Default)

* 8-Takt-Fenster: **add (1–2), hold (3–6), remove (7–8)** → Kinder spüren Struktur.
* Node-RED zeigt Logs („Krümel-Beweise“) live.
* CUT jederzeit verfügbar.

### Stage (Show)

* Clock „free run“, **Scenes** feuern mehrere Topics als Makro.
* CUT bleibt „großer roter Knopf“.

---

## 4) Die 4 iPad-Rollen

1. **Clock/Conductor**

   * Fader: `bpm` (80–140) → `crumb/clock/bpm`
   * Buttons: `crumb/cmd/cut=NOW`, `crumb/cmd/scene=A|B|C`
   * Takt-Reset (`tick=0`)

2. **Beat**

   * 8 Step-Pads → `crumb/stem/beat`
   * „Ghost“-Taste: nur Visuals (kein Ton)

3. **Lights & Bubbles**

   * Zonen-Pads: `crumb/stem/light/front|hex|sky`
   * Slider: H/S/V, Modes: `pulse|aurora`

4. **FX / Prompts**

   * Kurztexte → `crumb/ui/hint`
   * „Solo“: alles Mute außer gewählte Zone

> **UX-Regel:** Pro iPad nur 3–4 Controls gleichzeitig aktiv. Kein Überladen.

---

## 5) Node-RED Mini-Flow (Tag-1)

* **mqtt-in**: `crumb/#` → **debug** (Live-Sicht für Kinder & Crew)
* **function „tick gate“**: lässt nur Messages zu Takt-Beginn (1/3/5/7) durch → Groove bleibt sauber.
* Optional: **Ableton-Link → MQTT** (kleines Python-Skript) publisht `bpm` & `tick`.

---

## 6) Safety (Nullfeld)

* **CUT** muss auf jedem iPad groß, eindeutig, erreichbar sein.
* Jedes ESP: Wenn **3 Ticks fehlen** oder `bpm` **out-of-range**, lokal **Failsafe** (Schwarz/Still) bis `tick=0`.
* **Watchdog**: Bei fehlendem `heartbeat` → Node-RED zeigt Warnkarte.
* **Firewall**: ESP-VLAN darf **nur** DNS/DHCP/MQTT; kein „Internet by default“.

---

## 7) Bring-up in 10 Schritten

1. **Broker** IP fix (z. B. `192.168.50.10`). Lokal testen: `mosquitto_pub/sub`.
2. **MikroTik**: CREWPADS → Broker TCP/1883 erlauben; ESP-VLAN nur DNS/DHCP/MQTT.
3. **Node-RED**: `mqtt-broker` Node + Panels „Clock / Logs“.
4. **Clock-Publisher (RPi)**: `bpm=120`, `tick 0..7` senden (8er Raster).
5. **iPad #1 (Clock)**: CUT + Scene + BPM-Fader live testen.
6. **iPad #2 (Beat)**: Step-Pads → `crumb/stem/beat`.
7. **ESP-LED**: `crumb/stem/light/hex` → Farbe ändert.
8. **OpenMV**: `heartbeat`/`ui/hint` publisht („Bubble time!“).
9. **CUT-Test**: Alles geht sofort aus, Re-Start bei `tick=0`.
10. **„Regel der 8“** mit Kids üben (add/hold/remove) → Ruhe & Kontrolle.

---

## 8) Beispiel: mini-Clock (Python, skizziert)

```python
# sendet bpm & 8er tick
import time, paho.mqtt.client as mq
c = mq.Client()
c.connect("192.168.50.10", 1883, 60)
bpm = 120
t = 0
while True:
    c.publish("crumb/clock/bpm", bpm, qos=0, retain=True)
    c.publish("crumb/clock/tick", t, qos=0, retain=False)
    t = (t + 1) % 8
    time.sleep(60.0 / bpm / 2)  # 8tel oder wie gewünscht
```

---

## 9) Akzeptanzkriterien (Done)

* **CUT** schaltet **alles** in < 200 ms stumm/aus.
* **Tick-Sync**: Alle sichtbaren Akteure reagieren im Raster (kein „Schwimmen“).
* **Logs**: Node-RED zeigt alle eingehenden Topics (kindverständlich).
* **Failsafe**: 3 fehlende Ticks → alle ESPs gehen „sicher“.

---

## 10) Rollback / Notfall

* Broker down → Clock stoppt → ESPs gehen sicher (Schwarz/Still).
* MikroTik-Regeln off? **Fallback-Profile** bereit halten (export `.rsc`).
* CUT bleibt lokal (auch ohne Broker) als letzte Instanz.

---

## 11) Backlog (kurz)

* TouchOSC/MIDI-Mapping Templates versionieren.
* „Scene-Makros“ als Node-RED Subflows.
* Ableton-Link Bridge härten (Jitter-Messung).
* Telemetrie-Dashboard (LED-Zonen, RSSI, Tick-Lag).
* Workshop-Kit: „Regel der 8“ als Boden-Hexa mit LED-Ring (Eule in der Mitte).

---

### Nullfeld-Merksatz

> **Die 1 (Clock) führt, die 0 (CUT) schützt.**
> Dazwischen sind nur so viele Nachrichten, wie Kinderhände zählen können.

---