Anwenderdoku um Beispiele für Fehlerfälle ergänzt.

2025-12-18 16:17:03 +01:00
parent 57765706f7
commit a731889561
2 changed files with 350 additions and 5 deletions
@@ -140,8 +140,7 @@ Für den Fall, dass während des Programmablaufs Fehler auftreten bzw. Fehler im
  - Zeigt alle nicht mit den Kabeltrassen verbundenen Elemente (Sensoren / Aktoren / Unterverteiler) an
  - Gibt neben dem Typen, den Bezeichner und die x, y-Koordinate des Elements zurück
  - Verbindungsfehler möglicherweise aufgrund zu großen Abstandes zur nächsten Kabeltrasse
- ERR-Routing:
-  - Zeigt alle fehlgeschlagenen Kabelverbindungen an
+- ERRORS-Routing  - Zeigt alle fehlgeschlagenen Kabelverbindungen an
  - Fallunterscheidung:
    - Unterverteiler nicht in Layout vorhanden: Unterverteiler ist in der Kennzeichnung der Sensor-Blöcke im Layout erwähnt aber nicht im Layout selbst positioniert. Es wird nur der betroffene Unterverteiler angezeigt. Keine explizite Auflistung aller damit ebenfalls nicht verbundenen Sensoren / Aktoren
    - Unterverteiler **und** Sensor / Aktor nicht angebunden: Sowohl Sensor als auch Aktor sind nicht mit den Kabeltrassen verbunden. Beide damit auch in *ERR-Equipment-Conncetion* aufgeführt
@@ -748,8 +747,8 @@ Schritt 2: Bei Ausbleiben eines Schnittpunktes -> Vergrößern des Kreises. Bei
 # Ideen für "Umbau" der Programme

 - Eine Config in der unter mehreren Blöcken ## Routing ##, ##Ausgabe## die einzelnen Schalter 1 / 0 gesetzt werden
- Getpositions läuft immer 
-  - -> scheibt output in positions.json in work 
+- Getpositions läuft immer
+  - -> scheibt output in positions.json in work
  - -> damit werden alte positions.json überschrieben und work ordner nicht zugemüllt
 - Routing läuft immer -> schreibt output in routing.json
  - wenn schalter in Config für Graph gesetzt ist wird Graph als .svg in work gespeichert
@@ -759,3 +758,346 @@ Schritt 2: Bei Ausbleiben eines Schnittpunktes -> Vergrößern des Kreises. Bei
  - hier muss man entscheiden ob Cabel-dxf immer gleich heisst oder so wie Eingabefile (Gefahr der Zumüllung)
  - selbes gilt für excel-File

