¶ GitLab-Projekt
The current status is accessible under following address:
https://artemis.mt.haw-hamburg.de/Lucca.Kuvecke/md2-hub
¶ Team
| Name | Matr. | Role |
| Conrad Bader | ****751 | |
| Paul Bleyer | ****032 | |
| Malte Bungard | ****988 | |
| Lucca Kuvecke | ****706 |
¶ Materials
| Materials | Usage | Cost (€) |
|
Raspberry 5 mit 8 GB RAM, SD Karte und Netzteil. |
Zentraler Hub mit Websiten Host und API Backend | 99,10 |
|
1x ZigBee USB Dongle Sonoff ZBDongle-E, ZigBee 3.0 Gateway (Chip EFR32MG21) Oder Alternativen, aber dann bitte mit Chip: CC2652P oder EFR32MG21 |
Adapter damit ZigBee als funktechnologie benutzt werden kann. | 20,80 |
|
1x Bluetooth Dongle Alternativ: ASUS BT540 (wichtig, das Linux unterstützt wird, gut bei z.b. Realtek RTL8761B, RTL8761BU und Broadcom und ansonsten Mindestens 5.0. Besser 5.2/5.3/5.4 für EATT) |
Adapter, damit der interne Bluetooth Chip entlastet wird. | 17,23 |
| 1x FRITZ!Box (oder alternativer wifi Access Point mit mindestens einem LAN Port für Pi) | Wifi Access Point damit der interne Wifi Chip entlastet wird. | 40 |
| 1x LAN Kabel | Kabel um den Pi direkt mit der FRITZ!Box zu verbinde. | 5 |
| Total | 182,13 |
¶ Budget
| Budget Category | Specification | Estimated Cost (€) |
| Student Development | ||
| Consultant Fees | ||
| Total Estimate |
¶ First Software Protoype
Unfertig - Ideenwerkstatt..
Atribute:
is analog 1/0
Lösungsdatentypen: string, number, Farbe (hexadezimale als string), Musik Noten (Buchstaben A-G als string, mit noch mehr..(malte!) ), Bild, Emojis
Ideen:
Dummy Blöcke für Analoge Rätsel, die nicht das Tablet nutzen (alle, wirklich alle rätsle sollen abgebildet werden) (could)
custom live hint (ein hint der live vom operator eingegeben wird)
¶ Template für API für Gruppen v.0.2
Für eine leichte Integration haben wir Template skripte erstellt, die ihr in eurem Projekt nutzen könnt. Ohne die API selber zu implementieren.
¶ API Doku v.0.2
Das ist unsere interne API. Diese muss nicht von euch anderen Gruppen implementiert werden. Das meiste hier beschreibt die interne Kommunikation zwischen Backend und Frontend. Für eine leichte Integration haben wir weiter oben Template skripte erstellt, die ihr in eurem Projekt nutzen könnt.
¶ 1. Admin / Passwort
¶ 1.1 Admin-Login (für Frontend)
POST /admin/login
Prüft das eingegebene Admin-Passwort und gibt eine Session-/Token-Info für das Frontend zurück (oder nur „ok“).
Wird ausschließlich genutzt, um das Frontend zu sperren/freizuschalten.
¶ 1.2 Admin-Passwort ändern
POST /admin/password
Setzt ein neues Admin-Passwort.
Request enthält z. B. oldPassword und newPassword.
Fehlerfall: altes Passwort falsch.
¶ 2. Room-Templates und aktiver Raum (Editor-Modus)
¶ 2.1 Room-Templates
Templates sind gespeicherte Raum-Layouts für den Node-Editor (Puzzles, Logik-Blöcke, Verbindungen).
GET /room/templates
Liste aller vorhandenen Room-Templates (Name, ID, Beschreibung, zuletzt geändert).
GET /room/templates/{templateId}
Details eines Templates (Nodes, Verbindungen, Properties).
POST /room/templates
Neues Room-Template anlegen (z. B. aus aktuellem Editor-Stand oder einem leeren Raum).
Enthält Name, Beschreibung und komplette Graph-Struktur.
DELETE /room/templates/{templateId}
Löscht ein Room-Template.
¶ 2.2 Aktiver Raum – Konfiguration (Node-Editor)
Es gibt nur einen „aktiven Raum“. Dieser entspricht dem Raum, der später im Spielbetrieb verwendet wird.
POST /room
Erzeugt oder überschreibt den aktiven Raum.
Kann z. B. ein Template referenzieren (templateId) oder direkt einen Graph mitliefern.
GET /room
Liefert die komplette Konfiguration des aktiven Raums (Nodes, Verbindungen, Properties, Subräume).
PUT /room
Speichert Änderungen am aktiven Raum (z. B. nach Editieren im Node-Editor).
Hier können auch Autosaves mit Zeitstempel passieren.
POST /room/save-as-template
Speichert den aktuellen aktiven Raum als neues Room-Template (z. B. mit neuem Namen).
POST /room/validate
Prüft die Konfiguration des aktiven Raums:
Sind alle Puzzles korrekt konfiguriert?
Sind Logik-Blöcke vollständig verbunden?
Sind alle referenzierten Devices vorhanden?
Gibt eine Liste mit Fehlern/Warnungen zurück.
¶ 2.3 Nodes im aktiven Raum (Puzzles und Logik-Blöcke)
Nodes können Puzzles, Logik-Blöcke (AND/OR etc.) oder andere Elemente sein.
GET /room/nodes
Gibt alle Nodes im aktiven Raum zurück (inkl. Typ: puzzle, logic_and, logic_or, etc.).
POST /room/nodes
Fügt einen neuen Node zum aktiven Raum hinzu.
Request: Node-Typ, Position im Editor, initiale Properties.
GET /room/nodes/{nodeId}
Details eines Nodes im Raum (Konfiguration, Verbindungen, Typ, zugehöriger Subraum).
PATCH /room/nodes/{nodeId}
Konfiguriert einen Node:
Bei Puzzles: z. B. MQTT-Topic, Pins, Startwerte, statischer Hint.
Bei Logik-Blöcken: Eingänge, Ausgänge, Bedingungen.
DELETE /room/nodes/{nodeId}
Löscht einen Node aus dem aktiven Raum.
¶ 3. Subräume (Bereiche im Raum)
Ein Raum besteht aus einem oder mehreren Subräumen (Kapitel/Zonen), die getrennt steuerbar sind.
GET /room/subrooms
Liste aller Subräume des aktiven Raums (ID, Name, Reihenfolge).
PATCH /room/subrooms/{subroomId}
Ändert Properties eines Subraums (z. B. Name, Zeitlimit, Auto-Reset-Einstellungen).
¶ 4. Runtime / Spielbetrieb
¶ 4.1 Raum- und Subraum-Steuerung
GET /runtime/room/status
Status des aktiven Raums:
Welcher Subraum ist aktiv?
Globaler Timer / Raumzeit?
Übersicht über gelöste / offene Puzzles.
POST /runtime/room/start
Startet den Spielbetrieb für einen bestimmten Subraum oder den ersten Subraum.
Request kann z. B. subroomId enthalten.
POST /runtime/room/stop
Stoppt den Raumlauf (z. B. Spielende oder Abbruch).
POST /runtime/room/reset
Setzt alle Puzzle-Zustände im aktiven Raum zurück und vorbereitet eine neue Runde.
Optional kann subroomId angegeben werden, um nur einen Teilbereich zu resetten.
¶ 4.2 Puzzle-Status (lesen und setzen)
GET /runtime/puzzles/{puzzleId}/status
Liefert den aktuellen Status eines Puzzles:
Zustandswert (z. B. locked, unlocked, solved, error)
Ob das zugehörige Device als online gilt
Zeitstempel der letzten Statusänderung.
POST /runtime/puzzles/{puzzleId}/status
Setzt den Status eines Puzzles manuell (Gamemaster-Override), z. B. solved.
Kann optional eine Notiz enthalten (Grund für das manuelle Setzen).
POST /runtime/puzzles/{puzzleId}/reset
Startet das Puzzle neu (setzt den Anfangszustand).
Optional: Parameter, ob ein „hard reset“ (inkl. Hardware) ausgeführt werden soll.
¶ 4.3 Heartbeat der Puzzles
Heartbeat wird von den Puzzles (oder deren Controllern) aktiv an das Backend gesendet.
POST /runtime/puzzles/{puzzleId}/heartbeat
Wird von einem Puzzle regelmäßig aufgerufen.
Aktualisiert die „lastSeen“-Zeit und kann optional Statusinformationen mitliefern (Temperatur, Batterie, Fehlercodes).
Das Backend nutzt dies, um in anderen Endpoints online: true/false zu berechnen.
¶ 4.4 Lösungsschlüssel (Solution Key)
GET /runtime/puzzles/{puzzleId}/solution
„Call Lösungsschlüssel“ – gibt den für dieses Puzzle hinterlegten Lösungsschlüssel zurück, damit der Gamemaster ihn sehen kann.
Nur für das Frontend zugänglich, das bereits über das Admin-Passwort gesichert ist.
POST /runtime/puzzles/{puzzleId}/solution
„Say Lösungsschlüssel“ – setzt oder sendet einen Lösungsschlüssel für das Puzzle.
Beispiel: Backend publish’t den Key über MQTT an die Hardware oder speichert ihn für eine Überprüfung.
¶ 4.5 Hints
GET /runtime/puzzles/{puzzleId}/hint
Liefert den am Puzzle gespeicherten statischen Hint (aus der Node-Konfiguration).
Kann im Frontend angezeigt oder an ein Hinweis-Display geschickt werden.
GET /runtime/room/hub-hints
Gibt alle vom Hub (Gamemaster) gesetzten Hints für den aktuellen Raum/Subraum zurück.
POST /runtime/room/hub-hints
Setzt einen neuen Hub-Hint (z. B. Text, optional Bezug zu einem Puzzle).
Diese Hints werden im Hub eingetippt und können den Spielern angezeigt werden.
¶ 5. Devices
¶ 5.1 Zigbee-Devices
GET /devices/zigbee
Liste aller bekannten Zigbee-Devices: ID, Typ, Name, Online-Status, letzter Heartbeat, ggf. zugeordneter Node.
GET /devices/zigbee/{deviceId}
Details zu einem Zigbee-Device (z. B. Modell, Cluster, Signalstärke, letzte Events).
PATCH /devices/zigbee/{deviceId}
Ändert Metadaten des Devices, z. B. Anzeigename oder Zuordnung zu einem Raum/Node.
POST /devices/zigbee/{deviceId}/pair
Startet oder bestätigt einen Pairing-Vorgang für dieses Device (optional, wenn ihr Pairing über das Hub steuert).
POST /devices/zigbee/{deviceId}/unpair
Entfernt die Verbindung eines Zigbee-Devices aus dem Hub.
POST /devices/zigbee/{deviceId}/test
Löst eine einfache Testaktion aus (z. B. LED blinken), um das Device im Raum identifizieren zu können.
¶ 5.2 Bluetooth-Devices
GET /devices/bluetooth
Liste der bekannten Bluetooth-Devices (ID, Name, Typ, Online-Status).
GET /devices/bluetooth/{deviceId}
Details zu einem Bluetooth-Device.
POST /devices/bluetooth/{deviceId}/test
Führt eine Testaktion aus oder triggert eine Verbindung, um das Device zu überprüfen.
¶ 6. Update-System (Git)
Update-Funktion für das Hub-Projekt (Code + ggf. Assets).
GET /update/status
Gibt den aktuellen Stand an:
Laufende Version (Version, Commit)
Letzter erfolgreicher Update-Lauf
Ob aktuell ein Update läuft
Ob eine neuere Version verfügbar ist (falls schon geprüft).
POST /update/check
Prüft remote (Git) auf neue Änderungen und ermittelt Unterschiede (z. B. geänderte Dateien, neuer Commit).
Führt noch kein Update aus, nur Check.
POST /update/apply
Startet den Update-Prozess:
Repository fetchen
Tests/Healthchecks ausführen
Bei Erfolg: Deploy und ggf. Neustart der Services
Antwort enthält eine updateId, mit der der Fortschritt abgefragt werden kann.
GET /update/logs/{updateId}
Liefert Logs und Status eines bestimmten Update-Laufs (Schritte, Erfolg/Fehlschlag, Fehlermeldungen).
POST /update/dry-run
Führt einen „Dry-Run“ durch: Tests und Checks werden ausgeführt, aber kein Deploy.
Dient dazu, zu sehen, ob ein Update prinzipiell durchlaufen würde.
POST /update/rollback
Rollback auf die letzte stabile Version, falls ein Update schiefging oder Probleme verursacht.
Antwort enthält Infos zur Version, auf die zurückgerollt wurde.
¶ 7. Optionale Puzzle-Logs
Diese Endpoints sind optional, aber praktisch für Debugging und Analyse.
GET /runtime/puzzles/{puzzleId}/logs
Liefert eine Liste von Logeinträgen zu diesem Puzzle, z. B.:
Statusänderungen
Resets
Heartbeat-Aussetzer
Fehlercodes
GET /runtime/room/logs
(Optional) Aggregierte Logs für den gesamten Raumlauf: Start/Stop, Subraum-Wechsel, globale Fehler.