Anwenderdoku etwas ergänzt

doc/Anwenderdoku.md

@@ -46,7 +46,9 @@ done
 
 ### Ausgabe des Toolsets
 
-Alle drei oben genannten Teilprogramme erzeugen eine eigene Ausgabedatei. Die Ausgaben der ersten beiden Programme dienen als Eingabe für das folgende. Die Ausgaben des letzten Teilprogrammes `drawdxf.py` sind für den Anwender bestimmt. Zu Informationszwecken können auch die Zwischenergebnisse im "Work"-Ordner geöffnet werden (genauere Informationen zu den Ausgaben in den jeweiligen Abschnitten zu den Teilporgrammen).Als wesentliche Ausgabe nach Aufruf des Gesamtprogramms dienen:
+Alle drei oben genannten Teilprogramme erzeugen eine eigene Ausgabedatei. Die Ergebnisse der ersten beiden Programme dienen als Eingabe für die folgendem. Jedes der genutzten Programme besitzt eine eingebaute Hilfe, wenn man das Programm mit dem Schalter --help aufruft.  
+
+ Die Ausgaben des letzten Teilprogrammes `drawdxf.py` sind für den Anwender bestimmt. Zu Informationszwecken können die Zwischenergebnisse im "Work"-Ordner geöffnet werden (genauere Informationen zu den Ausgaben in den jeweiligen Abschnitten zu den Teilprogrammen). Als wesentliche Ausgabe nach Aufruf des Gesamtprogramms dienen:
 
 - Die .dxf-Datei mit den Kabelwegen: `NamederEingabedatei_cables.dxf`
 - Die tabellarische Aufbereitung der Kabellängen mit zugehörigen Sachnummern für jeden Sensor / Aktor: `NamederEingabedatei_cables.xlsx`
@@ -58,17 +60,36 @@ Nachfolgend sind Infomationen zu den Einzelprogrammen aufgeführt. Diese enthalt
 
 ### Details zu `getpositions.py`
 
+Hier die vorhandenen Schalter des Programms:
+
+```text
+usage: getpositions [-h] -f myfile.dxf [-s] [-r] [-w WRITE] [-c]
+
+fetches the x/y positions from a dxf file
+
+options:
+  -h, --help            show this help message and exit
+  -f myfile.dxf, --filename myfile.dxf
+                        which file should be fetched
+  -s, --sensors         fetch all position of sensors, motors, actors and subdistributors
+  -r, --rack            fetch all positions of all cable racks
+  -w WRITE, --write WRITE
+                        write results into a json file
+  -c, --console         print results to output
+
+```
+
 Das erste Programm im Ablauf bestimmt maßgeblich die Ausgaben der weiteren Programme und ist weiterhin maßgeblich von der Eingabedatei (.dxf-Datei der Anlage) abhängig.
 
 Eine .dxf-Datei (mit standardisierten Merkmalen!) wird in `getpositions.py` eingelesen. Das Programm extrahiert aus der 2D-Zeichnungsdatei alle Anfangs- und Endpunkte der Kabeltrassen sowie alle Positionen der Sensoren / Aktoren und Unterverteiler innerhalb des 2D-Layouts der Anlage. Diese werden gesammelt und in einer temporären Datei abgespeichet (`NamederEingabedatei.json `).  
 Bei der Erstellung der .dxf-Datei, welche vearbeitet werden soll, ist es wichtig, dass die Kabeltrassen konsistent auf den gleichen Layern gezeichnet werden und bei der Erstellung / Positionierung der Sensoren und Aktoren folgendes beachtet wird:
 
-- Sensoren / Aktoren, die ein "x" zur Bestimmung der tatsächlichen Sensorposition enthalten, werden mit Kabeln bis zum "x" versehen
+- Sensoren / Aktoren müssen als Block in der dxf Datei definiert sein und das Attribut "REALE_POSITION=x" enthalten. Das x dieses Attributs kann dann unabhängig von der Beschreibung im Kasten verschoben werden, so dass man dieses auf der echten Sensorposition verschieben kann. Das Kabel wird dann vom Unterverteiler bis zur Position des x erzeugt.
-- Sensoren / Aktoren, die keine tatsächliche markierung enthalten, werden auf die Mitte des Textblockes mit einem Kabel versehen
+- Sensoren / Aktoren, die keine solche Markierung enthalten, werden auf die Mitte des Textblockes mit einem Kabel versehen
 
