sps_skel/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project purpose

`sps_skel` takes a mechanical layout (from project planning/sales) together with an
electrical layout (list of sensors, stoppers, switches, etc.) and generates a **skeleton
of Siemens SCL code** ("TRO" — Transfer Route Object — blocks for a conveyor/material-flow
control system) that can be imported directly into TIA Portal.

The repository has moved past pure analysis: `lib/` now holds working Python tooling that
runs the **full CSV → TRO-JSON → SCL pipeline in a first version**. From a CSV export (ILS
2.0) it derives a material-flow graph and a TRO list, writes the TROs as a TRO-JSON defined
by the shared pydantic model `lib/model.py`, and emits an `FB_Main` **SCL skeleton** from
that JSON. A copy of the BricsCAD drawing annotated with the same TROs serves as a viewer
for visual checking; it is no longer a data source. 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/` holds the first tests
(`tests/test_model.py`); `examples/` is 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 into a material-flow graph,
  a derived TRO list/diagram, a TRO-JSON (`lib/model.py`), an `FB_Main` SCL skeleton, and
  (with the BricsCAD DXF) an annotated copy of the drawing for visual checking;
  `lib/e_planning.py` assigns the E-planning's sensors/valves (from the cable-length
  tool's `*_positionsdraw.json`) to the layout parts so the skeleton can carry real names.
  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/tro_overrides.ini` — hand-maintained corrections to the derived TROs (see `tro_overrides.py`);
  `cfg/e_planning.ini` — project-specific rules for assigning E-planning symbols to layout parts;
  `cfg/<csv>_tro_ids.ini` — per-plant TRO-ID file (versioned, IDs renamed by the SPS
  programmers), created/extended by `tro_flow.py` via `lib/tro_ids.py`
- `doc/*.md` — analysis documents that reverse-engineer the SCL patterns and propose the
  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
domain model this project is meant to implement.

## Environment scripts (bin/)

Every script has a `.bat` (Windows) and `.sh` (Linux/macOS) pair. The four scripts below are
environment/venv management only — they never invoke a concrete Python script:

| Script | Purpose |
|---|---|
| `setenv.bat` / `source setenv.sh` | Sets `SPS_SKEL` (project root) and `SKEL_BIN/LIB/CFG/DATA/LOG/RESULTS/EXAMPLES/TESTS`; prepends `SKEL_LIB` to `PYTHONPATH`; creates missing folders |
| `install_py.bat` / `install_py.sh` | Calls `setenv`, creates `.venv` (`py -m venv` / `python3 -m venv`), installs `requirements.txt`. Aborts with a message if `.venv` already exists |
| `activate_venv.bat` / `activate_venv.sh` | Calls `setenv`, activates `.venv` (errors if missing — run `install_py` first) |
| `get_cmd.bat` / `get_cmd.sh` | Calls `setenv`, opens a new shell with the environment variables set |

**Convention:** every CLI tool added to `lib/` gets its own `.bat`/`.sh` wrapper pair in
`bin/`, named after the module (e.g. `lib/tro_flow.py` → `bin/tro_flow.bat` /
`bin/tro_flow.sh`). Each wrapper calls `setenv`, activates `.venv` if present, then runs the
module with `py`/`python3 "%*"`/`"$@"`. This supersedes the old "env-only" rule — see
`bin/material_flow.bat`, `bin/tro_flow.bat`, `bin/tro_annotate.bat` (+ `.sh`) for the current
pattern, and `doc/Python_Scripts.md` for what each tool does and which switches it takes.

Typical workflow on Windows:

```
bin\install_py.bat          # one-time: create venv + pip install
bin\activate_venv.bat       # each session: activate venv + show versions
```

Linux/macOS equivalents must be **sourced**, not executed:

```
bash bin/install_py.sh
source bin/activate_venv.sh
```

Requires Python 3.10+. `requirements.txt` pins `pydantic>=2.0.0` (used throughout `lib/`
for validated models), `ezdxf>=1.4.0` (DXF read/write, `tro_annotate.py` only) and
`pytest>=9.0.0`.

Tests: `python -m pytest tests/` with `.venv` active. `tests/conftest.py` puts `lib/` on
`sys.path`, so `bin/setenv` is not required for the tests. No build step or linter is set
up.

## Domain model (from doc/)

