sps_skel/README.md

sps_skel

Das Programm erhält ein mechanisches Layout von der Projektierung oder dem Angebotswesen zusammen mit dem elektrischen Layout (Liste aller Sensoren, Stopper, Weichen, etc.). Daraus soll es ein Skelett für die SPS-Programmierung (Siemens SCL, TIA Portal) erzeugen — aufgebaut aus TRO-Bausteinen (Transfer Route Object), den wiederkehrenden Steuerungseinheiten einer Fördertechnik-Anlage.

Stand des Projekts

Die Kette CSV → TRO-JSON → SCL läuft in einer ersten Version durch. Aus einem CSV-Export der mechanischen Planung (ILS 2.0) entstehen automatisch:

• der Materialfluss-Graph der mechanischen Objekte (Strecken, Gefällestrecken, Kreisel),
• die daraus abgeleitete TRO-Liste samt eigenem Flussdiagramm,
• die TRO-JSON <name>_tro.json (Schema sps_skel-tro-v3, Modell lib/model.py) — die Schnittstelle zwischen Ableitung und SCL-Erzeugung,
• daraus ein SCL-Gerüst für FB_Main — ein REGION pro TRO mit Instanzaufruf und allen Parametern in der richtigen Reihenfolge, aber bewusst nicht lauffähig: jeder Wert, der aus der E-Planung stammen muss (Sensor-/Aktoradressen, Separator-/Weichennummern, Staubereiche, ungeprüfte Zeiten), ist als TODO(E-Planung) markiert statt geraten. Optional (--templates) kommen die REGIONs aus Jinja2-Templates (lib/scl_templates/<fbType>.scl.j2, für alle 7 Typen mit Referenz-Aufrufstelle),
• zur Sichtkontrolle eine annotierte Kopie der BricsCAD-Zeichnung mit einem Marker-Symbol pro TRO. Die Zeichnung ist nur Ansicht, keine Datenquelle für die SCL.

Details stehen in doc/, allen voran doc/Python_Scripts.md (alle Tools und Schalter) und doc/Klassenhierarchie.md (Klassen und wozu sie da sind).

Ablauf

data/<name>.csv  (ILS-2.0-Export)
   │
   ▼
material_flow  ──►  <name>_material_flow.dot/.svg/.md      Materialfluss der Mechanik
   │
   ▼
tro_flow --json ──►  <name>_tro.json  (+ .dot/.svg/.md)     TROs ableiten
   │                     │
   │                     ▼
   │                scl_skeleton  ──►  <name>_FB_Main.scl    SCL-Gerüst
   │
   └── gleiche Ableitung ──► tro_annotate ──► <name>_annotated.dxf   (nur Ansicht)
                              (braucht zusätzlich die DXF-Zeichnung)

Alle Ausgaben landen in results/ (%SKEL_RESULTS%).

Welche Skripte gibt es und wofür?

Umgebung (bin/, je .bat für Windows und .sh für Linux/macOS)

Diese vier Skripte verwalten nur Umgebung und venv, sie rufen kein Python-Programm auf.

Skript	Wofür
setenv	Setzt SPS_SKEL und die SKEL_*-Variablen, hängt SKEL_LIB an PYTHONPATH, legt fehlende Ordner an und gibt alles zur Kontrolle aus. .sh muss gesourct werden.
install_py	Einmalig: legt .venv an und installiert requirements.txt. Bricht ab, wenn .venv schon existiert.
activate_venv	Je Sitzung: aktiviert .venv und zeigt Python-Version und Pakete. .sh muss gesourct werden.
get_cmd	Öffnet eine neue Shell mit gesetzten Umgebungsvariablen.

CLI-Tools (lib/<name>.py, aufgerufen über bin/<name>.bat/.sh)

Jeder Wrapper ruft setenv, aktiviert .venv (falls vorhanden) und startet das Modul mit allen übergebenen Argumenten.

