Schoenenberger_Systeme_GmbH/sps_skel
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: reflect implemented DXF->JSON->SCL first version

Browse Source 
lib/scl_skeleton.py and lib/tro_extract.py already run the pipeline
end-to-end (annotated DXF -> TRO-JSON -> FB_Main SCL skeleton), but
CLAUDE.md and README.md still described these as unwritten tools
(tro_export.py / scl_gen.py). Update the current-state docs:

- CLAUDE.md: project purpose, reading order, roadmap section, and
  standard-template notes now describe the built pipeline plus the
  parts still open (full layout JSON schema, other per-controller
  blocks, timing defaults, --skip-json).
- README.md: bin/ tree and usage examples for tro_extract/scl_skeleton.
- doc/Python_Scripts.md: intro counts (8 modules / 5 CLI tools),
  header date, pipeline diagram, and tro_overrides.py in the lib list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Michael Stangl
2026-08-20 23:37:19 +02:00
parent e630ec12d6
commit 9336f18466
3 changed files with 117 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+68 -52
View File
@@ -10,25 +10,30 @@ of Siemens SCL code** ("TRO" — Transfer Route Object — blocks for a conveyor
control system) that can be imported directly into TIA Portal.
The repository has moved past pure analysis: `lib/` now holds working Python tooling that
derives a material-flow graph and a TRO list from a CSV export (ILS 2.0) and can annotate a
copy of the BricsCAD drawing with the result. What does **not** exist yet is the actual
SCL-skeleton generator — the step that would emit TIA-Portal-importable SCL from a JSON
layout model — nor the tool that derives that JSON model from the annotated drawing; see
"Roadmap" below for the planned two-tool pipeline that closes this gap. `tests/` and
`examples/` are still empty scaffolding (see "Standard Programm Template" below). What
exists today is:
runs the **full DXF → JSON → SCL pipeline in a first version**. From a CSV export (ILS 2.0)
it derives a material-flow graph and a TRO list, annotates a copy of the BricsCAD drawing
with the result, reads the (possibly hand-edited) drawing back into a TRO-JSON, and emits an
`FB_Main` **SCL skeleton** from that JSON. The skeleton is deliberately not a running
program — every value that must come from the electrical planning is left as a visible
`TODO(E-Planung)` gap rather than guessed. What is **not** done yet is the fuller layout-JSON
schema (`doc/HundM/Json_Layout-Konzept.md`) as an intermediate format and the generation of
the other per-controller blocks (`FB_CallSensors`, `FC_Direction`/`FC_Call_Jams` as
standalone files); see "Roadmap" below. `tests/` and `examples/` are still empty scaffolding
(see "Standard Programm Template" below). What exists today is:
- `bin/` — environment/venv management scripts, plus one `.bat`/`.sh` wrapper pair per CLI
tool in `lib/` (see "Environment scripts" below)
- `lib/*.py` — CLI tools and libraries that turn a CSV export + BricsCAD DXF into a
material-flow graph, a derived TRO list/diagram, and an annotated copy of the drawing.
material-flow graph, a derived TRO list/diagram, an annotated copy of the drawing, a
TRO-JSON read back out of that drawing, and an `FB_Main` SCL skeleton.
See **`doc/Python_Scripts.md`** for what each script does and which switches it takes.
- `data/` — input CSV exports (gitignored, not committed)
- `cad/tro_types.lsp` — generated type list for the BricsCAD `TROEDIT` dialog (written by
`tro_annotate.py --emit-lisp`)
- `cfg/dxf_registration.json` — persisted, verified CSV↔DXF coordinate transform
- `cfg/dxf_registration.json` — persisted, verified CSV↔DXF coordinate transform;
`cfg/tro_overrides.ini` — hand-maintained corrections to the derived TROs (see `tro_overrides.py`)
- `doc/*.md` — analysis documents that reverse-engineer the SCL patterns and propose the
JSON schema / code-generation approach for the generator that's still to be written
fuller JSON layout schema for the parts of the pipeline still to be built out
Read `doc/` before writing any generator code — start with `doc/Python_Scripts.md` for the
existing tooling, then the domain-model documents below; together they contain the actual
@@ -83,9 +88,10 @@ routing, modeled around **TRO** (Transfer Route Object) blocks. Key documents, r
this order for onboarding:
0. **`doc/Python_Scripts.md`** — the existing CLI tooling (`lib/material_flow.py`,
`lib/tro_flow.py`, `lib/tro_annotate.py`, plus the `lib/tro_catalog.py` and
`lib/dxf_registration.py` libraries they share): what each script does, its switches,
inputs/outputs. This is working code, not a proposal — read it before touching `lib/`.
`lib/tro_flow.py`, `lib/tro_annotate.py`, `lib/tro_extract.py`, `lib/scl_skeleton.py`,
plus the `lib/tro_catalog.py`, `lib/dxf_registration.py` and `lib/tro_overrides.py`
libraries they share): what each script does, its switches, inputs/outputs. This is
working code, not a proposal — read it before touching `lib/`.
1. **`doc/HundM/Json_Layout-Konzept.md`** — the core proposal: a JSON file as single source
of truth (`plc`, `controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
`emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`, `connections[]`,
@@ -116,9 +122,10 @@ this order for onboarding:
6. **`doc/HundM/suggestion.md`** — a follow-up proposal to collapse the 7 `FB_ILS_MTRO_*`
variants into a single `FB_ILS_MTRO` block driven by an array/config descriptor
instead of hand-duplicated numbered members (`...1`, `...2`, `Dir1..Dir4`). References
a not-yet-written `lib/create_skel.py` (`guess_fbtype()`) as the intended generator
entry point — this is still the planned shape of the SCL-emitting generator itself;
the current `lib/` tooling derives TROs from a layout but does not yet emit SCL.
a `lib/create_skel.py` (`guess_fbtype()`) as the intended generator entry point. That
specific module does not exist in this repo — it is the HundM Excel-based generator
sketch, a different input source (see "Roadmap" below). This repo's own SCL emitter is
`lib/scl_skeleton.py`, which already emits an `FB_Main` skeleton from the TRO-JSON.
7. **`doc/500573_Mubea/TRO_Identifikation_500573.md`** — the derivation rules
`lib/tro_flow.py` implements: how to infer a TRO's type from its separator's host
object (Gefällestrecke/Strecke/Kreisel) when no I/O list or `FB_Main` exists yet.
@@ -139,38 +146,47 @@ local, fully-vendored SCL source (`FB_ILS_MTRO_Vario_workStation`, `FB_EmptyCarr
`doc/TRO_Katalog/scl_templates/*.scl` as **read-only reference material** for pattern
extraction, not code to execute or modify.
## Roadmap: DXF → JSON → SCL (planned, not implemented)
## Roadmap: DXF → JSON → SCL (first version implemented)
`tro_annotate.py` is where the current pipeline stops today: the user can keep hand-editing
the annotated DXF copy afterwards (via the BricsCAD `TRO_INSERT`/`TRO_EDIT` commands, see
`doc/HundM/BricsCAD_TRO_Symbol.md`) — moving TROs, adding new ones, or changing a type. Two
more `lib/` tools are planned to carry that drawing the rest of the way to importable SCL:
The DXF → JSON → SCL pipeline now runs end-to-end in a first version. After `tro_annotate.py`
burns the TROs into a copy of the drawing, the user can hand-edit that DXF in BricsCAD (via
the `TRO_INSERT`/`TRO_EDIT` commands, see `doc/HundM/BricsCAD_TRO_Symbol.md`) — moving TROs,
adding new ones, changing a type — and two further `lib/` tools carry the drawing the rest of
the way to importable SCL:
1. **`lib/tro_export.py`** (planned) — reads the (possibly hand-edited) annotated DXF plus
the CSV export and derives the JSON layout file described in
`doc/HundM/Json_Layout-Konzept.md` (`plc`, `controlUnits`, `sensors[]`, `conveyors[]`,
`tros[]`, `loadingBooms[]`, `emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`,
`connections[]`, `destinations[]`). Per-TRO timing (`trailingTime`, `handlingTime`,
`senFree`, `senWait`, `jamTime`, ...) comes from the type-based default table in
`doc/TRO_Typen.md` unless the CAD symbol carries an `OVERRIDE_TIMING_JSON` value (see
`doc/HundM/BricsCAD_TRO_Symbol.md`), in which case the override wins. The resulting JSON
file is meant to be hand-edited afterwards — that's the intended place to tweak defaults
or individual timings before code generation.
2. **`lib/scl_gen.py`** (planned) — reads the JSON layout file and emits the `.scl` files
(`FB_Main`, `FB_CallSensors`, `FC_Direction`, `FC_Call_Jams` per controller) ready for
TIA Portal import. Takes a `--skip-json` switch for the case where no manual JSON edits
are needed: it then reads the DXF + CSV directly (running the same derivation as
`tro_export.py` internally) and emits SCL immediately, without writing or reading an
intermediate JSON file.
1. **`lib/tro_extract.py`** (implemented) — reads the (possibly hand-edited) annotated DXF
**only** (not the CSV) and derives a TRO-JSON (`<drawing>_tro.json`): the TROs tagged with
XDATA, their `predecessors`/`successors` computed from the flow arrows, and plant
coordinates resolved through the persisted registration. See `doc/Python_Scripts.md` §5a.
2. **`lib/scl_skeleton.py`** (implemented) — reads that TRO-JSON and emits an `FB_Main` SCL
skeleton (`<source>_FB_Main.scl`): one `REGION` per TRO with the instance call and every
parameter line in the right order, plus inline `FC_Direction` calls for switch TROs.
Everything derivable from the layout is filled (REGION order, FB type, parameter-block
counts, destination list per switch exit, `nTo1Destinations` for single-switch TROs);
everything that must come from the electrical planning is a `TODO(E-Planung)` gap.
Switches `--json`, `--out`, `--start` (the last picks an entry point while the plant is a
closed loop with no loading/unloading station). See `doc/Python_Scripts.md` §5b.
Both tools follow the existing `lib/` conventions once written: a `bin/<name>.bat`/`.sh`
wrapper pair (see "Environment scripts" above) and a switches/outputs section in
`doc/Python_Scripts.md`. Note this is a separate concept from the `create_skel.py` /
`guess_fbtype()` generator sketched in `doc/HundM/suggestion.md` and
`doc/HundM/Json_Layout-Konzept.md` §14.5 — that one is designed to derive its skeleton JSON
from HundM's Excel I/O-list exports (`*_TIA.xlsx`, `*_positions.json`, ...), a different
input source than this repo's CSV+DXF pipeline. The JSON *schema* it targets is the same
(`doc/HundM/Json_Layout-Konzept.md`); only the derivation source differs.
What is **not** built out yet, relative to the original two-tool design:
- the fuller **layout-JSON schema** of `doc/HundM/Json_Layout-Konzept.md` (`plc`,
`controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
`emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`, `connections[]`,
`destinations[]`) as the intermediate format — `tro_extract.py` currently emits a
TRO-focused JSON, not this full schema;
- the **other per-controller blocks** (`FB_CallSensors`, `FC_Direction`/`FC_Call_Jams` as
standalone files) — only `FB_Main` is generated today;
- **type-based timing defaults** from `doc/TRO_Typen.md` and the `OVERRIDE_TIMING_JSON` CAD
attribute (timings are emitted as `TODO(E-Planung): pruefen` placeholders for now);
- a **`--skip-json`** convenience path that would read DXF + CSV directly and emit SCL
without an intermediate JSON file.
Note the `create_skel.py` / `guess_fbtype()` generator sketched in `doc/HundM/suggestion.md`
and `doc/HundM/Json_Layout-Konzept.md` §14.5 is a **separate concept** and is not implemented
here: it is designed to derive its skeleton JSON from HundM's Excel I/O-list exports
(`*_TIA.xlsx`, `*_positions.json`, ...), a different input source than this repo's CSV+DXF
pipeline. The JSON *schema* it targets is the same (`doc/HundM/Json_Layout-Konzept.md`); only
the derivation source differs.
## Standard Programm Template
@@ -188,14 +204,14 @@ sps_skel/
examples/ example files — empty for now
lib/ Python source, importable via SKEL_LIB on PYTHONPATH — CLI tools and
libraries that derive material flow / TRO lists / CAD annotations from a
layout (see doc/Python_Scripts.md); the JSON-driven SCL generator itself
is not yet written
layout, read the TROs back into JSON, and emit an FB_Main SCL skeleton
(see doc/Python_Scripts.md)
log/ gitignored
results/ gitignored — CLI tool output (.dot/.svg/.md/.dxf)
results/ gitignored — CLI tool output (.dot/.svg/.md/.dxf/.scl/.json)
tests/ unit tests — empty for now
```
When adding the SCL generator, put it under `lib/` (importable via `SKEL_LIB` on
`PYTHONPATH`), add a `bin/<name>.bat`/`.sh` wrapper pair for it following the pattern of
`bin/tro_flow.bat`/`.sh` (see "Environment scripts" above), document its switches in
`doc/Python_Scripts.md`, and add tests under `tests/`.
When extending the pipeline (the remaining pieces in "Roadmap" above), put new modules under
`lib/` (importable via `SKEL_LIB` on `PYTHONPATH`), add a `bin/<name>.bat`/`.sh` wrapper pair
for each following the pattern of `bin/tro_flow.bat`/`.sh` (see "Environment scripts" above),
document its switches in `doc/Python_Scripts.md`, and add tests under `tests/`.
README.md
+32 -36
View File
@@ -9,51 +9,37 @@
## Stand des Projekts
Der eigentliche SCL-Generator (JSON-Layout → TIA-Portal-Code) ist **noch nicht
geschrieben**. Was bereits funktioniert, ist die Ableitung der Vorstufen dazu:
aus einem CSV-Export der mechanischen Planung (ILS 2.0) werden automatisch
Aus einem CSV-Export der mechanischen Planung (ILS 2.0) werden automatisch
- der **Materialfluss-Graph** der mechanischen Objekte (Strecken, Gefällestrecken,
Kreisel),
- die daraus abgeleitete **TRO-Liste** samt eigenem Flussdiagramm, und
- die daraus abgeleitete **TRO-Liste** samt eigenem Flussdiagramm,
- eine **annotierte Kopie der BricsCAD-Zeichnung** mit einem Marker-Symbol pro
TRO
TRO (danach in BricsCAD von Hand nachbearbeitbar — TROs verschieben,
ergänzen, Typ ändern),
- daraus zurückgelesen ein **JSON-Modell der TROs** (liest nur die Zeichnung,
erfasst also auch von Hand vorgenommene Korrekturen), und
- 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.
erzeugt. Diese drei Werkzeuge liegen als CLI-Tools in `lib/` und sind über
Diese fünf Werkzeuge liegen als CLI-Tools in `lib/` und sind über
`bin/`-Wrapper aufrufbar (siehe unten). Details, Domänenmodell und die
Roadmap zum Generator stehen in `doc/`, allen voran `doc/Python_Scripts.md`.
verbleibende Roadmap stehen in `doc/`, allen voran `doc/Python_Scripts.md`.
## Roadmap
`tro_annotate.py` ist aktuell die letzte Stufe: Der Nutzer kann die annotierte
DXF-Kopie danach von Hand weiterbearbeiten — TROs verschieben, ergänzen oder
deren Typ ändern (`TRO_INSERT`/`TRO_EDIT` im BricsCAD-Menü, siehe
`doc/HundM/BricsCAD_TRO_Symbol.md`). Geplant sind zwei weitere Tools, die diese
Zeichnung bis zum fertigen SCL-Code weiterführen:
1. **`tro_export.py`** (geplant) — liest die (ggf. von Hand nachbearbeitete)
annotierte DXF zusammen mit dem CSV-Export und leitet daraus die
JSON-Layout-Datei nach dem in `doc/HundM/Json_Layout-Konzept.md`
beschriebenen Schema ab (`plc`, `controlUnits`, `sensors[]`, `conveyors[]`,
`tros[]`, `loadingBooms[]`, `emptyCarrBuffers[]`, `routing`, `jamAreas[]`,
`scanners[]`, `connections[]`, `destinations[]`). Timing-Werte pro TRO
(`trailingTime`, `handlingTime`, `senFree`, `senWait`, `jamTime`, ...)
kommen dabei standardmäßig aus der typspezifischen Default-Tabelle
(`doc/TRO_Typen.md`); trägt das CAD-Symbol einen `OVERRIDE_TIMING_JSON`-Wert
(siehe `doc/HundM/BricsCAD_TRO_Symbol.md`), gewinnt der Override. Die
erzeugte JSON-Datei ist danach von Hand editierbar, um einzelne Defaults
oder Zeiten anzupassen, bevor daraus SCL generiert wird.
2. **`scl_gen.py`** (geplant) — liest die JSON-Layout-Datei und erzeugt daraus
die `.scl`-Skeleton-Dateien für den direkten TIA-Portal-Import (`FB_Main`,
`FB_CallSensors`, `FC_Direction`, `FC_Call_Jams` je Steuerung). Mit dem
Schalter `--skip-json` läuft dieser Schritt auch ohne manuell
nachbearbeitete JSON-Datei: `scl_gen.py` liest dann DXF und CSV direkt (wie
`tro_export.py`) und erzeugt sofort SCL mit den Typ-Defaults, ohne eine
Zwischen-JSON-Datei zu schreiben oder einzulesen — sinnvoll, wenn an den
Defaults nichts manuell angepasst werden muss.
Beide Tools bekommen wie üblich ein `bin/<name>.bat`/`.sh`-Wrapper-Paar und
werden in `doc/Python_Scripts.md` dokumentiert, sobald sie existieren.
Offen ist vor allem die JSON-Layout-Datei nach dem in
`doc/HundM/Json_Layout-Konzept.md` beschriebenen Schema (`plc`,
`controlUnits`, `sensors[]`, `conveyors[]`, `tros[]`, `loadingBooms[]`,
`emptyCarrBuffers[]`, `routing`, `jamAreas[]`, `scanners[]`, `connections[]`,
`destinations[]`) als von Hand editierbares Zwischenformat vor der
SCL-Erzeugung, sowie die Generierung der übrigen Bausteine je Steuerung
(`FB_CallSensors`, `FC_Direction`, `FC_Call_Jams`) — `scl_skeleton.py` deckt
bisher nur `FB_Main` ab. Siehe `CLAUDE.md` (Abschnitt "Roadmap") für den
aktuellen Stand der Planung dazu.
## Projektstruktur
@@ -67,6 +53,8 @@ sps_skel/
material_flow.bat/.sh Wrapper fuer lib/material_flow.py
tro_flow.bat/.sh Wrapper fuer lib/tro_flow.py
tro_annotate.bat/.sh Wrapper fuer lib/tro_annotate.py
tro_extract.bat/.sh Wrapper fuer lib/tro_extract.py
scl_skeleton.bat/.sh Wrapper fuer lib/scl_skeleton.py
cad/ generiertes BricsCAD-LISP (tro_types.lsp) fuer den TROEDIT-Dialog
cfg/ Konfigurationsdateien (INI/JSON); dxf_registration.json
data/ Eingabedaten - CSV-Exporte, DXF (nicht im Git)
@@ -158,6 +146,14 @@ bin\tro_flow.bat --file mubea.csv --tosvg --doc
REM 3) TROs als Marker-Symbole in eine Kopie der CAD-Zeichnung einbrennen
bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
REM (Zeichnung optional in BricsCAD von Hand nachbearbeiten)
REM 4) TROs aus der (ggf. bearbeiteten) Zeichnung zurueck in JSON lesen
bin\tro_extract.bat --dxf export_annotated.dxf
REM 5) FB_Main-SCL-Geruest aus dem JSON erzeugen
bin\scl_skeleton.bat --json export_tro.json --start TRO07
```
Alle Switches, Ausgabedateien und Exit-Codes der drei Tools sind in
doc/Python_Scripts.md
+17 -7
View File
@@ -1,12 +1,13 @@
# Python Scripts — CLI Tooling Overview
**As of:** 2026-08-03
**As of:** 2026-08-20
`lib/` currently holds five Python modules (three of them runnable CLI tools,
two supporting libraries), plus one documentation-generator script that lives
`lib/` currently holds eight Python modules (five of them runnable CLI tools,
three supporting libraries), plus one documentation-generator script that lives
under `doc/TRO_Katalog/tro_graphs/`. Together the CLI tools turn a CSV export
of the mechanical layout (ILS 2.0) into a material-flow graph, a derived TRO
list/diagram, and an annotated copy of the BricsCAD drawing.
list/diagram, an annotated copy of the BricsCAD drawing, a TRO-JSON read back
out of that drawing, and an `FB_Main` SCL skeleton generated from that JSON.
This document is the practical "what does each script do and which switches
does it take" reference. For the underlying domain model (TRO types, JSON
@@ -27,8 +28,14 @@ tro_flow.py ──► <name>_tro_flow.dot / .svg, _tro_doc.md, _tro_error
│ (derives TROs, using the type catalog in tro_catalog.py)
▼
tro_annotate.py ──► <name>_annotated.dxf, <name>_registration.json
(also needs the BricsCAD DXF; uses dxf_registration.py for the CSV↔DXF
coordinate offset and tro_catalog.py for marker shape/color per TRO type)
│ (also needs the BricsCAD DXF; uses dxf_registration.py for the CSV↔DXF
│ coordinate offset and tro_catalog.py for marker shape/color per TRO type)
▼ (drawing may be hand-edited in BricsCAD before the next step)
tro_extract.py ──► <drawing>_tro.json
│ (reads only the drawing; resolves plant coords via the registration)
▼
scl_skeleton.py ──► <source>_FB_Main.scl
(one REGION per TRO; E-planning values left as TODO(E-Planung) gaps)
```
- `material_flow.py` models the material flow of the **mechanical** objects only
@@ -47,6 +54,9 @@ Supporting libraries (no CLI of their own, imported by the tools above):
- **`lib/dxf_registration.py`** — derives, verifies and persists the rigid
(rotation + offset) transform between the CSV export's coordinate system and
the DXF drawing's.
- **`lib/tro_overrides.py`** — reads the hand-maintained
`%SKEL_CFG%\tro_overrides.ini` (type corrections, open points, TRO merges)
that survive re-runs of `tro_flow.py`. See §6a.
Separate, documentation-only tool (not part of the generator pipeline):
@@ -74,7 +84,7 @@ bin\tro_annotate.bat --file mubea.csv --dxf 500573_60_1.dxf --flow --fb --legend
(`--use-cords` lays both graphs out at the real plant coordinates; drop it for
Graphviz's computed left-to-right arrangement.)
Conventions shared by all three tools:
Conventions shared by the CLI tools:
- `--file` / `--dxf` accept either a bare filename — resolved against
`%SKEL_DATA%` — or a full path.