Datenkonverter¶

Datenkonverter sind erforderlich, um die über GInOut verfügbaren Byte-Daten typisiert einzulesen oder zu schreiben, z.B. als Ganzzahl.

Folgende Konverter sind in Viper.NET verfügbar:

GenericInputConverter
Byte array -> Byte
Byte array -> Byte array
Byte array -> String
Byte array -> S7 String
Byte array -> Int16 bzw. Int32
Byte array bits -> Bool, Int16 oder Int32
Byte array string -> Int16, Int32, Double
Byte array hex string -> UInt32
GenericArrayConverter
GenericBitArrayConverter
StringArrayConverter

Alle Konverter unterstützen den Parameter

TwistBytes: [True|False] Bei True wird die Reihenfolge der Bytes im Speicher gedreht (niederwertigstes Byte zuerst). Bei False bleibt die Reihenfolge der Bytes unverändert.

Beispiel:

Int16 val = 5;
Byte-Daten [TwistBytes = False]: [0x05][0x00]
Byte-Daten [TwistBytes = True]:  [0x00][0x05]

Für einige Konverter sind zusätzliche Parameter erforderlich.

GenericInputConverter¶

Für den GenericInputConverter muss, im Gegensatz zu den anderen Konvertern, zusätzlich der Zieltyp angegeben werden. Folgende Zieltypen sind verfügbar:

Zieltyp	Datenlänge in Byte
Boolean	1
Byte	1
SByte	1
Char	2
Int16	2
Int32	4
Int64	8
UInt16	2
UInt32	4
UInt64	8
Single (=float)	4
Double	8
Decimal	16

Es muss darauf geachtet werden, dass die erwartete Datenlänge eingehalten wird.

Byte array -> Byte¶

Dieser sehr einfache Converter gibt das erste Byte im Byte-Array zurück bzw. beschreibt dieses.

Byte array -> Byte array¶

Die Bytedaten werden 1:1 übernommen. Allerdings kann es vorkommen, dass die Datenlängen nicht übereinstimmen. Hier müssen zwei Fälle unterschieden werden:

Der Datenbereich in GInOut ist größer als oder gleich groß wie die zu schreibenden Byte-Daten.
- Der Datenbereich in GInOut wird mit „MemSetVal“ aufgefüllt.
Der Datenbereich in GInOut ist kleiner als die zu schreibenden Daten:
- Unzulässig, generiert einen Fehler (Die Daten können nicht geschrieben werden).

Es muss also darauf geachtet werden, dass der Datenbereich ausreichend groß dimensioniert wird.

Zusätzliche Konverterparameter:

Length: Wofür gleich wieder? Bei „-1“ wird die Länge des Datenbereichs verwendet.
MemSetVal: Mit diesem Byte-Wert wird der Datenbereich aufgefüllt, falls die zu schreibenden Daten kürzer sind.

Byte array -> String¶

Dieser Konverter interpretiert Daten als ASCII-codierte Zeichenkette (String). Bei unterschiedlichen Datenlängen gelten die gleichen Regeln wie bei Byte array -> Byte array.

Zusätzliche Konverterparameter:

Length: Wofür gleich wieder? Bei „-1“ wird die Länge des Datenbereichs verwendet.
MemSetVal: Mit diesem Byte-Wert wird der Datenbereich aufgefüllt, falls die zu schreibenden Daten kürzer sind.
TrimCharacters: Auflistung aller Einzel-Character, die das Ende der Zeichenkette darstellen können. Die Zeichen können entweder als ASCII-Zeichen oder in Hex-Schreibweise angegeben werden ([0x31] ist z.B. das Zeichen ‚a‘).

Beispiel:

Datenbereich mit Länge 5, Inhalt in HEX: 3132330000
TrimCharacters [0x00]
Der Konverter liefert hier "123"

Byte array -> S7 String¶

Dieser Konverter interpretiert Daten als S7 STRING:

Konverterparameter:

Capacity: Gibt die maximale Länge des Strings an. Bei „-1“ wird die Länge des Datenbereichs verwendet, was für die meisten Anwendungsfälle korrekt ist.
MemSetVal: Mit diesem Byte-Wert wird der Datenbereich aufgefüllt, falls die zu schreibenden Daten kürzer sind.
TrimCharacters: Auflistung aller Einzel-Character, die das Ende der Zeichenkette darstellen können. Die Zeichen können entweder als ASCII-Zeichen oder in Hex-Schreibweise angegeben werden ([0x31] ist z.B. das Zeichen ‚a‘).

