machine node User Stories

Machine Node — User Stories

Dieses Dokument beschreibt die Kernabläufe aus Nutzersicht. Der Machine Node zeigt den Boot-Prozess auf einem kleinen OLED-Display; im Betrieb erfolgt Feedback über LED-Signale und einen optionalen Buzzer.

Kontext: Was der Machine Node tut

Der Machine Node sitzt zwischen Netzstecker und Maschine. Er entscheidet, ob Strom fließt:

Karte gültig + berechtigt → Relais schließt → Maschine bekommt Strom
Karte ungültig / nicht berechtigt / Netzwerk weg → Relais bleibt offen / öffnet → Maschine bleibt aus

Es gibt zwei Betriebsmodi, konfiguriert per Firmware:

Modus	Verhalten
`auth_permanent`	Karte muss dauerhaft anliegen. Karte weg → Maschine aus. Serververbindung wird kontinuierlich geprüft.
`auth_onetime`	Einmaliges Einlesen reicht. Maschine bleibt an bis zur nächsten Interaktion (z. B. Tür).

Feedback-Kanäle

Der Node hat zwei Feedback-Kanäle:

Kanal	Wann aktiv	Zweck
OLED-Display	Boot-Prozess	Zeigt Initialisierungsschritte; nach erfolgreichem Boot: Bereit-Screen
LED + Buzzer	Normalbetrieb	Signalisiert Zustandswechsel ohne Display

Feedback-Signale (LED / Buzzer)

Genaue Belegung wird mit der Hardware-Entwicklung festgelegt. Platzhalter:

Zustand	LED	Buzzer
Bereit (warte auf Karte)	Blau blinkt	—
Karte wird geprüft...	Gelb	—
Freigegeben	Grün	kurzer Ton
Abgelehnt (keine Berechtigung)	Rot blinkt	2× kurz
Netzwerk/API nicht erreichbar	Rot dauerhaft	—

Gesamtübersicht

stateDiagram-v2
    direction TB

    [*] --> Boot

    state "⚙️ Boot" as Boot
    state "📶 WLAN verbinden..." as WiFi
    state "🔗 API erreichbar?" as API
    state "🟡 Bereit" as Bereit
    state "🟡🟢 Prüfen..." as Pruefen
    state "🟢 Freigegeben" as Freigegeben
    state "🔴 Reset" as Reset

    Boot --> WiFi : HW OK
    WiFi --> API  : verbunden
    API  --> Bereit : erreichbar

    Bereit --> Pruefen : Karte vorhalten (onetime) / Karte einstecken (permanent)

    Pruefen --> Freigegeben : berechtigt
    Pruefen --> Reset       : nicht berechtigt

    Freigegeben --> Freigegeben : Heartbeat fehlgeschlagen · WLAN weg
    Freigegeben --> Reset       : Stop-Knopf (onetime) · Karte weg nach 5 s (permanent)

    Reset --> Bereit : nach 2 s

    note right of Freigegeben
        auth_onetime: Karte kann entfernt werden
        auth_permanent: Karte muss anliegen bleiben
    end note

US-00: Node-Start / Boot-Sequenz

Als Werkstattnutzer möchte ich sehen, dass der Node hochfährt und betriebsbereit ist, bevor ich eine Karte vorhalt — damit ich weiß, ob das Gerät funktioniert oder noch initialisiert.

stateDiagram-v2
    direction LR

    [*] --> HW_Init

    state "⚙️ Hardware Init" as HW_Init
    state "📶 WLAN verbinden..." as WiFi
    state "🔗 API erreichbar?" as API
    state "🔵 Bereit" as Bereit
    state "🔴 Boot-Fehler" as Fehler

    HW_Init --> WiFi    : OLED, RFID, Relais OK
    HW_Init --> Fehler  : Hardware-Fehler

    WiFi --> API    : Verbunden
    WiFi --> Fehler : Timeout / SSID nicht gefunden

    API --> Bereit  : Erreichbar
    API --> Fehler  : Timeout / HTTP-Fehler

OLED-Anzeige während Boot

