Update documentation for RFID/NFC writing process: enhance architecture overview, clarify asynchronous model, and refine step-by-step instructions.

This commit is contained in:
Manuel Weiser committed 2026-02-19 20:04:15 +01:00
1 parent 6d58c3cdfe
commit fa338c6947
1 file changed
+143 -42
+143 -42
View File
@@ -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://<DEVICE_IP>/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 <TOKEN>`
- **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 <TOKEN>`
**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://<DEVICE_IP>/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://<BACKEND_IP>/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 <TOKEN>`
- 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.