The target system is a Siemens TIA Portal / SCL project for automated conveyor/carrier
routing, modeled around **TRO** (Transfer Route Object) blocks. Key documents, read in
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`, `lib/tro_extract.py`, `lib/scl_skeleton.py`,
   `lib/e_planning.py`, plus the `lib/tro_catalog.py`, `lib/model.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[]`,
   `destinations[]`) from which the repetitive, per-topology SCL code in `FB_Main`,
   `FB_CallSensors`, `FC_Direction`, `FC_Call_Jams` would be generated.
2. **`doc/TRO_Typen.md`** — catalogs all 10 TRO function-block types actually found across
   the 5 reference controllers (UH01–UH05) and shows that 9 of them are additive
   combinations of one base type (`1Sep` = one separator/stopper) plus reusable
   sub-blocks (`FB_ILS_STRO_Sep`, `FB_ILS_STRO_Switch`, `FB_ILS_STRO_Vario`,
   `FB_BarcodeReaderCognex`, `FB_CarrAccumulate1Sep`). Only `LoadingBoom` is structurally
   independent. `lib/tro_catalog.py` is the executable form of this catalog (name, FB
   block, sub-components, color, CAD symbol per type).
3. **`doc/HundM/EA-Listen-Analyse.md`** — analyzes the raw I/O list Excel exports
   (`*_EA.xlsx`/`*_TIA.xlsx`/`*_WSCAD.xlsx`) and companion position/cabling JSON exports,
   and what can vs. cannot be auto-derived from them (signal naming prefixes `BG/SF/DI/BP`
   for inputs, `MB/MA/QA/DQ/FC/PF` for outputs; topology/timing/customCode cannot be
   derived from I/O lists alone — those must come from the JSON model or CAD symbol).
4. **`doc/HundM/BricsCAD_TRO_Symbol.md`** — proposes a BricsCAD block symbol whose
   attributes feed the JSON `tros[]` entries; documents which fields are captured on the
   symbol vs. derived from drawing topology or type-based timing defaults.
   `lib/tro_annotate.py` implements a first version of this (marker blocks with `ID`/
   `TYPE`/`FB_BLOCK` attributes), plus the `TROEDIT` BricsCAD dialog (`cad/tro_types.lsp`,
   generated by `tro_annotate.py --emit-lisp`).
5. **`doc/HundM/SCL_Analyse_Standardisierung.md`** — cross-controller duplication analysis;
   identifies ~22 blocks duplicated identically across all 5 controllers (candidates for
   a shared library) and flags "version chaos" areas (e.g. `FB_StockRemovalBLKModul*`
   variants) that should NOT be naively merged.
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 `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.
8. **`doc/TRO_Katalog/TRO_Katalog.md`** — central image/concept catalog per TRO type
   (schematic, real layout image, SCL template, JSON example, CAD symbol attributes);
   its generated images come from `doc/TRO_Katalog/tro_graphs/gen_tro_graphs.py`
   (doc-tooling, not part of the generator — see `doc/Python_Scripts.md` §8) built from
   `doc/TRO_Katalog/connect.ini`.
9. **`doc/Datenquellen_Layout_Hardwareplanung.md`** — which TRO/SCL data comes from the
   mechanical layout (CSV), which from the hardware planning (EA list, TIA import,
   WSCAD, `positionsdraw`) and which is a default; two reference call sites annotated
   line by line. The full raw field lists of both sources are in
   `doc/Klassenhierarchie.md`, chapter "Daten".
10. **`doc/Konzept_Layout_Hardware_SCL.md`** — the target workflow (planned, not built):
    layout → `<csv>_tro.json` (with slots, `jamAreas`), hardware planning →
    `hw_import.py` → `<projekt>_hw.json`, `hw_assign.py` → `<csv>_anlage.json`,
    then `scl_skeleton.py`; what happens to `e_planning.py` (split),
    `tro_annotate.py` (viewer reading the JSON) and `tro_extract.py` (dropped).

### Used libraries (referenced but not vendored)

Most `FB_ILS_MTRO_*` types exist in this repo **only as `.liblink`** references to an
external `ILSLib` library — the actual FB source is not in this Git repo.
`doc/TRO_Katalog/scl_templates/*.scl` contains the real **call-site/instantiation code**
(parametrization in `FB_Main`) for those types, not the FB body. Only a few types have
local, fully-vendored SCL source (`FB_ILS_MTRO_Vario_workStation`, `FB_EmptyCarrBuffer`,
`FB_LoadingBoom_INBOUND`, `FB_ILS_MTRO_2Sep1Swi` — the last one unused/orphaned). Treat
`doc/TRO_Katalog/scl_templates/*.scl` as **read-only reference material** for pattern
extraction, not code to execute or modify.

## Roadmap: CSV → TRO-JSON → SCL (first version implemented)