Schritt	Angezeigter Text (Beispiel)
Hardware Init	`Initialisierung...`
WLAN verbinden	`WLAN: Verbinde...` → `WLAN: OK`
API prüfen	`API: Prüfe...` → `API: OK`
Bereit	Maschinenname + `Bereit`
Fehler	Fehlermeldung (z. B. `WLAN: Timeout`)

Akzeptanzkriterien

Jeder Boot-Schritt erscheint auf dem OLED bevor der nächste startet
Nach erfolgreichem Boot zeigt das OLED den Maschinenname und den Bereit-Zustand
Bei Boot-Fehler bleibt die Fehlermeldung auf dem OLED stehen — kein stiller Absturz
Das Relais bleibt während des gesamten Boot-Prozesses geöffnet (Maschine aus)
Boot-Dauer (Ziel): < 10 s bis Bereit-Zustand unter Normalbedingungen

US-01a: Maschine freischalten — Karte einstecken (`auth_onetime`)

Als Werkstattnutzer möchte ich meine RFID-Karte einstecken, die Maschine freischalten und meinen Namen auf dem Display sehen.

Modus: auth_onetime (RFIDCARD_AUTH_CONST = false) — kein kontinuierlicher Karten-Check während RUNNING.

stateDiagram-v2
    direction LR

    [*] --> Bereit

    state "🟡 Bereit" as Bereit
    state "🟡🟢 Prüfen..." as Pruefen
    state "🟢 Freigegeben" as Freigegeben

    Bereit      --> Pruefen     : Karte vorhalten
    Pruefen     --> Freigegeben : berechtigt
    Freigegeben --> Freigegeben : Karte kann entfernt werden

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`
Prüfen... (`IDENTIFICATION`)	Gelb + Grün	AUS	`Prüfe...`
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers

Akzeptanzkriterien

Karte erkannt → wechselt in < 1 s zu Prüfen
Nach erfolgreicher API-Antwort → Relay schließt, OLED zeigt Nutzername
OLED zeigt während RUNNING den Nutzernamen aus der API-Antwort (nicht nur UID)

US-01b: Maschine beenden — Karte ziehen (`auth_onetime`)

Als Werkstattnutzer möchte ich die Maschine durch Drücken des Stop-Knopfs beenden — der Node zeigt kurz einen Reset-Zustand und kehrt dann automatisch in den Bereit-Zustand zurück.

Modus: auth_onetime — setzt US-01a (Freigegeben) voraus.

stateDiagram-v2
    direction LR

    [*] --> Freigegeben

    state "🟢 Freigegeben" as Freigegeben
    state "🔴 Reset" as Reset
    state "🟡 Bereit" as Bereit

    Freigegeben --> Reset  : Stop-Knopf gedrückt
    Reset       --> Bereit : nach 2 s

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers
Reset (`RESET`)	Rot	AUS	—
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`

Akzeptanzkriterien

Stop-Knopf gedrückt → Relay öffnet sofort, rote LED für 2 s (RESET_DISPLAY_MS)
Nach 2 s → automatisch zurück zu Bereit

US-01c: Karte vorhalten — keine Berechtigung (`auth_onetime`)

Als Werkstattnutzer möchte ich eine klare Rückmeldung erhalten, wenn meine Karte nicht berechtigt ist — der Node zeigt kurz den Reset-Zustand und kehrt dann zurück zu Bereit.

Modus: auth_onetime.

