Files
OIlczuk 0b0cb0f62f chore: update course designation to TINF23 in readme, handbooks, and prompts
- 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
2026-06-01 13:35:21 +02:00

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:1883 für Services, 192.168.35.20:1883 fü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+C killt alles. Nutzt Defaults aus dem Code, überschreibbar via Env-Vars (MQTT_BROKER_HOST, AL1340_IOT_HOST).
  • Produktion (Pi 192.168.35.20): vier sf-*.service-Units in /etc/systemd/system/ mit EnvironmentFile=/home/smartfactory/smart_factory/.env. Auto-Start beim Boot, Auto-Restart bei Crash.

Wichtige Konventionen

Konfiguration

  • Eine .env für alle Services — Vorlage in deploy/systemd/.env.example.
  • Keine Hardcoded-IPs / Credentials im Code (außer als os.environ.get(..., default)-Defaults für lokale Dev-Bequemlichkeit).
  • .env ist 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 — immer from shared.topics import ....
  • QoS 1 ist Default. retain=True nur für factory/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) und order_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 unter rfid_test/ ausgenommen).
  • Keine emojis in Logs (verschmutzt journalctl-Pipes).

State-Management

  • control_agent ist die einzige Komponente mit echter State Machine (OrderState Enum in control_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.py zuerst, dann alle Subscriber anpassen. factory/#-Wildcards in control_agent.main() checken.
  • Neuer Geräteparameter → .env.example UND zugehörige systemd- Unit-Doku in deploy/systemd/README.md.
  • Neue Python-Dependency → requirements_all.txt UND ggf. service- spezifische <service>/requirements.txt. Pi-Update braucht dann pip install -r requirements_all.txt im venv.
  • OrderState erweitern → State-Übergänge in OrderWorker.run() anpassen, EventLog-Schema bleibt rückwärtskompatibel (text-Spalten).
  • OpenZ-Service-Versionswechsel (z. B. von OrderServiceV200 auf V300) → erp_bridge/openz_client.py UND soap_adapter/openz_client.py separat 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, dass pdin[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 .env committen. Wenn in .env.example neue Felder dazukommen, gibt es Doku-Updates in BENUTZERHANDBUCH.md und deploy/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.md mit Bindestrich existiert parallel zu mqtt_topics.md und 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/