Controlling and Monitoring RS232 Handshake Signals (Scripting)

The Docklight project settings for Flow Control support offer a Manual Mode that allows you to set or reset the RTS and DTR signals manually by clicking on the corresponding indicator. The following section describes how to use the Function Character '!' (F11 key) to change the RTS and DTR signals temporarily within a Send Sequence, or detect changes for the CTS, DSR, DCD or RI lines using a Receive Sequence.

Preconditions

•	Docklight is ready to run a test as described in testing a serial device or a protocol implementation.

•	Flow Control Support is set to "Manual" in the project settings.

•	The Docklight project already contains one or several Send Sequences, but there is an additional requirement for changing RTS / DTR signals while sending.

Implementing RTS/DTR signal changes

For our example we assume that we are using a RS485 converter which requires RS485 Transceiver Control, but uses the DTR signal instead of RTS for switching between "transmit" and "receive" mode. We further assume there is already a "Test" Send Sequence which looks like this in ASCII mode:

T | e | s | t

A) Modifying the existing Send Sequence

1.	Open the Edit Send Sequence dialog.

2.	Switch the Edit Mode to Decimal. Our "Test" example looks like this in decimal mode:

084 | 101 | 115 | 116

3.	Insert an RTS/DTR function character at the beginning: Press F11, or open the context menu using the right mouse button and choose Function character '!' (RTS and DTR signals) . The example sequence now reads:

! | 084 | 101 | 115 | 116

4.	Add the new RTS/DTR state as a decimal parameter value (see below). In our example we need the DTR signal set to high. We choose "002" as the parameter value, so the sequence is now:

! | 002 | 084 | 101 | 115 | 116

5.	Add a RTS/DTR function character at the end of the sequence, and use "000" as parameter value to reset the DTR signal low. The sequence data is now:

! | 002 | 084 | 101 | 115 | 116 | ! | 000

6.	Click OK to confirm the changes

NOTE: To distinguish a '!' RTS/DTR function character from a exclamation mark ASCII character (decimal code 33), the RTS/DTR function character is shown on a different background color by the sequence editor.

NOTE: The character after a RTS/DTR function character is used to set the RTS / DTR signals and is not sent to the serial device (see parameter values below).

B) Sending the data with additional DTR control

1.	Send the test sequence using the Send button.

Docklight will now set the DTR signal to high, send the ASCII sequence "Test" and then reset DTR.

NOTE: The RTS/DTR indicators will indicate any changes of the RTS or DTR state. However, in the above example the DTR is set and reset very quickly, so the DTR indicator will probably not give any visual feedback. If you want to actually "see" the DTR behavior, try introducing a small inter-character delay.

Parameter values for the function character '!' (RTS and DTR signals)

Character Value (Decimal Mode)	RTS	DTR
000	Low	Low
001	High	Low
002	Low	High
003	High	High

Temporary parity changes / 9 bit applications

Some protocols and applications require a 9th data bit, e.g. for device addressing on a bus. The only way to talk to such devices using a standard UART with maximum 8 data bits is to use serial settings that include a parity bit and change this parity bit temporarily within a Send Sequence. The function character '!' supports additional parameter values for this purpose:

Character Value (Decimal Mode)	Parity
016	No parity
032	Odd parity
048	Even parity
064	Mark. Set parity bit to logic '1'
080	Space. Set parity bit to logic '0'

The new parity settings are applied starting with the next regular character, both on the TX and the RX side. The parity is switched back to the original Communication Settings after the Send Sequence has been completely transmitted.

NOTE: The most useful parameters for this function character are the "Mark" and "Space" settings, because they allow you to set the parity bit to a defined value that effectively serves as a 9th data bit.

NOTE: It is recommended to set the Parity Error Character to "(ignore)", so you can evaluate incoming data in both cases, 9th bit = high and 9th bit = low.

TIP: See also the SwitchParityDemo.ptp sample project (folder Extras\ParitySwitch_9BitProtocols in your Script Samples directory).

Detecting changes for CTS, DSR, DCD or RI

Docklight Scripting detects changes of the handshake signals CTS, DSR, DCD or RI, but in normal operation these changes are not visible in the Docklight Communication Window (similar to a Break State).

Using the function character '!' you can make these changes visible, and/or define an action after detecting such changes. The function character '!' supports the following parameter values for this purpose:

Character Value (Decimal Mode)	Handshake Signal
001	CTS = High
002	DSR = High
004	DCD = High
008	RI (Ring Indicator) = High

Example Receive Sequence definitions in Decimal Edit Mode:

Receive Sequence (Decimal Mode)	Description
! \| 001	triggers when CTS=high, all other signals low
! \| 006	triggers when CTS=low, DSR=high, DCD=high, RI=low
! \| ???	triggers on any change of the status lines

For the following example we assume that Docklight is ready to run a test as described in testing a serial device or a protocol implementation and Flow Control Support is set to "Manual" in the project settings.

A) Create a new Receive Sequence for detecting handshake signal changes.

1.	Open the Edit Receive Sequence dialog.

2.	Switch the Edit Mode to Decimal.

3.	Insert a 'signals' function character at the beginning: Press F11, or open the context menu using the right mouse button and choose Function character '!' (CTS/DSR/DCD/RI changes) .

4.	Add the handshake state as a decimal parameter value (see above). In our example we want to detect when CTS is high, while all other signals are low. This means we need to enter "001" as the parameter value, so the sequence is now:

! | 001

5.	Specifiy a Comment for this sequence, e.g. "[CTS = high, DSR/DCD/RI = low]"

6.	Click OK to confirm the new sequence

B) Start the test and confirm that Docklight now detects when the CTS line changes from low to high.

NOTE: This example only works if CTS is the only handshake line with "high" level. For a more flexible approach, you can define the character after the '!' function character as a wildcard, and use the DL_OnReceive() event procedure to evaluate the state of the handshake lines.