feat(utils): adapt WAGO CC100 hardware module

docs/module/CC100-Hardware/README.md

@@ -1,29 +1,136 @@
 # CC100 Hardware
 
-> Status: Diskussionsentwurf. Keine EMS-Abhängigkeit.
+> Status: Implementiert fuer den WAGO Compact Controller 100, Artikel 751-9301,
+> mit IP-Symcon ab Version 8.0.
 
-Stellt nur ausgewählte DI-, DO-, PT-, AI- und AO-Kanäle bereit. Kanal,
-Anzeigename, Aktivierung und Abfrageintervall werden je Eintrag festgelegt.
+Das Modul bindet die komplette Onboard-I/O des CC100 direkt ueber die von WAGO
+dokumentierten Linux-Schnittstellen an:
 
-## Variablen
+- 8 digitale Eingaenge (DI)
+- 4 digitale Ausgaenge (DO)
+- 2 analoge Eingaenge 0 bis 10 V (AI)
+- 2 analoge Ausgaenge 0 bis 10 V (AO)
+- 2 PT1000-Temperatureingaenge (PT)
 
-| Ident | Typ / Zugriff | Beschreibung |
-| --- | --- | --- |
-| Dynamisch je Kanal | passend / Anzeige oder bedienbar | Nur ausgewählte Kanäle; DO/AO erst nach geprüfter Zuordnung bedienbar. |
-| `Hardwarestatus` | Integer / Anzeige | Anschlussstatus. |
-| `Stoertext` | String / Anzeige | Zugriffs- oder Messfehler. |
+## Kanalauswahl
+
+Die Property 'Kanalauswahl' enthaelt alle 18 Kanaele. Pro Zeile werden
+Aktivierung, Typ, Kanalnummer, Anzeigename und Abfrageintervall festgelegt.
+Nur aktive Kanaele werden als IP-Symcon-Variablen angelegt. Wird ein Kanal
+deaktiviert, entfernt das Modul seine dynamische Variable beim naechsten
+Uebernehmen der Konfiguration.
+
+DO- und AO-Variablen sind bedienbar. DI, AI und PT sind reine Messwerte.
+AI und AO werden in Volt dargestellt, PT in Grad Celsius.
 
 ## Properties
 
-| Ident | Typ | Standard / Beschreibung |
+| Property | Standard | Bedeutung |
 | --- | --- | --- |
-| `Kanalauswahl` | String/JSON | `[]`; Kanalart, Nummer, Anzeigename, Aktiv und Abfrageintervall in ms je Zeile. |
-| `StartverhaltenAusgaenge` | Auswahl | `Lesen/uebernehmen` oder definierte Startwerte schreiben. |
-| `StartwerteAusgaenge` | String/JSON | `{}`; nur bei ausdrücklich gewähltem Schreibmodus. |
+| 'Kanalauswahl' | alle Kanaele inaktiv | Sichtbare und abgefragte Kanaele |
+| 'DigitalInputPath' | WAGO-DI-Sammelpfad | 8-Bit-Eingangswert, LSB ist DI1 |
+| 'DigitalOutputPath' | '/sys/kernel/dout_drv/DOUT_DATA' | 4-Bit-Ausgangswert, LSB ist DO1 |
+| 'CalibrationPath' | '/etc/calib' | WAGO-Zweipunktkalibrierung |
+| 'AI1Path', 'AI2Path' | WAGO-IIO-Pfade | Analoge Eingangswerte |
+| 'AO1ValuePath', 'AO2ValuePath' | WAGO-IIO-Pfade | Analoge Ausgangswerte |
+| 'AO1PowerPath', 'AO2PowerPath' | WAGO-IIO-Pfade | Freigabe der analogen Ausgaenge |
+| 'PT1Path', 'PT2Path' | WAGO-IIO-Pfade | PT1000-Rohwerte |
+| 'Debug' | 'false' | Zusaetzliche Diagnose im Debug-Log |
 
-## Verhalten und offene Punkte
+Die Hardwarepfade sind im Konfigurationsformular unter **Erweiterte
+Hardwarepfade** sichtbar. Dadurch koennen Firmwarevarianten angepasst werden,
+ohne den Modulcode zu aendern.
 
