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`](doc/Python_Scripts.md) (alle Tools und Schalter) und
[`doc/Klassenhierarchie.md`](doc/Klassenhierarchie.md) (Klassen und wozu sie da
sind).

## Ablauf

```text
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

```text
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

```bat
bin\install_py.bat          # Windows
```

```sh
bash bin/install_py.sh      # Linux / macOS
```

## Nutzung

### Umgebung

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

```sh
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%`.

```bat
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

```bat
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)