CalcChecksum

<< Click to Display Table of Contents >>

Navigation:  Reference (Scripting) > Docklight Script Commands - The DL Object > Methods (Advanced) >

CalcChecksum

Returns a checksum or CRC value for a given sequence, or a part of a sequence.

 

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 Calculating and Validating Checksums for introduction. If the CRC-specific terms and parameters seem confusing to you, see the CRC Glossary for some background information.

 

Return Value

 

String

 

Syntax

 

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

 

The CalcChecksum method syntax has these parts:

 

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", "XOR", "CRC-8", "CRC-CCITT", "CRC-16", "CRC-MODBUS" and "CRC-32"

See checksumSpec Format for the full format specification.

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 of the 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).

 

startPos also accepts negative values, e.g. -1 for "last character", -2 for "2nd character from the end", -3 for "3rd character from the end".

endPos

Optional Integer value. Specifies the last character that should be included in the calculation. Default value is the size of the dataStr Sequence.

 

endPos also accepts negative values, see startPos above.

 

 

Remarks

 

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 are an awful lot of different CRC variations and algorithms around, and choosing (not to mention - understanding) the right CRC flavor is a rather 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.

 

With the help of CalcChecksum you can generate CRCs for Send Sequences on the fly. See the Sub DL_OnSend() Event Procedure for details. See also the MODBUS protocol example example.  

 

Example

 

' Example CalcChecksum

 

DL.ClearCommWindows

 

DL.AddComment

DL.AddComment "Simple checksum (Mod 256) for '123456789'"

DL.AddComment "CalcChecksum = " & DL.CalcChecksum("MOD256", "123456789", "A")

 

DL.AddComment

DL.AddComment "8 bit CRC (CRC DOW) for '123456789'"

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

 

DL.AddComment

DL.AddComment "16 bit CRC (CRC-16) for '123456789'"

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

 

DL.AddComment

DL.AddComment "16 bit CRC (CRC-MODBUS) for '123456789'"

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

DL.AddComment "16 bit CRC (CRC-CCITT) for '123456789'"

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

DL.AddComment "Now do the same thing, but specify all CRC details yourself..."

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

 

DL.AddComment

DL.AddComment "32 bit CRC (CRC-32) for '123456789'"

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

 

DL.AddComment

DL.AddComment "A 32 bit CRC (CRC-32) on a HEX sequence 01 02 03 04 05"

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:

 

Simple checksum (Mod 256) for '123456789'

CalcChecksum = DD

 

8 bit CRC (CRC DOW) for '123456789'

CalcChecksum = A1

 

16 bit CRC (CRC-16) for '123456789'

CalcChecksum = BB 3D

 

16 bit CRC (CRC-MODBUS) for '123456789'

CalcChecksum = 4B 37

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

 

16 bit CRC (CRC-CCITT) for '123456789'

CalcChecksum = 29 B1

Now do the same thing, but specify all CRC details yourself...

CalcChecksum = 29 B1

 

32 bit CRC (CRC-32) for '123456789'

CalcChecksum = CB F4 39 26

 

A 32 bit CRC (CRC-32) on a HEX sequence 01 02 03 04 05

CalcChecksum = 47 0B 99 F4