Tool	Wofür	Wichtige Schalter
material_flow	Liest den CSV-Export und baut den gerichteten Materialfluss-Graphen der mechanischen Objekte (Strecke, Gefällestrecke, Kreisel); Separatoren/Scanner hängen an ihrem Objekt. Grundlage für tro_flow.	--file, --tosvg, --use-cords, --doc, --connect, --track, --show-bbs, --chain-graph
tro_flow	Leitet aus demselben Graphen die TROs ab (Typ aus dem Trägerobjekt des Separators, Weichen aus den Abgängen), verknüpft sie und zeichnet ihren Fluss. Mit --json entsteht die TRO-JSON — der Hauptweg zur SCL.	--file, --json, --tosvg, --use-cords, --doc, --connect
scl_skeleton	Liest die TRO-JSON (geprüft gegen lib/model.py) und schreibt das FB_Main-Gerüst als SCL. Mit --templates aus den Jinja2-Templates, sonst generisch.	--json, --out, --start, --templates [DIR], --strict
tro_annotate	Zeichnet dieselben TROs als Marker (Farbe/Form je Typ, Attribute ID/TYPE/FB_BLOCK) in eine Kopie der BricsCAD-Zeichnung — zur Sichtkontrolle. Bestimmt dafür den CSV↔DXF-Lagebezug und legt ihn in cfg/dxf_registration.json ab. Erzeugt mit --emit-lisp die Typliste cad/tro_types.lsp für den TROEDIT-Dialog.	--file, --dxf, --flow, --fb, --legend, --offset, --re-register, --check, --emit-lisp
tro_extract	Geparkt. Liest TROs aus der annotierten Zeichnung zurück in das alte JSON-Format sps_skel-tro-extract-v1, das scl_skeleton nicht mehr annimmt. Nicht gelöscht, nicht weiterentwickelt.	--dxf

Bibliotheken (lib/, ohne eigenen Aufruf)

Modul	Wofür
tro_catalog.py	Katalog der TRO-Typen: Kurzname, Siemens-FB, Bauteile, Farbgruppe, CAD-Symbol. Einzige Quelle für FB-Typ und Bauteile.
model.py	Gemeinsames Modell der TRO-Instanzen und der TRO-JSON (TroBase, DerivedTro, Connection, TroCandidate, Analysis, TroDocument).
scl_context.py	Wandelt die TRO-JSON in den Render-Kontext für die SCL (Reihenfolge, Bauteilblöcke, Staubereiche, Weichenziele, offene Namen).
scl_templates/	Jinja2-Templates je FB-Typ (<fbType>.scl.j2) plus gemeinsame Makros; nur mit scl_skeleton --templates.
dxf_registration.py	Ermittelt, prüft und speichert die Transformation zwischen CSV- und DXF-Koordinaten.
tro_overrides.py	Liest die Handkorrekturen aus cfg/tro_overrides.ini; heute nur von material_flow --connect genutzt.

Sonstige Skripte

Skript	Wofür
doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py	Doku-Werkzeug, nicht Teil der Pipeline: erzeugt die Typ-Schaubilder und Topologie-Graphen für doc/TRO_Katalog/TRO_Katalog.md aus connect.ini. Aufruf: py doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py
cad/tro_types.lsp	Generiertes BricsCAD-LISP (Typliste für den TROEDIT-Dialog), erzeugt von tro_annotate --emit-lisp.
tests/	pytest-Tests: TRO-Modell, Render-Kontext, Golden-Files der SCL-Ausgabe (tests/fixtures/scl/), Templates gegen die Referenz-Aufrufstellen.

Projektstruktur

sps_skel/
  bin/          Umgebungsskripte + ein .bat/.sh-Wrapper-Paar je CLI-Tool
  cad/          generiertes BricsCAD-LISP (tro_types.lsp) für den TROEDIT-Dialog
  cfg/          Konfiguration: dxf_registration.json, tro_overrides.ini
  data/         Eingabedaten - CSV-Exporte, DXF (nicht im Git)
  doc/          Dokumentation, siehe doc/Python_Scripts.md
  examples/     Beispieldateien (noch leer)
  lib/          Python-Quellcode (CLI-Tools, Bibliotheken, scl_templates/)
  log/          Log-Dateien (nicht im Git)
  results/      Ergebnisse der CLI-Tools (.dot/.svg/.md/.json/.scl/.dxf, nicht im Git)
  tests/        Unit Tests (pytest)
  .gitignore
  LICENSE
  README.md
  requirements.txt