stateDiagram-v2
    direction LR

    [*] --> Bereit

    state "🟡 Bereit" as Bereit
    state "🟡🟢 Prüfen..." as Pruefen
    state "🔴 Reset" as Reset

    Bereit  --> Pruefen : Karte vorhalten
    Pruefen --> Reset   : nicht berechtigt
    Reset   --> Bereit  : nach 2 s

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`
Prüfen... (`IDENTIFICATION`)	Gelb + Grün	AUS	`Prüfe...`
Reset (`RESET`)	Rot	AUS	—

Akzeptanzkriterien

Nicht berechtigte Karte → sofort in Reset, Relay bleibt offen
Rote LED für 2 s, dann zurück zu Bereit
Kein Unterschied im Ablauf zwischen unbekannter Karte und bekannter aber nicht freigeschalteter Karte

US-02a: Maschine freischalten — Karte einstecken (`auth_permanent`)

Als Werkstattnutzer möchte ich meine RFID-Karte einstecken, die Maschine freischalten und meinen Namen auf dem Display sehen — die Karte muss dabei anliegen bleiben.

Modus: auth_permanent (RFIDCARD_AUTH_CONST = true) — Karte muss dauerhaft anliegen.

stateDiagram-v2
    direction LR

    [*] --> Bereit

    state "🟡 Bereit" as Bereit
    state "🟡🟢 Prüfen..." as Pruefen
    state "🟢 Freigegeben" as Freigegeben

    Bereit      --> Pruefen     : Karte einstecken
    Pruefen     --> Freigegeben : berechtigt
    Freigegeben --> Freigegeben : Karte muss anliegen bleiben

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`
Prüfen... (`IDENTIFICATION`)	Gelb + Grün	AUS	`Prüfe...`
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers

Akzeptanzkriterien

Karte vorhalten → wechselt in < 1 s zu Prüfen
Nach erfolgreicher API-Antwort → Relay schließt, OLED zeigt Nutzername
OLED zeigt während RUNNING den Nutzernamen aus der API-Antwort (nicht nur UID)

US-02b: Maschine beenden — Karte ziehen (`auth_permanent`)

Als Werkstattnutzer möchte ich die Maschine durch Ziehen der Karte beenden — der Node erkennt die abwesende Karte nach kurzer Toleranzzeit und schaltet die Maschine ab.

Modus: auth_permanent — setzt US-02a (Freigegeben) voraus.

