Many serial devices support a set of commands to transmit measurement data and other related information. In common text-based protocols the response from the serial device consists of a fixed part (e.g. "temperature="), and a variable part, which is the actual value (e.g "65F"). To detect all these responses correctly in the serial data stream, you can define Receive Sequences containing wildcards.

Take, for example, the following situation: A serial device measures the temperature and periodically sends the actual reading. Docklight shows the following output:

07/30/2012 10:20:08.022 [RX] - temperature=82F<CR>

07/30/2012 10:22:10.558 [RX] - temperature=85F<CR>

07/30/2012 10:24:12.087 [RX] - temperature=93F<CR>

07/30/2012 10:26:14.891 [RX] - temperature=102F<CR>

...

Defining an individual Receive Sequence for every temperature value possible would not be a practical option. Instead you would define one Receive Sequence using wildcards. For example:

t | e | m | p | e | r | a | t | u | r | e | = | ? | # | # | F | r

("r" is the terminating <CR> Carriage Return character)

This ReceiveSequence would trigger on any of the temperature strings listed above. It allows a 1-3 digit value for the temperature (i.e. from "0" to "999"). The following step-by-step example describes how to define the above sequence. See also the additional remarks at the end of this section for some extra information on '#' wildcards.

NOTE: See Calculating and Validating Checksums on how to receive and validate checksum data, e.g. CRCs. There are no wildcards required for checksum areas. Instead, use some default character values, e.g. "00 00" in HEX representation.

Preconditions

•Docklight is ready to run a test as described in the previous use cases, e.g. testing a serial device or a protocol implementation.

•The serial device (the temperature device in our example) is operating.

Using Receive Sequences with wildcards

A) Preparing the project

Create a new Docklight project and set up all communication parameters.

B) Defining the Receive Sequences used

1.	Create a new Receive Sequence. Enter a Name for the sequence.

2.	Enter the fixed part of your expected answer in the Sequence section. For our example you would enter the following sequence in ASCII mode:

t | e | m | p | e | r | a | t | u | r | e | =

3.	Open the popup / context menu using the right mouse button, and choose Wildcard '?' (matches one character) to insert the first wildcard at the cursor position. Add two '#' wildcards using the popup menu Wildcard '#' (matches zero or one character). The sequence now looks like this:

t | e | m | p | e | r | a | t | u | r | e | = | ? | # | #

4.	Enter the fixed tail of our temperature string, which is a letter 'F' and the terminating <CR> character. You can use the default control character shortcut Ctrl+Enter to enter the <CR> / ASCII code 13. The sequence is now:

t | e | m | p | e | r | a | t | u | r | e | = | ? | # | # | F | r

5.	Specify an Action to perform after a temperature reading has been detected.

6.	Click OK to add the new sequence to the Receive Sequence list.

NOTE: To distinguish the wildcards '?' and '#' from the regular question mark or number sign characters (decimal code 63 / 35), the wildcards are shown on a different background color within the sequence editor.

C) Running the test

Start Docklight by choosing Run > Start Communication.

Docklight will now detect any temperature reading and perform the specified action.

NOTE: The DL_OnReceive() event procedure allows further evaluation and processing of the actual measurement data received.

Additional notes on '#' wildcards

1. '#' wildcards at the end of a Receive Sequence have no effect. The Receive Sequence "HelloWorld###" will behave like a Receive Sequence "HelloWorld".

2. A "match inside a match" is not returned: If a Receive Sequence "Hello#######World" is defined, and the incoming data is "Hello1Hello2World", the Receive Sequence detected is "Hello1Hello2World", not "Hello2World".

Receive Sequence comment macros

Macro keywords can be used in the Edit Receive Sequence > 3 - Action > Comment text box, to create Docklight comment texts with dynamic data, e.g. the actual data received.

Macro	Is Replaced By
%_S	BELL signal. Produce a 'beep sound', depending on your Windows sound scheme.
%_L	Line break
%_T	Time stamp for the data received
%_C	Docklight channel no. / data direction (1 or 2) for the data received
%_X	The channel name or channel alias that corresponds to the data direction %_C. E.g. "RX", "TX" or "COM5".
%_I	Receive Sequence List Index, see the Dialog: Edit Receive Sequence
%_N	Receive Sequence Name
%_A	The actual data that triggered this Receive Sequence. Use ASCII representation
%_H	Same as %_A, but in HEX representation
%_D	Same as %_A, but in Decimal representation
%_B	Same as %_A, but in Binary representation
%_A(1,4)	Extended syntax: Insert only the first 4 characters of this Receive Sequence (start with Character No. 1, sequence length = 4).
%_H(3,-1)	Extended Syntax: Insert everything from the third character until the end of the sequence (length = -1). Use HEX representation.

Example:

For a Receive Sequence as described above ( t | e | m | p | e | r | a | t | u | r | e | = | ? | # | # | F | r ), you could define the following comment text:

New Temp = %_L %_A(13, -3) °F

Docklight output could then look like this:

10/30/2012 10:20:08.022 [RX] - temperature=82F<CR>

New Temp =

82 °F

10/30/2012 10:22:10.558 [RX] - temperature=85F<CR>

New Temp =

85 °F

10/30/2012 10:24:12.087 [RX] - temperature=93F<CR>

New Temp =

93 °F