SF_eventdriven-rfid

Ereignisbasierte RFID-Anbindung für die DHBW-Smart-Factory mit Echtzeit-ERP-Integration über OpenZ.

Studienarbeit von Oliver Ilczuk (DHBW Stuttgart, Campus Horb, Studiengang Angewandte Informatik TINF23, Semester 5).

---

1. Systemarchitektur

Das Gesamtsystem basiert auf einer ereignisgesteuerten Microservice-Architektur. Die Kommunikation erfolgt lose gekoppelt über einen zentralen MQTT-Broker. Der Master-Raspberry-Pi (sf-pi-01, 192.168.35.20) hostet die fünf zentralen Software-Dienste und den Mosquitto-Broker. Zwei weitere physische Komponenten (Roboter und Tür-Aktor) sind direkt über das MQTT-Netzwerk angebunden.

Architektur-Übersicht

                       ┌──────────────────────────────────┐
                       │ Mosquitto Broker (Pi, Port 1883)  │
                       └──────────────────────────────────┘
                             ▲      ▲      ▲      ▲      ▲
                             │      │      │      │      │
       ┌─────────────────────┘      │      │      │      └─────────────────────┐
       │                            │      │      │                            │
 ┌───────────────┐          ┌───────────────┐ ┌───────────────┐        ┌───────────────┐
 │ rfid_gateway  │          │ control_agent │ │  tlv_gateway  │        │   erp_bridge  │
 │ (Python-Dienst)          │ (Python-Dienst) │ │  (Python-Dienst)          │ (Python-Dienst)
 └───────────────┘          └───────────────┘ └───────────────┘        └───────────────┘
         │                          │                 │                        ▲
         │                          │                 │                        │
 ┌───────────────┐                  │                 ▼                        │
 │ AL1340 IoT    │                  │          ┌───────────────┐       ┌───────────────┐
 │ (192.168.     │                  │          │ TruMark Laser │       │ soap_adapter  │
 │  35.80)       │                  │          │ (192.168.     │       │ (FastAPI :8000)│
 └───────────────┘                  │          │  35.60)       │       └───────────────┘
                                    │          └───────────────┘               │
                                    ▼                                          ▼
                          ┌───────────────────┐                         OpenZ SOAP via
                          │   Robot System    │                         Lab-Gateway:8080
                          │   (UR5e, TM12)    │
                          └───────────────────┘
                                    ▲
                                    │ MQTT
                                    ▼
                          ┌───────────────────┐
                          │ ESP32 Door        │
                          │ (192.168.35.48)   │
                          └───────────────────┘

Komponenten-Übersicht

