From fa338c69472c9fb05585f9860595eec1ad94e336 Mon Sep 17 00:00:00 2001 From: Manuel Weiser Date: Thu, 19 Feb 2026 20:04:15 +0100 Subject: [PATCH] Update documentation for RFID/NFC writing process: enhance architecture overview, clarify asynchronous model, and refine step-by-step instructions. --- WRITE-TAG.md | 185 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 143 insertions(+), 42 deletions(-) diff --git a/WRITE-TAG.md b/WRITE-TAG.md index 1b543f6..5cd70de 100644 --- a/WRITE-TAG.md +++ b/WRITE-TAG.md @@ -2,79 +2,180 @@ Diese Dokumentation beschreibt den Prozess des Schreibens von RFID/NFC-Tags im FilaMan-System. Sie dient als Referenz für KI-Systeme, um zu verstehen, wie Befehle delegiert, verarbeitet und zurückgemeldet werden. -## 1. Übersicht der Architektur +## 1. Architektur-Übersicht (Asynchrones Modell) -Der Schreibvorgang folgt einem **Delegations-Modell**. Das System (Server) agiert als Orchestrator zwischen der Benutzeroberfläche (Frontend) und der physischen Hardware (Device). +Der Schreibvorgang folgt einem **asynchronen Modell**, um robuster für IoT-Geräte mit unzuverlässigen Netzwerkverbindungen zu sein. + +``` +┌─────────┐ 1. Trigger ┌─────────┐ 2. Fire&Forget ┌─────────┐ +│ Frontend│ ────────────────→│ Backend │ ─────────────────→ │ Device │ +└─────────┘ └─────────┘ └─────────┘ + ↑ │ + │ 4. DB-Update │ + │ 5. Polling ←───────────────────────────────────────┘ + │ (Page Reload) 3. Result-Request + │ + 6. User Feedback +``` ### Beteiligte Komponenten: -* **Frontend (Astro/Web):** Initiiert den Schreibvorgang durch Benutzerinteraktion. -* **Backend (Python/FastAPI):** Validiert die Anfrage, findet das Zielgerät und delegiert den Befehl. -* **Device (Hardware/ESP32):** Führt den physischen Schreibvorgang aus und meldet die Tag-UID zurück. +* **Frontend:** Initiiert Schreibvorgang und pollt auf Ergebnis (via Page-Reload). +* **Backend:** Delegiert Befehl an Device und aktualisiert DB, wenn Device Result sendet. +* **Device:** Führt physischen Schreibvorgang aus und sendet eigenständig Ergebnis zurück. --- ## 2. Der Ablauf (Step-by-Step) -### Schritt 1: Initiierung (Frontend -> Backend) -Wenn ein Benutzer eine Spule oder einen Ort mit einem Tag verknüpfen möchte, sendet das Frontend eine Anfrage an das Backend. +### Schritt 1: Initiierung (Frontend → Backend) +Das Frontend sendet eine Anfrage an das Backend. - **Endpunkt:** `POST /api/v1/devices/{device_id}/write-tag` - **Payload:** ```json { - "spool_id": 123, // ODER + "spool_id": 123 // ODER "location_id": 45 } ``` -### Schritt 2: Delegation (Backend -> Device) -Das Backend prüft, ob das Gerät online ist (letzter Heartbeat < 180s) und sendet den Befehl an die lokale IP des Geräts. +### Schritt 2: Fire & Forget (Backend → Device) +Das Backend sendet einen Trigger an das Device: - **Endpunkt am Gerät:** `POST http:///api/v1/rfid/write` -- **Wartezeit (Timeout):** Das Backend wartet bis zu **180 Sekunden** auf eine Antwort vom Gerät. Dies gibt dem Benutzer genug Zeit, den Tag physisch an den Leser zu halten. - -### Schritt 3: Physische Verarbeitung (Device) -Das Gerät muss: -1. Den Befehl empfangen. -2. In einen "Schreib-Modus" wechseln (meist signalisiert durch LED/Display). -3. Auf die Annäherung eines beschreibbaren Tags warten. -4. Die eindeutige **`tag_uuid`** (UID) des Tags auslesen. - -### Schritt 4: Rückmeldung (Device -> Backend) -Nach erfolgreichem Scan/Schreibvorgang antwortet das Gerät dem Backend innerhalb der bestehenden HTTP-Verbindung. -- **Response vom Gerät:** +- **Timeout:** Das Backend wartet nur kurz (5 Sekunden) auf eine Bestätigung, dass der Trigger empfangen wurde. Es wartet NICHT auf das RFID-Ergebnis. +- **Response an Frontend:** Das Backend antwortet sofort mit: ```json { - "tag_uuid": "E28011052000700D2171010A" + "success": true, + "message": "Schreibvorgang wurde gestartet. Bitte Tag bereit halten..." } ``` -### Schritt 5: Abschluss (Backend -> DB & Frontend) -Das Backend empfängt die `tag_uuid` und führt die Datenbank-Update aus: +### Schritt 3: Physische Verarbeitung (Device) +Das Device: +1. Empfängt den Trigger. +2. Startet den RFID-Schreibvorgang. +3. Sendet **eigenständig** das Ergebnis an das Backend. + +### Schritt 4: Ergebnis an Backend (Device → Backend) +Das Device sendet das Ergebnis nach Abschluss des Schreibvorgangs: +- **Endpunkt:** `POST /api/v1/devices/rfid-result` +- **Authentifizierung:** `Authorization: Device ` +- **Payload:** + ```json + { + "success": true, + "tag_uuid": "E2801234...", + "spool_id": 123, // Optional: ID der Spule + "location_id": 45 // Optional: ID des Ortes + } + ``` + +### Schritt 5: Datenbank-Update (Backend) +Das Backend empfängt das Ergebnis: - Bei `spool_id`: Update von `spools.rfid_uid`. - Bei `location_id`: Update von `locations.identifier`. -Anschließend wird der Erfolg an das Frontend gemeldet, welches den Ladezustand beendet. + +### Schritt 6: Frontend-Polling +Das Frontend pollt periodisch (alle 2 Sekunden) durch erneutes Laden der Spulen/Locations-Liste: +- Sobald die `rfid_uid` oder `identifier` gesetzt ist → Erfolgsmeldung. +- Nach max. 30 Versuchen (60 Sekunden) → Timeout-Meldung. --- -## 3. Wichtige Anforderungen an das Device +## 3. API-Referenz -### HTTP Server -Das Gerät muss einen HTTP-Server auf Port 80 (Standard) betreiben, der auf Anfragen unter `/api/v1/rfid/write` reagiert. +### 3.1 Trigger Endpoint (Frontend → Backend) -### Heartbeat & IP-Tracking -Damit das Backend das Gerät erreichen kann, **muss** das Gerät regelmäßig seine IP-Adresse melden: -- **Endpunkt:** `POST /api/v1/devices/heartbeat` -- **Payload:** `{"ip_address": "192.168.x.y"}` -- **Frequenz:** Alle 60-120 Sekunden. +**`POST /api/v1/devices/{device_id}/write-tag`** -### Fehlerbehandlung -Falls das Gerät den Vorgang nicht abschließen kann (z.B. Timeout am Gerät selbst oder Hardwarefehler), sollte es einen entsprechenden HTTP-Statuscode zurückgeben: -- `408 Request Timeout`: Wenn kein Tag innerhalb der internen Zeit des Geräts gefunden wurde. -- `500 Internal Server Error`: Bei Hardwareproblemen. +Startet den Schreibvorgang auf dem Device. Antwortet sofort (Fire & Forget). + +**Request:** +```json +{ + "spool_id": 123, // Optional + "location_id": 45 // Optional (eins von beiden muss gesetzt sein) +} +``` + +**Response (sofort):** +```json +{ + "success": true, + "message": "Schreibvorgang wurde gestartet. Bitte Tag bereit halten..." +} +``` + +### 3.2 Result Endpoint (Device → Backend) + +**`POST /api/v1/devices/rfid-result`** + +Das Device ruft diesen Endpoint auf, nachdem der Schreibvorgang abgeschlossen ist. + +**Header:** +- `Authorization: Device ` + +**Request:** +```json +{ + "success": true, + "tag_uuid": "E2801234...", + "spool_id": 123, // Optional + "location_id": 45, // Optional + "error_message": null // Optional: Fehlermeldung falls success=false +} +``` + +**Response:** +```json +{ + "status": "ok", + "message": "Spool updated" // oder "Location updated" +} +``` --- -## 4. Zusammenfassung für die KI-Logik +## 4. Anforderungen an das Device -1. **Zustandsprüfung:** Das Gerät wird nur als "Online" markiert, wenn der Heartbeat aktuell ist. -2. **Synchronität:** Der HTTP-Call vom Server zum Gerät ist blockierend. Die KI muss diesen Zustand (Loading State) im UI beibehalten, bis die Antwort eintrifft oder der 180s-Timeout greift. -3. **Identifikation:** Das Ergebnis des Schreibvorgangs ist immer die physische UID des Tags (`tag_uuid`), welche als globaler Identifier im System für diese Ressource dient. +### 4.1 Endpoint für Trigger +Das Device muss folgenden Endpoint unterstützen: +- **URL:** `http:///api/v1/rfid/write` +- **Method:** POST +- **Content-Type:** application/json + +**Verhalten:** +- Empfängt den Trigger (spool_id oder location_id) +- Startet den RFID-Schreibvorgang +- Sendet NICHT sofort die tag_uuid zurück (Fire & Forget) + +### 4.2 Eigenständiges Senden des Ergebnisses +Nach dem Schreibvorgang muss das Device eigenständig das Ergebnis an das Backend senden: + +```cpp +// Pseudocode für ESP32 +void sendResultToBackend(String tagUuid, int locationId) { + HTTPClient http; + http.begin("http:///api/v1/devices/rfid-result"); + http.addHeader("Content-Type", "application/json"); + http.addHeader("Authorization", "Device " + deviceToken); + + String json = "{\"success\": true, \"tag_uuid\": \"" + tagUuid + "\", \"location_id\": " + locationId + "}"; + http.POST(json); + http.end(); +} +``` + +### 4.3 Authentifizierung +Das Device muss sich mit dem Token authentifizieren: +- Header: `Authorization: Device ` +- Der Token ist der gleiche, der auch für Heartbeat verwendet wird. + +--- + +## 5. Zusammenfassung für die KI-Logik + +1. **Fire & Forget:** Der Trigger-Request vom Backend zum Device ist asynchron. Das Backend antwortet sofort. +2. **Push-Modell:** Das Device ist für das Senden des Ergebnisses verantwortlich (nicht das Warten auf eine Antwort). +3. **Polling:** Das Frontend erkennt den Erfolg durch das Pollen/Neuladen der Daten (prüfen auf gesetzte `rfid_uid` oder `identifier`). +4. **Keine offene Verbindung:** Es gibt keine 180-Sekunden-Wartezeit mehr auf eine offene HTTP-Verbindung.