-- Beim Start werden Ausgänge nicht ungeprüft überschrieben.
-- Nur ausgewählte Kanäle werden angelegt, abgefragt oder bedient.
-- CC100-Hardwarepfade, Skalierung und Schreibbarkeit von AI/AO prüfen.
-- RS485-Schnittstelle bleibt ein eigener Prüfauftrag.
+## Aktualisierung
+
+Die CC100-Treiber stellen die Onboard-I/O als lesbare beziehungsweise
+schreibbare Systemdateien bereit. Fuer diese Dateien ist von WAGO kein
+zuverlaessiger Aenderungs-Eventkanal dokumentiert. Das Modul verwendet deshalb
+einen gemeinsamen Timer:
+
+1. Das kleinste aktive Kanalintervall bestimmt den Timer.
+2. Pro Lauf werden nur faellige Kanaele verarbeitet.
+3. DI beziehungsweise DO werden je Lauf nur einmal als Sammelwert gelesen.
+4. IP-Symcon-Werte werden nur bei einer echten Wertaenderung geschrieben.
+
+Das Intervall kann pro Kanal zwischen 100 ms und 3 600 000 ms eingestellt
+werden. Kurze Intervalle erhoehen CPU- und I/O-Last.
+
+## Kalibrierung
+
+AI, AO und PT verwenden die individuellen Zweipunktwerte aus '/etc/calib'.
+Das Modul akzeptiert die WAGO-Bezeichnungen 'AO1'/'AO2' sowie die in der
+WAGO-Beispieldatei vorkommenden Schreibweisen 'A01'/'A02'.
+
+- AI-Rohwerte werden kalibriert und von mV nach V umgerechnet.
+- AO-Sollwerte werden von V nach mV und danach invers in den Rohwert umgerechnet.
+- PT-Rohwerte werden zuerst in Ohm und anschliessend mit der
+  Callendar-Van-Dusen-Kennlinie in Grad Celsius umgerechnet.
+
+## Ausgangssicherheit
+
+'ApplyChanges()' schreibt keine Ausgaenge. Beim Start werden DO und AO nur
+eingelesen. Ein DO-Schaltbefehl liest zuerst den gesamten Ausgangswert, aendert
+genau das gewaehlte Bit und erhaelt die anderen Ausgaenge. AO akzeptiert nur
+Werte von 0 bis 10 V und schreibt zuerst die WAGO-Freigabe, danach den
+kalibrierten Rohwert.
+
+Die rekursive Schreibschleife des Enelix-1-Moduls wurde verworfen. Ein
+fehlgeschlagener Schreibzugriff blockiert IP-Symcon nicht bis zu fuenf Sekunden,
+sondern liefert sofort Status '203' und einen Stoertext.
+
+## Variablen
+
+| Ident | Typ | Zugriff |
+| --- | --- | --- |
+| 'DI1' bis 'DI8' | Boolean | Anzeige, nur wenn aktiviert |
+| 'DO1' bis 'DO4' | Boolean | Bedienbar, nur wenn aktiviert |
+| 'AI1', 'AI2' | Float / V | Anzeige, nur wenn aktiviert |
+| 'AO1', 'AO2' | Float / V | Bedienbar, nur wenn aktiviert |
+| 'PT1', 'PT2' | Float / Grad Celsius | Anzeige, nur wenn aktiviert |
+| 'Hardwarestatus' | Integer | '0' unkonfiguriert, '1' bereit, '2' Lesefehler, '3' Fehler |
+| 'Stoertext' | String | Letzter zusammengefasster Fehler |
+
+## Migration aus Enelix 1
+
+### Unveraendert uebernommen
+
+- vier DO, acht DI und zwei PT-Kanaele
+- Bitreihenfolge mit DI1 beziehungsweise DO1 als LSB
+- die vorhandenen WAGO-Systempfade als Standardwerte
+
+### Angepasst
+
+- getrennte feste Timer durch einen gruppierten, kanalspezifischen Poller ersetzt
+- DO-Aktionen lesen den Sammelwert und aendern nur das gewaehlte Bit
+- PT-Auswertung verwendet die individuelle Kalibrierung und Kennlinie
+
+### Neu implementiert
+
+- beide AI- und AO-Kanaele
+- frei waehlbare Kanaele und dynamische Variablen
+- konfigurierbare Intervalle und ueberschreibbare Hardwarepfade
+- Status-, Fehler- und Debugdiagnose
+
+### Verworfen
+
+- rekursives Schreiben mit bis zu fuenf Sekunden Blockierzeit
+- zyklisches Neuschreiben aller DO ohne neuen Schaltbefehl
+- feste PT-Rohwertbereiche und nicht kalibrierte Skalierungsfaktoren
+
+Das alte Modul kann nicht in-place aktualisiert werden. Fuer die Umstellung:
+
+1. Vorhandene Ausgangszustaende und verwendete Kanaele dokumentieren.
+2. Eine neue Instanz 'CC100 Hardware' anlegen.
+3. Benoetigte Kanaele aktivieren und Anzeigenamen vergeben.
+4. Hardwarepfade und Kalibrierdatei pruefen.
+5. Zuerst nur Eingaenge testen.
+6. Ausgaenge einzeln und unter Aufsicht freigeben.
+
+## RS-485
+
+RS-485 gehoert nicht zur Onboard-I/O-Abbildung dieses Moduls. Der CC100 stellt
+die Schnittstelle als '/dev/ttySTM1' bereit. Protokoll, Teilnehmeradressen,
+Baudrate, Paritaet, Registerbereiche und Zeitvorgaben gehoeren in eine separate
+serielle beziehungsweise Modbus-Instanz. So bleibt die I/O-Abfrage unabhaengig
+von langsamen oder fehlerhaften Busteilnehmern.

docs/module/README.md

@@ -1,13 +1,13 @@
 # Modulübersicht Enelix Utils
 
-> Status: Verbrauchskostenreport, Energiediagramm und Shelly Modul sind
-> implementiert. Die übrigen Module sind als Diskussionsentwürfe dokumentiert.
+> Status: Verbrauchskostenreport, CC100 Hardware, Energiediagramm und Shelly
+> Modul sind implementiert. Die übrigen Module sind als Diskussionsentwürfe dokumentiert.
 
 | Modul | Herkunft | EMS-Abhängigkeit |
 | --- | --- | --- |
 | [Verbrauchskostenreport](Verbrauchskostenreport/README.md) | Kosten- und Verbrauchsauswertung | Keine |
 | [Virtuelle Batterie](Virtuelle-Batterie/README.md) | Bat_EV_SDL_V4 | Optionaler Vertrag, keine Code-Abhängigkeit |
-| [CC100 Hardware](CC100-Hardware/README.md) | CC100_HW | Keine |
+| [CC100 Hardware](CC100-Hardware/README.md) | CC100_HW (implementiert) | Keine |
 | [Energiediagramm](Energiediagramm/README.md) | Energy_Pie (implementiert) | Keine |
 | [VGT-Schnittstelle](VGT-Schnittstelle/README.md) | MQTTPVSDL + MQTTBatterySDL | Optional konfigurierbar |
 | [Shelly Modul](Shelly-Modul/README.md) | Shelly_Parser_MQTT | Keine |