Umgebungsvariablen

Variable	Beschreibung
SPS_SKEL	Wurzelverzeichnis
SKEL_BIN	Skriptverzeichnis
SKEL_LIB	Python-Quellcode
SKEL_CFG	Konfigurationsdateien
SKEL_DATA	Eingabedaten
SKEL_DOC	Dokumentation
SKEL_LOG	Log-Dateien
SKEL_RESULTS	Ergebnisse
SKEL_EXAMPLES	Beispieldateien
SKEL_TESTS	Unit Tests
PYTHONPATH	Erweitert um SKEL_LIB

Installation

Voraussetzungen

• Python 3.10 oder höher
• Pakete aus requirements.txt: pydantic, jinja2 (SCL-Templates), ezdxf (nur tro_annotate), pytest
• Graphviz (dot, für --use-cords bei tro_flow auch neato) auf PATH für --tosvg — optional, aber empfohlen

Setup

bin\install_py.bat          # Windows

bash bin/install_py.sh      # Linux / macOS

Nutzung

Umgebung

bin\setenv.bat              # Windows: nur Variablen setzen
bin\activate_venv.bat       # Windows: venv aktivieren
bin\get_cmd.bat             # Windows: neue Shell mit Umgebung

source bin/setenv.sh
source bin/activate_venv.sh
bash bin/get_cmd.sh

Typischer Durchlauf

--file/--dxf nehmen einen Dateinamen (aufgelöst gegen %SKEL_DATA%) oder einen vollen Pfad; --json sucht in %SKEL_RESULTS%.

REM 1) Materialfluss der mechanischen Objekte (optional, zur Kontrolle)
bin\material_flow.bat --file mubea.csv --tosvg --doc

REM 2) TROs ableiten und als TRO-JSON schreiben
bin\tro_flow.bat --file mubea.csv --tosvg --doc --json

REM 3) FB_Main-SCL-Geruest erzeugen (generisch bzw. aus Templates)
bin\scl_skeleton.bat --json mubea_tro.json
bin\scl_skeleton.bat --json mubea_tro.json --templates

REM 4) Optional: TROs zur Sichtkontrolle in eine Kopie der Zeichnung
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend

--start TRO07 bei scl_skeleton ist nur nötig, solange die Anlage ein geschlossener Kreis ohne Be-/Entladestation ist. Danach im erzeugten *_FB_Main.scl nach TODO(E-Planung) suchen — das sind die Stellen, die aus der E-Planung gefüllt werden müssen.

Tests

python -m pytest tests/

mit aktivem .venv. Die Golden-Files in tests/fixtures/scl/ legen die SCL-Ausgabe byteweise fest; neu schreiben (SKEL_UPDATE_GOLDEN=1) nur bei einer geprüften, gewollten Änderung.

Roadmap

Noch offen:

• das volle JSON-Layout-Schema aus doc/HundM/Json_Layout-Konzept.md (plc, controlUnits, sensors[], conveyors[], tros[], jamAreas[], routing, …) als Zwischenformat — die TRO-JSON ist bisher TRO-zentriert;
• die übrigen Bausteine je Steuerung (FB_CallSensors, FC_Direction, FC_Call_Jams als eigene Dateien) — erzeugt wird bisher nur FB_Main;
• Templates für die weiteren FB-Typen (siehe doc/SCL_Templates.md);
• typabhängige Zeit-Defaults statt TODO(E-Planung): pruefen.

Details: Abschnitt "Roadmap" in CLAUDE.md.

Lizenz

MIT License - siehe LICENSE

Autor

Michael Stangl (GitHub: mistamichael)