Calculating and Validating Checksums

<< Click to Display Table of Contents >>

Navigation:  Working with Docklight (Advanced) >

Calculating and Validating Checksums

Many communication protocols include additional checksum fields to ensure data integrity and detect transmission errors. A common algorithm is the CRC (Cyclic Redundancy Code), which is used in different variations for different protocols. The following step-by-step example describes how to set up on-the-fly checksum calculation for a Send Sequence, and how to enable automatic validation of a checksum area within a Receive Sequence.

 

TIP: For a working example to address a Modbus slave device, see the tutorial Modbus RTU With CRC checksum.

 

TIP: See also the DL.CalcChecksum method on how to calculate checksums using script code as an alternative.

 

Preconditions

 

You know the checksum specification for the protocol messages:

Which area of the sequence data is guarded by a checksum?

Where is the checksum located? (Usually at the end of the sequence.)

What checksum algorithm should be used? (Most likely one of the standard CRC types, or a simple MOD256 sum.)

 

Using Send Sequences with automatic checksum calculation

 

A) Defining a Send Sequence that includes a checksum

 

1.Create a new Send Sequence. Enter a Name for the sequence.
 
2.Enter the Sequence part of your message in the Sequence section. For example, here we use a very simple HEX message as our sequence:

01 | 02 | 03 | 04 | ??

 

Use the context menu via right mouse button or F7 to create the ?? wildcard.
 
NOTE: See also the Send Sequence Parameter section for more information on wildcards and parameters.
 

3.Now add one additional 00 value as a placeholder for the checksum.

01 | 02 | 03 | 04 | ?? | 00

 
NOTE: In a Send Sequence, you can use any character code from 00-FF as a placeholder at the positions where the calculated checksum should be inserted later. This is different from the way it works in a Receive Sequence, where you use ?? wildcards. See the Receive Sequence example below.
 

4.Go to the Additional Settings | Checksum tab and define the checksum. For example, here we chose to use MOD256 from the dropdown list.

 

NOTE: The text field for Checksum allows comments. Everything behind a # character is just a comment. You can add your own comments to describe what this checksum is about.
 
5.Click OK to add the new sequence to the Send Sequence list.

 

B) Performing the test

 

6. Use the Pt_Send_Button Send button to send one of the predefined commands. Enter a parameter value, e.g. 05.

 

Before sending the data, Docklight calculates the actual MOD256 checksum. The result goes to the specified checksum position. For MOD256 this is the last character  position by default, which means that the 00 placeholder is overwritten with the checksum result.

 

If we use 05 as a parameter when sending the sequence, the data sent by Docklight will look like this:

 

18.06.2015 11:07:23.251 [TX] - 01 02 03 04 05 0F

 

The placeholder has been replaced by the sum over the message bytes:

1 + 2 + 3 + 4 + 5 = 15 or Hex 0F.

 

Using Receive Sequences with automatic checksum validation

 

A) Defining a Receive Sequence with checksum

 

1.Create a new Receive Sequence. Enter a Name for the sequence.
 
2.Enter the Sequence data, including a wildcard area for both a random payload byte, plus a wildcard for the checksum. We use the same telegram as in the above Send Sequence example:

01 | 02 | 03 | 04 | ?? | 00.
 

3.Go to the Action | Comment tab and enter the following text: Correct checksum
 
4.Go to the Checksum tab and pick MOD256 in the left dropdown list.

 

5.    Keep the Detect Checksum OK option. It means that the Receive Sequence is only triggered if the MOD256 checksum byte in the received data is correct.

 

5.Click OK to confirm the changes
 

B) Running the test

 

6.Start communications and send some data telegrams to your Docklight application / COM port.

 

The Communication Window output could look like this:

 

15.02.2016 17:43:28.072 [RX] - 01 02 03 04 05 0F Correct checksum

 

15.02.2016 17:43:31.870 [RX] - 01 02 03 04 0F 19 Correct checksum

 

15.02.2016 17:43:35.833 [RX] - 01 02 03 04 10 1A Correct checksum

 

NOTE: This example showed how to define a Receive Sequence that is triggered by data telegrams with correct checksum only. It is also possible to do the opposite: detecting a checksum error. Go to the Checksum tab and change the option Detect Checksum OK to Checksum Wrong.