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