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

type, projekt, stand, tags

type	projekt	stand	tags
konzept-modul	3d.lehrstun.de	2026-05-23	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

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 (Python, aktiv gepflegt). Alternativ Code aus pybambu (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

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