Update documentation for RFID/NFC writing process: enhance architecture overview, clarify asynchronous model, and refine step-by-step instructions.
This commit is contained in:
1 parent
6d58c3cdfe
commit
fa338c6947
1 file changed
+143
-42
+143
-42
@@ -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.
|
||||
Reference in new issue
Block a user