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 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:

• 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. 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
• 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

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) and ezdxf>=1.4.0 (DXF read/write, tro_annotate.py only); pytest is commented out as not yet needed.

There is no build/lint/test command configured yet — tests/ is empty and no test runner or linter is set up. Once tests exist, use pytest (already anticipated in requirements.txt, just commented out) and set PYTHONPATH via bin/setenv first so imports resolve against lib/.

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

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: DXF → JSON → SCL (planned, not 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:

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.

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.

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 / CAD annotations from a
             layout (see doc/Python_Scripts.md); the JSON-driven SCL generator itself
             is not yet written
  log/       gitignored
  results/   gitignored — CLI tool output (.dot/.svg/.md/.dxf)
  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/.