Initial commit: Konzept v2 + Etappe 1 (Blueprints + Login + Profile)
Schwester-Projekt zu arduino.lehrstun.de fuer die 3D-Druck-AG am Lessing-Gymnasium. Offene jahrelange Nachmittags-AG (kein Trimester), 8-10 Einzel-SuS mit optionalen 2er-Paarungen, 4 Bambu-Lab-Drucker (3 geschlossen + 1 A1 mini). Konzept v2 (Reality-Check-Iteration 2026-05-24): - Onboarding-Pfad statt Pflicht-Lektionen (L1-L3 selbst-zertifiziert) - Selbstlern-Loop als Kern: SuS-Projekte wachsen die interne Bibliothek - Drill-Down-Lehrer-Dashboard (Wer ist hier / Wartet Review / Haengt fest) - Cockpit progressiv: zeigt nur was zum Status passt - Bambu-Cloud-API fuer Drucker-Live-Status (fragil + Fallback manuell) - Three.js-Vorschau fuer Cover-aus-3D-Ansicht (Etappe 6) - Vollstaendige Doku als Obsidian-Vault (24 Markdown-Dateien) - Entscheidungen E-001 bis E-022 in docs/decisions.md Etappe 1 lauffaehig (~1800 Zeilen Code): - Blueprint-Struktur (V8): routes/oeffentlich+profil+admin+api, services/auth+bambu+datei - Komplettes Schema in database.py (14 Tabellen, idempotent) - Login mit bcrypt + persistentem Lockout in DB (V7, verbessert ggue Arduino-Kurs der In-Memory-Dict nutzt) - Admin-Login + Profile-CRUD + PIN-Reset + PIN-Karten-Druckbogen - Inline-Edit-Endpunkt mit Whitelist + Audit-Log - Seeds: AG lessing-3d-ag + 4 Drucker + Default-Einstellungen - Smoke-Test bestanden (Login, Profil-Anlage, Lockout-Logging) Nicht im Repo (.gitignore): .env, *.db, venv/, .obsidian/workspace.json
This commit is contained in:
96
docs/druckerapi.md
Normal file
96
docs/druckerapi.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
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]]
|
||||
Reference in New Issue
Block a user