Service / Modul	Typ / Ort	Aufgabe / Funktion	Schnittstellen / Protokolle
rfid_gateway	Python-Service (Pi)	Übersetzt zwischen ifm AL1340 IoT-Core API und MQTT	HTTP/JSON, MQTT (factory/rfid/reader_01/#)
control_agent	Python-Service (Pi)	Zentrale Orchestrierung (State Machine), Logik-Koordinator	MQTT, SQLite (control_agent_events.db)
tlv_gateway	Python-Service (Pi)	Steuert den TruMark-Laser über das TLV-Socket-Protokoll	TCP-Socket, MQTT (factory/laser/trumark/#)
erp_bridge	Python-Service (Pi)	Quittiert fertiggestellte Produktionsaufträge im ERP	SOAP (OpenZ), MQTT (factory/erp/production/event)
soap_adapter	Python-Service (Pi)	REST-Fassade zur Übersetzung von REST-API-Aufrufen zu SOAP	REST (FastAPI), SOAP, MQTT (factory/production/order/cmd)
trumark_door	C++ PlatformIO (ESP32)	Öffnet und schließt die Haube der Laserkammer	GPIOs, MQTT (factory/door/trumark/#)
ur5e	URP/Script (UR5e)	Steuert die physische Werkstückhandhabung des UR5e-Roboters	URScript, MQTT (factory/robot/ur5e/#)

---

2. Repository-Struktur

code/
├── control_agent/   # Zustandsmaschine und Produktions-Orchestrierung
├── deploy/          # Bereitstellungswerkzeuge für den Pi
│   ├── network/     # NAT-Bridges (Notfall-Entwicklungshilfe)
│   ├── systemd/     # Konfigurationsdateien für systemd-Dienste und .env-Vorlage
│   └── healthcheck.sh # Diagnose- und Validierungsskript für das Gesamtsystem
├── docs/            # Netzpläne, Protokollspezifikationen und Hardware-Notizen
├── erp_bridge/      # ERP-Rückmeldung nach Auftragsabschluss mit Idempotenz-Prüfung
├── rfid_gateway/    # Kommunikation mit dem ifm-RFID-Master über IoT-Core-API
├── rfid_test/       # Diagnose- und Live-Testskripte für RFID-Antennen
├── shared/          # Gemeinsam genutzte Module (MQTT-Basis-Client, Logger, Topics)
├── soap_adapter/    # REST-Schnittstelle zur Triggerung von ERP-Aufträgen
├── tests/           # Offline-Unit- und Integrationstests (Mocking aller Hardware)
├── tlv_gateway/     # Gateway-Service zur Steuerung des TruMark-Lasers (TLV-Protokoll)
├── trumark_door/    # ESP32-Quellcode für die Haubensteuerung der Laserkammer
└── ur5e/            # URScript-Vorlagen und Anleitungen für den UR5e-Roboter

---

3. Netz- und Hardware-Konfiguration (VLAN 88)

Alle physischen und virtuellen Geräte kommunizieren im dedizierten Labor-Netzwerk VLAN 88 (192.168.35.0/24).

Gerät / Host	IP-Adresse	Funktion im Lab
sf-pi-01	192.168.35.20	Master-Pi (Mosquitto-Broker und alle Backend-Dienste)
sf-ur5e	192.168.35.41	UR5e-Roboterarm (Choreografie-Empfänger)
sf-rfid-master-01	192.168.35.80	ifm AL1340 IoT-Core Schnittstelle (RFID-Antenne DT1513)
sf-laser	192.168.35.60	TruMark-Laser PC (TLV-Port 51201)
sf-door-laser	192.168.35.48	ESP32-Türcontroller (physisch verkabelt an Haubensteuerung)
sf-switch-01	192.168.35.10	Lokaler Netzwerk-Switch

Note

Ausführliche Details zur Netzarchitektur und den IP-Zuweisungen befinden sich in docs/network.md.

---

4. Setup und Inbetriebnahme

Voraussetzungen

1. Python 3.11+ installiert.
2. Mosquitto MQTT-Broker installiert und gestartet.
3. Virtuelle Python-Umgebung erstellen und Abhängigkeiten installieren:

cd code
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_all.txt

Konfiguration

Kopieren Sie die Vorlage für die Umgebungsvariablen und tragen Sie die entsprechenden Zugangsdaten ein:

cp deploy/systemd/.env.example .env

Die .env ist im Stammverzeichnis von code/ abzulegen. Wichtige Parameter:

• MQTT_BROKER_HOST: IP des Pi (192.168.35.20 oder lokal 127.0.0.1)
• AL1340_IOT_HOST: IP des RFID-Masters (192.168.35.80)
• OPENZ_URL: Endpunkt des OpenZ-ERP-Systems

---

5. Ausführen und Testen

Lokaler Entwicklungsbetrieb (Mac/PC)

Um alle fünf Backend-Services gleichzeitig im Vordergrund zu starten und auf Fehler zu überwachen:

./start_all.sh

Beenden mit Ctrl+C stoppt alle gestarteten Hintergrundprozesse sauber.

Produktion (Systemd auf dem Pi)

Die Backend-Services sind auf dem Raspberry Pi als systemd-Units eingerichtet, was einen automatischen Start beim Booten sowie automatische Neustarts bei Fehlern gewährleistet:

# Dienste auf dem Pi steuern
sudo systemctl start sf-rfid-gateway sf-control-agent sf-soap-adapter sf-erp-bridge sf-laser-gateway

# Status prüfen
sudo systemctl status sf-rfid-gateway sf-control-agent sf-soap-adapter sf-erp-bridge sf-laser-gateway

Offline-Tests (CI)

Die komplette Programmlogik kann ohne physisch verbundene Hardware über Mocks getestet werden:

PYTHONPATH=. pytest tests/ -q

System-Diagnose (Live-Check)

Zur Überprüfung des gesamten Pi-Stacks, der IP-Routing-Pfade und des MQTT-Datenflusses vom Mac aus:

./deploy/healthcheck.sh

---

6. Weiterführende Dokumentation

Die einzelnen Teilsysteme sind in detaillierten Spezifikationen dokumentiert:

• Einstieg & Systembetrieb: BENUTZERHANDBUCH.md – Umfassende Anleitung zur Installation, Migration, Fehlerbehebung und zum täglichen Betrieb.
• Entwickler-Briefing: AGENTS.md – Kurze Zusammenfassung für die Arbeit mit KI-Coding-Assistenten.
• MQTT-Topics & Schemata: docs/mqtt_topics.md – Kompakte Übersicht aller Kanäle sowie docs/mqtt-topics.md als Subscriber-Guide mit Payload-Beispielen.
• Roboter-Schnittstelle: docs/robot_protocol.md – Spezifikation der Choreografie-Ebene zwischen control_agent und UR5e.
• Netzwerkplan: docs/network.md – Detaillierte Zuweisung aller statischen IP-Adressen und VLAN 88 Migrationsschritte.