- Updated Oliver Ilczuk's course from TINF2023 to TINF23 in README.md, AGENTS.md, and BENUTZERHANDBUCH.md - Updated course in Claude prompt templates for trumark_door and E2E testing
9.3 KiB
9.3 KiB
AGENTS.md — Kontext für KI-Assistenten
Diese Datei ist die Einstiegs-Briefing-Datei für KI-Coding-Agenten (Claude Code, Cursor, Codex, Copilot etc.), die im Smart-Factory-Repo arbeiten. Sie zielt auf knappe, dichte Information für LLM-Konsum.
Menschliche Leser → BENUTZERHANDBUCH.md.
Was ist das hier
Studienarbeit Oliver Ilczuk (DHBW Horb, TINF23, Sem. 5). Ereignisbasierte RFID-Anbindung des DHBW-Smart-Factory-Lab-Testbeds an das OpenZ-ERP. Microservices in Python, MQTT als Message-Bus, RFID-Hardware ifm DT1513 + AL1340.
Sprache: Code-Kommentare und Doku auf Deutsch. Identifier auf
Englisch (order_key, nicht auftragsschluessel).
Tech-Stack
- Python 3.11+ (Pi: Debian Trixie venv, Mac: pyenv oder System)
- paho-mqtt 2.x mit
CallbackAPIVersion.VERSION2— die alte API ist deprecated, nicht verwenden - zeep 4.x für SOAP gegen OpenZ
- fastapi + uvicorn für den
soap_adapter - requests für HTTP gegen AL1340 IoT-Core-API
- paho-mqtt + Mosquitto als Broker (Pi-lokal,
127.0.0.1:1883für Services,192.168.35.20:1883für externe Clients) - SQLite als Persistenz-Layer (kein Postgres im Lab — bewusst)
- systemd für Service-Management auf dem Pi
- pytest für Tests, pyright für Type-Checking
Repo-Layout
code/
├── shared/ MQTT-Client, Logging, Topic-Konstanten — gemeinsam
├── rfid_gateway/ AL1340-IoT-Core-API <-> MQTT (Phase A)
├── control_agent/ State-Machine-Orchestrierung (Phase A)
├── soap_adapter/ FastAPI-REST -> OpenZ-SOAP -> MQTT (Phase C)
├── erp_bridge/ MQTT-Done -> OpenZ-Quittung mit Idempotenz (Phase C)
├── tests/ Offline-Tests (alle Hardware gemockt)
├── rfid_test/ Live-Probe-Skripte, teils historisch (Modbus-Reste)
├── deploy/
│ ├── systemd/ sf-*.service-Units + .env.example
│ ├── network/ Mac-NAT-Bridge (Notfall-Werkzeug, im Normalbetrieb nicht aktiv)
│ └── healthcheck.sh
└── docs/ Hardware-Doku, RFID-Protokoll-Notizen, IP-Plan
Vier Microservices, eine Codebasis
| Service | Modul | Funktion |
|---|---|---|
rfid_gateway |
rfid_gateway.gateway |
DT1513 polling + write, MQTT publish |
control_agent |
control_agent.agent |
OrderState State Machine, MQTT-Orchestrierung |
soap_adapter |
soap_adapter.main:app |
FastAPI auf :8000, REST + OpenZ + MQTT-Publish |
erp_bridge |
erp_bridge.main |
MQTT-Subscriber, OpenZ submitOrder, Idempotenz |
Alle vier laufen auf demselben Pi. Mosquitto läuft separat als System-Service.
Wo läuft was
- Lokale Dev (Mac):
./start_all.sh— startet alle vier Services im Vordergrund,Ctrl+Ckillt alles. Nutzt Defaults aus dem Code, überschreibbar via Env-Vars (MQTT_BROKER_HOST,AL1340_IOT_HOST). - Produktion (Pi
192.168.35.20): viersf-*.service-Units in/etc/systemd/system/mitEnvironmentFile=/home/smartfactory/smart_factory/.env. Auto-Start beim Boot, Auto-Restart bei Crash.
Wichtige Konventionen
Konfiguration
- Eine
.envfür alle Services — Vorlage indeploy/systemd/.env.example. - Keine Hardcoded-IPs / Credentials im Code (außer als
os.environ.get(..., default)-Defaults für lokale Dev-Bequemlichkeit). .envist gitignored. Niemals Default-Werte mit echten Lab- Passwörtern committen.
MQTT-Topics
- Schema:
factory/{subsystem}/{device}/{cmd|event}plus drei Spezialfälle (factory/errors/{service},factory/order/{id}/state,factory/production/order/cmd,factory/erp/production/event). - Topic-Konstanten und Builder-Funktionen in
shared/topics.py. Niemals Topic-Strings direkt im Service-Code hardcoden — immerfrom shared.topics import .... - QoS 1 ist Default.
retain=Truenur fürfactory/order/{id}/state(und ggf. künftige Last-Known-State-Topics). - Payloads sind JSON, UTF-8 mit Pflichtfeldern
event_type(für Events) bzw.command(für Commands) undorder_id/order_key(wo zutreffend).
Logging
from shared.logging_setup import get_logger- JSON-Logs mit
event_type,outcome(ok/error/warning/pending/skipped), service-spezifische Felder als Kwargs. - Niemals
print()in Service-Code (Test-Skripte unterrfid_test/ausgenommen). - Keine emojis in Logs (verschmutzt journalctl-Pipes).
State-Management
control_agentist die einzige Komponente mit echter State Machine (OrderStateEnum incontrol_agent/state_machine.py). Andere Services sind stateless oder rein technische Caches.- Persistenz über SQLite —
control_agent_events.db(EventLog),erp_idempotency.db(Idempotenz-Store). - MQTT-State über
retain=True— Subscriber bekommen den letzten Zustand jedes aktiven Auftrags ohne Replay-Logik.
Tests
pytest tests/ -q— alle Tests offline, AL1340 / Mosquitto / OpenZ gemockt.- Live-Tests sind unter
rfid_test/als Skripte, kein Teil der CI-Test-Suite. - Wenn neue Logik auf Hardware-Verhalten beruht, erst pytest-Mock, dann Live-Probe.
Wenn du X änderst, beachte Y
- MQTT-Topic ändern oder hinzufügen →
shared/topics.pyzuerst, dann alle Subscriber anpassen.factory/#-Wildcards incontrol_agent.main()checken. - Neuer Geräteparameter →
.env.exampleUND zugehörige systemd- Unit-Doku indeploy/systemd/README.md. - Neue Python-Dependency →
requirements_all.txtUND ggf. service- spezifische<service>/requirements.txt. Pi-Update braucht dannpip install -r requirements_all.txtim venv. OrderStateerweitern → State-Übergänge inOrderWorker.run()anpassen, EventLog-Schema bleibt rückwärtskompatibel (text-Spalten).- OpenZ-Service-Versionswechsel (z. B. von OrderServiceV200 auf
V300) →
erp_bridge/openz_client.pyUNDsoap_adapter/openz_client.pyseparat anpassen — die beiden teilen sich keinen Code (siehe Architektur-Begründung in der Studienarbeit, Abschnitt 4.4).
Hardware-spezifische Stolperfallen
Detailliert in docs/RFID_PROTOCOL_NOTES.md
und BENUTZERHANDBUCH.md §6. Kurz für KI-Agents:
- DT1513 Auto-Read zeigt nur N Byte, wobei N der Geräteparameter
"Data Length for Auto Read/Write" ist. Code umgeht das mit
read_tag_full()(zusätzlicher Mode-0x03-Read). Niemals annehmen, dasspdin[2..32]voll mit Tag-Daten gefüllt ist. - Mode 0x02 (Auto-Write) NICHT verwenden — schreibt lautlos N Byte Daten und meldet "Erfolg". Stattdessen Mode 0x04 mit explizitem Address+Length-Setup.
- Cmd Start braucht steigende Flanke — vor jedem Mode-Wechsel
withdraw_pdout()(Preset, alle 32 Byte = 0) senden. - PDin Bit 1:
- Bit 0 = Cmd Start Ack
- Bit 1 = Cmd End
- Bit 2 = Tag Present
- Bit 3 = Antenna Off
- Es gibt kein Error-Bit in PDin Word 0 — Errors stehen in
pdin[31].
- AL1340-Modbus-Stack ist im Code nicht referenziert — alle Pdin/Pdout-Operationen laufen über die HTTP-IoT-Core-API.
Build / Run / Test (Cheatsheet)
# Lokale Dev (Mac):
cd code
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements_all.txt
MQTT_BROKER_HOST=192.168.35.20 AL1340_IOT_HOST=192.168.35.80 ./start_all.sh
# Tests (offline):
PYTHONPATH=. python3 -m pytest tests/ -q
# Type-Check:
pyright
# Deploy auf Pi:
ssh smartfactory@192.168.35.20 'cd ~/smart_factory && git pull && \
sudo systemctl restart sf-rfid-gateway sf-control-agent sf-soap-adapter sf-erp-bridge'
# Live-Logs vom Pi:
ssh smartfactory@192.168.35.20 'journalctl -u sf-rfid-gateway -f'
# MQTT mitlauschen (vom Mac aus, im VLAN 88):
mosquitto_sub -h 192.168.35.20 -u smartfactory -P 'fqtXF8tZcD#y' -t 'factory/#' -v
Was du als KI-Agent NICHT automatisch tun solltest
- Niemals in
archive/schreiben. Das ist read-only Vorgänger- Material, kein Eigenbau. - Niemals
.envcommitten. Wenn in.env.exampleneue Felder dazukommen, gibt es Doku-Updates inBENUTZERHANDBUCH.mdunddeploy/systemd/README.md. - Keine Co-Authored-By-Trailer in Commit-Messages. Studienarbeit ist Einzelautor-Werk.
- Architektur-Argumente nicht mit Einzelvorfällen begründen (z. B. nicht "wir hatten mal Stromausfall, deshalb…"). Argumente müssen aus Anforderungen oder Eigenschaften der Komponenten ableitbar sein.
- Nicht beim ersten Anzeichen von "outdated docs" einfach umbenennen
—
mqtt-topics.mdmit Bindestrich existiert parallel zumqtt_topics.mdund beide haben Cross-References. Konsolidieren ja, aber bewusst und gemeinsam mit dem Autor.
Wo finde ich tiefere Erklärung wenn etwas unklar ist
| Thema | Quelle |
|---|---|
| Architektur, Datenfluss, IPs, Ops | BENUTZERHANDBUCH.md |
| DT1513 Protokoll Bring-up und Bugs | docs/RFID_PROTOCOL_NOTES.md |
| IP-Plan und Hostnamen-Konventionen | docs/network.md |
| systemd-Units und Pi-Workflow | deploy/systemd/README.md |
| Mac-NAT-Bridge (Notfall) | deploy/network/README.md |
| Lab-Session-Chronologie | LAB_SESSION_*.md |
| Wissenschaftliche Begründung | Studienarbeit-thesis/main.pdf (Schwester-Repo) |
| OpenZ-API-Konzepte | archive/heinl_studienarbeit.pdf, archive/openz_source/ |