Since 2026-10-09 the main path is **CSV → `tro_flow.py --json` → TRO-JSON →
`scl_skeleton.py` → SCL**. Layer order (who may import whom): `tro_catalog.py` (TRO *types*)
← `lib/model.py` (TRO *instances* and the TRO-JSON: `TroBase` → `DerivedTro`, `Connection`,
`TroCandidate`, `Analysis`, `TroDocument`) ← derivation (`material_flow.py`, `tro_flow.py`) ←
outputs (`scl_skeleton.py`, `tro_annotate.py`, reports). `items`/`fbType` are always read
from the catalog via the TRO type, never stored. See `doc/Python_Scripts.md` §6b.
Inside the SCL output, `lib/scl_context.py` (TRO-JSON → render context, all derivations)
sits between `model.py` and `scl_skeleton.py` (context → text only). With `--templates`
(opt-in) REGIONs come from Jinja2 templates in `lib/scl_templates/<fbType>.scl.j2`
(pilot: `FB_ILS_MTRO_1Sep1Swi`), each round-trip tested against its reference call site
in `doc/TRO_Katalog/scl_templates/` (`tests/test_scl_templates.py`); every line holding a
placeholder must carry `TODO(E-Planung)`. Migration steps, decisions per template line
and status: `doc/SCL_Templates.md`. Golden files in `tests/fixtures/scl/` pin the SCL output byte for
byte — rewrite them (`SKEL_UPDATE_GOLDEN=1`) only for a reviewed, intended change.

1. **`lib/tro_flow.py --json`** (implemented) — writes `<csv>_tro.json` (schema
   `sps_skel-tro-v4`, `model.TroDocument`): TROs with their hardware `slots`, system
   boundaries `SYSn`, connections with their kind, `jamAreas` (one per TRO entry, key
   `J<Separator>`, all predecessors that feed it), findings. TRO-IDs come from `cfg/<csv>_tro_ids.ini` (`lib/tro_ids.py`): each
   TRO is found again by the position of its separators, so IDs survive a new layout export
   (TeileIds do not); `--renumber` renumbers along the material flow, `--ids` points another
   export of the same plant at the same file. See `doc/Python_Scripts.md` §4.
2. **`lib/scl_skeleton.py`** (implemented) — reads that TRO-JSON through `TroDocument` (a
   wrong/renamed key or `items` not matching the catalog stops the run) 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.
3. **`lib/tro_annotate.py`** — **viewer only**: draws the same TROs (same `analyse_tros`
   call as `tro_flow.py`) into a copy of the DXF for a visual check in BricsCAD.
4. **`lib/tro_extract.py`** — **parked**: reads the annotated DXF back into the old
   `sps_skel-tro-extract-v1` JSON, which `scl_skeleton.py` no longer accepts. Not deleted, not
   extended; if drawing edits (`TRO_INSERT`/`TRO_EDIT`) are ever needed again, it should
   write `model.TroDocument`. See `doc/Python_Scripts.md` §5a.
5. **`lib/e_planning.py`** (implemented, first version) — CSV + E-planning
   `*_positionsdraw.json` → `<csv>_eplan.json` (`EplanDocument`): registers the E drawing to
   the CSV (`dxf_registration.py`) and assigns BMKs to layout parts by rules in
   `cfg/e_planning.ini` (distance, target distance, numbering rule `MB = BG + 1`).
   `scl_skeleton.py --eplan` fills separator sensor and stopper valve from it; jam sensors
   and outfeed/switch valves are assigned but not yet placed in the SCL. See
   `doc/Python_Scripts.md` §5c and `doc/E-Planung_Bruecke.md`.

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 — `model.TroDocument` is a TRO-focused
  JSON, not this full schema yet;
- 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);
- `Component` classes per part type (Separator, Switch, Scanner, VarioDrive, …) on the TRO,
  driving the per-part SCL emitters in `scl_skeleton.py`.

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

This project follows the user's standard Python project scaffold convention:

```
sps_skel/
  bin/       environment scripts, plus one .bat/.sh wrapper pair per lib/ CLI tool
  cad/       generated BricsCAD LISP support (tro_types.lsp) for the TROEDIT dialog
  cfg/       config files (INI/JSON); dxf_registration.json holds the persisted,
             verified CSV<->DXF coordinate transform
  data/      input CSV exports — gitignored, not committed
  doc/       documentation — see doc/Python_Scripts.md for the CLI tools, plus the
             domain-model documents listed above
  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 from a layout, write
             them as TRO-JSON (model.py), emit an FB_Main SCL skeleton, and draw
             the TROs into the CAD drawing (see doc/Python_Scripts.md)
  log/       gitignored
  results/   gitignored — CLI tool output (.dot/.svg/.md/.dxf/.scl/.json)
  tests/     unit tests (pytest) — test_model.py for the TRO-JSON model
```

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/`.