Beispiel:

Data segment with length=5, content in HEX: 3132330000
TrimCharacters [0x00]
Converter returns "123"

Byte array -> Int16 bzw. Int32¶

Diese Konverter wurden durch den GenericInputConverter ersetzt und sind nur noch für die Abwärtskompatibilität erforderlich.

Byte array bits -> Bool, Int16 bzw. Int32¶

Mit den „Byte array bits“-Konvertern werden einzelne Bits aus dem Datenbereich ausgelesen und ein boolscher bzw. Zahlenwert gebildet. Dadurch können einzelne Bits innerhalb eines Bytes ausmaskiert und die Reihenfolge der Bits beeinflusst werden.

Zusätzliche Konverterparameter:

MapWeightToBitIdx: Komma-separierte Liste der Bit-Indices aus dem Datenbereich, die für die Konvertierung verwendet werden. Die Reihenfolge bildet gleichzeitig die Gewichtung.

Beispiel:

Data segment with length=1, value t 0x17. (Binary1: 0b00010111)
MapWeightToBitIdx: 4, 3, 2
Result after conversion: 5 (Bit 4: 1, Bit 3: 0, Bit 2: 1).

Byte array string -> Int16, Int32 bzw. Double¶

Die „Byte array string“-Konverter werden hauptsächlich zur Kommunikation mit Waycom Prodel benötigt, da diese Steuerung ihre Daten ausschließlich in ASCII-codierter Form zur verfügung stellt. Ein Bit in Prodel hat bspw. immer den Wert „0x30“ (LOW) bzw. „0x31“ (HIGH).

Die zusätzlichen Konverterparameter sind analog zu Byte array -> String.

Byte array hex string -> UInt32¶

GenericArrayConverter¶

Mit diesem Konverter können Arrays einfacher Werttypen eingelesen werden. Unterstützt werden dieselben Datentypen wie beim GenericInputConverter. Die Datenlänge ergibt sich aus der Anzahl der Elemente (`Length`), dem ausgewählten Datentyp, sowie zusätzlichen 4 Byte wenn `FixedLength=False` ist.

Zusätzlich zu `TwistBytes` unterstützt dieser Konverter noch folgende Parameter:

MaxCount: Gibt die maximale Anzahl der Elemente im Array an.
FixedCount: [True]: Es sind immer alle Elemente gültig. [False]: Die ersten 4 Byte im Datenbereich die Anzahl geben an, wie viele Elemente im Array gültig sind. Für die Konvertierung dieser Bytes wird der GenericInputConverter für Int32 verwendet.

GenericBitArrayConverter¶

Dieser Konverter ordnet jedem Bit im Datensegment einen von zwei Werten zu, je nachdem ob das Bit 0 oder 1 ist. Durch diese Methode wird Platz im Datensegment eingespart, wenn mehrere boolsche Informationen gleichzeitig übertragen werden sollen.

MaxCount: Gibt die maximale Anzahl der Elemente im Array an.
FixedCount: [True]: Es sind immer alle Elemente gültig. [False]: Die ersten 4 Byte im Datenbereich die Anzahl geben an, wie viele Elemente im Array gültig sind. Für die Konvertierung dieser Bytes wird der GenericInputConverter für Int32 verwendet.
LowVal: Wert im Array wenn das zugehörige Bit 0 ist.
HighVal: Wert im Array wenn das zugehörige Bit 1 ist.

StringArrayConverter¶

Analog zum GenericArrayConverter können mit diesem Konverter Arrays von Zeichenketten konvertiert werden. Die Zeichenketten haben dabei eine maximale Länge. Für die Zeichenketten selbst wird Byte array -> String verwendet.

MaxCount: Gibt die maximale Anzahl der Elemente im Array an.
FixedCount: [True]: Es sind immer alle Elemente gültig. [False]: Die ersten 4 Byte im Datenbereich die Anzahl geben an, wie viele Elemente im Array gültig sind. Für die Konvertierung dieser Bytes wird der GenericInputConverter für Int32 verwendet.
Length: Die maximale Länge einer Zeichenkette im Array.
MemSetVal: Siehe Byte array -> String
TrimCharacters: Siehe Byte array -> String