CalcChecksum

The CalcChecksum method is an advanced Docklight Scripting feature and requires some knowledge about checksums in serial application protocols, and how Docklight deals with send data in general.

TIP: We recommend the section Generating Checksums for Send Sequences for introduction. If the CRC-specific terms and parameters seem confusing to you, see the CRC Glossary for some background information.

result = DL.CalcChecksum( checksumSpec, dataStr, [, representation] [, startPos] [, endPos] )

Part	Description
checksumSpec	Required. String that specifies the checksum algorithm and its parameters. CalcChecksum supports predefined names for common checksum algorithms, or you can pass a generic CRC specification for calculating more exotic CRCs. Predefined names are: "MOD256", "CRC-CCITT", "CRC-16", "CRC-MODBUS" and "CRC-32" See below for details and examples.
dataStr	Required. String value that contains the input Sequence for the checksum calculation, as for example returned by the OnSend_GetData() function.
representation	Optional. String value to define the format for dataStr Sequence: "H" = Hex (default), "A" = ASCII , "D" = Decimal or "B" = Binary.
startPos	Optional Integer value. Specifies the character position where the calculation should start. Default value is 1 (beginning of the dataStr Sequence).
endPos	Optional Integer value. Specifies the last character that should be included in the calculation. Default value is the size of the dataStr Sequence.

Value	Description
"MOD256"	Calculates an 8 bit checksum: Sum on all bytes, modulo 256.
"XOR"	Calculates an 8 bit checksum: XOR on all bytes
"CRC-7"	Calculates an 7 bit with CRC used for example in MMC/SD card applications. This is equal to passing the following checksumSpec string: "CRC:7,09,00,00,No,No" See the "CRC:..." syntax described in the last row for details.
"CRC-8"	Calculates an 8 bit width CRC, e.g. for ATM Head Error Correction. Equals to: "CRC:8,07,00,00,No,No"
"CRC-DOW"	Calculates an 8 bit width CRC known as DOW CRC or CCITT-8 CRC. Can be found in Dallas iButton(TM) applications. Equals to: "CRC:8,31,00,00,Yes,Yes"
"CRC-CCITT"	Calculates a 16 bit width CRC as designated by CCITT. Equals to: "CRC:16,1021,FFFF,0000,No,No"
"CRC-16"	Calculates a 16 bit width CRC as used in IBM Bisynch, ARC. Equal to: "CRC:16,8005,0000,0000,Yes,Yes"
"CRC-MODBUS"	Calculates a 16 bit width CRC as used in MODBUS. It is actually a CRC-16, but with an init value of FFFF: "CRC:16,8005,FFFF,0000,Yes,Yes"
"CRC-32"	Calculates a 32 bit CRC as used in PKZip, AUTODIN II, Ethernet, FDDI. Equal to: "CRC:32,04C11DB7,FFFFFFFF,FFFFFFFF,Yes,Yes"
"CRC:width, polynomial, init, finalXOR, reflectedInput, reflectedOutput"	Generic CRC computer where all CRC parameters can be set individually: width : The CRC width from 1..32. polynomial : HEX value. The truncated CRC polynomial. init : HEX value. The initial remainder to start off the calculation. finalXor : HEX value. Apply an XOR operation on the resulting remainder before returning it to the user. reflectedInput : Yes = Reflect the data bytes (MSB becomes LSB), before feeding them into the algorithm. reflectedOutput : Yes = Reflect the result after completing the algorithm. This takes places before the final XOR operation.

The return value is a string with the CRC/checksum in the Docklight HEX sequence format, e.g. "CB F4 39 26". The number of HEX bytes returned depends on the width of the checksum algorithm. See the example script and communications window output below.

Each of the predefined CRC algorithms can actually be replaced by a specification string for the generic CRC computer described above. We have carefully tested and cross-checked our implementations against the common literature and resources as listed in the CRC Glossary.

There is an awful lot of different CRC variations and algorithms kicking around, and choosing (not to mention: understanding) the right CRC flavor is a pretty difficult job. A good way to make sure your CRC calculation makes sense is running an ASCII test string "123456789" through it. This is the most commonly used testing string, and many specifications will refer to this string and provide you the correct checksum your CRC should return when applied on this string.

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-MODBUS", "123456789", "A")

DL.AddComment "Note: 4B is the high byte, 37 is the low byte. MODBUS transmits the other way round!"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-CCITT", "123456789", "A")

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC:16,1021,FFFF,0000,No,No", "123456789", "A")

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("CRC-32", "01 02 03 04 05", "H")

The above script code produces the following output in the Docklight communication window:

Note: 4B is the high byte, 37 is the low byte. MODBUS transmits the other way round!