+# Fehlerfälle und Fehlerbehandlung
+
+## Allgemeine Fehler und Warnungen (beide Workflows)
+
+Die folgende Tabelle zeigt alle möglichen Fehler- und Warnungstypen, die von `getpositions.py` erkannt werden. Diese gelten **für beide Workflows** (Cable Routing und I/O Conversion):
+
+| Fehlertyp | Kategorie | Beschreibung | Ursache | Behebung |
+|-----------|-----------|--------------|---------|----------|
+| `double_ids` | Fehler | Mehrere Blöcke haben dieselbe ID (z.B. MA0062@1) | Doppelte Bauteile mit identischer Kennzeichnung und SPS-Präfix im Layout | IDs eindeutig vergeben oder doppelte Blöcke entfernen |
+| `missing_attributes` | Warnung | Block hat fehlende oder unvollständige Attribute | Block enthält z.B. nur A, B, C, ARTINR aber keine SPS-, IO- oder KENNZEICHNUNG-Attribute | Fehlende Attribute im DXF-Block ergänzen (z.B. SPS, KENNZEICHNUNG) |
+| `missing_distributors` | Fehler | Unterverteiler in KENNZEICHNUNG erwähnt aber nicht im Layout | Sensor verweist auf UV (z.B. UH01) in KENNZEICHNUNG, aber UV-Symbol fehlt im Layout | Unterverteiler-Block im Layout positionieren oder KENNZEICHNUNG korrigieren |
+| `missing_sensors` | Fehler | Sensor/Aktor nicht gefunden | Sensor wird in Mappings referenziert, aber Block fehlt oder hat ungültige Attribute | Sensor-Block im Layout ergänzen oder fehlerhafte Attribute korrigieren |
+| `missing_tunnel` | Fehler | Tunnel hat weniger als 2 Positionen | Tunnel-Eingang oder -Ausgang fehlt (TUNNEL-Block oder MTEXT mit Muster `TUNNEL<nr>-<länge>`) | Zweiten Tunnel-Eingang/Ausgang im Layout ergänzen |
+| `overdefined_tunnel` | Fehler | Tunnel hat mehr als 2 Positionen | Mehr als zwei TUNNEL-Blöcke mit demselben Namen (z.B. TUNNEL2 dreimal) | Überzählige Tunnel-Positionen entfernen |
+| `tunnel_missing_length` | Warnung | Tunnel-Block hat kein LAENGE-Attribut | LAENGE-Attribut fehlt in Tunnel-Block, Default-Länge (5m) wird verwendet | LAENGE-Attribut im Tunnel-Block ergänzen |
+| `mapping_warnings` → `keine KENNZEICHNUNG vorhanden` | Warnung | KENNZEICHNUNG-Attribut fehlt komplett | Block hat kein KENNZEICHNUNG-Attribut | KENNZEICHNUNG-Attribut im Format `=<Anlage>+<UV>-<Karte>` ergänzen |
+| `mapping_warnings` → `Ungültiger Pfad in Kennzeichnung` | Warnung | KENNZEICHNUNG hat falsches Format | Trennzeichen `+`, `-` oder `=` fehlen oder falsch positioniert | KENNZEICHNUNG-Format korrigieren (z.B. `=A01+UH01-KF1DQ04`) |
+| `missing_sps_prefix` | Fehler | SPS-Präfix fehlt für Block-ID | Beim Zusammenführen von Blöcken fehlt der SPS-Präfix | SPS-Attribut in Block ergänzen |
+
+## Detaillierte Beschreibung der Warnungen (Warnings)
+
+Warnungen (Warnings) sind **nicht-kritische Probleme**, bei denen das Programm zwar fortfahren kann, aber das Ergebnis möglicherweise unvollständig oder fehlerhaft ist. Im Gegensatz zu Fehlern führen Warnungen nicht zum Abbruch, sollten aber trotzdem behoben werden, um die Qualität der Ausgabe zu gewährleisten.
+
+### 1. `missing_attributes` (Fehlende oder unvollständige Block-Attribute)
+
+**Was wird geprüft:**
+- Jeder Block im Layout sollte mindestens zwei zusammengehörige Blöcke haben (z.B. einen für das Bauteil und einen für das Kabel)
+- Blöcke müssen bestimmte Pflichtattribute enthalten (z.B. SPS, KENNZEICHNUNG, ARTINR)
+
+**Wann tritt die Warnung auf:**
+- Nur ein einzelner Block mit einer bestimmten ID gefunden wird
+- Der Block hat fehlende Attribute (z.B. kein SPS-Präfix, keine KENNZEICHNUNG)
+- Die Block-Zuordnung ist unvollständig
+
+**Beispiel-Warnung:**
+```json
+"missing_attributes": {
+  "BX0101": "Nur ein Block und/oder fehlende Attribute: dict_keys(['A', 'B', 'C', 'ARTINR'])"
+}
+```
+
+**Mögliche Ursachen:**
+- Block wurde nur einmal statt zweimal gezeichnet (Rahmen innen/außen fehlt)
+- Attribute wie `SPS`, `KENNZEICHNUNG` oder `IO` wurden nicht ausgefüllt
+- Block-Kopie beim Zeichnen vergessen
+
+**Behebung:**
+- Überprüfen Sie den betroffenen Block im DXF-Layout
+- Ergänzen Sie fehlende Attribute (besonders SPS, KENNZEICHNUNG)
+- Falls nötig, korrigieren Sie die Block-Struktur gemäß den Layoutrichtlinien
+
+**Auswirkung:**
+- Der betroffene Block wird **nicht verkabelt** und **nicht in die Ausgabe** übernommen
+- Keine Kabellängenberechnung für dieses Bauteil
+- Block erscheint nicht in der Stückliste
+
+---
+
+### 2. `tunnel_missing_length` (Fehlende Längenangabe bei Tunnel)
+
+**Was wird geprüft:**
+- Jeder Tunnel-Block sollte ein Attribut `LAENGE` haben, das die physische Länge des Tunnels angibt
+- Alternativ kann die Länge über MTEXT-Eintrag (`TUNNEL<nr>-<länge>`) definiert werden
+
+**Wann tritt die Warnung auf:**
+- Ein Tunnel wurde gefunden, aber das `LAENGE`-Attribut fehlt oder ist leer
+- Keine Längenangabe in der MTEXT-Beschriftung vorhanden
+
+**Beispiel-Warnung:**
+```json
+"tunnel_missing_length": {
+  "TUNNEL1": "Tunnel 'TUNNEL1' hat keine LAENGE-Angabe. Verwende Default-Länge: 5m"
+}
+```
+
+**Mögliche Ursachen:**
+- Das `LAENGE`-Attribut wurde beim Zeichnen des Tunnel-Blocks vergessen
+- MTEXT-Beschriftung folgt nicht dem erwarteten Muster (`TUNNEL<nr>-<länge>`)
+- Tunnel wurde aus älterer Layoutversion übernommen, wo Längenangaben noch nicht Pflicht waren
+
+**Behebung:**
+- Öffnen Sie den Tunnel-Block im DXF-Layout
+- Fügen Sie das Attribut `LAENGE` hinzu und tragen Sie die tatsächliche Tunnel-Länge in Metern ein
+- Alternativ: Verwenden Sie MTEXT im Format `TUNNEL1-12.5` (für 12,5 Meter)
+
+**Auswirkung:**
+- Es wird eine **Default-Länge von 5 Metern** verwendet
+- Die Kabellängenberechnung kann dadurch **ungenau** sein
+- In der Routing-Berechnung wird mit dem Default-Wert gearbeitet, was zu falschen Kabellängen führen kann
+
+---
+
+### 3. `mapping_warnings` (Probleme bei KENNZEICHNUNG-Zuordnung)
+
+**Was wird geprüft:**
+- Jeder Sensor/Aktor sollte ein Attribut `KENNZEICHNUNG` haben
+- Die KENNZEICHNUNG muss dem Format `=<Anlage>+<UV>-<Karte>` entsprechen (z.B. `=AH01+UH02-KF1FDI7`)
+- Die Zuordnung zu einem Unterverteiler muss eindeutig möglich sein
+
+**Wann tritt die Warnung auf:**
+
+#### 3a. "keine KENNZEICHNUNG vorhanden"
+- Das Attribut `KENNZEICHNUNG` fehlt komplett im Block
+
+**Beispiel-Warnung:**
+```json
+"mapping_warnings": {
+  "MA0099": "keine KENNZEICHNUNG vorhanden"
+}
+```
+
+**Ursachen:**
+- Attribut wurde beim Erstellen des Blocks vergessen
+- Block-Template war unvollständig
+- Manuelle Bearbeitung hat das Attribut gelöscht
+
+**Behebung:**
+- Fügen Sie das Attribut `KENNZEICHNUNG` im Block hinzu
+- Tragen Sie den korrekten Wert ein (z.B. `=A01+UH01-KF1DQ04`)
+
+**Auswirkung:**
+- Sensor/Aktor wird **nicht verkabelt**
+- Keine Zuordnung zu einem Unterverteiler möglich
+- Element erscheint nicht in der Kabelberechnung
+
+---
+
+#### 3b. "Ungültiger Pfad in Kennzeichnung"
+- KENNZEICHNUNG ist vorhanden, aber das Format stimmt nicht
+- Trennzeichen (`=`, `+`, `-`) fehlen oder sind falsch positioniert
+- Es werden nicht genau drei Teile (Anlage, UV, Karte) erkannt
+
+**Beispiel-Warnungen:**
+```json
+"mapping_warnings": {
+  "BG3240": "Ungültiger Pfad in Kennzeichnung: UH01-KF1DQ04: +, - oder = fehlen an entsprechender Stelle, keine drei Teile sichtbar",
+  "MA0062": "Ungültiger Pfad in Kennzeichnung: AH01+UH02"
+}
+```
+
+**Mögliche Ursachen:**
+- Falsches Format verwendet (z.B. `UH01-KF1DQ04` statt `=A01+UH01-KF1DQ04`)
+- Trennzeichen fehlen (z.B. `AH01UH02KF1DQ04`)
+- Nur Teile der Kennzeichnung eingetragen (z.B. nur `AH01+UH02` ohne Kartenangabe)
+- Sonderzeichen oder Leerzeichen in der Kennzeichnung
+
+**Behebung:**
+- Korrigieren Sie die KENNZEICHNUNG im Block
+- Verwenden Sie das korrekte Format: `=<Anlage>+<UV>-<Karte>`
+- Beispiel: `=AH01+UH02-KF1FDI7`
+- Achten Sie auf die **exakte Position** von `=`, `+` und `-`
+
+**Auswirkung:**
+- Sensor/Aktor wird **nicht verkabelt**
+- Keine Zuordnung zu einem Unterverteiler möglich
+- Element erscheint nicht in der Kabelberechnung
+
+---
+
+### Zusammenfassung: Umgang mit Warnungen
+
+**Wichtig:** Auch wenn das Programm bei Warnungen fortfährt, sollten diese **nicht ignoriert** werden. Warnungen führen oft dazu, dass:
+- Bauteile nicht verkabelt werden
+- Kabellängen falsch berechnet werden
+- Stücklisten unvollständig sind
+
+**Empfohlene Vorgehensweise:**
+1. Prüfen Sie nach jedem Programmlauf, ob eine `*_errors.json`-Datei erstellt wurde
+2. Arbeiten Sie alle Warnungen systematisch ab
+3. Führen Sie das Programm erneut aus, bis keine Warnungen mehr auftreten
+4. Dokumentieren Sie wiederkehrende Probleme und passen Sie ggf. die Block-Templates an
+
+---
+
+## Cable Routing spezifische Fehler
+
+Die folgenden Fehler treten **nur im Cable Routing Workflow** (`getexdraw.bat`) auf. Sie werden während der Routing- und Zeichnungsphase erkannt und in der Excel-Datei `*_cables.xlsx` als separate Worksheets ausgegeben.
+
+### Fehlertypen im Routing-Prozess
+
+| Fehlertyp | Ausgabe in Excel | Beschreibung | Ursache | Behebung |
+|-----------|------------------|--------------|---------|----------|
+| **Equipment Connection Errors** | `ERR-Equipment-Connection` | Sensoren, Aktoren oder Unterverteiler können nicht mit Kabeltrassen verbunden werden | Abstand zur nächsten Kabeltrasse überschreitet die konfigurierte Toleranz (Standard: 5000 mm) | Position des Elements anpassen oder Kabeltrasse näher zum Element verlegen; Toleranz in `allgemein.cfg` unter `[Sensoren]` → `ConnectionTolerances` erhöhen |
+| **Routing Errors** | `ERR-Routing` | Kabelweg zwischen Unterverteiler und Sensor/Aktor kann nicht berechnet werden | Keine Verbindung im Graph zwischen Start- und Zielpunkt; UV oder Sensor nicht angebunden; fehlende Kabeltrasse | Kabeltrassen-Geometrie prüfen und Lücken schließen; fehlende Unterverteiler ergänzen; Equipment-Connection-Fehler beheben |
+| **Tunnel Connection Errors** | `ERR-Equipment-Connection` | Tunnel-Eingang oder -Ausgang kann nicht mit Kabeltrassen verbunden werden | Tunnel-Position liegt zu weit von nächster Kabeltrasse entfernt | Tunnel-Position anpassen oder Kabeltrasse zum Tunnel verlegen |
+
+### Detail-Beschreibungen der Routing-Fehler
+
+#### Equipment Connection Errors (ERR-Equipment-Connection)
+
+**Was wird geprüft:**
+- Jedes Equipment-Element (Sensor, Aktor, Unterverteiler, Tunnel) muss innerhalb der konfigurierten Toleranz zu einer Kabeltrasse liegen
+- Die Toleranz ist in `allgemein.cfg` unter `[Sensoren]` → `ConnectionTolerances` definiert (Standard: 3000 mm)
+
+**Ausgabe in Excel:**
+Das Worksheet `ERR-Equipment-Connection` enthält folgende Spalten:
+- **Type**: Art des Elements (Sensor / Actuator, Subdistributor, Tunnel)
+- **ID**: Bezeichner des Elements (z.B. MA0062, UH01)
+- **x, y**: Koordinaten der Position im Layout
+
+**Beispiel:**
+| Type | ID | x | y |
+|------|-----|------|------|
+| Sensor / Actuator | MA0062 | 15000 | 8000 |
+| Subdistributor | UC0105 | 2000 | 12000 |
+
+**Mögliche Ursachen:**
+- Element wurde zu weit entfernt von Kabeltrassen platziert
+- Kabeltrasse endet vor dem Equipment
+- Falscher Layer für Kabeltrassen verwendet (nicht in `allgemein.cfg` konfiguriert)
+- `REALE_POSITION`-Attribut zeigt auf falsche Position
+
+**Behebung:**
+1. Öffnen Sie das Layout und navigieren Sie zu den angegebenen Koordinaten
+2. Prüfen Sie den Abstand zur nächsten Kabeltrasse
+3. Verschieben Sie entweder das Element näher zur Trasse oder verlängern Sie die Trasse
+4. Alternativ: Erhöhen Sie die `ConnectionTolerances` in `allgemein.cfg` (nicht empfohlen für Produktivbetrieb)
+
+**Auswirkung:**
+- Element wird **nicht verkabelt**
+- Keine Kabellängenberechnung für dieses Element
+- Element erscheint nicht in der Kabelübersicht
+- Folge-Fehler in `ERR-Routing` möglich
+
+---
+
+#### Routing Errors (ERR-Routing)
+
+**Was wird geprüft:**
+- Für jede Sensor-Unterverteiler-Verbindung muss ein Pfad im Kabeltrassen-Graph existieren
+- Der Graph basiert auf den Kabeltrassen-Geometrien und den Equipment-Verbindungen
+
+**Ausgabe in Excel:**
+Das Worksheet `ERR-Routing` enthält folgende Spalten:
+- **Subdistributor**: Unterverteiler-ID (z.B. UH01)
+- **Sensor / Actuator**: Element-ID (z.B. MA0062)
+- **Details**: Detaillierte Fehlerbeschreibung
+
+**Mögliche Fehlermeldungen:**
+- `"Distributor not found in given layout"` - UV in KENNZEICHNUNG erwähnt, aber nicht im Layout vorhanden
+- `"Subdistributor and sensor / actuator not connected to racks"` - Beide Endpunkte nicht angebunden
+- `"Sensor / actuator not connected to racks"` - Nur Sensor nicht angebunden (siehe ERR-Equipment-Connection)
+- `"Subdistributor not connected to racks"` - Nur UV nicht angebunden (siehe ERR-Equipment-Connection)
+- `"Failed routing (not caused by missing connection)"` - Andere Routing-Probleme (z.B. Lücke im Kabeltrassen-Netz)
+
+**Beispiel:**
+| Subdistributor | Sensor / Actuator | Details |
+|----------------|-------------------|---------|
+| UH01 | MA0062 | Sensor / actuator not connected to racks |
+| UC0105 | - | Distributor not found in given layout |
+| UH02 | BG3240 | Failed routing (not caused by missing connection) |
+
+**Mögliche Ursachen:**
+- Equipment-Connection-Fehler (siehe oben)
+- Fehlende oder fehlerhafte KENNZEICHNUNG (Verweis auf nicht existierenden UV)
+- Lücke im Kabeltrassen-Netz (zwei nicht verbundene Trassen-Abschnitte)
+- Fehlende Kabeltrassen-Verbindung zwischen zwei Ebenen
+- Tunnel nicht korrekt definiert
+
+**Behebung:**
+1. **Bei "Distributor not found in given layout":**
+   - Prüfen Sie, ob der UV-Block im Layout vorhanden ist
+   - Prüfen Sie die KENNZEICHNUNG der betroffenen Sensoren
+   - Fügen Sie fehlenden UV hinzu oder korrigieren Sie die KENNZEICHNUNG
+
+2. **Bei Connection-Fehlern:**
+   - Beheben Sie zuerst die Equipment-Connection-Fehler aus `ERR-Equipment-Connection`
+   - Führen Sie das Programm erneut aus
+
+3. **Bei "Failed routing":**
+   - Prüfen Sie visuell die Kabeltrassen zwischen UV und Sensor
+   - Suchen Sie nach Lücken oder fehlenden Verbindungen
+   - Prüfen Sie, ob alle Kabeltrassen auf den konfigurierten Layern liegen
+   - Verwenden Sie die `--graph` Option von `routing.py` zur Visualisierung des Graphen
+
+**Auswirkung:**
+- Betroffene Kabelverbindung wird **nicht berechnet**
+- Keine Kabellänge in der Ausgabe
+- Kabel fehlt in Stückliste
+- Kabel wird nicht in DXF gezeichnet
+
+---
+
+#### Tunnel Connection Errors
+
+**Was wird geprüft:**
+- Tunnel-Eingänge und -Ausgänge müssen wie normale Equipment-Elemente mit Kabeltrassen verbindbar sein
+- Beide Tunnel-Positionen müssen innerhalb der ConnectionTolerances liegen
+
+**Ausgabe in Excel:**
+Tunnel-Connection-Fehler erscheinen im Worksheet `ERR-Equipment-Connection` mit Type = "Tunnel"
+
+**Mögliche Ursachen:**
+- Tunnel-Block wurde zu weit von Kabeltrasse positioniert
+- Tunnel-Position falsch eingetragen (MTEXT oder Block-Attribut)
+- Kabeltrasse endet vor Tunnel-Ein-/Ausgang
+
+**Behebung:**
+1. Prüfen Sie die Tunnel-Positionen im Layout
+2. Verlängern Sie Kabeltrassen bis zu den Tunnel-Positionen
+3. Korrigieren Sie ggf. die Tunnel-Positionen
+4. Prüfen Sie, ob beide Tunnel-Enden (Ein- und Ausgang) definiert sind
+
+**Auswirkung:**
+- Tunnel kann nicht für Routing verwendet werden
+- Kabelwege, die durch den Tunnel führen sollten, schlagen fehl
+- Längere Kabelwege über alternative Routen (falls vorhanden)
+
+---
+
+### Hinweise zur Excel-Fehlerausgabe (Cable Routing)
+
+Die Fehler-Worksheets in `*_cables.xlsx` erscheinen **nur**, wenn tatsächlich Fehler aufgetreten sind:
+- **ERR-Equipment-Connection** - nur bei Connection-Fehlern
+- **ERR-Routing** - nur bei Routing-Fehlern
+- **ERR-Attributes** - nur bei Attribut-Fehlern (aus getpositions)
+
+**Workflow zur Fehlerbehebung:**
+1. Öffnen Sie `*_cables.xlsx` und prüfen Sie, welche ERR-Worksheets vorhanden sind
+2. Beheben Sie **zuerst** die Equipment-Connection-Fehler
+3. Führen Sie das Programm erneut aus
+4. Beheben Sie verbleibende Routing-Fehler
+5. Wiederholen Sie, bis keine ERR-Worksheets mehr erstellt werden
+
+---
+
+## I/O Conversion Workflow - Hinweise
+
+Der **I/O Conversion Workflow** (`ioconverter.bat`) führt **keine Routing-Berechnungen** durch und erzeugt daher auch keine Routing-spezifischen Fehler. Es werden ausschließlich die **allgemeinen Fehler und Warnungen** aus `getpositions.py` gemeldet (siehe [Allgemeine Fehler und Warnungen](#allgemeine-fehler-und-warnungen-beide-workflows)).
+
+### Ausgabedateien bei Fehlern
+
+- `*_errors.json` - enthält alle Fehler und Warnungen aus getpositions
+- `*_positionsconv.json` - Zwischenergebnis mit extrahierten Positionen
+- `*_TIA.xlsx`, `*_WSCAD.xlsx`, etc. - werden auch bei Warnungen erzeugt, können aber unvollständig sein
+
+### Wichtige Hinweise
+
+- **Fehlende Attribute** führen dazu, dass Elemente in den Export-Dateien fehlen
+- **Fehlende KENNZEICHNUNG** verhindert die korrekte Zuordnung zu Unterverteilern
+- **Doppelte IDs** können zu falschen Einträgen in den Excel-Listen führen
+
+**Empfehlung:** Beheben Sie alle Warnungen aus `*_errors.json`, bevor Sie die Export-Dateien an nachgelagerte Systeme (TIA Portal, WSCAD) übergeben.