stateDiagram-v2
    direction LR

    [*] --> Freigegeben

    state "🟢 Freigegeben" as Freigegeben
    state "🔴 Reset" as Reset
    state "🟡 Bereit" as Bereit

    Freigegeben --> Reset  : Karte weg (5 s Toleranz)
    Reset       --> Bereit : nach 2 s

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers
Reset (`RESET`)	Rot	AUS	—
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`

Akzeptanzkriterien

Karte entfernt → Node erkennt Abwesenheit nach max. 5 s (10 × 500 ms, CARD_ABSENT_RESET × CARD_POLL_MS)
Relay öffnet sobald Toleranz überschritten, rote LED für 2 s (RESET_DISPLAY_MS)
Nach 2 s → automatisch zurück zu Bereit

US-02c: Karte einstecken — keine Berechtigung (`auth_permanent`)

Als Werkstattnutzer möchte ich eine klare Rückmeldung erhalten, wenn meine Karte nicht berechtigt ist — der Node zeigt kurz den Reset-Zustand und kehrt dann zurück zu Bereit.

Modus: auth_permanent.

stateDiagram-v2
    direction LR

    [*] --> Bereit

    state "🟡 Bereit" as Bereit
    state "🟡🟢 Prüfen..." as Pruefen
    state "🔴 Reset" as Reset

    Bereit  --> Pruefen : Karte einstecken
    Pruefen --> Reset   : nicht berechtigt
    Reset   --> Bereit  : nach 2 s

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Bereit (`STANDBY`)	Gelb	AUS	Maschinenname + `Bereit`
Prüfen... (`IDENTIFICATION`)	Gelb + Grün	AUS	`Prüfe...`
Reset (`RESET`)	Rot	AUS	—

Akzeptanzkriterien

Nicht berechtigte Karte → sofort in Reset, Relay bleibt offen
Rote LED für 2 s, dann zurück zu Bereit

US-02d: Heartbeat schlägt fehl — Maschine bleibt an (`auth_permanent`)

Als Werkstattnutzer möchte ich, dass ein kurzzeitiger Netzwerkausfall die laufende Maschine nicht unterbricht — der Node ignoriert fehlgeschlagene Heartbeats absichtlich.

Modus: auth_permanent — setzt US-02a (Freigegeben) voraus.

stateDiagram-v2
    direction LR

    [*] --> Freigegeben

    state "🟢 Freigegeben" as Freigegeben

    Freigegeben --> Freigegeben : Heartbeat fehlgeschlagen (Maschine bleibt an)

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers

Akzeptanzkriterien

Fehlgeschlagener Heartbeat ändert weder LED noch Relay noch OLED
Maschine läuft weiter; Karten-Check bleibt aktiv
Erst wenn die Karte entfernt wird (US-02b) oder der Stop-Knopf gedrückt wird, endet die Session

US-02e: WLAN fällt aus — Maschine bleibt an (`auth_permanent`)

Als Werkstattnutzer möchte ich, dass ein WLAN-Ausfall die laufende Maschine nicht unterbricht — der Node verliert zwar die Serververbindung, der lokale Karten-Check läuft aber weiter.

Modus: auth_permanent — setzt US-02a (Freigegeben) voraus.

stateDiagram-v2
    direction LR

    [*] --> Freigegeben

    state "🟢 Freigegeben" as Freigegeben

    Freigegeben --> Freigegeben : WLAN weg (Maschine bleibt an)

Zustände & Feedback

Zustand (Firmware)	LED	Relais	OLED
Freigegeben (`RUNNING`)	Grün	EIN	Name des Nutzers

Akzeptanzkriterien

WLAN-Verlust ändert weder LED noch Relay noch OLED
Heartbeat wird übersprungen (tryLoginID gibt -1 zurück, Ergebnis wird ignoriert)
Karten-Check läuft weiter — er ist rein lokal (PN532 via SPI, kein Netzwerk nötig)
Node versucht WLAN im Hintergrund wiederherzustellen (non-blocking reconnect)
Erst wenn die Karte entfernt wird (US-02b), endet die Session

Offene Fragen

Frage	Status
Wie genau sind LED-Farben / Buzzer-Töne belegt?	Offen
Was passiert bei `auth_permanent` wenn die API kurz wegfällt (Jitter)? Sofort abschalten oder Toleranzfenster?	Offen
Gibt es eine manuelle Override-Funktion (z. B. für Wartung)?	Offen
Wie wird dem Nutzer kommuniziert, dass er nicht eingewiesen ist vs. Karte unbekannt?	Offen

Uh oh!

machine node User Stories

Machine Node — User Stories

Kontext: Was der Machine Node tut

Feedback-Kanäle

Feedback-Signale (LED / Buzzer)

Gesamtübersicht

US-00: Node-Start / Boot-Sequenz

OLED-Anzeige während Boot

Akzeptanzkriterien

US-01a: Maschine freischalten — Karte einstecken (auth_onetime)

Zustände & Feedback

Akzeptanzkriterien

US-01b: Maschine beenden — Karte ziehen (auth_onetime)

Zustände & Feedback

Akzeptanzkriterien

US-01c: Karte vorhalten — keine Berechtigung (auth_onetime)

Zustände & Feedback

Akzeptanzkriterien

US-02a: Maschine freischalten — Karte einstecken (auth_permanent)

Zustände & Feedback

Akzeptanzkriterien

US-02b: Maschine beenden — Karte ziehen (auth_permanent)

Zustände & Feedback

Akzeptanzkriterien

US-02c: Karte einstecken — keine Berechtigung (auth_permanent)

Zustände & Feedback

Akzeptanzkriterien

US-02d: Heartbeat schlägt fehl — Maschine bleibt an (auth_permanent)

Zustände & Feedback

Akzeptanzkriterien

US-02e: WLAN fällt aus — Maschine bleibt an (auth_permanent)

Zustände & Feedback

Akzeptanzkriterien

Offene Fragen

Weiterführende Links

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

US-01a: Maschine freischalten — Karte einstecken (`auth_onetime`)

US-01b: Maschine beenden — Karte ziehen (`auth_onetime`)

US-01c: Karte vorhalten — keine Berechtigung (`auth_onetime`)

US-02a: Maschine freischalten — Karte einstecken (`auth_permanent`)

US-02b: Maschine beenden — Karte ziehen (`auth_permanent`)

US-02c: Karte einstecken — keine Berechtigung (`auth_permanent`)

US-02d: Heartbeat schlägt fehl — Maschine bleibt an (`auth_permanent`)

US-02e: WLAN fällt aus — Maschine bleibt an (`auth_permanent`)