6.0 KiB
Dokumentation: RFID/NFC Schreibvorgang (Technischer Guide für KI)
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. Architektur-Übersicht (Asynchrones Modell)
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: 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)
Das Frontend sendet eine Anfrage an das Backend.
- Endpunkt:
POST /api/v1/devices/{device_id}/write-tag - Payload:
{ "spool_id": 123 // ODER "location_id": 45 }
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 - 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:
{ "success": true, "message": "Schreibvorgang wurde gestartet. Bitte Tag bereit halten..." }
Schritt 3: Physische Verarbeitung (Device)
Das Device:
- Empfängt den Trigger.
- Startet den RFID-Schreibvorgang.
- 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:
{ "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 vonspools.rfid_uid. - Bei
location_id: Update vonlocations.identifier.
Schritt 6: Frontend-Polling
Das Frontend pollt periodisch (alle 2 Sekunden) durch erneutes Laden der Spulen/Locations-Liste:
- Sobald die
rfid_uidoderidentifiergesetzt ist → Erfolgsmeldung. - Nach max. 30 Versuchen (60 Sekunden) → Timeout-Meldung.
3. API-Referenz
3.1 Trigger Endpoint (Frontend → Backend)
POST /api/v1/devices/{device_id}/write-tag
Startet den Schreibvorgang auf dem Device. Antwortet sofort (Fire & Forget).
Request:
{
"spool_id": 123, // Optional
"location_id": 45 // Optional (eins von beiden muss gesetzt sein)
}
Response (sofort):
{
"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:
{
"success": true,
"tag_uuid": "E2801234...",
"spool_id": 123, // Optional
"location_id": 45, // Optional
"error_message": null // Optional: Fehlermeldung falls success=false
}
Response:
{
"status": "ok",
"message": "Spool updated" // oder "Location updated"
}
4. Anforderungen an das Device
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:
// 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
- Fire & Forget: Der Trigger-Request vom Backend zum Device ist asynchron. Das Backend antwortet sofort.
- Push-Modell: Das Device ist für das Senden des Ergebnisses verantwortlich (nicht das Warten auf eine Antwort).
- Polling: Das Frontend erkennt den Erfolg durch das Pollen/Neuladen der Daten (prüfen auf gesetzte
rfid_uidoderidentifier). - Keine offene Verbindung: Es gibt keine 180-Sekunden-Wartezeit mehr auf eine offene HTTP-Verbindung.