Enelix-Utils/CC100Hardware/README.md

# CC100 Hardware

> Status: Implementiert fuer den WAGO Compact Controller 100, Artikel 751-9301,
> mit IP-Symcon ab Version 8.0.

Das Modul bindet die komplette Onboard-I/O des CC100 direkt ueber die von WAGO
dokumentierten Linux-Schnittstellen an:

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

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

| Property | Standard | Bedeutung |
| --- | --- | --- |
| '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 |

Die Hardwarepfade sind im Konfigurationsformular unter **Erweiterte
Hardwarepfade** sichtbar. Dadurch koennen Firmwarevarianten angepasst werden,
ohne den Modulcode zu aendern.

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