3d.lehrstun.de/docs/druckerapi.md

---
type: konzept-modul
projekt: 3d.lehrstun.de
stand: 2026-05-23
tags: [konzept, druckerapi, bambu]
---

# Drucker-API-Anbindung (Bambu Cloud)

> Architektur-Einbettung: [[architektur#3-Fehlerfälle]].
> Entscheidung dazu: [[../decisions#E-005]] und [[../decisions#E-006]].

## Ziel

Live-Status aller 4 Bambu-Lab-Drucker auf der Site anzeigen, mit Fallback auf manuellen Status bei API-Ausfall.

## Variante (gewählt): Cloud-API-Polling vom Hetzner

```mermaid
flowchart LR
    PW[Poll-Worker<br/>auf Hetzner] -->|GET alle 30s| BAMBU[api.bambulab.com]
    BAMBU --> PW
    PW --> DB[(drucker_status)]
    FE[Frontend] -.alle 30s.-> API[/api/drucker/status/]
    API --> DB
```

- **Auth:** Bambu-Cloud-Konto-Credentials in `.env` (`BAMBU_EMAIL`, `BAMBU_PASSWORT`, `BAMBU_REGION=eu`).
- **Lib:** [`bambulabs_api`](https://github.com/BambuTools/bambulabs_api) (Python, aktiv gepflegt). Alternativ Code aus [`pybambu`](https://github.com/greghesp/ha-bambulab) (Home-Assistant-Integration) extrahieren.
- **Frequenz:** ~30 s pro Drucker. Bei 4 Druckern unkritisch.
- **Polling-Worker:** entweder als Hintergrund-Thread in Flask oder eigener systemd-Service (saubere Trennung, wird in [[etappen#etappe-5]] entschieden).

## Welche Felder lesen wir?

| Feld | Beispiel | Pflicht? |
|---|---|---|
| `status` | `printing`, `idle`, `paused`, `finished`, `failed`, `offline` | ja |
| `job_name` | "schluesselanhaenger_mia.3mf" | ja |
| `progress_pct` | 67.5 | ja |
| `restzeit_min` | 42 | ja |
| `bett_temp` | 58.2 | nein |
| `duese_temp` | 210.0 | nein |
| `fehlermeldung` | "AMS error: filament jam" | nein |

Die Bonus-Felder werden im UI nur angezeigt, wenn vorhanden.

## Fallback-Strategie

```mermaid
flowchart TB
    A[Poll-Versuch] --> B{Erfolg?}
    B -- ja --> C[drucker_status aktualisiert]
    B -- nein --> D[Lasse alten Wert stehen]
    D --> E{gepollt_am > 5 Min alt?}
    E -- ja --> F[UI: 'Status veraltet']
    F --> G[Admin: Button 'Manueller Status']
    E -- nein --> H[Noch ignorierbar]
```

- **Admin-Override**: `/admin/drucker/<id>/manueller_status` — Herb/Markus setzen manuell, überschreibt nächsten Poll.
- **Notbetrieb ohne API**: Wenn die Cloud dauerhaft nicht erreichbar ist, kann der Slot-Betrieb komplett manuell laufen — SuS sehen Status nur über Bambu Handy App, Reservierungen funktionieren weiter, weil sie nicht von API abhängen.

## Was wir **nicht** machen

- **Keine Druckjob-Übertragung von der Site zum Drucker.** Würde "Developer Mode" am Drucker brauchen → Verlust der Bambu-Cloud-Funktionen. Siehe [[../decisions#E-006]].
- **Keine Kamera-Streams** auf der Site. SuS nutzen die Bambu Handy App fürs Bild. DSGVO-Frage in der Schule wäre sonst aufwendig.

## Spike vor Integration

Bevor wir das in die Site einbauen, baue ich ein eigenständiges Script:

```
scripts/drucker_api_spike.py
```

- Liest Credentials aus `.env`.
- Fragt einmalig alle 4 Drucker ab.
- Gibt JSON auf STDOUT.
- Validiert: funktioniert die Auth? Werden alle 4 Drucker gefunden? Welche Felder liefert die API?

Wenn der Spike läuft, übernehmen wir die Logik in einen sauberen Poll-Worker (Etappe 5).

## Risiken (Stand 2026-05)

- **Bambu hat 2024/25 die API mehrfach geändert** ("Authorization Control"-Update). Status-Lesen funktioniert weiterhin, aber kann jederzeit brechen.
- **Inoffizielle API**: Bambu supportet keine Drittsoftware. Bei Bruch helfen nur die GitHub-Communities (`bambulabs_api`, `pybambu`).
- **Cloud-Login-Flow** ändert sich gelegentlich (2FA, Captcha). Wenn das passiert, Spike-Script anpassen.

→ Deshalb ist [[slotsystem]] so gebaut, dass es **ohne** Drucker-API funktioniert. Status-Anzeige ist Komfort, nicht Pflicht.

## Querverweise

- DB-Schema: [[datenmodell#drucker]]
- Route: `/api/drucker/status` siehe [[routen]]
- Architektur: [[architektur]]
- Entscheidungen: [[../decisions#E-005]], [[../decisions#E-006]]