-Die Ausgabe des Programms ist eine .json-Datei, welche **strukturiert, in Textform** die Infomationen aus der Zeichnungsdatei weitergibt. Nachstehend ein Auszug der .json-Ausgabe des oben gezeigten Layouts.
+Die Ausgabe des Programms ist eine .json-Datei, welche **strukturiert, in Textform** die Informationen aus der Zeichnungsdatei weitergibt. Nachstehend ein Auszug der .json-Ausgabe des oben gezeigten Layouts.
 
-```yaml
+```json
 {
   "sensors": {
     "BG3241": {
@@ -125,19 +146,36 @@ Die Ausgabe des Programms ist eine .json-Datei, welche **strukturiert, in Textfo
 Die Ausgabedatei ist gegliedert in vier große Blöcke:
 
 - **Sensoren und Aktoren** ("sensors"): Enthält alle Sensoren und Aktoren der Anlage mit allen zugewiesenen Informationen.
-- **Unterverteiler** ("distributors"): Enthält die Positionsinfomation der Unterverteiler
+- **Unterverteiler** ("distributors"): Enthält die Positions-Infomation der Unterverteiler
 - **Kabeltrassen** ("racks"): Enthält die Koordinaten der Anfangs und Endpunkte einer Kabeltrasse. Wenn Kabeltrasse als *Polylinie* gezeichnet ist, sind mehrere einzelsegmente aufgeführt (siehe bspw. "Rack_2")
 - **Zuweisung von UV zu Sensoren / Aktoren** ("mapping"): Enthält die Zuweisung von einem Unterverteiler zu allen daran angeschlossenen Sensoren und Aktoren
 
 ### Details zu `routing.py`
 
-Die .json-Ausgabe, welche oben in einem Auszug gezeigt ist, stellt die Daten der .dxf-Datei in einer einfach zu weiterverarbeitetenden Fassung dar. Die ausgegebenben Daten sind jedoch weiterhin im weitesten Sinne "Rohdaten", welche noch weiter behandelt werden müssen. In dem Einzelprogramm `routing.py` wird aus den Daten mithilfe der Funktionen, welche in `plant.py` implementiert sind, eine "virtuelle" Anlage (eng.: *plant*) aufgebaut. Als Eingabe dient lediglich die .json, welche von `getpositions.py` ausgegeben wird.  Hauptfunktionen von `routing.py` bzw. `plant.py` sind:
+Hier die vorhandenen Schalter des Programms:
+
+```text
+usage: routing.py [-h] -f my_positions.json [-c] [-g] [-w WRITE]
+
+Berechne Wege von Sensoren zu Verteilern über Kabeltrassen
+
+options:
+  -h, --help            show this help message and exit
+  -f my_positions.json, --filename my_positions.json
+                        file with all informations about positions gathered from getpositions
+  -c, --console         Ausgabe auf Konsole
+  -g, --graph           Zeichnet den Graphen der Anlage
+  -w WRITE, --write WRITE
+                        erstellt Ausgabe-file für das Zeichnen von Kabeln in drawdxf
+```
+
+Die .json-Ausgabe, welche oben in einem Auszug gezeigt ist, stellt die Daten der .dxf-Datei in einer  maschinen- und menschenlesbarer Fassung dar. Die ausgegebenen Daten sind jedoch weiterhin im weitesten Sinne "Rohdaten", welche noch weiter behandelt werden müssen. In dem Einzelprogramm `routing.py` wird aus den Daten mithilfe der Funktionen, welche in `plant.py` implementiert sind, eine "virtuelle" Anlage (eng.: *plant*) aufgebaut. Als Eingabe dient lediglich die .json, welche von `getpositions.py` ausgegeben wird.  Hauptfunktionen von `routing.py` bzw. `plant.py` sind:
 
 - Aufbauen des "Grundgerüstes" der Anlage bestehend aus Kabeltrassen (Racks)
   - Finden von Schnittpunkten einzelner Racks und Erstellung von expliziten Knoten dort
   - Finden von "eigentlichen" Schnittpunkten und Anpinnen von nahezu verbundenen Racks aneinander
 - Verknüpfen von Sensoren / Aktoren / Unterverteilern mit dem Grundgerüst der Anlage
-  - Finden des nächstgelegenen Racks zu jedem S / A / UV
+  - Finden des nächstgelegenen Racks zu jedem **S**ensor / **A**ktor / **U**nter**V**erteiler
   - Erstellen eines Aufpunktes für die Strecke vom Rack zum S / A / UV
   - Verknüpfen des jeweiligen S / A / UV mit dem Aufpunkt über den kürzesten Weg
 - Erstellen eines Graphen (=mathematisches Modell für netzartige Struktur) zur Anwendung von Wegfindungs-Algorithmen zur Bestimmung der kürzesten Kabelwege von Sensor / Aktor zu Unterverteiler entlang der Racks
@@ -192,6 +230,23 @@ Als weitere Ausgabedatei kann in der Konfigurationsdatei `routing.cfg` die Ausga
 
 ### Details zu `drawdxf.py`
 
+
+Hier die vorhandenen Schalter des Programms:
+
+```text
+usage: drawdxf [-h] -f myfile.json [-d myfile.dxf] [-n NEW]
+
+draws a dxf file with the given cable coordinates
+
+options:
+  -h, --help            show this help message and exit
+  -f myfile.json, --filename myfile.json
+                        this json file contains all cables and its coordinates which should be drawn. Saved with an unique timestamp
+  -d myfile.dxf, --dxf myfile.dxf
+                        this dxf drawing will be copied and the new layer with the cables will be added
+  -n NEW, --new NEW     create a new dxf file with cables in it. Name is basename and a timestamp
+```
+
 Das letzte Einzelprogramm, welches in der Routine aufgerufen wird, dient der Erstellung einer eigenen .dxf-Datei, welche die Kabelwege dastellt. Diese .dxf Datei trägt stets den Namen der Eingabedatei mit der Ergänzung `..._cables.dxf`. Die Datei kann als neue Layer in das bestehende Anlagen-Layout importiert werden, um die Kabelwege zu verifizieren. Die sich aus dem behandelten Beispiel ergebende Datei ist nachfolgend alleine sowie importiert in das Layout dargestellt:
 
 ![easy_cables_allein](img\easy_cables.png)
@@ -209,7 +264,7 @@ Die in den Details zu `getpositions.py` beschriebene Handhabung der Verbindung d
 
 ### Wo stelle ich ein, was das Toolset am Ende ausspuckt?
 
-Hier müssen wir das mit der einzelnen Konfig noch implementieren
+Hier müssen wir das mit der einzelnen Config noch implementieren
 
 ### Warum werden manche Kabeltrassen nicht mit anderen verbunden?
 
@@ -241,12 +296,12 @@ Schritt 2: Bei Ausbleiben eines Schnittpunktes -> Vergrößern des Kreises. Bei
 
 # Ideen für "Umbau" de Programme
 
-- Eine Konfig in der unter mehreren Blöcken ## Routing ##, ##Ausgabe## die einzelnen Schalter 1 / 0 gesetzt werden
+- 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 
   - -> damit werden alte positions.json überschrieben und work ordner nicht zugemüllt
 - Routing läuft immer -> schreibt output in routing.json
-  - wenn schalter in Konfig für Graph gesetzt ist wird Graph als .svg in work gespeichert
+  - wenn schalter in Config für Graph gesetzt ist wird Graph als .svg in work gespeichert
     - Name der Datei *eingabefile*_graph.svg
 - Drawdxf umbennen in sowas wie *cables.py* oder so
   - Schalter steuern was alles ausgegeben wird (Excel, dxf, ... was könnte man noch machen)