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 is currently in the design/analysis phase: lib/, tests/, examples/, and cfg/ are empty scaffolding directories (see "Standard Programm Template" structure below). No generator code has been written yet. What exists today is:

• bin/ — environment/venv management scripts (see "Environment scripts" below)
• data/*.scl — real SCL code extracted from an existing plant ("HundM_Fortna", 5 controllers UH01–UH05), used as reference templates for the planned generator
• doc/*.md — analysis documents that reverse-engineer the SCL patterns and propose the JSON schema / code-generation approach

Read doc/ before writing any generator code — it contains the actual domain model this project is meant to implement.

Environment scripts (bin/)

Every script has a .bat (Windows) and .sh (Linux/macOS) pair. None of them invoke a concrete Python script — they only manage the environment and virtualenv.

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

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 currently has no real dependencies pinned yet (placeholders for pydantic, pytest).

There is no build/lint/test command configured yet — tests/ is empty and no test runner or linter is set up. Once code exists in lib/, use pytest (already anticipated in requirements.txt) 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:

1. doc/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.
3. doc/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/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.
5. doc/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/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 the planned shape of the generator, not existing code.

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. data/*.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 data/*.scl as read-only reference material for pattern extraction, not code to execute or modify.

Standard Programm Template

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

sps_skel/
  bin/       environment scripts (see above)
  cfg/       config files (INI/JSON) — empty for now
  data/      input data, gitignored except the .scl reference templates
  doc/       documentation
  examples/  example files — empty for now
  lib/       Python source — empty for now, this is where the generator belongs
  log/       gitignored
  results/   gitignored
  tests/     unit tests — empty for now

When adding the generator, put it under lib/ (importable via SKEL_LIB on PYTHONPATH), keep bin/*.bat/*.sh scripts environment-only (do not add project-specific script invocations to them per the user's convention), and add tests under tests/.