Home

Docklight Scripting V2.1 User Manual 08/2015

Contents

1. eeeeeeeee esee eee eee eene enne tunes tnu 29 6 Working with Docklight Advanced 30 6 1 Sending Commands With Parameters Send Sequence Wildcards 31 6 2 How to Increase the Processing Speed and Avoid Input Buffer Overflow Mess ges un nn aa 32 6 3 How to Obtain Best Timing Accuracy iini antur eoa enano unn suas arva 33 6 4 Calculating and Validating Checksums eese eee eere esee e eene eene teen enne 33 6 5 Controlling and Monitoring RS232 Handshake Signals 35 6 6 Creating and Detecting Inter Character Delays eese crecen ee eene enean 39 6 7 Setting and Detecting a Break State eee eere ee ee ente enne tn nennen 41 6 8 Testing a TCP Server Device Scripting eee eene esee ener en eene en nene enne nnt 42 6 9 Monitoring a Client Server TCP Connection Scripting e 43 7 Examples and Tutorials 46 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Table of Contents 71 Testing a Modem Sample Project ModembDiagnostics ptp ee 47 7 2 Reacting to a Receive Sequence Sample Project PingPong ptp 48 7 3 MODBUS RTU With CRC checksum Sample Project ModbusRtuCrc ptp
2. O nameOrlndex Required String containing the Name or Sequence Index of a Receive Sequence Remarks See also WaitForSequence Example See WaitForSequence 10 2 1 4 GetDocklightTimeStamp Returns the current Docklight date time stamp according to the following settings 1 The Docklight date time stamp format chosen in the Options dialog e Time stamp e Date stamp e Use time stamps with 1 100 seconds precision 2 The Windows setting for Region and Language gt Formats gt Short date and Long time The GetDocklightTimeStamp function is especially useful for printing additional time information using the AddComment method Return Value String Syntax 1 result DL GetDocklightTimeStamp Remarks Syntax 1 GetDocklightTimeStamp adds a trailing space to the date time string This is for historical reasons and compatibility See Syntax 2 for a trimmed version See also the AddComment method Example 1 Example GetDocklightTimeStamp L ClearCommWindows L StartCommunication AddComment Communication started at amp L GetDocklightTimeStamp L AddComment Waiting for data U0000 i Endless loop to prevent the script from terminating immediately Do Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL Pause 1 the pause reduces CPU load while idle Loop Syntax 2 result DL GetDocklightTimeStamp
3. iw could return the following lHello CR NUL NUL Hello 10 2 2 3 GetChannelSettings Retums the current communication channel settings COM port number or TCP address serial port settings NOTE GetChannelSettings is a companion to the SetChannelSettings method and intended for advanced Docklight Scripting applications where control of the communication channel settings is required Return Value String Syntax result DL GetChannelSettings channelNo The GetChannelSettings method syntax has these parts channelNo Optional Integer that specifies the communication channel if Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting REED a s Mode Monitoring is used Default value is 1 Channel 1 Remarks GetChannelSettings returns a string with the current serial or TCP settings for the specified communication channel If the channel is a serial port the return value has the following format COMxxx BaudRate Parity DataBits StopBits FlowControl ParityErrorChar e g COM1 9600 NONE 8 1 OFF 63 If the channel is a TCP client the return value is the current IP address and TCP port number e g 192 0 0 1 3001 If the channel is a TCP server the return value is the string SERVER plus the TCP port number e g SERVER 3001 See also the SetChannelSettings method for a detailed overview on the return value data fo
4. result DL GetEnvironment name The GetEnvironment method syntax has these parts Required name can be 1 The name of the Windows environment variable Not including the signs around it that are used in the Windows Command Shell cmd exe 2 One of the Docklight specific names listed below Docklight Scripting Environment Variables Name Description 2744 Docklight Scripting application version DOCKLIGHT SCRIPTDIR the folder the script runs in DOCKLIGHT DIALOGDIR the folder used for the last script file dialog used DOCKLIGHT PORTLIST list of COM ports available on this PC l SENDSEQ list of all Send Sequence names in the current Docklight project ptp file EIVESEQ list of all Receive Sequence names ENDSEQDE list of all Send Sequences Name and Sequence in HEX format Name and Sequence are returned in separated text lines HT SENDSEQDEF Lists the definition only for the sequence names that SequenceName match SequenceName G G SequenceName can contain wildcards e g you can use DOCKLIGHT SENDSEQDEF Test I S DOCKLIGHT RECEIVESEQDE same as DOCKLIGHT SENDSEQDEF but for Receive F Sequences Remarks The list of environment variables used in the example below is just an example For details and available variables on other versions of Windows please refer to the other resources e g the
5. 49 8 Examples and Tutorials Scripting 51 8 1 Automated Modem Testing Sample Script ModemsScript pts 52 8 2 Startup From Command Line Sample Script LogStartupScript pts 55 8 3 Manipulating a RS232 Data Stream Sample Script CharacterManipulation pts una 56 8 4 TCP IP Communications Sample Projects PingPong_TCP_Server Client ptp 57 9 Reference 58 91 Menu and Toolbar Scripting sssessssessesssesssesesosessosessesesesssesesceeseonesonsssessseseseesesesse 59 9 2 Dialog Edit Send Sequence sesssssssssesssssoossssoossesssesesececssssconsssoosseseeeesecseessssoosseseosssee 61 9 3 Dialog Edit Receive Sequence sesssssssssssoosssseossessseseseceessssconsssoossesseeesecsesssssoosseseosssse 62 9 4 Dialog Create Log FIlels ne sa ee een 63 9 5 Dialog Find Sequence deem 63 9 6 Dialog Send Sequence Parameter uuussssnssonsesnnnsnnsnnnnsnnnsnnnnnnnnnnnnnsnnnnnnnsnnnnnnnsnnnsnnnns 64 9 7 Dialog Project Settings Communication esssssrsennnnnssnnnnnnnnnnnnnsnnnnnnnsnnnnnnnsnnnnnnnne 64 9 8 Dialog Project Settings Flow Control suusssssssnnssennnnnssnnnnnnnnnnnnnsnnnnnnnsnnnnnnnsnunnnnnne 67 9 9 Dialog Project Settings Communication Filter eeeee esee eere eene 68 9 10 Dialog Options Gem P 68 9 11 Dialog Customize HTML Output cesses eee enne ee eene eene etn nennen nas
6. 5 5 Logging and Analyzing a Test ge mec aS E Preconditions e Docklight is ready to run a test as described in the previous use cases e g Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Testing a serial device or a protocol implementation Logging the test Click on the A Start Logging button on the main toolbar A dialog window will open for choosing log file settings For each representation ASCII HEX a separate log file may be created Choose at least one representation Log files will have a txt or htm file extension Docklight additionally adds the representation type to the file name to distinguish the different log files E g if the user specifies Test1 as the base log file name the plain text ASCII file will be named Test1 asc txt whereas an HTML HEX log file will be named Test1 hex htm Confirm your log file settings and start logging by clicking the OK button To stop logging and close the log file s click the SS Stop Logging button on the main toolbar Unless the log file s have been closed it is not possible to view their entire contents TIP If you have additional requirements for your log file format e g starting a new file every hour you can use a Docklight script and the StartLogging method for this purpose See also the LogFileNamesTimestamp zip sample script folder Extra LogFileNamesTimestamp in yo
7. Further Information e The sample uses the DL OnReceive event procedure to perform additional operations each time a new character is received See Evaluating Receive Sequence Data for more details e The performance of a character by character processor in Docklight Scripting is quite limited You can easily overload it by sending a constant flow of data Docklight will display a comment in the communication window in this case e g DOCKLI GHT reports Input buffer overflow on COMI e For performance reasons all TX and RX data display is disabled in Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting CharacterManipulationPrj ptp e If you are thinking of writing a manipulator for your own protocol consider a packet based approach where one Receive Sequence can detect a whole packet or command from your protocol This will allow higher data rates than the character based approach presented here 8 4 TCP IP Communications Sample Projects PingPong_TCP_Server Client ptp The project files PingPong_TCP_Server ptp and PingPong_TCP_Client ptp in the ScriptSamples Network folder demonstrate how to use Docklight Scripting as a TCP server or TCP client and exchange data The samples show how a server and a client can be run on the same computer using the LOCALHOST network name which always refers to the computer Docklight is running on Getting started
8. fromDouble Convert to a IEEE double precision 64 bit sequence source string with floating point number Both period and comma are accepted as decimal separator result 64 bit sequence data Example DL ConvertSequenceData fromDouble 9 87987987987E 53 D False retums 103 154 149 160 081 161 036 075 fromText Converts a plain text into a Hex Decimal or Binary sequence E g DL AddComment DL ConvertSequenceData fromText Hello World retums 48 65 6C 6C 6F 20 57 6F 72 6C 64 bigEndian false If this option is used for fromText the resulting sequence is without separator e g 48656C6C6F20576F726C64 tolnteger16 Convert to from a signed 16 bit integer value fromInteger16 Examples DL ConvertSequenceData toIntegerl6 80 00 retums 32768 DL ConvertSequenceData fromIntegerl6 1 retums FF FF toUnsigned16 Same as tolnteger16 fromInteger16 but for unsigned 16 bit integer fromUnsigned1 data 6 Examples DL ConvertSequenceData toUnsignedl6 80 00 retums 32768 DL ConvertSequenceData fromUnsignedl16 65535 p retums 255 255 tolnteger32 Convert to from a signed 32 bit integer value fromInteger32 Examples DL ConvertSequenceData toInteger32 00 00 00 80 H False retums 2147483648 DL ConvertSequenceData fromInteger32 2 H False retums FE FF FF FF toUnsigned32 Same as tolnteger32 fromInteger32 but for unsigned 32 bit integer
9. slave 2 responded 10000 slave 3 responded 0 and slave 4 responded 1024 NOTE If you are using the Docklight MODBUS example on a RS485 bus you need to check if your RS485 hardware correctly switches between transmit and receive state You might need to use Docklight s RS485 Transceiver Control feature Further Information e The CRC calculation is made according to the specifications for MODBUS serial line transmission RTU mode Docklight s checksum function supports a CRC MODBUS model for this purpose See Calculating and Validating Checksums for more general information on implementing checksum calculations e If you do not have any MODBUS slave devices available you can use a software simulator See http www modbus org Modbus Technical Resources MODBUS Serial RTU Simulator This simulator was used to produce the sample data shown above Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting Examples and Tutorials Scripting 8 Examples and Tutorials Scripting This chapter describes sample scripts that demonstrate some of the possibilities when using Docklight Scripting The corresponding Docklight script files pts files and other related files can be found in the folder ScriptSamples within the Docklight Scripting installation directory e g C Program Files FuH Docklight Scripting V2 1 ScriptSamples NOTE If you are w
10. 07 02 2013 18 17 254 083 TX ATQOUVIEOSCR2SLE Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials 07 02 2013 18 17 54 107 RX ATOOVIEO lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 07 02 2013 18 18200 511 TX ATIZ CR XLE 07 02 2013 18 18 00 747 RX lt CR gt lt LF gt V 11 10 lt CR gt lt LE gt 13 05 11 lt CR gt lt LF gt RM 721 lt CR gt lt LF gt c Nokia lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 97 02 2013 18 18501 393 TX ATIS lt CR gt lt LE gt 074 202 2013 18 18201 421 RX lt CR gt lt LF gt Nokia C2 01 lt CR gt lt LF gt lt CR gt lt LE gt OK lt CR gt lt LF gt Further Information The Send Sequences list includes the following standard AT modem commands Send Sequence Description Modem Response ATQOV1EO Initializes the query AT GMM Model identification ITU V 250 recommendation is not supported by all modems AT FCLASS Fax classes supported by the modem if any ATHCLS Shows whether the modem supports the Rockwell voice command set Displays manufacturer s information for n 1 through 7 This provides information such as the port speed the result of a checksum test and the model information Check the manufacturer s documentation for the expected results The Samples folder also contains a log file ModemDiagnostics Logfile asc txt It shows a
11. ATI5 lt CR gt lt LF gt 3 8 2009 16 23 09 912 RX lt CR gt lt LF gt 2 1 46 AMR Intel MB AC97 ID SIL REV 0x27 O06 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 10 104 TX ATI6 lt CR gt lt LF gt 3 8 2009 16 23 10 110 RX lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 10 308 TX ATI7 lt CR gt lt LF gt 3 8 2009 16 23 10 315 RX lt CRS lt LF gt AMR Intel MB lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 10 510 TX ATI8 lt CR gt lt LF gt 3 8 2009 16 23 10 513 RX lt CRO lt LE gt AC97 ID SIL REV 0x27 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting 3 8 2009 16 23 10 713 TX ATI9 lt CR gt lt LF gt 3 8 2009 16 23 10 723 RX lt CR gt lt LF gt Germany lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 10 916 TX ATI10 lt CR gt lt LF gt 3 8 2009 16 23 10 921 RX lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 11 119 TX ATLIIL lt CR gt lt LF gt 3 8 2009 16 23 11 120 RX DBeseription Status lt CR gt lt LF gt LLL AJ S lt CR gt lt LF gt Last Connection Unknown lt CR gt lt LF gt Initial Transmit Carrier Rate O lt CR gt lt LF gt Initial Receive C
12. Docklight Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Table of Contents 1 Copyright 7 2 Introduction 8 2 1 Docklieht Overview ATE T UU TT T 9 2 2 Docklight Scripting Overview ussnssssnsnssnsnnnonnnnnnnsnnnnnnnsnnnnnnnsnnnsnnnnnsnnnnnnnsnnsnnsnsnnnnnnnns 10 2 3 Typical Applications una 10 2 4 System Requirements voee cree teer eren ne ne eren rona aa ore eror TEE aene sano Em Ge ra areae anos aoa ar aiuE n 11 3 User Interface 13 3 1 Main Window Scripting een 14 3 2 Clipboard Cut Copy amp Paste 145 resp tinet dur anna nun nn en ana 15 3 3 NOteEpad ie c ere enrrer errs 15 4 Features and Functions 16 4 1 How Serial Data Is Processed and Displayed eren 17 4 2 Editing and Managing Sequences ceres e esee eee ee eene enne tonne tunes tans 17 5 Working with Docklight 19 5 1 Testing a Serial Device or a Protocol Implementation eee 20 5 2 Simulating a Serial Device sun 21 5 3 Monitoring Serial Communications Between Two Devices e eere 23 5 4 Catching a Specific Sequence and Taking a Snapshot of the Communication 25 5 5 Logging and Analyzing a Test nn ana 25 5 6 Checking for Sequences With Random Characters Receive Sequence III Eme Pc 26 5 7 Saving and Loading Your Project Data
13. 123456789 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 retum when applied on this string Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Edit Send Sequence Edit Receive Sequence In the Checksum tab choose one of the predefined definition strings from the drop down list or type in your own definition in the following format startPos len checksumSpec A or L targetPos optional user comment with anything inside being an optional part Part checksumSpec Required String that specifies the checksum algorithm and its parameters according to the checksumSpec Format table above Optional Start and length of the character area that is used to calculate the checksum By default everything before the checksum result is used Optional If used the resulting checksum value is converted into a readable ASCII text This is for example used in MODBUS ASCII Optional Little Endian the resulting checksum value is stored with the least significant byte LSB first Default is Big Endian MSB first Optional Specifies the first character position for storing the resulting checksum value By default Docklight places the checksum result at the end of the sequence data unless you have specified A for ASCII result In this case the results is stored on
14. 2 GetChannelStatus 2 GetChannelStatus 2 GetChannelStatus 2 GetChannelStatus 1 Connected 10 2 2 5 GetCommWindowData Returns the accumulated contents of the communication windows buffer NOTE This method is for special applications For many standard uses cases the OnSend OnReceive event procedures or the GetReceiveComments method will be the preferred solution Return Value String Syntax result DL GetCommWindowData representation The GetCommWindowData method syntax has these parts Pat Description O representation Required String value to define the window buffer format requested A ASCII default H Hex D Decimal or B Binary Remarks Only a representation enabled in Docklight Options Communication Window Modes can be used By default this is ASCII HEX and Decimal If required load different options using LoadProgramOptions The maximum size of the GetCommWindowData buffer is 128000 characters If more communication data is accumulating without calling GetCommWindowData the oldest data gets deleted 10 2 2 6 GetEnvironment Retums the value of a Windows environment variable in the currently active user profile or a value of one of the Docklight specific environment variables described below Return Value String Syntax Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting
15. Open as a text file rawData True Open as a raw binary data file Filelnput CloseFile Closes the file result Filelnput GetLine Returns a string with the next line of text result does not contain the line break characters CR LF The GetLine method can only be used for text files rawData False result Filelnput GetByte Returns the next byte result Filelnput IsOpen Returns True if a file is open False if not result Filelnput EndOfFile Returns True if all data has been read and the end of file mark has been reached result Filelnput Dialog caption Shows a File Open dialog and return the Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting defaultPath chosen file path or an empty string if aborted result Filelnput FileExists filePath Returns True if filePath exists Remarks See also the FileOutput object Example FileInput FileOutput example DL ClearCommWindows Create a simple text file FileOutput CreateFile C test txt FileOutput WriteLine Hello World FileOutput WriteLine Goodbye World FileOutput CloseFile Open the file and print its contents DL AddComment Reading text file FileInput OpenFile C test txt Do Until FileInput EndOfFile DL AddComment FileInput GetLine Loop FileInput CloseFile Now try a raw data file FileOutput CreateFile C test bin True
16. e Open the project PingPong_TCP_Server ptp in Docklight Scripting Press the _ Start Communication button in the toolbar If you are using a Personal Firewall on your PC it will probably notify you that Docklight Scripting wants to act as a server Confirm and allow if required e Start a second instance of Docklight Scripting and open the PingPong TCP Client ptp project In this client instance press the Es Send button for the Ping sequence If you are using a Personal Firewall on your PC allow Docklight Scripting to connect to the Internet The client Docklight now connects to the server Docklight and data is exchanged as if the two Docklight instances were connected by a serial null modem cable The communication window on the client side now displays the following messages 3 9 2009 17 29 24 192 TX e p Ping 3 9 2009 17 29 24 218 RX o Pong Pong received 3 9 2009 T7T 29 24 221 TX 0 Ping 3 9 2009 17 29 24 249 RX o Pong Pong received 3 9 2009 17 29 24 254 TX gt Ping 3 9 2009 17 29 24 281 RX o Pong Pong received 3 9 2009 17 29 24 283 TX Ping 3 9 2009 17 29 24 312 RX o Pong Pong received On the server side you will see something like this 3 9 2009 17 29 24 203 RX o Ping Ping received 3 9 2009 17 29 24 206 TX o Pong 3 9 2009 17 29 24 235 RX o Ping Ping received 3 9 2009 17 29 24 238 TX 6 Pong
17. fromUnsigned3 data 2 Examples DL ConvertSequenceData toUnsigned32 FF 00 FF 00 retums 4278255360 DL ConvertSequenceData fromUnsigned32 21121977 DW retums 001 066 075 185 Returns True if the first source character is 0 Example DL ConvertSequenceData toBool 00 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting retums False DL ConvertSequenceData toBool 01 00 retums True Converts sequence data into a text string with printing characters only see ASCII Character Set ASCII code 0 31 and 127 255 are filtered out and do not appear in the result source sequence with the original data including non printing character codes result the ASCII text using only ASCII code 32 126 Example DL ConvertSequenceData toText FF 48 65 6C 6C 6F 21 0D 00 00 retums Hello Remarks Carefully check your protocol specification on the data format including Endianness little endian big endian When using the result of a toSingle or toDouble conversion for further calculations keep in mind that result can be a non numeric strings like NaN not a number or Inf Infinity Note that toText is not the same as reading out a data sequence in ASCII representation A Example iw L AddComment DL OnSend GetData A L AddComment DL ConvertSequenceData toText L OnSend GetData H iw
18. should be played back If dataDirection is an empty string the first channel that appears in the log file is used timelnterval Optional Integer value Use a pause time in milliseconds between two messages instead of the original timing from the log file see remarks below Remarks Playback is only possible in Communication Mode Send Receive and only for log files in HEX Decimal or Binary representation Both HTML htm and plain text txt files can be used for playback If filePathName does not exist Docklight reports an error and the script execution is stopped The log file used must contain date time stamps for the two communication directions filePathName needs to contain the original Docklight style name extension to determine the type of log file e g log1_hex txt log1 dec txt or log1 bin txt If filePathName has a different format a HEX log file is assumed PlaybackLogFile evaluates the date time stamps from the log file and emulates the timing of the original communications logged If you want to change this e g to slow down things for debugging purposes you can use the optional time nterval argument Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Example Example PlaybackLogFile Playback the first data direction from a sample log file DL AddComment Playback TX side DL PlaybackLogFile modbus logfile hex txt S
19. 02 03 04 05 3 Now add one or several additional HEX 00 value s as a placeholder for the checksum In our example we choose a single byte checksum at the end of the sequence 01 02 03 04 05 00 4 Goto the Additional Settings Checksum tab and define the checksum Choose MOD256 from the dropdown list for a simple example NOTE 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 Repeat steps 1 5 to define other commands needed to perform your test B Performing the test 6 Use the Eg Send button to send one of the predefined commands Before sending the data Docklight calculates the actual checksum and overwrites the 00 placeholder with the checksum value For our simple example command defined above and a MOD256 checksum one byte sum of all character values the transmitted data looks like this 18 06 2015 11207 23 291 TX 1 2 03 04 05 UF The placeholder has been replaced by the sum over the message bytes 1 2 3 4 5 15orHex OF Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced Using Receive Sequences with automatic checksum validation A Defining Receive Sequences with checksums 1 Create a new Receive Sequence Enter a Name for the sequence 2 Enter the Sequence data including on
20. ASCII mode RTU mode is the default mode that must be implemented by all devices See http www modbus org for a complete specification of the MODBUS protocol 13 11 Multidrop Bus MDB o Aaa B sil Multidrop Bus MDB is a more exotic RS232 RS485 application used for example in vending machine controllers which requires a 9 bit compliant UART The 9th data bit is used for selecting between an ADDRESS and a DATA mode A way to monitor and simulate such communication links using standard 8 bit UARTs i e standard RS232 to USB converters is to use temporary parity changes See also Wikipedia on MDB and the original MDB 3 0 specification for more information and details 13 12 Named Pipe a A Named Pipe is a shared memory mechanism that can be used for communication between two processes on a Windows PC Docklight Scripting can open a client connection to a Named Pipe server and send or receive 8 bit ASCII or byte data For details on Named Pipes see the Windows Development Center 13 13 Receive Sequence fs e_zuom ocoz mi _ _ _ m _ A Receive Sequence is a sequence that can be detected by Docklight within the incoming serial data A Receive Sequence is specified by 1 an unique name e g Modem Answer OK 2 a character sequence e g 6F 6B 13 10 in HEX format 3 an action that is triggered when Docklight rec
21. DL AddComment DL AddComment 8 bit CRC CRC DOW for 123456789 DL AddComment CalcChecksum amp DL CalcChecksum CRC DOW 123456789 A Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL AddComment DL AddComment 16 bit CRC CRC 16 for 123456789 DL AddComment CalcChecksum amp DL CalcChecksum CRC 16 123456789 A DL AddComment DL AddComment 16 bit CRC CRC MODBUS for 123456789 DL AddComment CalcChecksum amp 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 AddCommen DL AddComment 16 bit CRC CRC CCITT for 123456789 DL AddComment CalcChecksum amp DL CalcChecksum CRC CCITT 123456789 A DL AddComment Now do the same thing but specify all CRC details yourself ct ct ct DL AddComment CalcChecksum amp DL CalcChecksum CRC 16 1021 FFFF 0000 No No 123456789 AU DL AddCommen DL AddComment 32 bit CRC CRC 32 for 123456789 DL AddComment CalcChecksum amp DL CalcChecksum CRC 32 123456789 A a ri DL AddCommen DL AddCommen 04 05 DL AddComment CalcChecksum amp DL CalcChecksum CRC 32 O1 02 03 04 05 TH et ct A 32 bit CRC CRC 32 on a HEX sequence 01 02 03 The above script code produces the following output in the D
22. Measured delay values are significantly higher because Docklight always waits a minimum time to ensure the UART TX FiFo buffer is empty Also the display format and the additional performance settings affects the timing If you have more specific requirements on Send Sequence timing and need to control the Docklight wait time as well as your UART FiFo settings please contact our e mail support TIP If you require the same delay between each character of the transmitted data have a look at the SendByteTiming pts sample script see the folder Extras SendByteTiming in your Script Samples directory This script will automatically slice your Send Sequences into individual characters and send the data byte by byte using a predefined inter character delay Pause detection using a Receive Sequence Docklight already offers the Pause detection display option to insert additional time stamps or line breaks after communication pauses Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced If you require not only visual formatting but need to define actions after a minimum pause or simply make sure the Receive Sequence detection algorithm starts anew after a pause you can add the delay function character to your Receive Sequence definition In most applications the best place for the delay function character will be at the beginning ofthe Receive Sequence
23. received Ping received Pong received Ping received Pong received 10 2 2 15 SetHandshakeSignals Sets the RTS and DTR handshake signals Only allowed when Flow Control Manual is used Syntax DL SetHandshakeSignals rts atr The SetHandshakeSignals method syntax has these parts Pat Description L Required Boolean value to set RTS High True or RTS Low False Required Boolean value to set DTR High True or DTR Low False Remarks Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting See also the GetHandshakeSignals function for reading the current state of the handshake signals SetHandshakeSignals can be used before opening the communication channel to ensure a certain state of the RTS and DTR lines on initialization Example Example SetHandshakeSignals DL SetHandshakeSignals true false DL StartCommunication DL Pause 1000 DL SetHandshakeSignals false true DL Pause 1000 10 2 2 16 UploadFile Opens an existing file and sends out its contents Starts the communication if not already running see StartCommunication Return Value Void Syntax DL UploadFile filePathName representation The UploadFile method syntax has these parts Pat Description Required String containing the file path directory and file name of the file to send If no directory is specified Docklight uses the cur
24. 0 1 10001 4 Confirm the settings and close the dialog by clicking the OK button TIP If you want to connect to a server that runs on the same computer as Docklight Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced you can use the keyword LOCALHOST instead ofthe actual IP address of your computer e g LOCALHOST 10001 for connecting to a server on port 10001 on the same computer Using the loopback address 127 0 0 1 will have the same effect B Defining the Send Sequences and Receive Sequences used Define all of the commands and responses required for your test as described in Testing a Serial Device or a Protocol Implementation C Running the test Establish a connection by choosing Run gt Start Communication Docklight Scripting now tries to connect to the TCP server device After the connection is established you can send one of your predefined Send Sequences using the Send button Until the TCP server accepts the connection request you will not see any TX transmission data appearing in the Communication Window NOTE If the server closes the TCP session before you choose M Run gt Stop Communication in Docklight you will receive the error message TCP IP connection closed by the remote computer and the communication will be stopped NOTE If you receive the error IP Address TCP port in use when starting communications c
25. 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight 5 7 Saving and Loading Your Project Data pl E ION cec mm meu ccc o eu 0 E 0 mes All project data may be saved in a Docklight project file using the menu File gt El Save Project or File Save Project As The project data includes e Send Sequences defined e Receive Sequences defined e additional Project Settings communication mode COM ports used COM port settings baud rate parity e the Notepad contents It is recommended to save your current project before starting a test run Please note the difference between storing the project settings as described here and logging the communication during a test see section logging and analyzing a test Test run results are stored separately from Projects Loading a project is done using the File gt amp Open Project menu Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced Working with Docklight Advanced 6 Working with Docklight Advanced 6 1 Sending Commands With Parameters Send Sequence Wildcards pasenaxicacmceumc d E E A When testing a serial device the device will most likely support a number of commands that include a parameter Example A digital camera supports a command to set the exposure time For setting the
26. 45 06 119 line 9 Debug count 3 07 04 2009 15 45 06 131 line 9 Debug count 4 07 04 2009 15 45 06 145 line 9 Debug count ll O1 07 04 2009 15 45 06 158 line 11 Debug Assert is False here the user manually continues using the By Continue Script button 07 04 2009 15 45 07 781 line 9 Debug count 6 07 04 2009 15 45 07 805 line 9 Debug count ll 07 04 2009 15 45 07 830 line 9 Debug count Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR ll Reference Scripting 07 04 2009 15 45 07 853 line 9 Debug count 9 07 04 2009 15 45 07 881 line 9 Debug count 10 Debug test ended 10 6 include Directive Instructs the Docklight script preprocessor to insert the contents of the specified file at the point where the Zinclude directive appears Syntax include filePathName The include syntax has these parts Pat Description O filePathName Required String containing the file path directory and file name of the Docklight script file pts file to include The file extension pts can be omitted If no directory is specified Docklight uses the current working directory Remarks If filePathName is not a valid Docklight script file or does not exist Docklight reports an error and the script is not started The Zinclude directive tells the preprocessor to treat the contents of a specified file as
27. 7 Quit Stops the Docklight script immediately Return Value Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Void Syntax DL Quit Remarks If communication has been started using a script command see StartCommunication the communication is stopped too If a log file has been opened using StartLogging the file is closed Files opened using Filelnput or FileOutput are closed as well Using VBScript s built in Stop statement or other VBScript debugging features that alter the program flow is not possible in Docklight Scripting Always use the DL Quit statement to terminate script execution 10 2 1 8 ResetReceiveCounter Resets one or all Receive Sequence hit counter s Also resets the search algorithm which checks the character stream for a matching Receive Sequence see example code below Return Value Void Syntax DL ResetReceive Counter nameOrindex The ResetReceiveCounter method syntax has these parts Pat Description nameOrlndex Optional String containing the Name or Sequence Index of a Receive Sequence If specified only the corresponding counter is reset If nameOrlndex is omitted all counters are reset Remarks See also GetReceiveCounter and WaitForSequence Example See WaitForSequence for a basic example A second application is demonstrated below resetting the receive sequence detection each time a new Send
28. CRC as used in MODBUS It is a a CRC 16 but with an init value of FFFF CRC 16 8005 FFFF 0000 Yes Yes CRC 32 Calculates a 32 bit CRC as used in PKZip AUTODIN Il Ethernet FDDI Equal to CRC 32 04C11DB7 FFFFFFFF FFFFFFFF Yes Yes CRC width polynomial Generic CRC computer where all CRC parameters can be init set individually finalXOR reflectedInput width The CRC width from 1 32 reflectedOutput polynomial HEX value The truncated CRC polynomial init HEX value The initial remainder to start off the calculation finalXor HEX value Apply an XOR operation on the resulting remainder before returning it to the user reflectedInput Yes Reflect the data bytes MSB becomes LSB before feeding them into the algorithm reflectedOutput Yes Reflect the result after completing the algorithm This takes places before the final XOR operation 8 Remarks Each of the predefined CRC algorithms CRC 8 CRC CCITT can be replaced by a specification string for the generic CRC computation CRC 16 as described above We have carefully tested and cross checked our implementations against the common literature and resources as listed in the CRC Glossary Unfortunately there are a lot of CRC variations and algorithms around and choosing not to mention understanding the right CRC flavor can be a rather difficult job A good way to make sure your CRC calculation makes sense is to run it over an ASCII test string of
29. Docklight project Return Value Integer Syntax result DL NoOfReceiveSequences Remarks See NoOfSendSequences 10 3 OnSend OnReceive Event Procedures egut Docklight Scripting supports two dedicated procedures that are called by the Docklight Scripting engine before transmitting a new Send Sequence or after detecting a Receive Sequence Procedure Definition Sub DL OnSend DL OnSendq is called after a new send operation has my script code been triggered manual send or DL SendSequence Special End Sub manipulation functions are available to read out and modify the data before it is actually transmitted See Send Sequence Data Manipulation Sub DL OnReceive DL OnReceive is called after a Receive Sequence has my script code been detected Special manipulation functions are available End Sub to read out and further process the data received See Evaluating Receive Sequence Data The procedures can be defined anywhere in the script code at module level not within a class See Send Sequence Data Manipulation for an example NOTE The DL OnSend and DL OnReceive code is only executed while the script is running Sending a Send Sequence does not automatically execute the related DL OnSendq code The script must be started manually using the menu Scripting gt Bb Run Script Any error during script executio
30. GbR Working with Docklight Advanced mask value Is a match for the next character received when the following is true nextCharacterReceived XOR value AND mask 0 In other words the character picks only the bits marked in mask and compares them with the corresponding bits in value See below for examples OF 05 Is a match when for the next character the following is true Bit 0 1 Bit 1 0 Bit 2 1 Bit 3 0 Bit 4 7 don t care 04 04 This Receive Sequence triggers when the new handshake signal state says DCD High All other handshake signals can have any state NOTE This Receive Sequence will trigger for any change of any handshake signal in case DCD still remains High TIP This extension is also demonstrated in the Docklight Scripting example project Docklight_TapPro_Demo ptp see the folder Extras TapPro in your Samples directory 6 6 Creating and Detecting Inter Character Delays Some applications especially microcontroller applications without a dedicated serial data buffer require an extra delay between individual characters to avoid buffer overflows and allow the microcontroller to execute other code In Docklight you can implement inter character delays by inserting one or several Function Characters amp F9 key in your Send Sequence data followed by a character specifying the desired delay time from 0 01 seconds to 2 55 seconds You can also use the amp delay cha
31. OD CR Carriage return 14 OE so Shift out 15 OF SI Shift in XON resume output 16 10 DLE Data link escape 17 11 DC1 XON Device control character 1 18 12 DC2 Device control character 2 19 13 DC3 XOFF Device control character 3 20 14 DC4 Device control character 4 21 15 NAK Negative Acknowledgment 22 16 SYN Synchronous idle 23 17 ETB End of transmission block 24 18 CAN Cancel 25 19 EM End of medium 26 1A SUB substitute end of file 27 1B ESC Escape 28 1C FS File separator 29 1D GS Group separator 30 1E RS Record separator 31 IF US Unit separator Printing Characters Dec Hex ASCII Char Meaning 32 20 Space 33 21 34 22 35 23 36 24 37 25 38 26 amp amp 39 27 y 40 28 41 29 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 42 2A 43 2B 44 2C 45 2D 46 2E 3 47 2F 48 30 0 Zero 49 31 1 One 50 32 2 Two 51 33 3 Three 52 34 4 Four 53 35 5 Five 54 36 6 six 55 37 7 Seven 56 38 8 Eight 57 39 9 Nine 58 3A 59 3B 60 3c lt lt 61 3D 62 3E gt gt 63 3F 64 40 65 41 A A 66 42 B B 67 43 C C 68 44 D D 69 45 E E 70 46 F F 71 47 G G 72 48 H H 73 49 T T 74a AA J J 75 4B K K 76 4C L L 77 4D M M 78 4E N N 79 AF O O 80 50 P P 81 51 Q Q 82 52 R R 83 53 S S 84 54 T T 85 55 U U 86 56 V V 87 94 W W 88 58 X X 8
32. Send your test command using SendSequence 3 Now use WaitForSequence to wait for the expected answer It is very important that you use ResetReceiveCounter before SendSequence ResetReceiveCounter will not only set the detection counter to zero but also reset the character matching process so any characters that have been previously received are not considered when looking for a sequence match See also the remarks on wildcard search for additional information on how Docklight handles Receive Sequence pattern matching During a WaitForSequence no DL OnReceive procedure calls can be processed If you need to process DL OnReceive events while waiting see the Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting pauseWithEvents code described at OnReceive Example 2 If you need to wait for any of the Receive Sequences to trigger the DL OnReceive procedure provides the solution See the OnReceive Example 3 Example Y Example WaitForSequence Count the number of occurrences of the first Receive Sequence within a 10 seconds interval Requires at least one Receive Sequence definition Y DL StartCommunication DL ClearCommWindows r D esult DL WaitForSequence 0 1 10000 L AddComment vbCrLf amp vbCrLf amp Receive Sequence 40 hit count amp result alternative way to read the counter afterwards DL AddComment Receive Sequen
33. TX Onel00 lt CR gt lt LF gt 08 05 2008 13 50 35 665 TX Onel00Two20 08 05 2008 13 50 35 682 TX One 1 Two0 lt CR gt lt LF gt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 08 05 2008 13 50 35 699 TX Custom Data 08 05 2008 13 50 35 713 TX Onel Two2 08 05 2008 13 50 35 745 TX One2 Two3 08 05 2008 13 50 35 771 TX One3 Two4 08 05 2008 13 50 35 807 TX One4 Two5 08 05 2008 13 50 35 846 TX One5 Two6 08 05 2008 13 50 35 878 TX One6 Two7 08 05 2008 13 50 35 907 TX One7 Two8 08 05 2008 13 50 35 922 TX One8 Two9 08 05 2008 13 50 35 955 TX One9 Twol0 08 05 2008 13 50 35 987 TX OnelO Twoll 10 2 1 10 StartCommunication Opens the communication port s and enables the data transfer Return Value Void Syntax DL StartCommunication Remarks The methods SendSequence WaitForSequence and UploadFile will automatically open the communication port s if they have not been opened before by using the StartCommunication method See also StopCommunication 10 2 1 11 StopCommunication Stops the data transfer and closes the communication port s Return Value Void Syntax DL StopCommunication Remarks See the StartCommunication method for more information 10 2 1 12 StartLogging Creates new log file s and starts logging the incoming outgoing serial data Return Value Void Syntax Doc
34. Then structure to execute one or more statements conditionally You can use either a single line syntax or a multiple line b ock syntax If condition Then statement If condition Then statements End If The condition is usually a comparison If condition is True VBScript executes all the statements following the Then keyword You can use either single line or multiple line syntax to execute just one statement conditionally these two examples are equivalent If anyDate Now Then anyDate Now If anyDate Now Then anyDate Now End If Notice that the single line form of If Then does not use an End If statement If you want to execute more than one line of code when condition is True you must use the multiple line block If Then End If syntax Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting e f Then Else Use an lf Then Else block to define several blocks of statements one of which will execute If conditioni Then statementblock 1 ElseIf condition2 Then e Select Case VBScript provides the Select Case structure as an alternative to If Then Else for selectively executing one block of statements from among multiple blocks of statements A Select Case statement provides capability similar to the If Then Else statement but it makes code more readable when there are several choices Example Select Case Weekday n
35. applications that are not really designed to be controlled from outside If you find a smart configuration file for your personal favorite editor or you are experiencing problems with the above interface our Customer Support would be happy to hear about it Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR 11 11 1 11 2 Support Web Support and Troubleshooting pa O mm For up to date FAQs and troubleshooting information see our online support pages available at http www docklight de support E Mail Support EEE ee We provide individual e mail support to our registered customers Please include your Docklight license key number in your request We will contact you as soon as possible to find a solution to your problem Send your support request to docklight fuh edv de Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix Appendix 12 Appendix 12 1 ASCII Character Set Tables Control Characters Dec Hex ASCII Char Meaning 0 00 NUL Null 1 01 SOH Start of heading 2 02 STX Start of text 3 03 ETX Break end of text 4 04 EOT End of transmission 5 05 ENO Enquiry 6 06 ACK Positive acknowledgment 7 07 BEL Bell 8 08 BS Backspace 9 09 HT Horizontal tab 10 0A LF Line feed 11 OB VT Vertical tab 12 0C FF Form feed 13
36. aput esdiouE Us RUE Dou EDU oV ND Kn Cd D e DeL eben iodine E EODD Nd DES ea 160 vcICEBIDpe 160 13 24 UART eec cr c raas Kisn 160 TO MENS D m 160 1326 Wirt al Null Modem un 161 13 27 Wildeard e 161 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Table of Contents Index 0 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Copyright 1 Copyright Copyright 2015 Flachmann und Heggelbacher GbR All rights reserved No parts of this work may be reproduced in any form or by any means graphic electronic or mechanical including photocopying recording taping or information storage and retrieval systems without the written permission of the publisher Trademarks Products that are referred to in this document may be either trademarks and or registered trademarks of the respective owners The publisher and the author make no claim to these trademarks Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and or other countries Disclaimer While every precaution has been taken in the preparation of this document the publisher and the author assume no responsibility for errors or omissions or for damages resulting from the use of information contained in this document or f
37. before the actual receive data characters You can also create a Receive Sequence that contains a delay pause definition only and no actual serial data This can be very useful for implementing timing constraints e g resetting the telegram detection after a pause occurred TIP See the LineParser ptp LineParser pts project and script file folder Extras LineParser in your Script Samples directory for a sample application 6 7 Setting and Detecting a Break State Er EEE NN qq Some serial application protocols e g LIN make use of the so called Break state for synchronization purposes Docklight Scripting supports sending a break within a Send Sequence and detecting a break state using a Receive Sequence definition break signals are added to your sequence definition by inserting a Function Character Jo F10 key A Docklight break signal has a minimum length of 15 nominal bit length Preconditions e Docklight is ready to run a test as described in testing a serial device or a protocol implementation e The Docklight project already contains one or several Send Sequences but signalling or detecting a break state is also required Sending a Break state We assume there is already a Test Send Sequence which looks like this in ASCII mode Tlels t 1 Open the Edit Send Sequence dialog Insert a Break function character at the beginning Press F10 or open the context menu using the right mouse button and
38. but with SUB D9 male connectors on both ends null modem cable with partial handshaking but with SUB D9 male connectors on both ends SUB D9 Simple Straight Cable Area of Application DTE DCE Communication where no additional handshake signals are used prote ctive shielding ground SUB DSfemae SUB DS male SUB D9 Full Straight Cable Area of Application DTE DCE Communication with hardware flow control using additional handshake signals Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix SUB D9 femae SUB DI male SUB D9 Simple Null Modem Cable without Handshaking Area of Application DTE DTE Communication where no additional handshake signals are used prote ctive shielding ground SUB D3femae SUB DS female SUB D9 Null Modem Cable with Partial Handshaking Area of Application DTE DTE Communication with DTE DCE compatible hardware flow control Works also when no handshake signals are used prote ctive shielding ground SUB DS3femae SUB DS female Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 12 5 Docklight Monitoring Cable RS232 SUB D9 a a Sa Docklight Monitoring Mode requires a full duplex monitoring cable that feeds the two data directions into two separate COM ports Area of application Monitoring serial communications between two devices We offer a custom RS232 cable that is d
39. e Variables Variable names follow the standard rules for naming anything in VBScript A variable name e Must begin with an alphabetic character e Cannot contain an embedded period e Must not exceed 255 characters e Must be unique in the scope in which it is declared Examples ApplesSold 10 The value 10 is passed to the variable ApplesSold ApplesSold 1 The variable is incremented e Arrays Arrays allow you to refer to a series of variables by the same name and to use a number an index to tell them apart This helps you create smaller and simpler code in many situations because you can set up loops that deal efficiently with any number of cases by using the index number Example Dim A 10 A 0 256 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting A 1 324 A 2 100 A 10 55 LBound Function Returns the smallest available subscript for the indicated dimension of an array Syntax LBound arrayname dimension art arrayname Name of the array variable follows standard variable naming conventions dimension Optional Whole number indicating which dimension s lower bound is returned Use 1 for the first dimension 2 for the second and so on If dimension is omitted 1 is assumed UBound Function Returns the largest available subscript for the indicated dimension of an array Syntax UBound arr
40. example sequence now reads 103 amp 101 116 013 4 Add the delay time In this example a decimal value of 002 20 milliseconds after the amp function character is added The sequence is now 103 amp 002 101 116 013 5 Insert a delay between all other inter character positions the delay character and delay time can be copied using Ctrl C and pasted in the desired positions using Ctrl V Our example sequence finally reads 103 amp 002 101 amp 002 116 amp 002 013 Or back in ASCII Mode gl amp Ole amp Olt amp Olr 6 Click OK to confirm the changes NOTE To distinguish a amp delay character from a regular ampersand ASCII character decimal code 38 the delay function character is shown on a different background color by the sequence editor NOTE The character after a delay function character is interpreted as the delay time and is not sent to the serial device B Sending the command to the microcontroller application 1 Send the modified Send Sequences using the Es Send button Docklight will send out the same data as before but leave additional timing gaps as specified by the delay characters The communication display will show the same communication data as without the delays NOTE Docklight s accuracy for delay timing is limited because it has no control over the UARTS internal TX FiFo buffer The specified delay times for the amp delay function character are minimum values
41. exposure time to 25 milliseconds you need to send the following sequence elx p 0 2 5 r r is aterminating CR Carriage Return character To avoid defining a new Send Sequence for every exposure time you want to try you can use a Send Sequence with wildcards instead elxIpl I 1 1 Ir The following step by step example describes how to define an exposure time command with a parameter and use a different exposure value each time the sequence is sent Preconditions e Docklight is ready to run a test as described in testing a serial device or a protocol implementation Performing the test using commands with parameters A Preparing the project Create a new Docklight project and set up all communication parameters B Defining the commands used 1 Create anew Send Sequence Enter aName for the sequence Enter the fixed part of your command in the Sequence section For our example you would enter the following sequence in ASCII mode e xIpl 3 Now open the context menu using the right mouse button and choose Wildcard matches one character to insert one wildcard at the cursor position In our example we would have to repeat this until there are three wildcards for our three digit exposure time The sequence now looks like this e x p 1 1 4 Now add the terminating CR character using the default control character shortcut Ctrl Enter The example sequence now is e xIp I 1 r 5 Click OK to add the new seq
42. format for fast logging and storing huge amounts of data An HTML file format with styled text lets you easily distinguish between incoming and outgoing data or additional information Docklight can also log any binary data stream including ASCII 0 lt NUL gt bytes and other control characters detecting specific data sequences In many test cases you will need to check for a specific sequence within the RS232 data that indicates a problem condition Docklight manages a list of such data sequences for you and is able to perform user defined actions after detecting a sequence e g taking a snapshot of all communication data before and after the error message was received responding to incoming data Docklight lets you specify user defined answers to the different communication sequences received This allows you to build a basic simulator for your serial device within a few minutes It can also help you to trace a certain error by sending out a diagnostics command after receiving the error message Docklight will work with the COM communication ports provided by your operating system Physically these ports will be RS232 SUB D9 interfaces in many cases However it is also possible to use Docklight for other communication standards such as RS485 and RS422 which have a different electrical design to RS232 but follow the RS232 communication mechanism Docklight has also been successfully tested with many popular USB to Serial converters Blueto
43. methods described below are executed Breaks the script execution if assertCondition is False The script execution can be continued manually using the EP Continue Script toolbar Debug Break Breaks the script execution unconditionally Debug PrintMsg debugMsg Adds an additional debug text to the communication Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting window display including a date time stamp and the current line of script code Remarks The PrintMsg and Assert methods are very useful to print and watch variable values at various points of execution For the Debug methods to have any effect you need to enable Debug Mode first by setting the Mode property to one Debug Mode 1 Example Y Example Debug object Debug Mode 1 Count 0 Do Count Count 1 print some debug information the value of the count variable Debug PrintMsg count amp count break script execution when reaching 5 Debug Assert Count 5 Loop Until Count 10 now the same thing with debug mode off Debug methods have no effect Debug Mode 0 Debug PrintMsg this is never printed Debug Break this is never executed DL AddComment Debug test ended After running this script the communication window could look like this 07 04 2009 15 45 06 078 line 9 Debug count 1 07 04 2009 15 45 06 100 line 9 Debug count 2 07 04 2009 15
44. myDateTime milliseconds trimmed Pat Description myDateTime Optional a VBScript Date Time variable which provides the date time information in resolution 1 second Default value is 0 for use Docklight s own time information milliseconds Optional integer value with corresponding milliseconds from 0 999 Default value is 1 for use Docklight s own time information trimmed Optional True Remove the trailing space see Syntax 1 False Default use the original format for compatibility Remarks Syntax 2 The extended syntax is typically used for formatting Receive Sequence timing information obtained within a Sub DL OnReceive event procedure See the Example 2 10 2 1 5 OpenProject Opens an existing Docklight project file ptp file Return Value Void Syntax DL OpenProject filePathName The OpenProject method syntax has these parts Pat Description filePathName Required String containing the file path directory and file name of the Docklight project file ptp file to open The file extension ptp can be omitted If no directory is specified Docklight uses the current working directory Remarks If filePathName is not a valid Docklight project file or does not exist Docklight reports an error and the script execution is stopped If filePathName is an empty string a file dialog will be displayed to choose a project file All Receive Sequence counters are reset w
45. number of data bits and stop bits here As with the baud rate some of the available settings may not be supported by the COM port device s on your PC Parity All common parity check options are available here The settings Mark and Space will probably not be used in practical applications Mark specifies that the parity bit always is 1 Space that the parity bit is always 0 regardless of the character transmitted Parity Error Character This is the character that replaces an invalid character in the data stream whenever a parity error occurs You should specify an ASCII character printing or non printing that does not usually appear within your serial data stream Characters may be defined by entering the character itself or entering its decimal ASCII code please enter at least two digits NOTE Choose ignore for the Parity Error Character if you need to transmit receive the parity bit but Docklight should preserve all incoming characters even when the parity bit is wrong This is useful for applications where a 9th bit is used for addressing purposes and not for error checking 9 8 Dialog Project Settings Flow Control E AAAZ2AzA TzAALhlLLLLLLEZZZLL Menu Tools gt Project Settings Flow Control Used to specify additional hardware or software flow control settings for serial communications in Docklight Send Receive Mode Flow Control Support Off No hardware or software flow control mechanism is used RT
46. 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 tjelm plelrlaltjujrje Fir 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 gt 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 HHHHN orld is defined and the incoming data is Hello1Hello2World the Receive Sequence detected is Hello1Hello2World not HelloWorld Receive Sequence comment macros Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Macro key
47. port and vice versa By using a virtual null modem driver on your PC you can easily debug and simulate serial data connections without the use of real RS232 ports and cables Virtual COM connections do not give you the same timing as real RS232 connections and usually do not emulate the actual bit by bit transmission using a predefined baud rate Any data packet sent on the first COM port will appear in the second COM port s receive buffer almost immediately For most debugging and simulation purposes this limitation can be easily tolerated Some virtual null modem drivers offer an additional baud rate emulation mode where the data transfer is delayed to emulate a real RS232 connection and its limited transmission rate For an Open Source Windows software that has been successfully tested with Docklight see http comOcom sourceforge net 13 27 Wildcard pam H ee A wildcard is a special character that serves as a placeholder within a sequence It may be used for Receive Sequences when parts of the received data are unspecified e g measurement readings reported by a serial device Wildcards can also be used to support parameters in a Send Sequence The following types of wildcards are available in Docklight Wildcard F7 Matches exactly one arbitrary character any ASCII code between 0 and 255 Wildcard F8 Matches zero or one chara
48. printing characters letters A z digits 0 9 and non printing control characters ASCII Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference code 0 to 31 Predefined shortcuts are Ctrl Enter for carriage return CR decimal code 13 Ctrl Shift Enter for line feed lt LF gt decimal code 10 Use Options gt Control Character Shortcuts to define other shortcuts you find useful 9 4 Dialog Create Log File s Menu Tools gt 4 Start Communication Logging Log file format The available log formats are plain text txt files or HTML files for web browsers htm Plain text files are a good choice if you expect your log files to become very large HTML log files are more comfortable to analyze because they include all the visual formatting of the communication windows colors bold characters italic characters However the file will be larger than a plain text file and some browsers may process large HTML files quite slowly If you have specific requirements on the output format you can customize the HTML output Log file directory and base name Choose the directory and base file name for the log file s here The actual file path used for the individual log file representations are displayed in the text boxes within the Log file representation frame Overwrite append mode Choose append new data if you do not want Docklight to overwrite exi
49. received USBHID vendorld USB HID input output report access productid Docklight opens a connection to the specificed USB HID device or a Bluetooth HID device and allows sending and USBHID 4D8 F708 receiving HID report data See also the USB HID advanced settings below PIPE myNamedPipe Client connection to a Named Pipe with read write access PIPEREAD myNamedPip Client connection with read access only e Write access only PIPEWRITE myNamedPi pe Monitoring Mode Channel Combinations And Their Applications In Monitoring Mode two communication channels are available which can be set up individually This allows Docklight Scripting to be used in a large number of different applications and test environments Below is a list of typical channel combinations Communication Example Application Channel Settings Ch1 COM Port COM1 Monitoring Serial Communications Between Two Ch2 COM Port COM2 Devices using the Docklight Monitoring Cable Ch1 Docklight Monitoring Serial Communications Between Two Tap Devices using the Docklight Tap Ch2 Docklight Tap Ch1 COM Port Emulating a Serial Device Server A client can Ch2 TCP Server SERVER 1000 connect to the Docklight server on port 10001 and talk to the serial device connected on COM1 Ch1 TCP Client 10 0 0 1 502 Monitoring a Client Server TCP Connection Ch2 TCP Server SERVER 502 Chi UDP Peer UDP 10 0 0 1 8 Monitoring and forwarding a UDP transmission Ch2 U
50. section How to Obtain Best Timing Accuracy for details Control Characters Shortcuts Here you can define your own keyboard shortcuts for ASCII Control Characters ASCII code 32 or for any character code 126 Keyboard shortcuts can be used within the following Docklight dialogs and functions e Dialog Edit Send Sequence e Dialog Edit Receive Sequence e Dialog Find Sequence e Dialog Send Sequence Parameter e Keyboard Console Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference For each character from decimal code 0 to 31 and from 127 to 255 you can define a keyboard combination to insert this character into a sequence Shortcut You may also define a letter which is used to display this control character when editing a sequence in ASCII mode Editor Double click to change the value of a Shortcut or Editor field Predefined shortcuts are Ctrl Enter for carriage return CR decimal code 13 Ctrl Shift Enter for line feed lt LF gt decimal code 10 9 11 Dialog Customize HTML Output HR M Rr H B This dialog allows you to change the appearance of the HTML log files by modifying the HTML template code that Docklight uses when generating the HTML log file data You need some basic understanding of HTML documents and CSS style attributes We recommend http www htmldog com English or http www selfh
51. simple text box that does not offer formatting menus or toolbars but you can paste formatted text from the Windowsclipboard The notepad contents are stored along with all other Docklight project settings see saving and loading your project data When opening a Docklight project file the notepad is displayed automatically if project notes are available NOTE Closing the notepad window does not delete your notes They will be still available when you press F12 again To remove all notes empty the text box using Ctrl A Select All and the DEL key Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Features and Functions Features and Functions Features and Functions 4 1 How Serial Data Is Processed and Displayed p w Docklight handles all serial data in an 8 bit oriented way Every sequence of serial data consists of one or more 8 bit characters Docklight allows you to e display the serial data in either ASCII HEX Decimal or Binary format e copy serial data to the clipboard and paste it into a standard text file or a formatted Microsoft amp Word document or create a Send Receive Sequence using the data e print out serial data user comments and other information Docklight s communication window shows the current communication on the selected serial port s Docklight distinguishes between two commun
52. test run where the above Send Sequences were sent to a real modem 7 2 Reacting to a Receive Sequence Sample Project PingPong ptp The Docklight project PingPong ptp is a simple example for how to define and use Receive Sequences Getting started e Go to the Project Settings dialog and choose a COM port e Apply a simple loopback to this COM port Connect Pin 2 RX with Pin 3 TX See RS232 SUB D9 Pinout e Now press the Iz Send button for either of the two Send Sequences Communication is started and the Send Sequence is transmitted It will of course be Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials instantly received on the COM port s RX line Docklight will detect the incoming data as being one of the defined Receive Sequences It will then perform the action predefined for this event which is sending out another sequence As a result Docklight will send out alternating Send Sequences Ping and Pong e Use the B Stop communication button to end the demo The Docklight communication display should look similar to this S 872009 16 25244 201 TX e e o Ping 3 8 2009 16 25 44 216 RX o Ping Ping received 3 8 2009 16 25 44 218 TX eese Fong 3 8 2009 16 25 44 233 RX o Pong Pong received 2 872009 16 25 44 236 TX Bing 3 8 2009 16 25 44 251 RX o Ping Ping received 3 8 2009 16s 25244254 TX geeee
53. the definitions and examples listed below For getting started try some of the following examples by copying amp pasting the code into the script editor window and running the script Docklight Scripting also comes with a number of sample scripts for you to try out This chapter introduces some basic VBScript functions and features For a complete reference please see the original documentation from Microsoft at the following locations e Visual Basic Scripting Edition or go to www microsoft com and search for VBScript e VBScript Users Guide e VBScript Language Reference TIP Use the ScriptEngine function to find out which version of VBScript is installed on your computer NOTE Docklight Scripting executes the VBScript code in safe mode safe subset and disallows potentially harmful actions For example creating a FileSystemObject file I O is one of the actions disallowed in the VBScript safe subset The Docklight script will abort with an error message Please contact our e mail support if you have special requirements and need to use unsafe VBScript statements By popular request file I O is now easily possible using Docklight s Filelnput FileOutput objects Docklight Specific Features e Docklight Script Commands The DL Object e Docklight OnSend OnReceive event procedures e Docklight Filelnput FileOutput Object for Reading and Writing Files VBScript Basic Features by Categories Control Structures D
54. 0 9 and non printing control characters ASCII code 0 to 31 Predefined shortcuts are Ctrl Enter for carriage return CR decimal code 13 Ctrl Shift Enter for line feed lt LF gt decimal code 10 Use Options gt Control Character Shortcuts to define other shortcuts you find useful Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference 9 3 Dialog Edit Receive Sequence pum 4 This dialog is used to define new Receive Sequences and edit existing ones See also Editing and Managing Sequences Index The index of the sequence displayed below The first sequence has index 0 zero 1 Name Unique name for this sequence e g Ping received This name is for referencing the sequence It is not the sequence received through the serial port See 2 Sequence below 2 Sequence The character sequence which should be detected by Docklight within the incoming serial data TIP Special Function Characters are available for detecting inter character delays evaluating handshake signal changes or detecting a break state 3 Action The action s performed when Docklight detects the sequence defined above You may choose from the following actions Answer After receiving the sequence transmit one of the Send Sequences Only Send Sequences that do not contain wildcards can be used as
55. 1 amp rl amp Result 2 amp r2 The VBScript constant vbCrLf can be used for an additional line break too DL AddComment DL AddComment Result 1 amp rl amp vbCrLf DL AddComment Result 2 amp r2 Disabling the line break and padding characters gives you better control over the actual output DL AddComment vbCrLf Here s some bit of info False False DL AddComment rmation vbCrLf False False A beep signal for user notification DL AddComment Chr 7 10 2 1 2 ClearcommWindows Deletes the contents of the communications window This applies to all four representations ASCII HEX Decimal Binary of the communication window Return Value Void Syntax DL ClearcommWindows Example Example ClearCommWindows fresh start DL ClearCommWindows DL AddComment Test run started 10 2 1 3 GetReceiveCounter Returns the current hit counter value for the specified Receive Sequence The counter is incremented each time the Receive Sequence is detected within the incoming data Stream It can be reset using the ResetReceiveCounter command The OpenProject and StartCommunication commands also reset the hit counter to zero Return Value Long Syntax result DL GetReceiveCounter nameOrindex Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting The GetReceiveCounter method syntax has these parts Pat Description
56. 3 04 02 00 00 CO EO 4 26 2009 13 30 27 075 TX 04 04 02 04 00 77 FO Playback TX with fixed 500 milliseconds interval 4 26 2009 13 30 27 095 TX 01 04 00 00 00 01 31 CA 4 26 2009 13230 27 595 TX 2 04 00 00 00 01 31 F9 4 26 2009 13230 28 096 TX 03 04 00 00 00 01 30 28 4 26 2009 13 30 28 596 TX 04 04 00 00 00 01 31 9F Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 2 2 12 SaveProgramOptions Saves the current Docklight program options everything that can be adjusted in the Options dialog and the active communication window mode ASCII HEX Decimal or Binary to a file Return Value Void Syntax DL SaveProgramOptions filePathName The SaveProgramOptions method syntax has these parts Part filePathName Required String containing the file path directory and file name of the Docklight settings file create If no directory is specified Docklight uses the current working directory If filePathName is an empty string a file dialog will be displayed to choose a file Remarks A file created with SaveProgramOptions can be loaded using LoadProgramOptions SaveProgramOptions creates XML files xml file extension SaveProgramOptions and LoadProgramOptions are very useful to ensure that Docklight uses specific display and time stamp settings for executing your Docklight script This is great for automated testing tools that are intended fo
57. 3 9 2009 17 29 24 266 RX o Ping Ping received 3 9 2009 17 29 24 268 TX o Pong 3 9 2009 17 29 24 298 RX o Ping Ping received 3 9 2009 17 29 24 301 TX 6 Pong Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Reference 9 Reference 9 1 Menu and Toolbar Scripting pr M J File Menu New Project Close the current Docklight project and create a new one amp Open Project Close the current Docklight project and open another project Import Sequence List Import all Send Sequences and Receive Sequences from a second Docklight project El Save Project Save Project As Save the current Docklight project Print Project Print the project data i e the list of defined Send Sequences and Receive Sequences The sequences are printed in the same representation ASCII HEX Decimal or Binary that is used in the Docklight main window The representation may be chosen using the Options dialog window amp Print Communication Print the contents of the communication window The communication data is printed in the same representation that is currently visible in the communication window Exit Quit Docklight Edit Menu Edit Send Sequence List Edit the Send Sequences list i e add new sequences or delete existing ones Edit Receive Sequence List Edit the Receive Seq
58. 9 59 Y ae 90 5A Z Z 91 5B 92 5G N N 93 5D 94 5E A A 95 5F m B 96 60 97 61 a a 98 62 b b Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 99 63 c c 100 64 d d 101 65 e e 102 66 f f 103 67 g g 104 68 h h 105 69 i T 106 6A j j 107 6B k k 108 6C L L 109 6D m m 110 6E n n 111 6F o o 112 70 p p 113 71 q q 114 72 r r 115 73 S S 116 74 t E 117 75 u u 118 76 v v 119 77 w w 120 78 x x 121 79 y y 122 7A z Z 123 7B 124 we 125 7D 126 7E Tilde 127 7F DEL Delete 12 2 Hot Keys General Hot Keys Applies to e Communication window ASCII HEX Decimal Binary e Edit Send Sequence dialog Edit Receive Sequence dialog e Docklight Notepad Function oy SOS Context specific Hot Keys Docklight menu Menu Funcion HotKey Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix Fie Open Project ctro O Fie Save Project o etrs O Edit Edit Find Sequence in Comm Window Run Start Communication Run Stop Communication File New Project File File Run Run C B C C F F Tools c c F s S S S S S Stop Script Break Script Show Hide Docklight Notepad 12 Scripting Continue Script Ishift rs CELF trl trl trl 5 6 trl F5 trl F6 12 ift F5 ift F6 ift F7 ift F8 ifti ift Tu dou Scripting Show Editor
59. ANU Bae ST The Docklight script CharacterManipulation pts demonstrates how to manipulate a RS232 data stream using the DL OnReceive event procedure All data received on the RX line is sent out again on the TX line but with some of the characters replaced Getting started e Open the project file CharacterManipulationPrj ptp using the amp Open Project menu and the script file CharacterManipulation pts using the Open Script menu The files are located in the ScriptSamples folder Go to the Project Settings dialog and choose a COM port Press the E gt Run Script button in the toolbar Start a second instance of Docklight and open the project file CharacterManipulationTest ptp Choose a different COM port for this second Docklight instance or even use another computer Connect the two COM ports using a simple null modem cable Or use a virtual null modem instead e Use the ea Send button on the second instance of Docklight to send the test sentence The communication display ofthe second instance of Docklight should look similar to this 2 21 2009 11 56 57 343 TX This is a test for the character manipulation sample script 2 21 2009 11 56 57 502 RX Dhis is a desd for dhe characder manibuladion samble scribd Each T is replaced by a D and each P is replaced by a B Visitors to the Nuremberg area where our company is located might notice that dialect speakers here do something similar
60. APPDATA C Users docklight AppData Local LOGONSERVER FUHEDV5 NUMBER OF PROCESSORS 4 OS Windows NT PROCESSOR_ARCHITECTURE x86 PROCESSOR IDENTIFIER Intel64 Family 6 Model 37 Stepping 5 GenuineIntel PROCESSOR LEVEL 6 PROCESSOR REVISION 2505 PUBLIC C Users Public TEMP C Users docklight AppData Local Temp TMP C Users docklight AppData Local Temp USERDOMAIN FUHEDV5 USERNAME docklight USERPROFILE C Users docklight 10 2 2 7 GetHandshakeSignals Returns the current handshake signal states CTS DSR DCD RI as an integer bit value in the same way the Receive Sequence function character works Return Value Integer Syntax result DL GetHandshake Signals Remarks result is a bit value with the following components Bit No Decimal Value Handshake Signal o lo CTS High 0 000 O Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting RI Ring Indicator High In Tap Pro Tap 485 applications GetHandshakeSignals returns the following extended set of handshake signal states Bit No Decimal Value Handshake Signal jo 1001 CTS High DCE side Docklight Receive Channel 2 LM DSR High DCE side Channel 2 hm ig eo hm te man 016 Jose High TE si Channa See also SetHandshakeSignals for controlling the state of the RTS and DTR lines
61. C library http www boost org libs crc index html Last not least if you are truly fascinated by CRC alchemy you will sooner or later run Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used into the following article A Painless Guide to CRC Error Detection Algorithms by Ross N Williams http www ross net crc 13 5 DCE Data Communications Equipment The terms DCE and DTE refer to the serial devices on each side of an RS232 link A modem is a typical example of a DCE device DCE are normally equipped with a female SUB D9 or SUB D25 connector See also DTE 13 6 DTE Data Terminal Equipment The terms DCE and DTE refer to the serial devices on each side of an RS232 link A PC or a terminal are examples of a typical DTE device DTE are commonly equipped with a male SUB D9 or SUB D25 connector All pinout specifications are written from a DTE perspective See also DCE 13 7 Flow Control Flow control provides a mechanism for suspending transmission while one device is busy or for some reason cannot further communicate The DTE and DCE must agree on the flow control mechanism used for a communication session There are two types of flow control hardware and software Hardware Flow Control Uses voltage signals on the RS232 status lines RTS DTR set by DTE and CTS DSR set by DCE to control the transmission and reception of data See also RS232 pinout Sof
62. DP Peer similar to the TCP example above Note that for UDP 10 0 0 2 8 each channel you need to specify a different UDP port because each channel needs to listen on its own separate port number COM Port Settings COM TAP and VTP channels only Baud Rate Choose a standard baud rate from the dropdown list or use a non standard baud rate by typing any integer number between 110 and 9999999 NOTE Non standard baud rates may not work correctly on all COM ports dependant on the capabilities of your COM port s hardware UART chip You will receive no warning if any non standard rate cannot be applied NOTE Although Docklight s Project Settings allow you to specify baud rates up to 9 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference MBaud this does not mean Docklight is able to handle this level of throughput continuously The average data throughput depends very much on your PC s performance and the Docklight display settings See also How to Increase the Processing Speed NOTE There are many COM ports drivers and applications that do not use actual RS232 422 or 485 transmission and do not require any of the RS232 communication parameters In some cases such COM port drivers even return an error when trying to set the RS232 parameters so Docklight would fail to open the COM channel Use the Baud Rate setting None for these applications Data Bits and Stop Bits Specify the
63. End If End If End If End Sub After starting the script and manually sending out a Send Value sequence with parameter value 95 the Communication Window could look like this 7 29 2012 15 43 43 823 TX VALUE 95 7 29 2012 15 43 43 826 RX VALUE 95 Value received 95 7 29 2012 15 43 43 879 TX VALU Eri ll o o 7 29 2012 15 43 43 880 RX VALUE 96 Value received 96 7 29 2012 15 43 43 926 TX VALUE 97 7 29 2012 15 43 43 927 RX VALU Value received 97 Eri Il Ko 7 29 2012 15 243 43 977 IX VALU ea ll o oo 7 29 2012 15 43 43 978 RX VALUE 98 Value received 98 7 29 2012 15 43 44 025 TX VALUE 99 7 29 2012 15 43 44 026 RX VALUE 99 Value received 99 VALUE 99 stopping Example 2 Example using DL OnReceive in code with Pause statements Predefined Send Sequence 0 Hello Hello lt CR gt lt LF gt Predefined Receive Sequence 0 Hello Hello lt CR gt lt LF gt Run this test on a COM port with a loopback connector TX connected to RX of the same port DL ClearCommWindows Get the communication started Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting started True DL SendSequence Hello Wait for about 1 second but make sure that the DL OnReceive events are processed meanwhile pauseWithEvents 1000 St
64. Example Example GetHandshakeSignals DL StartCommunication Do DL AddComment DL GetDocklightTimeStamp amp GetHandshakeSignals amp DL GetHandshakeSignals DL Pause 200 Loop Example Communication Window output 6 23 2012 10 07 44 244 GetHandshakeSignals 0 6 23 2012 10 07 44 469 GetHandshakeSignals 48 6 23 2012 10 07 44 677 GetHandshakeSignals 48 6 23 2012 10 07 44 884 GetHandshakeSignals 48 NOTE It can take 5 10 milliseconds after Start Communication until GetHandshakeSignals reports the correct signal state 10 2 2 8 GetReceiveComments Retums a chronological list of all Receive Sequence comments issued as an alternative to the Sub DL OnReceive processing Return Value String Syntax result DL GetReceiveComments Remarks result contains all Receive Sequence Comments in chronological order separated by a line break since the last call of GetReceiveComments With the help of Receive Sequence comment macros you can implement a parser for all incoming Receive Sequence data as an alternative to Sub DL OnReceive Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting NOTE A maximum of 10000 Receive Sequence events are stored and returned by GetReceive Comments which should be sufficient for all practical applications 10 2 2 9 InputBox2 Alternative to the original VBScript InputBox method Displa
65. F gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt Testing with settings COM3 115200 NONE 8 1 28 01 2008 16 28 239 73 TX ATIS lt ZER gt lt LE gt 28 01 2008 16 28 39 73 RX ATLI lt CR gt lt CR gt lt LF gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LE gt OK lt CR gt lt LF gt 10 2 2 14 SetContentsFilter Use a different Contents Filter setting than the one defined in the Project Settings Communication Filter dialog Return Value Void Syntax DL SetContentsFilter newContentsFilter The SetContentsFilter method syntax has these parts Pat Description o O newContentsFilt Required Integer value to select the new filter 0 Show all original communication data channel 1 and channel 2 1 Show channel 1 or TX data only 2 Show channel 2 or RX data only 3 Hide all original serial data show additional comments only Remarks After the script execution has ended the Contents Filter is set to the original project setting defined in Project Settings Communication Filter Example Requires the Docklight basic example project PingPong and a loopback on the chosen communication channel L OpenProject PingPong L ClearCommWindows L SendSequence Ping L Pause 50 L AddComment vbCrLf SetContentsFilter 1 L SetContentsFilter 1 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelb
66. Fong 3 8 2009 16 25 44 268 RX o Pong Pong received 2 872009 16 25244 9 71 TX Ping 3 8 2009 16 25 44 286 RX o Ping Ping received 3 8 2009 16 25 44 289 TX Pong 3 8 2009 16 25 44 303 RX o Pong Pong received 23 8 2009 16 25 44 307 TX 6 Ping 3 8 2009 16 25 44 322 RX o Ping Ping received 378720093 16 25 442 324 TX 83 Pong See also the corresponding log files in the Samples folder PingPong Logfile asc htm and PingPong Logfile hex htm Further Information This demo project can also be run in three alternative configurations 1 Run two Docklight applications on the same PC using different COM ports The two COM ports are connected using a simple null modem cable 2 Instead of two RS232 COM ports and a null modem cable you can use a virtual null modem 3 Use two PCs and run Docklight on each PC Connect the two PCs using a simple null modem cable TIP For Docklight Scripting there is also a related example project that uses a UDP loopback connection and does not require any serial data ports See the PingPong UDP Loopback ptp project in the Network folder of the ScriptSamples directory 7 3 MODBUS RTU With CRC checksum Sample Project ModbusRtuCrc ptp TE TEE EG The Docklight project file ModbusRtuCrc ptp demonstrates how to automatically calculate the CRC value required to send a valid MODBUS RTU frame Docklight Scripting V2 1 User Manu
67. For i 0 To 255 FileOutput WriteByte i Next FileOutput CloseFile And load it DL AddComment DL AddComment Reading raw data file FileInput OpenFile C test bin True Do Until FileInput EndOfFile DL AddComment Right 0 Hex FileInput GetByte 2 False False Loop FileInput CloseFile The above script code produces the following output in the Docklight communication window Reading text file Hello World Goodbye World Reading raw data file Q0 01 02 03 04 05 06 07 08 09 0A 0B OC OD OE OF 10 11 12 13 14 15 16 17 X9 19 1A LB ie 1D 1 20 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 41 42 ti Im 20 2122 23 24 25 26 27 2 29 2A 2B Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77 78 79 TA TE 7C 7D 7E JF 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F AO Al A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF BO B1 B2 B3 B4 B5 B6 B7 BS BO BA BB BC BD BE BF CO C1 C2 C3 C4 C5 Ce C7 C8 C9 CA CB CC CD E CF DO D1 D2 D3 D4 D5 D D7 D DI DA DB DC DD DE DF EO El E2 E3 EA E5 E6 E7 E8 E9 EA EB EC ED EE EF FO F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF 10 42 fFileOutput Wr
68. Heggelbacher GbR Appendix 12 7 Docklight Tap Pro Tap 485 EEEE Docklight Tap Pro and Docklight Tap 485 are advanced high resolution monitoring solutions for the USB port They are supported by Docklight in a similar way as the Docklight Tap Docklight has built in support for Tap Pro and Tap 485 Use Docklight Monitoring Mode and Receive Channel settings VTPO VTP1 See Docklight Project Settings and How to Obtain Best Timing Accuracy for details Please also see our product overview pages for more information about the Docklight Tap Pro Device 1 Device 2 Sub D9 Sub D9 female male Mini USB Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used Glossary Terms Used 13 Glossary Terms Used 13 1 Action For a Receive Sequence the user may define an action that is performed after receiving the specified sequence Possible actions are e Sending a Send Sequence Only Send Sequences without any wildcards can be used e Inserting a comment A user defined text or an additional date time stamp is added to the communication data window and log file e Triggering a Snapshot e Stopping communication 13 2 Break A break state on an RS232 connection is characterized by the TXline going to Space logical 0 for a longer period than the maximum character frame length including start and stop bits Some application protocols e g LIN use this for synchron
69. P Address 192 0 0 2 Docklight Channel 1 Server 502 Docklight Channel 2 192 0 0 1 502 Docklight PC Preconditions e Device 1 Device 2 and the PC with Docklight are connected in a common network LAN e All IP addresses and the TCP port number are known e Device 1 is currently configured to connect to Device 2 and communications between the two devices is working Route and debug TCP traffic A Route the traffic through Docklight Scripting In Device 1 change the communication parameters Device 1 must connect to the Docklight PC in our example IP 192 0 0 2 B Setup Docklight Scripting for operating as a bridge for the communication between Device 1 and Device 2 1 Choose the menu Tools Project Settings 2 Choose communication mode Monitoring Receive only 3 ForReceive Channel 1 type the keyword SERVER and the TCP port to listen on e g SERVER 502 4 ForReceive Channel 2 type the IP address and TCP Port number for connecting to Device 2 e g 192 0 0 1 502 5 Confirm the settings and close the dialog by clicking the OK button C Running the test Start Docklight Scripting using Run gt Start Communication Let Device 1 connect and perform a test run Docklight Scripting will act as a bridge between the devices and show you all the TCP data transferred between the devices in the communication window NOTE Docklight Scripting does not allow multiple connections on a SERVER p
70. PCI COM card 9 9 Dialog Project Settings Communication Filter p g M Menu Tools gt Project Settings Communication Filter Contents Filter Use this option if you do not need to see the original communication data on the serial line and only require the additional comments inserted by a Receive Sequence This is useful for applications with high data throughput where most of the data is irrelevant for testing and you only need to watch for very specific events These events and related display output can be defined using Receive Sequences Channel Alias This allows you to re label the two Docklight data directions according to your specific use case E g Docklight Device instead of TX RX Or Master Slave instead of TAPO TAP 1 9 10 Dialog Options EE Menu Tools Options Display Formatted Text Output Rich Text Format used for setting the appearance of the Docklight communication window The two different serial data streams Channel 1 and Channel 2 may be displayed using different colors and styles The standard setting uses different colors for the two channels but using different font styles e g Italics for Channel 2 is also possible You may also choose the overall font size here NOTE If you change the font size the communication window contents will be deleted For all othe
71. S and DTR are enabled when the COM port is opened Manual Use this mode to control the RTS and DTR signals manually and display the current state of the CTS DSR DCD and RI lines If flow control is set to Manual an additional status element is displayed in the Docklight main window You may toggle the RTS and DTR lines by double clicking on the corresponding indicator NOTE Flow control signals are not treated as communication data and will not be displayed in the communication window or logged to a file Hardware Handshaking Software Handshaking Support for RTS CTS hardware flow control and XON XOFF software flow control These Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference are expert settings rarely required for recent communication applications RS485 Transceiver Control Some RS232 to RS485 converters require manual RTS control i e the RS232 device PC tells the converter when it should enable its RS485 driver for transmission If you choose RS485 Transceiver Control the COM port sets RTS to High before transmitting the first character of a Send Sequence and resets it to Low after the last character has been transmitted NOTE Many USB to Serial converters or virtual COM port drivers do not implement the Windows RTS CONTROL TOGGLE mode properly If you experience problems with RS485 Transceiver Control try using a PC with an on board COM interface or a standard
72. Scripting Hide Editor Scripting _ Save Script Communication Window h h h h h h Hot Key Clear All Communication Windows tr Toggle Between ASCII HEX Decimal and Binary Ctrl Tab Representation Send Sequences Receive Sequences List Function Ht Key Delete This Sequence Del Edit This Sequence Send This Sequence Send Sequences List only Wildcard matches one character Notepad Window Function Ht Key Default Font Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 12 3 RS232 Connectors Pinout ZZ m gt gt gt gt gt _ LL LL LLLLS SS The most common connectors for RS232 communication are e 9 pole SUB D9 EIA TIA 574 standard Introduced by IBM and widely used See below e 25 pole SUB D25 RS232 C This is the original connector introduced for the RS232 standard It provides a secondary communication channel e 8 pole RJ45 RS232 D according to EIA TIA 561 standard RS232 SUB D9 Pinout View Looking into the male connector Pinout From a DTE perspective the DTE transmits data on the TX Transmit Data line while the DCE receives data on this line Pin No Signal Name Description DTE in out Signal Ground ET 6 DSR DataSetReady 2 input a OTS Clear To Send input 9 R Ring indicator jnpt RS232 SUB D25 Pinou
73. Sequence is transmitted This is especially useful when Docklight is testing a serial device and the sequence detection should not get confused by incomplete or faulty packets received earlier See also DL OnSend Example ResetReceiveCounter Reset sequence detection each time a new sequence is sent Endless loop to prevent the script from terminating immediately Do Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL Pause 1 the pause reduces CPU load while idle Loop Sub DL OnSend DL ResetReceiveCounter End Sub 10 2 1 9 SendSequence Sends a Send Sequence or a custom data sequence Starts the communication if not already running see StartCommunication Return Value Void Syntax 1 DL SendSequence nameOrindex parameters representation Sends out the Send Sequence that matches nameOrlndex The SendSequence method syntax 1 has these parts nameOrindex Required String containing the Name of the Send Sequence The first Send Sequence from the list with a name that matches nameOrlndex is used As an alternative you may pass an integer value specifying the Sequence Index Valid Sequence Index range is from 0 to NoOfSendSequences 1 parameters Optional String containing one or several parameter value s for a Send Sequence with wildcards Parameters are passed in ASCII representation by default The space character is use
74. SetChannelSettings command that specified a non existing COM port number See also SetChannelSettings and GetChannelSettings Example Example GetChannelStatus requires Docklight in Send Receive mode Y DL ClearCommWindows DL AddComment COM port access DL SetChannelSettings COM3 9600 NONE 8 1 1 DL AddComment GetChannelStatus before StartCommunication amp DL GetChannelStatus 1 DL StartCommunication DL AddComment GetChannelStatus after StartCommunication amp DL GetChannelStatus 1 DL StopCommunication DL AddComment DL AddComment TCP client mode DL AddComment Connecting to docklight de DL SetChannelSettings docklight de 80 1 DL StartCommunication y wait until connected Do commStatus DL GetChannelStatus 1 DL AddComment GetChannelStatus amp commStatus DL Pause 10 Loop Until commStatus 2 If commStatus 1 Then DL AddComment Connected Else DL AddComment Error End If DL StopCommunication Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting After running the script on a computer with a built in COM3 port e g modem and Internet connection the communications window could look like this COM port access GetChannelStatus before StartCommunication 0 GetChannelStatus after StartCommunication 1 TCP client mode Connecting to docklight de GetChannelStatus
75. Signals 3 m 8 een D REPERI EROR HER EEE GRE FUE BOXER RE RENE EXER teal en 10 2 2 16 Uere TELS 10 2 3 Properties seinen 10 2 3 1 NoOfsendSequences ciiin niei e i ann EEVEE nennen 10 2 3 2 NoOfReceiveSequences 10 3 OnSend OnReceive Event Procedures 10 3 1 Sub DL OnSend Send Sequence Data Manipulation eeeesssss 122 10 3 2 Sub DL OnReceive Evaluating Receive Sequence Data ss 124 10 3 3 OnSend OnReceive Timing and Program Flow cccccsseceseceseceeeeesssecsseceneeeees 129 10 4 Filelnput FileOutput Objects for Reading and Writing Files 131 10 4 1 Filelnput Reading Files u a 131 10 4 2 FileOutput Writing Files ae 133 10 4 3 Multiple Input Files Multiple Output Files ueeneneseesssensnnenenenennsensnennnnenennnnnn 134 10 5 Debug Object Script Debugging eese senes eene eere eene enne nnne nnns ennt nn nen 134 10 6 include Directive u nennen hinaus 136 10 7 Command Line Syntax ee re EEEY M EUM KP RE EP FEN NUS 137 10 8 Dialog Customize External Editor eese sees eee ee esee en nene en nene tn sesta non 137 11 Support 140 11 1 Web Support and Troubleshooting enses esee ee eee eere en nennen nennen sn nones 141 11 2 E Mail SUP DOME ss 141 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Table of Conten
76. Windows XP Command shell overview at www microsoft com For a list of variables available on your current user profile open a Windows Command Processor window cmd exe then type SET and press Enter NOTE In Docklight Scripting V2 0 and earlier this method was called GetEnvironmentVariable The old name is still supported for compatibility reasons It was changed to avoid confusion with the Windows API function of the same name Example Example GetEnvironment nameList ALLUSERSPROFILE APPDATA COMPUTERNAME HOMEDRIVE HOMEPATH LOCALA Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting PPDATA LOGONSERVER NUMBER OF PROCESSORS OS PROCESSOR ARCHITECTU RE PROCESSOR IDENTIFIER PROCESSOR LEVEL PROCESSOR REVISION PUBL IC TEMP TMP USERDOMAIN USERNAME USERPROFILE DL AddComment Running Docklight Scripting amp DL GetEnvironment DOCKLIGHT VERSION nameArray Split nameList For i 0 To UBound nameArray name nameArray i DL AddComment name amp amp DL GetEnvironment name Next On a Windows 7 x64 PC the communications window output could look like this Running Docklight Scripting Version 2 1 4 ALLUSERSPROFILE C ProgramData APPDATA C Users docklight AppData Roaming COMPUTERNAME FUHEDV5 HOMEDRIVE C HOMEPATH Users docklight LOCAL
77. XEN TFT Ju Acc sli Rn The global DL object is used to access Docklight specific functions from a VBScript program DL Methods DL AddComment DL ClearCommWindows DL GetReceiveCounter DL GetDocklightTimeStamp DL OpenProject DL Pause DL Quit DL ResetReceiveCounter DL SendSequence DL StartCommunication DL StopCommunication DL StartLogging DL StopLogging DL WaitForSequence DL Methods Advanced DL CalcChecksum DL ConvertSequenceData DL GetChannelSettings DL GetChannelStatus DL GetCommWindowData DL GetEnvironment DL GetHandshakeSignals DL GetReceiveComments DL InputBox2 DL LoadProgramOptions DL PlaybackLogFile DL SaveProgramOptions DL SetChannelSettings DL SetContentsFilter DL SetHandshakeSignals DL UploadFile Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL Properties DL NoOfSendSequences DL NoOfReceiveSequences Additional Docklight Scripting Features OnSend OnReceive Event Procedures Filelnput FileOutput Objects for Reading and Writing Files 10 2 1 Methods 10 2 1 1 AddComment Adds a user defined text to the communication data window and log file Return Value Void Syntax DL AddComment comment timeStampAfterComment lineBreak AndPadding The AddComment method syntax has these parts Pat Description S O Optional String containing the comment to add to the communication window s or log file s If comment i
78. acher GbR ovo0000 Reference Scripting D D DL DL DL D D Pause 50 AddComment vbCrLf SetContentsFilter 2 Pause 50 AddComment vbCrLf SetContentsFilter 3 Pause 50 E SetContentsFilter 2 SetContentsFilter 3 E After running the script the Docklight communication window could look like this 7 30 2012 17342 31 322 TX 2D 2D 2D 2D F 20 DI E 67 7 30 2012 17 42 31 326 RX 2D 2D 2D 2D 6F 20 50 69 6E 67 Ping received 7 30 2012 17 42 31 350 TX F 2D 2D 2D 2b 20 50 GF 6E 67 7 30 2012 17 42 31 352 RX 6P 2D 25 2D 2D 20 50 OF GE 67 Pong received 7 30 2012 17 42 31 499 TX 2D 2D 2D 2D F 20 50 69 E 67 SetContentsFilter 1 Ping received 7 30 2012 17 42 31 523 TX Fr 2D 2D 2D 2D 20 50 GF 6E 67 Pong received 1 30 2012 17 242 31 547 TX 2D 2D 2D 20 50 69 GE 67 Ping received 7 30 2012 17 242 31 572 TX 6F 2D 2D 2D 2D 20 50 GF GE 67 Pong received 7 30 2012 17 242 31 594 TX ZD 2D 2D 2D 6F 20 50 69 GE 67 Ping received 7 30 2012 17 42 31 619 TX 6F 2D 2D 2D 2D 20 50 GF 6E 67 SetContentsFilter 2 7 30 2012 17242 391 621 RX GF 2D 20 2D 2D 20 50 OF Gr 67 Pong received 2D 2D 2D 2D 6F 20 50 69 6E 67 Ping received 6F 2D 2D 2D 2D 20 50 6F 6E 67 Pong received 2D 2D 2D 2D GF 20 50 69 6E 57 Ping received 6F 2D 2D 2D 2D 20 50 GF 6E 67 Pong received SetContentsFilter 3 Ping received Pong
79. affic through Docklight using standard RS232 cabling Use the No Data Forwarding Expert Option for applications with two serial COM ports where you need to avoid that any TX data is sent This can be used to improve performance when using a Docklight Monitoring Cable or to work around problems caused with unstable serial device drivers For Docklight Tap applications e g using Communication Channel TAPO TAP1 the Data Forwarding setting has no effect The Docklight Tap is accessed in read only mode always and no data is forwarded 9 13 Keyboard Console aen The Keyboard Console tool allows you to send keyboard input directly to the serial port It can be activated using the menu Tools gt d Keyboard Console On The keyboard console is only available for communication mode Send Receive After activating the keyboard console click in the communication window and type some characters Docklight will transmit the characters directly through the selected serial port The communication window will display the characters the same way it does a Send Sequence NOTE The Keyboard Console tool supports pasting and transmitting a character sequence from the clipboard using Ctrl V This is similar to pasting clipboard data inside the Edit Send Sequence Dialog Clipboard contents that exceeds the maximum sequence size of 1024 characters gets truncated NOTE The
80. al 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials The project file uses the communication settings listed below according to the MODBUS implementation class Basic Communication Mode Send Receive Send Receive on comm channel COM1 COM Port Settings 9600 Baud Even parity 8 Data Bits 1 Stop Bit Getting started e Open the project file ModbusRtuCrc ptp menu zm Open Project The file is located in the Samples folder Connect the PC s COM port to your MODBUS network Open the Project Settings dialog and make sure you have selected the correct COM Port for Send Receive on comm channel Use the Eg Send button to read input register no 1 from a slave Enter a slave number in the Send Sequence Parameter dialog e g 01 for addressing slave no 1 After sending Read Input Register commands to slaves 1 4 the communication window could look like this 5 29 2015 18 45 23 193 TX 01 04 00 00 00 O1 31 CA 5 29 2015 18 45 23 342 RX 01 04 02 FF EF BS 80 5 29 2015 18 45 33 145 TX 02 04 00 00 00 01 31 F9 5 29 2015 18 45 33 292 RX 02 04 02 27 10 BY 0C 5 29 2015 18 45 43 237 TX 03 04 00 00 00 01 30 28 5 29 2015 18 45 43 392 RX 03 04 02 00 00 CO FO 5 29 2015 18 45 58 724 TX 04 04 00 00 00 01 31 9F 5 29 2015 18 45 58 870 RX 04 04 02 04 00 77 FO The RX channel shows the responses from the MODBUS slaves slave 1 responded value 1
81. ame file but now play the answers from the RX side DL AddComment DL AddComment DL AddComment Playback RX side DL PlaybackLogFile modbus logfile hex txt RX Same file but use a fixed time interval between the individual sequences DL AddComment DL AddComment DL AddComment Playback TX with fixed 500 milliseconds interval DL PlaybackLogFile modbus logfile hex txt 500 We assume that the log file modbus logfile hex txt was created during a previous MODBUS communication session and contains the following information 8 29 2006 18 45 23 19 TX 01 04 00 00 00 01 31 CA 8 29 2006 18 45 23 34 RX 01 04 02 FF FF B8 80 8 29 2006 18 45 33 14 TX 02 04 00 00 00 01 31 F9 8 29 2006 18 45 33 29 RX 02 04 02 27 10 E7 OC 8 29 2006 18 45 43 23 TX 03 04 00 00 00 01 30 28 8 29 2006 18 45 43 39 RX 03 04 02 00 00 CO FO 8 29 2006 18 45 58 72 TX 04 04 00 00 00 01 31 9F 8 29 2006 18 45 58 87 RX 04 04 02 04 00 77 FO After running the example script the communications window could look like this Playback TX side 4 26 2009 13 29 15 841 TX 01 04 00 DO 00 01 31 CA 4 26 2009 13 29 25 788 TX 02 04 00 00 00 01 31 F9 4 26 2009 13229 35 879 TX 03 04 60 DO 00 O1 30 28 4 26 2009 13 29 51 367 TX 04 04 00 00 00 01 31 9F Playback RX side 4 26 2009 13 29 51 545 TX 01 04 02 FF FF B8 80 4 26 2009 13 30 01 495 TX 02 04 02 27 10 ET 0C 4 26 2009 13 230 11 596 TX 0
82. an automatic answer Comment After receiving the sequence insert a user defined comment into the communication window and log file if available Various comment macros are available for creating dynamic comment texts Trigger Trigger a snapshot when the sequence is detected This is an advanced feature described in the section Catching a specific sequence e Stop Stop communications and end the test run e Checksum Perform automatic validation of a checksum including any type of CRC standard such as MODBUS CCITT CRC32 Set the Checksum Specification as well as what should be done with the result Detect Checksum OK the received data must have the same checksum than the calculated value from Docklight Checksum Wrong the opposite A mismatching checksum constitutes a sequence match Both OK Wrong the sequence is always detected The checksum area will contain all ASCII 1 HEX 31 for a matching checksum or ASCII 0 HEX 30 for a wrong checksum TIP See Calculating and Validating Checksums for a general overview and Checksum Specification for the text format used to define a checksum Wildcards Wildcards can be used to test for sequences that have a variable part with changing values e g measurement or status values See section Checking for sequences with random characters for details and examples Control Character Shortcuts Using keyboard shortcuts is a great help when editing a sequence that contains both
83. arrier Rate O lt CR gt lt LF gt Final Transmit Carrier Rate 9600 lt CR gt lt LF gt Final Receive Carrier Rate 9600 lt CR gt lt LF gt Protocol Negotiation Result NONE lt CR gt lt LF gt Data Compression Result NONE lt CR gt lt LF gt Estimated Signal Noise Ratio dB 00 lt CR gt lt LF gt Receive Signal Power Level dBm 00 lt CR gt lt LF gt Transmit Signal Power Level dBm 10 lt CR gt lt LF gt Round Trip Delay msec 1000 lt CR gt lt LF gt Near Echo Level dBm 00 lt CR gt lt LF gt Far Echo Level dBm 00 lt CR gt lt LF gt Transmit Frame Count O lt CR gt lt LF gt Transmit Frame Error Count O lt CR gt lt LF gt Receive Frame Count 0 lt CR gt lt LF gt Receive Frame Error Count O lt CR gt lt LF gt Retrain by Local Modem 0 lt CR gt lt LF gt Retrain by Remote Modem O lt CR gt lt LF gt Rate Renegotiation by Local Modem O lt CR gt lt LF gt Rate Renegotiation by Remote Modem 0 lt CR gt lt LF gt Call Termination Cause O lt CR gt lt LF gt Robbed Bit Signaling 0 lt CR gt lt LF gt Digital Loss dB OO0 CR LF Remote Server ID NA lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 11 441 TX ATI12 lt CR gt lt LF gt 3 8 2009 16 23 11 443 RX lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 11 643 TX ATI13 lt CR gt lt LF gt 3 8 2009 16 23 11 654 RX lt CR gt lt LF gt ERROR lt CR gt lt LF gt 3 8 2009 16 23 11 846 TX ATI14 lt CR gt
84. ayname dimension art arrayname Name of the array variable follows standard variable naming conventions dimension Optional Whole number indicating which dimension s lower bound is returned Use 1 for the first dimension 2 for the second and so on If dimension is omitted 1 is assumed Example Dim A 100 3 4 UBound A 1 returns 100 UBound A 2 returns 3 UBound A 3 returns 4 e Constants A Const statement can represent a mathematical or date time quantity Example Const conPi 3 14159265358979 Data Types VBScript has only one data type called a Variant A Variant is a special kind of data type that can contain different kinds of information depending on how it is used Because Variant is the only data type in VBScript it is also the data type returned by Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting all functions in VBScript Variant Subtypes Beyond the simple numeric or string classifications a Variant can make further distinctions about the specific nature of numeric information For example you can have numeric information that represents a date or a time When used with other date or time data the result is always expressed as a date or a time You can also have a rich variety of numeric information ranging in size from Boolean values to huge floating point numbers These different categories of information that can be
85. ce 0 hit count amp DL GetReceiveCounter 0 Send the first Send Sequence and wait for a device response no timeout DL AddComment vbCrLf amp vbCrLf amp Sending data and waiting for Receive Sequence 40 DL ResetReceiveCounter DL SendSequence 0 DL WaitForSequence 0 10 2 2 Methods Advanced 10 2 2 1 CalcChecksum Retums 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 checksumSpec Required String that specifies the checksum algorithm and its Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 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 checks
86. ced editing features support for external editors is available For more information about writing a Docklight script see the Docklight Scripting Reference Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR User Interface 3 2 Clipboard Cut Copy amp Paste EEEE Docklight supports the Windows clipboard and its Cut Copy and Paste operations Clipboard operations are available in the e Main Window Send Sequences Main Window Receive Sequences Main Window Communication Main Window Script Editor Docklight Scripting only Dialog Edit Send Sequence Dialog Edit Receive Sequence Dialog Find Sequence Dialog Send Sequence Parameter Notepad Keyboard Console You can cut a serial data sequence from the communication window and create a new Send or Receive Sequence by simply pasting it into the appropriate list Or edit a Send Sequence copy a part of this sequence to the clipboard and create a new Receive Sequence out of it by pasting it into the Receive Sequence window TIP Try the right mouse button to display a context menu for Cut Copy and Paste operations 3 3 Notepad E The Docklight Notepad is a separate window for writing down additional notes concerning your Docklight project how to use the Send Receive Sequences notes on additional test equipment etc The notepad window can be shown using the F12 key or the menu Tools gt Show Notepad The notepad is a
87. choose Function character break signal The example sequence now reads Tjelslit Click OK to confirm the changes gt 4 Send the test sequence using the Send button The TX line will go to Space logical 0 for at least 15 bit durations then the Test ASCII sequence will be transmitted The break character does not appear in the communication window display Detecting a Break state Received break signals are not displayed in the communication window because they are not part of the actual data sequence Nonetheless it is possible to define a Receive Sequence including a break function character Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced 1 2 Create a new Receive Sequence Enter a Name for the sequence Adda Function character break signal for the Sequence data 3 Enter a Receive Sequence Action for example printing the comment BREAK detected 4 Click OK to confirm the changes 5 Start communications Docklight will now add BREAK detected to the communication window display each time a break signal is detected NOTE After detecting a break signal an additional lt NUL gt character decimal code 0 may appear in the received data stream This behavor cannot be controlled by Docklight it depends on how the serial UART of your PC s COM port interpretes the break state NOTE If you need to impl
88. contained in a Variant are called subtypes Most of the time you can just put the kind of data you want in a Variant and the Variant behaves in a way that is most appropriate for the data it contains The following table shows subtypes of data that a Variant can contain Variant is uninitialized Value is O for numeric variables or a zero length string for string variables Contains integer in the range 32 768 to 32 767 922 337 203 685 477 5808 to 922 337 203 685 477 5807 Long Contains integer in the range 2 147 483 648 to 2 147 483 647 Single Contains a single precision floating point number in the range 3 402823E38 to 1 401298E 45 for negative values 1 401298E 45 to 3 402823E38 for positive values Double Contains a double precision floating point number in the range 1 79769313486232E 308 to 4 94065645841247E 324 for negative values 4 94065645841247E 324 to 1 79769313486232E308 for positive values Date Time Contains a number that represents a date between January 1 100 to December 31 9999 String Contains a variable length string that can be up to approximately 2 billion characters in length Object Contains an object 10 1 4 Operators e Arithmetic Symbol Exponentiation Unary negation po Multiplication Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting W asawmee a Bamdm O Sting concatenation a
89. cript from terminating immediately Do DL Pause 1 the pause reduces CPU load while idle Loop Sub DL OnSend Simple checksum Last byte of sequence is a checksum on all previous bytes mod 256 seqSize DL OnSend GetSize we need at least a three byte sequence If segSize gt 2 Then Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting instead of the X after Test put a random character DL OnSend Poke seqSize 2 65 Rnd 25 calculate a simple checksum on the new sequence chksumHex DL CalcChecksum MOD256 DL OnSend GetData H H 1 seqSize 1 Overwrite the last character of the Send Sequence with the actual checksum value DL OnSend Poke seqSize CInt amp h chkSumHex Using the Peek function for additional documentation DL AddComment vbCrLf amp vbCrLf DL AddComment Checksum on False False For i 1 To seqSize 1 DL AddComment amp DL OnSend Peek i H False False Next DL AddComment is amp DL OnSend Peek seqSize H amp Hex amp DL OnSend Peek seqSize D amp Decimal End If End Sub After starting the script and manually sending the Test sequence twice the ASCII communication window of Docklight could display the following output Checksum on 54 65 73 74 53 OD is OO0 Hex 000 Decimal 23 06 2015 11228231 695 TX 54 65 73 7TA 53 OD 00 Checksum on 54 65 73 74 4E OD i
90. cter This is useful for supporting variable length command arguments e g a status word in Send Receive Sequences See Checking for sequences with random characters or Sending commands with parameters for examples and additional information Other placeholders that allow random data Function Character F12 Bitwise comparison This is useful if there are one or several bits within a character which should be tested for a certain value See Function character F12 bitwise comparisons for details and an example Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR
91. cting 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 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 gt 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 ofthe handshake lines Function character F12 bitwise comparisons The Function Character can be added by pressing F12 in the Edit Receive Sequence dialog After the character two additional character values specify which bits to check mask and which values to expect for these bits value Receive Sequence Description HEX Mode Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher
92. currentLogFileName DL StartCommunication Do newLogFileName getFileNane Time for starting a new file If newLogFileName lt gt currentLogFileName Then DL StartLogging newLogFileName True LOG REPRESENTATIONS currentLogFileName newLogFileName End If DL Pause 1 reduce CPU load Loop Function getFileName dt Now Compose a file name The Right functions ensure that all months days hours are printed with two decimals getFileName BASE FILE PATH amp Year dt amp amp Right 0 amp Month dt 2 amp amp Right O amp Day dt 2 amp amp Right 0 amp Hour dt 2 amp H End Function 10 2 1 13 StopLogging Stops the logging and closes the log file s currently open Return Value Void Syntax DL StopLogging Remarks See the StartLogging method for more information on log files Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 2 1 14 WaitForSequence Waits for one or several occurrences of a Receive Sequence and returns the corresponding counter value see GetReceiveCounter Starts the communication if not already running see StartCommunication Return Value Long Syntax result DL WaitForSequence nameOrIndex maxCounter timeout The WaitForSequence method syntax has these parts nameOrlndex Required String containing the Name of the Receive Sequenc
93. d to separate several different parameters for different wildcard areas To pass parameters in HEX Decimal or Binary representation use the optional representation argument described below In HEX Decimal or Binary representation the comma is used as a separator between several different parameters representation Optional String value to define the format for parameters list A ASCII default H Hex D Decimal or B Binary Remarks Syntax 1 If the wrong number of parameters is provided by the parameters argument or the parameter length does not match the corresponding wildcards region Docklight will not raise an error but apply the following rules e If too few parameters are provided or the parameter string is too short all remaining wildcards are filled up with a blank character If you are using representation A ASCII the wildcards are filled with space characters ASCII code 32 For all other formats the wildcards will be filled with ASCII code O e If too many parameters are provided or the parameter string is too long the parameter s will be truncated or ignored Syntax 2 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL SendSequence customSequence representation Sends out a custom data sequence The SendSequence method syntax 2 has these parts Pat Description O customSeque
94. 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 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight 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 e Docklight is ready to run a test as described in the previous use cases e g testing a serial device or a protocol implementation e 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 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 plelrjaltjulrijel 7 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 tjelm plelrlaltjulrlel 4 Enter the fixed tail
95. e character before the end so there is still space for a end of line character typically a CR as in MODBUS ASCII comment You can type in a comment about this checksum specification Remarks startPos len and targetPos support negative values too as a way to specify positions relative to the end of the sequence and not relative to the start of the sequence Examples startPos is 4 start calculating at the 4th last character len is 1 use everything until and including the last character targetPos is 1 first and only byte of the result is stored at the last sequence character position targetPos is 2 result is stored starting at the 2nd last sequence character targetPos is 3 result is stored starting at the3rd last sequence character Examples off no checksum MOD256 simple one byte sum on all but the last character CRC MODBUS L MODBUS RTU checksum Lower Byte first Little Endian CRC MODBUS A 5 4 MODBUS ASCII checksum returned as text 1 3 CRC 16 10 CRC 16 checksum over the first 3 bytes 2 5 CRC 8 07 00 00 No Yes CRC with custom non standard spec Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Reference Scripting 10 Reference Scripting 10 1 VBScript Basics If you already know Visual Basic or Visual Basic for Applications VBA VBScript will be very familiar Have a look at
96. e or several additional HEX 00 value s as a placeholder for the checksum We use the same single byte placeholder as in the above Send Sequence example 01 02 03 04 05 00 3 Go to the Action Comment tab and enter the following text Correct checksum _H NOTE The _H is a comment macro to re print the actual data received as a Hex string 4 Goto the Checksum tab and pick MOD256 in the left dropdown list Leave the default Detect Checksum OK in the right box 5 Click OK to confirm the changes 6 Right click on the newly created sequence choose Copy and then Paste this immediately so you have two identical Receive Sequences now 7 Double click to edit one of the two Receive Sequences and make the following edits Name change to something like Checksum Error Action Comment change to Checksum error _H Checksum in the right combobox change to Checksum Wrong B Running the test 8 Start communications and send some data telegrams to your Docklight application COM port Example communication output could look like this 18 06 2015 12 43 07 388 RX 61 02 03 904 02 0C Correct checksum 01 02 03 04 02 OC 18 06 2015 12243 09 876 RX OL 02 03 04 05 OF Correct checksum 01 02 03 04 05 OF 18 06 2015 12 43 11 061 RX 01 02 03 04 05 B1 Checksum error 01 02 03 04 05 81 6 5 Controlling and Monitoring RS232 Handshake Signals The Docklight project settings for F
97. e sequence string either source or result depending on conversionT ype H Hex default D Decimal or B Binary Optional Boolean value to define the byte order for integer or float conversions True default Use big endian byte order first character is most significant False use little endian byte order first character is least significant The conversionType argument supports the following values and types of conversions Convert source to a single precision float number source IEEE single precision 32 bit sequence result string with floating point number in non localized format uses period as the decimal separator Example DL ConvertSequenceData toSingle 3F 9E B retums 1 234567 i Convert source to a IEEE single precision 32 bit sequence source string with floating point number Both period and comma are accepted as decimal separator result 32 bit sequence data Example DL ConvertSequenceData fromSingle 1 234567 retums 3F 9E 06 4B j Convert source to a double precision float number source IEEE double precision 64 bit sequence result string with floating point number in non localized format see Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting above Example DL ConvertSequenceData toDouble 103 154 149 160 081 161 036 075 D False returns 9 87987987987E 53
98. e to count The first Receive Sequence from the list with a name that matches nameOrlndex is used As an alternative you may pass an integer value specifying the Sequence Index Valid Sequence Index range is from 0 to NoOfReceiveSequences 1 maxCounter Optional Long number containing the counter limit until the function returns Default value is 1 one WaitForSequence returns after detecting the first occurrence of the receive sequence Return value is 1 in this case If maxCounter is 1 WaitForSequence does not use a counter limit It will only return after a timeout see below Use maxCounter 1 to count all occurrences of a Receive Sequence within a limited period of time timeout Optional Long number specifying an additional timeout in milliseconds Default value is 1 no timeout Maximum value is 86000000 23 88 hours Remarks The WaitForSequence method checks the number of hits for this Receive Sequence since the communication has been started see StartCommunication or the counter has been reset see ResetReceiveCounter WaitForSequence waits until the number of hits specified by the maxCounter have been detected One basic application for WaitForSequence is waiting for a specific answer after sending out a test command to your serial device To make sure that you do not miss a very quick response from your device use the following command order 1 Reset the counter s first using ResetReceiveCounter 2
99. ecision Structures Loop Structures Variables Arrays Constants and Data Types Operators Date Time Functions Miscellaneous VBScript Basic Features in Alphabetical Order Date Function Day Function Do Until Loop Do Loop While For Next Hour Function If Then I Then Else InputBox Function LBound Function Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 1 1 Copyright Notice Minute Function Month Function Now Function ScriptEngine Function Second Function Select Case Time Function Timer Function UBound Function While Wend Year Function The following sections ofthe VBScript Basics chapter are based on the Microsoft Windows Script V5 6 Documentation help file Script56 CHM For this help file the following copyright notice applies 2001 Microsoft Corporation All rights reserved The usage of Microsoft copyrighted material is according to the Microsoft Ten Percent Rule see http www microsoft com permission 10 1 2 Control Structures VBScript control structures allow you to control the flow of your script s execution To learn more about specific control structures see the following topics e Decision Structures An introduction to decision structures used for branching e Loop Structures An introduction to loop structures used to repeat processes 10 1 2 1 Decision Structures e f Then Use an If
100. eives the defined sequence 13 14 RS232 HERE EEE The RS232 standard is defined by the EIA TIA Electronic Industries Alliance Telecommunications Industry Associations The standard defines an asynchronous serial data transfer mechanism as well as the physical and electrical characteristics of the interface RS232 uses serial bit streams transmitted at a predefined baud rate The information is separated into characters of 5 to 8 bits lengths Additional start and stop bits are used Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used for synchronization and a parity bit may be included to provide a simple error detection mechanism The electrical interface includes unbalanced line drivers i e all signals are represented by a voltage with reference to a common signal ground RS232 defines two states for the data signals mark state or logical 1 and space state or logical 0 The range of voltages for representing these states is specified as follows Signal State Transmitter Voltage Receiver Voltage Range Range Mark logical 1 15V to 5V 25V to 3V Space logical 0 5V to 15V 3V to 25V Undefined 5V to 5V 3V to 3V The physical characteristics of the RS232 standard are described in the section RS232 Connectors Pinout 13 15 RS422 An RS422 communication link is a four wire link with balanced line drivers In a balanced differentia
101. ement a Receive Sequence that checks for a break signal followed by additional data keep in mind that Docklight cannot tell the exact position of the break signal within the data stream The break signal will sometimes show up earlier in the data stream but never later than the actual position To define a Receive Sequence that safely triggers on break specific data you can use the following workaround Insert some zero or one character wildcards between the break character and the additional data The resulting Receive Sequence could look like this 90 2 HT Tle st 6 8 Testing a TCP Server Device Scripting Docklight Scripting is TCP client TCP Server Comm Channel 192 0 0 1 10001 IP 192 0 0 1 TCP Port 10001 imi Docklight PC TCP Server Preconditions The IP address of the device is known and the device is accessible via the network from the computer running Docklight Scripting i e a ping to the device s IP address works e You know which TCP port you can connect to your device on You know the protocol specification for the device e g MODBUS TCP and the set of commands the device understands Testing TCP Server protocol functions A Setting the Communication Options 1 Choose the menu Tools gt Project Settings 2 Choose communication mode Send Receive 3 At Send Receive on comm channel enter the IP address and TCP port number for connecting to the device e g 192 0
102. ences table The Edit Send Sequence dialog is displayed see also Editing and Managing Sequences 2 Enter a Name for the sequence The sequence name should be unique for every Send Sequence defined 3 Enter the Sequence itself You may enter the sequence either in ASCII HEX Decimal or Binary format Switching between the different formats is possible at any time using the Edit Mode radio buttons 4 After clicking the OK button the new sequence will be added to the Send Sequence lists Repeat steps 1 4 to define the other Send Sequences needed to perform your test D Defining the Receive Sequences used Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight If you want Docklight to react when receiving specific sequences you have to define a list of Receive Sequences 1 Double click on the last line of the Receive Sequences table The dialog Edit Receive Sequence is displayed The dialog consist of three parts Name field Sequence field and Action field Edit the Name and Sequence fields 3 Specify an Action to perform after the sequence has been received by Docklight There are four types of actions available Answer After receiving the sequence transmit one of the Send Sequences Comment After receiving the sequence insert a user defined comment into the communication window and log file if available Trigger This is an advanced feature described i
103. eristic for a PC Windows system and the various hardware and software layers involved Unspecified delays and timing inaccuracies can be introduced by e The COM device s chipset e g the internal FIFO First In First Out data buffer e The USB bus transfer for USB to Serial converters e The serial device driver for Windows e The task process scheduling in a multitasking operating system like Windows e The accuracy of the date time provider Docklight comes with a very accurate date time provider with milliseconds granularity but it still needs to accept the restrictions from the hardware and software environment around it Here is what you can do to minimize additional delays and inaccuracies and achieve a typical time tagging accuracy of 5 milliseconds or better 1 Get our Docklight Tap for lowest USB related latency times Or use on board RS232 ports if still available on your PC 2 Choose External High Priority Process Mode in the Tools gt Expert Options dialog 3 When monitoring high amounts of data use the recommendations from the previous section How to Increase the Processing Speed to avoid input buffer overflows and that the computer become irresponsive because of high CPU usage NOTE The Expert Options recommended above will change the overall system balance and must be used with care Best results can be achieved only when logged in as an Administrator Please make sure you understood the remark
104. esigned for the use with Docklight Monitoring Mode according to the cable specification below Visit our product overview pages for the Docklight Monitoring Cable a professional and rugged cable solution for industrial applications prote ctive shielding ground To e Dexice2 o or null To modem Device 1 cable Co C SUB D9 male ok without protective shield if cable length is short and not used in EMI polluted area SUB D3femae SUB D9 female To To monitoring monitoring COM port 1 COM port 2 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 12 6 Docklight Tap SESE SSS SSS SS SSS SSS Ol Docklight Tap is a full duplex RS232 communications monitoring solution for the USB port Area of Application Monitoring serial communications between two devices Docklight has built in support for the Docklight Tap It recognizes the dual port USB serial converter and offers high speed low latency access to the monitoring data Use Docklight Monitoring Mode and Receive Channel settings TAPO TAP1 See the Docklight Project Settings and How to Obtain Best Timing Accuracy for details Please also see our product overview pages for more information about the Docklight Tap Device 1 Device 2 Sub D9 Sub D9 female male USB Serial Converter B USB Serial Converter A Mini USB Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und
105. etlndex Retums its index within the Receive Sequence list Returns a string containing the actual data representation of result A ASCII default H HEX D Decimal or B Binary The data returned does not contain any wildcards At wildcard positions the actual characters received are returned NOTE If the original Receive Sequence contains wildcards zero or one character the length of the DL OnReceive GetData sequence can be shorter than the original sequence with wildcards Syntax 2 Retums a string containing a specified number of DL OnReceive GetData representa characters from the data received tion start length start range 1 DL OnReceive GetSize Default value is 1 length number of characters or 1 until last character 2 until second last character a s o Default value is 1 result Returns the communication channel number on DL OnReceive GetChannel which this sequence has been detected In Communication Mode Monitoring the return value is 1 or 2 In Communication Mode Send Receive the return value is 2 always RX channel result Returns one character of the received data as an DL OnReceive Peek charNo integer value from 0 255 charNo is the position within the received data Valid charNo range 1 DL OnReceive GetSize Syntax 2 Retums a string instead of an integer value DL OnReceive Peek charNo representation specifies the format representa
106. f this is a custom data sequence created by a DL SendSequence command the return value is 1 Returns a string containing the actual send result A ASCII default H HEX D Decimal or B Binary The data returned does not contain any wildcards All wildcard positions have already been replaced by actual characters NOTE If the original Send Sequence contains 7 wildcards zero or one character the length of the DL OnSend GetData sequence can be shorter than the original sequence with Syntax 2 wildcards result DL OnSend GetData representatio Syntax 2 n start length Returns a string containing a specified number of characters from the data received DL OnSend_GetSize Default length number of characters or 1 until last character 2 until second last character a s o Default value is 1 DL OnSend SetData newData Replaces the data to be transmitted with the representation data provided in the newData string representation specifies the format of newData A ASCII default H HEX D Decimal or B Binary After exiting the DL OnSend procedure Docklight will transmit newData regardless of Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting what the original Send Sequence looked like The newData length can be different from the original Send Sequence length NOTE If newData is an empty
107. fault value by pressing Enter The script now establishes a connection with the modem and runs through the AT command set After successfully completing the test run the Docklight communication window could look like this Waiting for modem 3 8 2009 16 23 08 870 TX ATOOVIED lt CRS lt LF gt 3 8 2009 16 23 08 873 RX ATQOVIEO CR lt CR gt lt LF gt OK lt CR gt lt LF gt Checking AT command set Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting 3 8 2009 16 23 08 888 TX ATIO lt CR gt lt LF gt 3 8 2009 16 23 08 891 RX lt CR gt lt LF gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 09 091 TX ATI1 lt CR gt lt LF gt 3 8 2009 16 23 09 101 RX lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 09 293 TX ATI2 lt CR gt lt LF gt 3 8 2009 16 23 09 294 RX lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 09 496 TX ATI3 lt CR gt lt LF gt 3 8 2009 16 23 09 498 RX lt CR gt lt LF gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 09 700 TX ATI4 lt CR gt lt LF gt 3 8 2009 16 23 09 702 RX lt CRS lt LF gt Built on 07 22 2004 14 50 10 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt 3 8 2009 16 23 09 901 TX
108. for more information on the StartLogging functionality and arguments described above If baseFilePath is an empty string a file dialog will be displayed to choose the log file path and base file name If StartLogging is called while another log file is still open from a previous StartLogging call the file is closed and the new file is created opened This allows changing the log file name without losing any data The noHeaders flag is particularly useful when you are creating log data without time stamps You can then easily compare the result to previous test runs using an file compare tool Example Example StartLogging c L ClearCommWindows L StartLogging C DocklightLogging opens four log files C DocklightLogging asc txt C DocklightLogging hex txt DocklightLogging dec txt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR c Reference Scripting C NMDocklightLogging bin txt Wait for 5 seconds DL Pause 5000 Close the four log files DL StopLogging Example 2 This is a more advanced example which demonstrates how to include a date time stamp in the log file name and start a new log file every hour Example One Log File per Hour This is the base path and location where the log file s will be stored Const BASE FILE PATH logfile Create ASCII and HEX log files Const LOG REPRESENTATIONS AH mu
109. g ASCII mode disable the Control Characters Description option 2 Log the communication data to a plain text file instead of using the communication window s Use the plain text Log File Format Create only a log file for the Representation ASCII HEX Decimal Binary you Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced actually need Disable the communication windows while logging using the High Speed Logging option 3 Usethe Communication Filter from the Project Settings dialog and disable the original serial data for one or both communication directions This is especially useful if you actually know what you are looking for and can define one or several Receive Sequences for this pieces of data These Receive Sequences can print a comment each time the sequence appears in the data stream so you still know what has happened even if the original serial data is not displayed by Docklight 6 3 How to Obtain Best Timing Accuracy A Many RS232 monitoring applications including Docklight can only provide limited accuracy when it comes to time tagging the serial data As a result data from the two different communication directions can be displayed in chronologically incorrect order or several telegrams from one communication direction can appear as one chunk of data This behavior is not caused by poor programming but is rather charact
110. gt receive timestamp 8 1 2012 11 00 41 849 8 1 2012 11 00 41 861 TX Hello lt CR gt lt LF gt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 8 1 2012 11 00 42 825 TX Hello lt CR gt lt LF gt 8 1 2012 11 00 42 827 RX Hello CR 2 LE receive timestamp 8 1 2012 11 00 42 827 8 1 2012 11 00 42 839 TX Hello lt CR gt lt LF gt 8 1 2012 11 00 42 841 RX Hello lt CR gt lt LF gt receive timestamp 8 1 2012 11 00 42 841 8 1 2012 11 00 42 852 TX Hello lt CR gt lt LF gt 8 1 2012 11 00 42 855 RX Hello lt CR gt lt LF gt Number of Hello sequences detected 70 Example 3 Example using Sub DL OnReceive to wait for ANY sequence found False foundName foundDate Now foundMSec 0 Do DL Pause 1 the pause reduces CPU load while idle Loop Until found DL AddComment DL AddComment Sequence received amp foundName DL AddComment Date Time received amp DL GetDocklightTimeStamp foundDate foundMSec Sub DL OnReceive If Not found Then found True foundName DL OnReceive GetName foundDate DL OnReceive GetDateTime foundMSec DL OnReceive GetMilliseconds End If End Sub 10 3 3 OnSend OnReceive Timing and Program Flow Sub DL_OnSend Timing While a script is running the DL_OnSend even
111. he behavior of the serial device you want to simulate e g what kind of information is sent back after receiving a certain command e A second device is connected to a PC COM port which will communicate with your simulator This second device and its behavior is the actual object of interest An example could be a device that periodically checks the status of an UPS Uninterruptible Power Supply using a serial communication protocol You could use Docklight to simulate basic UPS behavior and certain UPS problem cases This is very useful when testing the other device because it can be quite difficult to reproduce an alarm condition like a bad battery at the real UPS NOTE The second device may also be a second software application It is possible to run both Docklight and the software application on the same PC Simply use a different COM port for each of the two applications and connect the two COM ports using a RS232 null modem cable You can also use a virtual null modem for this purpose Performing the test A Creating a new project Create a new Docklight project by selecting the menu File gt C New Project B Setting the Communication Options Choose the menu Tools gt Project Settings Choose communication mode Send Receive At Send Receive on comm channel set the COM Port where your serial device is connected Set the baud rate and all other COM Port Settings required Confirm the settings and close the dialog by clicki
112. heck if another server or even another Docklight Scripting instance is blocking the port Also try closing and restarting Docklight Scripting sometimes the TCP driver layer used by Docklight Scripting does not release a TCP port until the application using it is closed NOTE Even if there is no other server or client blocking a port it may take up to 4 minutes until a port is actually released and available again This is a restriction in the TCP driver layer used in Docklight Scripting and unfortunately Docklight Scripting cannot control this 6 9 Monitoring a Client Server TCP Connection Scripting Device 1 Device 2 Client connects to server using TCP Server Address 192 0 0 1 IP PortNo 192 0 0 1 502 TCP Port 502 TCP Server TCP Client Docklight Scripting allows you to monitor and debug a TCP based application with the same ease as when using RS232 ports and cables Instead of using a Docklight Monitoring Cable between the two devices being tested you can run Docklight Scripting within the network and simply have the client Device 1 connect to Docklight Scripting instead of the network enabled product Device 2 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced Device 1 Device 2 Client connects to Docklight using TCP Server Address 192 0 0 1 IP PortNo 192 0 0 2 502 TCP Port 502 im TCP Client Local I
113. hen re opening a Docklight project see the ResetReceiveCounter function Example Example OpenProject Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Load a Docklight project file DL OpenProject D My Docklight Files NTest ptp Load the file Test ptp from the current working directory DL OpenProject Test 10 2 1 6 Pause Pauses the script s execution for a specified number of milliseconds Return Value Void Syntax DL Pause milliseconds The Pause method syntax has these parts Pat Description S milliseconds Required Long value for the delay in milliseconds Minimum value is 0 Pause returns immediately Maximum value is 86000000 23 88 hours Remarks Docklight in general and the Pause function do not provide a very exact timing with milliseconds precision so the actual delay may vary from the milliseconds value During a Pause no DL OnReceive procedure calls can be processed If you need to process DL OnReceive events while waiting see the pauseWithEvents code described at Example 2 Example Example Pause Send a test command DL SendSequence Testi 5 seconds delay DL Pause 5000 Send another command DL SendSequence Test2 Typical main loop for processing data Do DL Pause 1 reduce CPU load countSomeThings DL GetReceiveCounter 1 ase do more things Loop 10 2 1
114. hen running the sample Further Information The batch file LogStartup bat contains the following line Docklight Scripting exe r LogStartupScript pts This will start Docklight Scripting open the script file LogStartupScript pts and run it immediately r option The script LogStartupScript pts contains the following commands LogStartupSeript pts Start up logging and communication DL OpenProject LogStartupSettings Create or append to a ASCII log file DL StartLogging C DocklightScripting Logfile True A DL Y L StartCommunication Keep communication amp logging alive until user stops Do Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting DL Pause 1 the pause reduces CPU load while idle Loop The communication settings used in LogStartupSettings ptp are just an example If you require different settings you need to open the project file modify the project settings and save the changes It is recommended that all related files LogStartupScript pts LogStartupSettings ptp and LogStartup bat be copied to a different location before making any changes You need to provide the complete actual path to the Docklight Scripting exe application within the bat file in this case 8 3 Manipulating a RS232 Data Stream Sample Script CharacterManipulation pts _ EIC CAMCN X EXGENNCG ELI Go M
115. ication channels channel 1 and channel 2 which represent the incoming and outgoing data in Send Receive Mode or the two communication channels being observed in Monitoring Mode Channel 1 and channel 2 data are displayed using different colors or fonts and the communication data may be printed or stored as a log file in plain text or HTML format Besides the serial data Docklight inserts date time stamps into the communication display By default a date time stamp is inserted every time the data flow direction Switches between channel 1 and channel 2 or before a new Send Sequence is transmitted There are several options available for inserting additional time stamps This is especially useful when monitoring a half duplex line with only one communication channel See Options gt Date Time Stamps Docklight is able to process serial data streams containing any ASCII code 0 255 decimal Since there are non printing control characters ASCII code 32 and different encodings for ASCII code gt 127 not all of these characters can be displayed in the ASCII text window Nonetheless all characters will be processed properly by Docklight and can be displayed in HEX Decimal or Binary format Docklight will process the serial data on any language version of the Windows operating system in the same way although the ASCII display might be different For control characters ASCII code 32 an additional display option is available to display the
116. if those contents had appeared in the source program at the point where the directive appears You can organize constant declarations and function definitions into include files and then use Zinclude directives to add these definitions to any script Include files are also useful for incorporating declarations of external variables and complex data types Example Example include directive finclude myIncludeFile pts DL AddComment Pi amp conPi With myIncludeFile pts containing the following definition Const conPi 3 14159265358979 The resulting communication window output would look like this Pi 3 14159265358979 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 7 Command Line Syntax The Docklight Scripting application supports command line arguments to load and run predefined project or script files Use the following command syntax Docklight Scripting exe r m projectPathName ptp scriptPathName pts The Docklight scripting command line has these parts Optional argument used in combination with scriptPathName pts Runs the script immediately If no run time error or user stop occurs the Docklight Scripting application is closed after the script execution ends Optional argument Minimize the Docklight Scripting application window on startup Optional argument Invisible operation no main window Useful
117. ight confuse the other host device Problems have been experienced for example with Telnet server applications The return value of SetChannelSettings is True if the channel could be successfully opened or the new settings are ok and dontTest is true The return value is False if the settings are invalid or an error occurred while trying to access the port e g the COM port already in use or the Firewall denied the TCP IP access NOTE Modifying the FlowControl parameter when Project Settings Flow Control is other than Off can result in undefined behavior See also GetChannelSettings and GetChannelStatus Example Example SetChannelSettings GetChannelSettings requires Docklight in Send Receive mode DL ClearCommWindows DL AddComment Searching for first COM port available on this PO Vu portAvailable DL SetChannelSettings COM1 9600 NONE 8 1 While Not portAvailable oldPort DL GetChannelSettings try next COM port portAvailable DL SetChannelSettings gt newPort DL GetChannelSettings tried out already all COM ports on this PC Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting If oldPort newPort Then DL AddComment No COM port available DL Quit End If Wend DL AddComment Using COM port amp DL GetChannelSettings Try a few different baud rates baudRatesStr 9600 14400 57600 115200 baudRa
118. in combination with the r option and scriptPathName pts projectPathName ptp Optional Loads the Docklight project file projectPathName ptp scriptPathName pts X Optional Loads the Docklight script file scriptPathName pts Remarks If your script uses the StartLogging or the Filelnput FileOutput interface and you just provide a file name but not a complete directory path as a parameter Docklight Scripting will use the current script project directory Example Docklight Scripting exe r C myScript pts Loads the Docklight script file C myScript pts and executes it 10 8 Dialog Customize External Editor ER Menu Scripting gt amp Customize External Editor Use external application as Docklight Script Editor Check this option to disable the built in script editor and launch an external editor application for this purpose A flexible configuration syntax allows you to work with almost any editor that at least supports opening a file using a command line like myEditor exe tempScriptFile vbs Application Control This configuration file defines how Docklight Scripting controls the external editor Load preset for Predefined configuration files for three widely available editors Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting TIP We recommend the Notepad editor available at http notepad plus sourceforge net The Windows Notepad exam
119. ir text equivalent in the communication window See Options dialog and Appendix ASCII Character Set Tables Docklight allows you to suppress all original serial data if you are running a test where you do not need to see the actual data but only the additional evaluations generated using Receive Sequences See the Project Settings for Communication Filter 4 2 Editing and Managing Sequences DI DIM E IUE AI MIACEC c I sl A Docklight project mainly consists of user defined sequences These may be either Send Sequences which may be transmitted by Docklight itself or Receive Sequences which are used to detect a special message within the incoming serial data Sequences are defined using the Edit Send Sequence or Edit Receive Sequence dialog window This dialog window is opened 1 by choosing Edit from the context menu available using the right mouse button 2 by double clicking on an existing sequence or pressing Ctrl E with the Send Sequence or Receive Sequence list selected 3 when creating a new sequence by double clicking on the blank field at the end of a list or pressing Ctrl E 4 when pasting a new sequence into the sequence list Docklight supports the use of wildcards e g wildcard as a placeholder for one Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Features and Functions arbitrary character within Receive Sequences and Send Sequences See the sections sendi
120. iting Files The global FileOutput object provides an easy interface to create files e g for writing custom data formats Methods and properties available for File Output Method Property FileOutput CreateFile filePathName Create a new output file rawData appenaData rawData False default Open as a text file rawData True Open as a raw binary data file appendData False default Overwrite file if exists appendData True Append data to an existing file FileOutput CloseFile Closes the file FileOutput WriteLine data Write the string data to the file appenaLineBreak appenaLineBreak True default Append a CR LF line break after the data string appendLineBreak False don t create a line break The WriteLine method can only be used for text files rawData False FileOutput Write Byte data Write the byte data to the file result FileOutput IsOpen Returns True if a file is open False if not result FileOutput Dialog caption defaultPath chosen file path or an empty string if aborted File Output File Exists filePath Remarks See the Filelnput object for an example Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 4 3 Multiple Input Files Multiple Output Files If you require to read or w
121. ive call is queued and executed after Pause or WaitForSequence returns See Example 2 below for a workaround to this problem See also Timing and Program Flow for some insight on how Docklight handles receive data events and executes the DL OnReceive code section Example Example DL OnReceive event code Predefined Send Sequence 0 Send Value VALUE lt gt lt gt lt CR gt lt LF gt Predefined Receive Sequence 0 Value Received VALUE lt gt lt gt lt CR gt lt LF gt Run this test on a COM port with a loopback connector TX connected to RX of the same port finished False DL ClearCommWindows Do DL Pause 1 the pause reduces CPU load while idle Loop Until finished Sub DL OnReceive If DL OnReceive GetName Value Received Then DL AddComment Value received amp DL OnReceive GetData A 7 3 Read the value from the receive data but only the changing value part myValue Mid DL OnReceive GetData 7 2 Y Ensure this is a numeric value If IsNumeric myValue Then increase myValue myValue 1 If myValue lt 100 Then If the value is still below 100 send it out again Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting newValueStr CStr myValue DL SendSequence Send Value newValueStr Else DL AddComment VALUE 99 stopping finished True
122. ive the data from one of the serial devices being monitored For a Docklight Tap setup please make sure you have installed up to date USB drivers FTDI drivers as available on our Docklight Download page Device 1 and Device 2 must be ready to operate Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Performing the test A Creating a new project Create a new Docklight project by selecting the menu File gt C New Project B Setting the Communication Options 1 Choose the menu Tools gt Project Settings 2 Choose communication mode Monitoring Alternative 1 Using Docklight Monitoring Cable 3 At Receive Channel 1 set the COM Port where the monitoring signal from serial device 1 is received At Receive Channel 2 set the COM port for the second device NOTE In Docklight Monitoring Mode all received data from one COM port is re sent on the TX channel ofthe opposite COM port Data Forwarding This does not have any effect for Docklight Monitoring Cable setups since the TX signal is not connected But it can be useful for special applications where you need to route the serial data traffic through Docklight using standard RS232 cabling If you require a pure passive monitoring behavior where no TX data appears you can disable the Data Forwarding using the menu Tools gt Expert Options Alternative 2 Using Docklight Tap 3 At Receive Channel 1 o
123. iver to its output terminal The term tristate refers to the three different states possible at the output terminal mark logical 1 space logical 0 or disconnected Extended Common Mode Voltage Vem range from 7V to 12V Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used The EIA Standard RS485 Standard for electrical characteristics of generators and receivers for use in balanced digital multipoint systems defines the characteristics of an RS485 system 13 17 Send Sequence mg ESSE A Send Sequence is a sequence that can be sent by Docklight A Send Sequence is specified by 1 an unique name e g Set modem speaker volume 2 a character sequence e g 41 54 4C 0D 0A in HEX format There are two ways to make Docklight send a sequence e Sending a sequence can be triggered manually by pressing the send button in the Send Sequences list see Main Window e Sending a sequence may be one possible reaction when Docklight detects a specific Receive Sequence within the incoming data see Action 13 18 Sequence El A sequence consists of one or more 8 bit characters A sequence can be any part of the serial communications you are analyzing It can consist of printable ASCII characters but may also include every non printable character between 0 and 255 decimal Example ATL2 ASCII format 41 54 4C 0D 0A HEX format This sequence is a mode
124. ization purposes 13 3 Character A character is the basic unit of information processed by Docklight Docklight always uses 8 bit characters Nevertheless the communication settings also allow data transmission with 7 bits or less In this case only a subset of the 256 possible 8 bit characters will be used but the characters will still be stored and processed using an 8 bit format 13 4 J e Cyclic Redundancy Code A CRC is a method to detect whether a received sequence message has been corrupted e g by transmission errors This is done by constructing an additional checksum value that is a function of the message data and then appending this value to the original message The receiver calculates the checksum from the received data and compares it to the transmitted CRC value to see if the message is unmodified CRCs are commonly used because they allow the detection of typical transmission errors bit errors burst errors with a very high accuracy CRC algorithms are based on polynomial arithmetic and come in many different versions Common algorithms are CRC CCITT CRC 16 and CRC 32 An example of an application protocol that uses a CRC is MODBUS over Serial Line A very popular article about CRCs is Easier said than done Michael Barr A guide to CRC calculation http www netrino com Connecting 2000 01 Docklight Scripting s CRC functionality DL CalcChecksum was inspired by the above article and the proposed Boost CR
125. k TCP UDP HID Named Pipes In Docklight Scripting a communication channel can be configured as e Serial COM port RS232 RS422 or RS485 e TAP port for Docklight Tap monitoring e VTP port for Docklight Tap Pro or Tap 485 monitoring e Network communication socket for TCP or UDP e USB HID connection e Named Pipes client The following settings can be used Setting Examples The channel is connected to a serial COM port Use the dropdown list to see all COM ports available on your PC from the Windows operating system The channel is connected to one of the Docklight Tap monitoring data directions The TAP connections are only available if Communication Mode is set to Monitoring the Docklight Tap is plugged in and the Docklight Tap USB device drivers are installed properly The channel is connected to one of the Tap Pro Tap 485 monitoring data directions similar to the Docklight Tap application using TAPx settings RemoteHost RemotePort The channel acts a TCP client When starting communications it connects to the host and 192 168 1 100 10001 TCP port specified For RemoteHost you can enter NIC COM 80 e an IP4 address e g 192 168 1 100 LOCALHOST 504 e a host name e g NIC COM for accessing a server on the Internet or the Windows NetBIOS name for another computer on your local network e the LOCALHOST keyword which always points to the computer Docklight is running on This is equivalent to using the l
126. keyboard console is not a full featured terminal and does not support specific terminal standards such as VT 100 The Enter key is transmitted as CR ASCII 13 plus lt LF gt ASCII 10 as per the Windows standard text file format Use control character shortcuts to send other ASCII control characters 9 14 Checksum Specification Er SS SS Se Checksum specifications are used in Edit Send Sequence and Edit Receive Sequence dialogs and in the Docklight Scripting method CalcChecksum See Calculating and Validating Checksums for a general overview checksumSpec Format Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference MOD256 Calculates an 8 bit checksum Sum on all bytes modulo 256 Calculates an 7 bit with CRC used for example in MMC SD card applications This is equal to using the following checksumSpec text CRC 7 09 00 00 No No See the CRC syntax described in the last row for details CRC Calculates an 8 bit width CRC e g for ATM Head Error Correction Equals to CRC 8 07 00 00 No No CRC DOW Calculates an 8 bit width CRC known as DOW CRC or CCITT 8 CRC Can be found in Dallas iButton TM applications Equals to CRC 8 31 00 00 Yes Yes presen as a 16 bit width CRC as designated by CCITT Equals to CRC 16 1021 FFFF 0000 No No CRC 16 Calculates a 16 bit width CRC as used in IBM Bisynch CRC 16 8005 0000 0000 Yes Yes CRC MODBUS Calculates a 16 bit width
127. klight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL StartLogging baseFilePath appendData representations html highspeed noHeaders The StartLogging method syntax has these parts Pat Description O baseFilePath Required String containing the directory and base file name for the log file s appendData Optional Boolean value True Default Append the new data to existing log file s False Overwrite existing log file s Previously saved logging data will be lost representations Optional String to choose the log file representations A ASCII H HEX D Decimal and or B Binary Default value is AHDB create all four representations ASCII HEX Decimal Binary html Optional Boolean value GENE False Default create plain text txt files True create HTML htm files for web browsers highspeed Optional Boolean value False Default not used True Disable communication window while logging e g for monitoring high speed communications on a slow PC noHeaders Optional Boolean value False Default create a standard header Docklight Log File started after opening the file Create a footer Docklight Log File stopped when closing the file True Do not create any additional header or footer information Remarks See also logging and analyzing a test and the Create Log Files s Dialog
128. l system one signal is transmitted using two wires A and B The signal state is represented by the voltage across the two wires Although a common signal ground connection is necessary it is not used to determine the signal state at the receiver This results in a high immunity against EMI electromagnetic interference and allows cable lengths of over 1000m depending on the cable type and baud rate The EIA Standard RS422 A Electrical characteristics of balanced voltage digital interface circuits defines the characteristics of an RS422 interface Transmitter and receiver characteristics according to RS422 A are Signal State Transmitter Differential Receiver Differential Voltage Vas Voltage Vas Mark or logical 1 6V to 2V 6V to 200mV Space or logical 0 2V to 6V 200mV to 6V Undefined 2V to 2V 200mV to 200mV Permitted Common Mode Voltage Vcm mean voltage of A and B terminals with reference to signal ground 7V to 7V 13 16 RS485 The RS485 standard defines a balanced two wire transmission line which may be shared as a bus line by up to 32 driver receiver pairs Many characteristics of the transmitters and receivers are the same as RS422 The main differences between RS422 and RS485 are e Two wire half duplex transmission instead of four wire transmission e Balanced line drivers with tristate capability The RS485 line driver has an additional enable signal which is used to connect and disconnect the dr
129. lculated after the wildcard parameter area has been filled with the actual data then the resulting sequence data is handed over to the send queue 6 2 How to Increase the Processing Speed and Avoid Input Buffer Overflow Messages B M M H sipe When monitoring serial communications between two devices Docklight cannot control the amount of incoming data Since Docklight applies a number of formatting and conversion rules on the serial data only a limited number of bytes per seconds can be processed There are numerous factors that determine the processing speed e g the PC and COM devices used the Display Settings and the Receive Sequence Actions defined It is therefore not possible to specify any typical data rates If Docklight cannot keep up with the incoming data it adds the following comment to the communication data display DOCKLIGHT reports Input buffer overflow on COMI TIP Search for this message using the f Find Sequence in Communication Window Ctrl F function Docklight will also react slowly to any user input including a Stop communication command If you are experiencing the above behavior Docklight offers you several ways to increase the data throughput 1 Simplify the display output Deactivate all unneeded Display Modes in the P Options dialog Use Plain Text Mode instead of Formatted Text Output If you are usin
130. led using the Windows Device Manager and opening the property page for the appropriate COM port e g COM1 13 25 UDP User Datagram Protocol UDP is a transport layer protocol used in IP networks UDP is a connectionless protocol the communication partners do not establish a connection before transmitting data UDP does not provide reliable or in order transmissions Datagrams can arrive out of order arrive duplicated or go missing during transmission Applications requiring ordered reliable delivery of streams of data should instead use TCP UDP is faster than TCP and has advantages for many lightweight or timing critical network applications UDP is used for the Domain Name System on the Internet for streaming media applications like Voice Over IP and for broadcasting in IP networks Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used UDP uses port numbers 1 65535 to identify application end points Examples of well known UDP services and port numbers are DNS 53 TIME 37 and SNMP 161 and 162 13 26 Virtual Null Modem ha X mmi A virtual null modem is a PC software driver which emulates two serial COM ports that are connected by a null modem cable If one PC application sends data on one virtual COM port a second PC application can receive this data on the second virtual COM
131. long with UDP is the main transport layer protocol used in IP networks TCP is connection oriented before two network hosts can communicate using TCP they must first establish a connection TCP is a byte stream protocol that guarantees delivery TCP ensures that data packets are transmitted error free and in the right order even if the underlying network is unreliable TCP uses port numbers 1 65535 to identify application end points Examples of well known TCP applications and port numbers are FTP 21 TELNET 23 SMTP 25 HTTP 80 and POP3 110 13 23 Trigger A Trigger is a Receive Sequence with the Trigger option enabled see Dialog Edit Receive Sequence When the Snapshot function is enabled Docklight will not produce any output until a trigger sequence has been detected in the serial communication data See Catching a specific sequence and taking a snapshot for more information 13 24 UART Universal Asynchronous Receiver Transmitter The UART is the hardware component that performs the main serial communications tasks converting characters into a serial bit stream adding start stop parity bits and checking for parity errors on the receiver side all tasks related to timing baud rates and synchronization Common UARTS are compatible with the 16550A UART They include a 16 byte buffer for incoming data RX FiFo and a 16 byte buffer for outgoing data TX FiFo Usually these buffers can be disabled enab
132. low 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 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced Preconditions e Docklight is ready to run a test as described in testing a serial device or a protocol implementation e Flow Control Support is set to Manual in the project settings e 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 els 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 c
133. lt LF gt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Scripting 3 8 2009 16723 11 852 RX lt CR3 lt LF gt ERROR lt CR gt lt LF gt Results Found 13 valid AT commands 2 AT command s did not work 8 2 Startup From Command Line Sample Script LogStartupScript pts The Docklight script LogStartupScript pts the related project file LogStartupSettings ptp and the batch file LogStartup bat demonstrate how to start Docklight from the command line create a log file according to predefined settings and start communications automatically The project file uses the communication settings listed below Communication Mode Monitoring receive only Receive channel 1 COM1 Receive channel 2 COM3 COM Port Settings 9600 Baud No parity 8 Data Bits 1 Stop Bit Getting started e Start the batch file LogStartup bat from a command line or go to the ScriptSamples directory and run LogStartup bat by double clicking the file Docklight Scripting is started an ASCII log file CDocklightScripting Logfile asc txt is created and communication is started immediately Use Shift F6 to stop the script s execution and close the communication ports and log file NOTE This sample requires a software license for the Docklight standard version since it makes use of the Docklight Logging function A Docklight Scripting license is not required w
134. m command to set the speaker volume on AT compatible modems It includes a Carriage Return 0D and a Line Feed 0A character at the end of the line The maximum sequence size in Docklight is 1024 characters 13 19 Sequence Index pure mu n gung eu css n The Sequence Index is the element number of a Send Sequence within the Send Sequence List or of a Receive Sequence within the Receive Sequence List The Sequence Index is displayed in the upper left corner of the Edit Send Sequence or Edit Receive Sequence dialog 13 20 Serial Device Server ZZ u M u A Serial Device Server is a network device that offers one or more serial COM ports RS232 RS422 485 and transmits receives the serial data over an Ethernet network Serial Device Servers are a common way for upgrading existing devices that are controlled via serial port and make them network enabled Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used 13 21 Snapshot Creating a snapshot in Docklight means generating a display of the serial communication shortly before and after a Trigger sequence has been detected This is useful when testing for a rare error which is characterized by a specific sequence See Catching a specific sequence and taking a snapshot for more information 13 22 TCP Transmission Control Protocol TCP is a
135. may define control sequences recognized by your device send them log and analyze the responses and test the device reaction r E Docklight PC e Simulate a serial device Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Introduction Although rare the possibility of a hardware fault must be considered in most systems Imagine you have a device that sends an error message in the case of a hardware fault A second device should receive this error message and perform some kind of reaction Using Docklight you can easily simulate the error message to be sent and test the second device s reaction C mug nm l Device 2 ie o Docklight PC Monitor the communication between two devices Insert Docklight into the communication link between two serial devices Monitor and log the serial communication in both directions Detect faulty communication Sequences or special error conditions within the monitored communication Take a snapshot of the communication when such an error condition has occurred r Device 2 Docklight Tap Docklight PC 2 4 System Requirements Operating system e Windows 10 Windows 8 Windows 8 x64 Windows 7 Windows 7 x64 Windows Vista Windows Vista x64 or Windows XP Additional requirements Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachma
136. mp e Comparison Emm e Logical 10 1 5 Date Time Functions e Date Function Example Date Function DL ClearCommWindows DL AddComment Date prints the current system date e Time Function Example Time Function DL ClearCommWindows DL AddComment Time prints the current system time Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting e Timer Function Example Timer Function The Timer function returns the number of seconds that have elapsed since 12 00 AM midnight StartTime Timer For i 1 To 1000 Next DL AddComment Duration milliseconds amp Timer StartTime 1000 e Now Function Example Now Function Dim MyVar MyVar Now MyVar contains the current date and time e Day Function Example Day Function DL AddComment Day Now e Month Function Example Month Function DL AddComment Month Now e Year Function Example Year Function Dim MyDate MyDate December 7 19684 Assign a date DL AddComment Year MyDate e Hour Function Example Hour Function DL AddComment Hour Now Minute Function Example Minute Function DL AddComment Minute Now Second Function Example Second Function Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL AddComment Second Now 10 1 6 Miscellaneous e InputBo
137. munication window logging in all formats is still possible See also the Plain Text Output option above Date Time Stamps Adding a Date Time Stamp Docklight adds a date time stamp to all data that is transmitted or received You may choose to insert this date time stamp into the communication window and the log file whenever the data flow direction changes between Channel 1 and Channel 2 For applications where the data flow direction does not change very often you may want to have additional date time stamps at regular time intervals For this activate the Clock additional date time stamp option then and choose a time interval On a half duplex line e g 2 wire RS485 changes in data direction are difficult to detect Still in most applications there will be a pause on the communication bus before a new device starts sending Use the Pause detection option to introduce additional time stamps and make the pauses visible in your communication log Date Time Format Docklight offers time stamps with a resolution of up to 1 1000 seconds 1 millisecond For compatibility to earlier Docklight versions V1 8 and smaller 1 100 seconds is available too NOTE The resulting time tagging accuracy can be considerably different e g 10 20 milliseconds only The actual accuracy depends on your serial communications equipment your PC configuration the Docklight Display Settings see above and the Docklight Expert Options See the
138. n Catching a specific sequence Stop After receiving the sequence Docklight stops communications 4 Click the OK button to add the new sequence to the list N Repeat steps 1 4 to define the other Receive Sequences you need to perform your test E Storing the project Before running the actual test it is recommended that the communication settings and sequences defined be stored This is done using the menu File gt El Save Project F Running the test Start Docklight by choosing Run gt gt Start Communication Docklight will open a serial connection according to the parameters specified It will then display all incoming and outgoing communication in the communication window Use the ESI Send button to send one of the defined sequences to the serial device The on screen display of all data transfer allows you to check the device s behavior All protocol information can be logged in a text file for further analysis Please see section Logging and analyzing a test TIP Using the notepad window F12 key menu Tools Show Notepad you can easily take additional notes or copy amp paste parts of the communication log for further documentation 5 2 Simulating a Serial Device L Device 2 ee Docklight PC Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Preconditions e You need the specification of t
139. n any number of wildcards Each set of consecutive wildcards is considered a separate parameter The value for each parameter is entered separately Minimum Characters Required For each wildcard exactly one character is required Therefore the minimum number of characters required is equal to the number of wildcards within one parameter NOTE While the Send Sequence Parameter dialog is shown all serial communication is paused Docklight does not receive any data and does not send any periodical Send Sequences 9 7 Dialog Project Settings Communication E Menu Tools gt Project Settings Communication Communication Mode Send Receive Docklight acts both as transmitter and receiver of serial data This mode is used when Testing the functionality or the protocol implementation of a serial device or simulating a serial device Naming conventions The received data RX will be displayed and processed as Channel 1 the transmitted data TX will be displayed as Channel 2 Monitoring Docklight receives serial data on two different communication channels This mode is used for example when Monitoring the communication between two devices Naming conventions The serial data from device 1 is Channel 1 the data from device 2 is Channel 2 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Communication Channels Serial COM ports Docklight TAP VTP networ
140. n will stop the script and prevent that further DL OnSend DL OnReceive procedure calls are made NOTE DL OnSend and DL OnReceive events are queued and can be processed at a later point See Timing and Program Flow for more information TIP If your script consist only of the DL OnSend and DL OnReceive procedures and nothing else use a simple endless loop at module level to prevent the script from terminating immediately See the Send Sequence Data Manipulation example Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 10 3 1 Sub DL OnSend Send Sequence Data Manipulation To allow additional calculations and algorithms e g checksums on Send Sequence data the following procedure can be defined in a Docklight script Sub DL OnSend my script code End Sub Before sending out a new Send Sequence the DL OnSend procedure is called by the Docklight script engine Inside the DL OnSend procedure the following functions are available to read and manipulate the current sequence data result DL OnSend GetSize Returns the send data size number of characters result DL OnSend GetName Returns the name of the Send Sequence to be transmitted If this is custom data sequence created by a DL SendSequence command the return value is an empty string result DL OnSend Getlndex Returns its index within the Send Sequence list I
141. nc Required String containing the sequence to send The sequence is passed in ASCII representation by default For HEX Decimal or Binary sequence data use the optional representation argument described below representation Optional String value to define the format for customSequence A ASCII default H HEX D Decimal or B Binary Example Example SendSequence Predefined Send Sequences 0 Test Test 1 One One lt gt lt gt lt gt lt cR gt lt LE gt 2 Two One lt gt lt gt lt gt Two lt gt lt gt lt gt DL StartCommunication DL ClearCommWindows Send sequence without parameter DL SendSequence Test Send sequence with one parameter DL SendSequence One 100 Send sequence with two parameters DL SendSequence Two 100 20 Pass two parameters in HEX representation including spaces and control characters DL SendSequence Two 20 31 20 30 OD OA H Send custom sequence data not using a predefined Send Sequence DL SendSequence Custom Data And now using a loop and the loop variable for the Send Sequence parameter values For i 1 To 10 parString i amp amp itl use a space to separate parameters DL SendSequence Two parString Next DL StopCommunication After running the script the Docklight communication window could look like this 08 05 2008 13 50 35 622 TX Test 08 05 2008 13 50 35 631
142. nd after this event You could look for this situation by logging the test and searching the log files for the characteristic error sequence This could mean storing and analyzing several MB of data when you are actually just looking for a few bytes though if they appeared at all As an alternative you can use the Snapshot feature as described below Preconditions e Docklight is ready to run a test as described in the previous use cases e g monitoring serial communications between two devices Taking a snapshot A Defining a trigger for the snapshot 1 Define the sequence that appears in your error situation as a Receive Sequence 2 Check the Trigger tab in the action part of the Receive Sequence dialog The trigger option must be enabled if this is the sequence that you want to track down NOTE Do not forget to disable the trigger option for all other Receive Sequences that should be ignored in your test so that they do not trigger the snapshot B Creating a snapshot Click on the amp amp Snapshot button of the toolbar Docklight will start communications but will not display anything in the communication window If the trigger sequence is detected Docklight will display communication data before and after the trigger event Further data is processed until the trigger sequence is located roughly in the middle of the communication window Docklight will then stop communication and position the cursor at the trigger sequence
143. nd no date time stamps see Options The UploadFile method does not support specific compiler output file formats such as Intel HEX File If you have any specific requirements please contact our e mail support NOTE The data is sent in blocks of max 512 bytes If you send a Send Sequence manually during a file upload the sequence will be sent between one of these blocks and will corrupt the data transmission Example Example Upload File Send a text file DL UploadFile helloworld txt A Send raw binary data file directly DL UploadFile test dat R Parse and send a HEX data file DL UploadFile hexfile txt H 10 2 3 Properties 10 2 3 1 NoOfSendSequences Retums the number of Send Sequences defined in the current Docklight project Return Value Integer Syntax result DL NoOfSendSequences Remarks The NoOfSendSequences property is very useful to create loop structures that make use of all Send Sequences available See the example below Example Example NoOfSendSequences Send out all Send Sequences defined with a 1 seconds delay between the individual sequences For i 0 To DL NoOfSendSequences 1 DL SendSequence i Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL Pause 1000 Next 10 2 3 2 NoOfReceiveSequences Retums the number of Receive Sequences defined in the current
144. ne Besides the above operations you can execute any Windows command line e g for launching your external editor Example notepadt exe nosession lvb nSLINE S SFILE o For each Edit Action you can define several command lines e g goto sendkeys HOME DOWN LINE UP goto activate The following wildcards are available for Application Control Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Wildcard Description O SFILES Path to a temporary file containing the script code to edit Docklight Scripting creates and manages the temporary file SFILE UNIX Same as FILES but uses a UNIX style for the path separator This is useful for some open source editor packages that have problems with the Windows backslash V separator SFILE ESC Same as 3FILE but uses a double backslash escape sequence for the path separator This is necessary e g when working with the SciTE free source code editor E The current source code line number This is used for the goto action Remarks The External Editor Support is a flexible and open solution to our users who are working with large script projects and would prefer to work with a full featured editing package The application control interface offered described above gives you flexibility but we are aware of the limitations of controlling third party
145. ng commands with parameters and checking for sequences with random characters for details and examples Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Working with Docklight 5 Working with Docklight 5 1 Testing a Serial Device or a Protocol Implementation Docklight PC Preconditions e You need the specification of the protocol to test e g in written form e The serial device to test should be connected to one of the PC s COM ports See section Standard RS232 Cables for details on how to connect two serial devices e The serial device must be ready to operate Performing the test A Creating a new project Create a new Docklight project by selecting the menu File gt C New Project B Setting the Communication Options Choose the menu Tools gt Project Settings Choose communication mode Send Receive At Send Receive on comm channel set the COM Port where your serial device is connected Set the baud rate and all other COM Port Settings required Confirm the settings and close the dialog by clicking the OK button OPa a C Defining the Send Sequences to be used You will probably test your serial device by sending specific sequences according to the protocol used by the device and observe the device s reaction Perform the following steps to create your list of sequences 1 Double click on the last line of the Send Sequ
146. ng the OK button ON a C Defining the Send Sequences used Define all the responses of your simulator Think of responses when the simulated device is in normal conditions as well as responses when in fault condition In the UPS example mentioned above a battery failure would be such a problem case that is hard to reproduce with the original equipment To test how other equipment reacts to a battery failure define the appropriate response sequence your UPS would send in this case NOTE See Testing a serial device to learn how to define Send Sequences D Defining the Receive Sequences used In most cases your simulated device will not send unrequested data but will be polled from the other device The other device will use a set of predefined command sequences to request different types of information Define the command sequences that must be interpreted by your simulator here For every command sequence defined specify Answer as an action Choose one of the sequences defined in C If you want to use two or more alternative response sequences make several copies of the same Receive Sequence give them a different name e g status cmd answer ok status cmd answer battery failure status cmd answer mains failure and assign different Send Sequences as an action In the example you Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight would ha
147. ng with the new communication channel and or the serial settings See below for detailed specification channelNo Optional Integer value that specifies the communication channel if Communication Mode Monitoring is used Default value is 1 Channel 1 dontTest Optional Boolean value If dontTest is set to True SetChannelSettings does not open and close the communication channel for testing purposes See the Remarks section below Default value is False channel is tested to determine return value The newSettings argument accepts the following values COMxxx Select new serial communication port e g COM7 RemoteHost RemotePort Make this channel a TCP client and connect to the SERVER LocalPort Makes this channel a UDP peer transmitting data to RemoteHost Port and listening to the local Port see rojects Settings USB HID input output report access see Projects Settings access see Projects Settings Select new serial port and serial communication BaudRate settings Parity DataBits StopBits Parity can be NONE EVEN ODD MARK SPACE Example COM18 9600 EVEN 8 1 BaudRate Changing the serial settings without knowing changing Parity DataBits StopBits the current serial port Example 38400 NONE 8 1 BaudRate Extended syntax to additionally change the hardware Parity DataBits StopBits flow control options FlowControl ParityErrorChar FlowControl can be OFF RTSCTS XONXOFF RTSSEND ParityErr
148. nn und Heggelbacher GbR Introduction e For RS232 testing or simulation Minimum one COM port available Two COM ports for monitoring communication between two serial devices e For low latency monitoring using Docklight Tap One USB port e For Docklight Scripting TCP or UDP applications Network Ethernet interface Additional cables or software drivers may be required for connecting the equipment to be tested See the sections on Docklight Tap Docklight Monitoring Cable RS232 SUB D9 Standard RS232 Cables and virtual null modem drivers Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR User Interface User Interface 3 User Interface 3 1 Main Window Scripting n The main window of Docklight Scripting is divided into five sections 1 Toolbar and Status 2 Send 4 Communication Sequences Window 3 Receive 5 Script Editor Sequences 1 Toolbar and Status All main Docklight functions may be selected from the Toolbar Additional information about the communication status and the current settings is shown in the status line below it 2 Send Sequences Define edit and manage your Send Sequences here Using the arrow symbol the selected sequence can be sent out immediately Double click on the blank field at the end of a list to create a new sequence The sequence list can be
149. ntly selected ASCII HEX Decimal or Binary You may however define your search string in any other representation Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Searching the communication windows is only possible ifthe communication is stopped You can search for anything that is already defined as a Send Sequence or a Receive Sequence or you may define a custom search sequence NOTE If you are looking for a sequence within the ASCII communication window please remember the following limitations e The Find Sequence function is not able to locate sequences containing non printing control characters ASCII decimal code 32 or other special characters decimal code gt 127 This is due to the nature of the ASCII display Search using the HEX or Decimal communication window tab instead e In ASCII mode the Find Sequence function will treat date time stamps and any other comments in the same way as regular communication data In HEX Decimal Binary mode all additional information is ignored as long as it does not look like a character byte value 9 6 Dialog Send Sequence Parameter sm Type in one or several value s for a Send Sequence with wildcards here As with the Edit Send Receive Sequence dialog you may use control character shortcuts or clipboard functions Parameter No A Send Sequence can contai
150. ocklight communication window Simple checksum Mod 256 for 123456789 CalcChecksum DD 8 bat CRC CRE DOW for 123456789 CalcChecksum Al 16 birt CRC CRC 16 for 123456784 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 1234567897 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 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 10 2 2 2 ConvertSequenceData Converts Sequence data to from a float number an integer number or other common types of data in technical applications Return Value String Syntax result DL ConvertSequenceData conversionType source representation bigEndian The ConvertSequenceData method syntax has these parts Part Deseip on _______ _wm See below for the list of conversions and examples Required Input data string for the conversion This can be a Docklight Sequence e g 4B 06 9E 3F or a string with the application value e g 1 234567 See below for details representation Optional Format of th
151. ode is recommended for high accuracy low latency monitoring using the Docklight Tap In External High Priority Process mode the data collection in Docklight becomes a separate Windows process with Realtime priority class It will be executed with higher priority than any other user application or additional application software like Antivirus For best results you need to be logged in as an Administrator Otherwise the data collection process will run with the maximum permitted priority but not Realtime class NOTE External High Priority Process mode must be used with care especially when you intend to monitor a high speed data connection with large amounts of data The PC might become unresponsive to user input To resolve such a situation simply pull the plug First disconnect the data connections or the monitoring cable to bring Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference down the CPU load and restore the responsiveness Then choose E Stop communication in Docklight NOTE See the section How to Obtain Best Timing Accuracy for some background information on timing accuracy Docklight Monitoring Mode When Monitoring Serial Communications Between Two Devices all received data from one COM port is re sent on the TX channel of the opposite COM port by default Data Forwarding This is intended for special applications that require routing the serial data tr
152. ontext menu using the right mouse button and choose Function character I 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 1002 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 Br Send button 1 Sendthe test sequence using the 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 behawor try introducing a small inte
153. oopback IP address 127 0 0 1 SERVER LocalPort The channel acts as a TCP server When communication is started Docklight accepts one connection from a TCP SERVER 10001 client When a client is connected further connection SERVER 80 attempts are rejected SERVER 504 PROXY LocalPort Same as SERVER but in Monitoring Mode it will control the second channel according to the connection accepted by PROXY 10001 the server If the second channel forcefully closes a connection the PROXY server drops the accepted connection too UDP RemoteHost Port The channel acts as a UDP peer Transmit data is sent to the destination RemoteHost Port and Docklight listens to UDP 10 0 0 1 8001 UDP data on the local UDP port number Port UDP LOCALHOST 10001 When using a channel setting like UDP LOCALHOST 10001 you effectively create a loopback similar to a serial port loopback where and all outgoing data is immediately received UDP RemoteHost The channel acts as a UDP peer but using different port RemotePort numbers for outgoing and incoming data Data is transmitted Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference LocalPort to RemotePort and Docklight listens on the LocalPort UDP 10 0 0 1 83001 8002 UDP LocalPort The channel acts as a UDP server Docklight listens for UDP data on LocalPort Send data is transmitted to the source IP UDP 10001 and port number of the last UDP packet
154. op of the screen If ypos is omitted the dialog box is vertically positioned approximately one third of the way down the screen helpfile Optional String expression that identifies the Help file to use to provide context sensitive Help for the dialog box If helpfile is provided context must also be provided context Optional Numeric expression that identifies the Help context number assigned by the Help author to the appropriate Help topic If context is provided helpfile must also be provided Example InputBox Function Dim MyInput MyInput InputBox Pleas nter text My Title Example Text DL AddComment MyInput Add the current input as comment ScriptEngine Function Returns a string representing the scripting language in use Use the following script example to get the complete description of script language und version number Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Example using the ScriptEngine Function DL AddComment GetScriptEngineInfo Function GetScriptEngineInfo Dim s S r Build string with necessary info ScriptEngine amp Version s amp ScriptEngineMajorVersion amp s amp ScriptEngineMinorVersion amp S amp ScriptEngineBuildVersion GetScriptEngineInfo s Return the results End Function nnn n 10 2 Docklight Script Commands The DL Object pL ESETE
155. op sending and wait until all data came back properly started False DL Pause 20 Data throughput DL AddComment DL AddComment Number of Hello sequences detected amp DL GetReceiveCounter Hello Sub DL OnReceive If started Then myDate DL OnReceive GetDateTime msec DL OnReceive GetMilliseconds DL AddComment receive timestamp amp DL GetDocklightTimeStamp myDate msec Send out the same sequence that has just been received DL SendSequence DL OnReceive GetIndex End If End Sub Sub pauseWithEvents milliseconds Unlike the DL Pause command this function allows DL OnReceive statements to be processed while waiting startTime Timer While Timer startTime milliseconds 1000 consider midnight jump reset of the Timer variable If Timer startTime 1 Then startTime startTime 86400 DL Pause 1 Wend End Sub After starting the script Docklight will keep sending and receiving the Hello sequence for about 1 second The total number of sequences sent and received depends on the COM port settings baud rate PC speed and Docklight display settings The Communication Window could look like this 8 1 2012 11 00 41 830 TX Hello lt CR gt lt LF gt 8 1 2012 11 00 41 834 RX Hello lt CR gt lt LF gt receive timestamp 8 1 2012 11 00 41 834 8 1 2012 11 00 41 846 TX Hello lt CR gt lt LF gt 8 1 2012 11 00 41 849 RX Hello lt CR gt lt LF
156. orChar The decimal ASCII code for the Parity Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Error Character see Projects Settings Default value is 63 Example 9600 NONE 8 2 RTSCTS 35 Find the next serial COM port available on this PC If the currently selected port is COM1 SetChannelSettings will start searching at COM2 Remarks For most applications it is not necessary to use SetChannelSettings or its companion GetChannelSettings Communication parameters can be chosen in the Project Settings dialog and stored in the Docklight project file see Saving and Loading Your Project Data and the Open Project method The SetChannelSettings method is intended for advanced Docklight Scripting applications where control of the communication channel settings during script runtime is required It allows you to create scripts that access different COM ports see example below or walk through a list of IP addresses SetChannelSettings method will produce an error if an illegal value is passed with newSettings If the newSettings argument is valid and the dontTest flag is not set the communication channel will be opened and closed again immediately for a test If dontTest is True SetChannelSettings will not open close the channel for testing and return always True This is useful in networking applications where additional connect disconnect attempts m
157. orking with a user account which has restricted system access you might not have permission to save into the program files directory In this case saving a project file or any other data into the ScriptSamples folder will produce an error NOTE For additional sample scripts projects and Application Notes see our online resources at www docklight de examples en htm 8 1 Automated Modem Testing Sample Script ModemScript pts FE z v ro sm_ rm sm _m m m The Docklight script ModemScript pts and the accompanying project file ModemATCommands ptp demonstrate how to use a Docklight script for an automated test or configuration task with user interaction The project file uses the communication settings listed below This should work for most standard modems Communication Mode Send Receive Send Receive on comm channel COM3 COM Port Settings 9600 Baud No parity 8 Data Bits 1 Stop Bit Getting started e Connect the modem to an available COM port e g COM1 and switch it on The demo may also run on a notebook with a built in modem In many cases you will find your notebook s built in modem on COMS so you can try and run the sample script without modifying the project settings Go to the Project Settings dialog and make sure you have selected the same COM Port for Send Receive on comm channel Press the By Run Script button in the toolbar Type in the AT command range to be tested or simply accept the de
158. ort Only one connection at a time may be used This is similar to the default operation of many Serial Device Servers Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced TIP An example that can be tried on any computer with a web browser and Internet access is the TCP_Monitoring_HTTP ptp project which can be found in the Network folder ofthe ScriptSamples directory Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Examples and Tutorials Examples and Tutorials 7 Examples and Tutorials This chapter describes two sample projects that demonstrate some of Docklight s basic functions The corresponding Docklight project files ptp files can be found in the Samples folder within the Docklight installation directory e g C Program Files FuH Docklight V2 1 Samples NOTE If you are logged on with a restricted user account you will not have permission to make any changes in the program files directory In this case saving a project file or any other data into the Samples folder will produce an error NOTE For additional sample projects and Application Notes see our online resources at www docklight de examples_en htm 7 1 Testing a Modem Sample Project ModemDiagnostics ptp Sa a The Docklight project ModemDiagnostics ptp can be used to perform a modem check A set of modem diagnostic commands a
159. oth serial ports GPS receivers virtual null modems Arduino MicroPython pyboard or other Embedded Development environments that add a COM port in Windows For RS232 full duplex monitoring applications we recommend our Docklight Tap USB accessory or our Docklight Monitoring Cable This manual only refers to RS232 serial connections in detail since this is the basis for other serial connections mentioned above TIP For getting started have a look at the Docklight sample projects which demonstrate some of the basic Docklight functions Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Introduction 2 2 Docklight Scripting Overview Docklight Scripting is an extended edition of Docklight RS232 Terminal RS232 Monitor It features an easy to use scripting language plus a built in editor to create and run automated test jobs A Docklight script allows you to execute all basic Docklight operations sending predefined data sequences detecting specific sequences within the incoming data stream and embed them in your own test code Docklight Scripting is network enabled Instead of using a serial COM port Docklight Scripting can establish TCP connections TCP client mode accept a TCP connection on a local port TCP server mode or act as a UDP peer It also supports USB HID connections and Named Pipes Docklight Scripting gives you both flexibility and simplicity Within minutes yo
160. ow Case 2 DL AddComment Monday Case 3 DL AddComment Tuesday Case 4 DL AddComment Wednesday Case 5 DL AddComment Thursday Case 6 DL AddComment Friday Case Else DL AddComment Weekend End Select 10 1 2 2 Loop Structures e Do Until Loop Example Do Until DefResp vbNo MyNum Int 6 Rnd 1 Generate a random integer between 1 and 6 DefResp MsgBox MyNum amp Do you want another number vbYesNo Loop e Do Loop While Example Do MyNum Int 6 Rnd 1 Generate a random integer Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting between 1 and 6 DefResp MsgBox MyNum amp Do you want another number vbYesNo Loop While DefResp vbYes e While Wend Example Dim Counter Counter 0 Initialize variable While Counter lt 20 Test value of Counter Counter Counter 1 Increment Counter DL AddComment Counter Wend End While loop when Counter gt 19 e For Next Example For I 1 To 5 For J 1 To 4 For K 1 To 3 DL AddComment I amp amp J amp amp K Next Next Next 10 1 3 Variables Arrays Constants and Data Types You often need to store values temporarily when performing calculations with VBScript For example you might want to calculate several values compare them and perform different operations on them depending on the result of the comparison
161. pen the dropdown list scroll down to the USB Taps section and choose the first Tap port e g TAPO At Receive Channel 2 the second tap port e g TAP1 is selected automatically 4 Setthe baud rate and all other communication parameters for the protocol being used NOTE Make sure your PC s serial interfaces port works properly at the baud rate and for the communication settings used by Device 1 and Device 2 If Device 1 and 2 use a high speed data transfer protocol the PC s serial interfaces and the Docklight software itself might be too slow to receive all data properly 5 Confirm the settings and close the dialog by clicking the OK button C Defining the Receive Sequences used Define Receive Sequences which should be marked in the test protocol or trigger an action within Docklight Docklight checks for Receive Sequence on both monitoring channels i e it does not matter whether the sequences come from serial device 1 or serial device 2 NOTE Since a special monitoring cable is used for this test all communication between serial device 1 and serial device 2 will remain unbiased and no additional delays will be introduced by Docklight itself This is particularly important when using Docklight for tracking down timing problems This means however that there is no way to influence the serial communication between the two devices While communication mode Monitoring is selected it is not possible to use Send Sequences D S
162. ple is just for illustrative purposes and explains how the configuration files work You can use it as a starting point for integrating your own editor How to integrate your own favorite editor You can set the application path at the beginning of the configuration file using the path syntax Example line path C Program Files Notepad All following lines of the configuration file have the following syntax Edit Action Application Control Example line open notepad exe SFILE S Edit Action can be one of the following Docklight editing actions Edit Action Description O Open a new script code file Go to a line number within the script file Save the current file open Close the current file open Application Control can be one of the following operations Application Description Control sendkeys Send one or more keystrokes to the external editor It uses the same argument syntax as the Windows Script Host SendKeys method See the related Microsoft documentation for details Example goto sendkeys HOME DOWN SLINES UP endtask End the external application Example close endtask activate Activate the external application window Example goto activate sleep Wait up to 500 milliseconds to give the external application some extra time to sort things out This might be necessary when working with the sendkeys operation described above Example open sleep 100 Command Li
163. r changes Docklight will try to preserve the display contents Plain Text Output faster display but no colors amp fonts The formatted text output is similar to a word processor and consumes a considerable amount of CPU time It also requires frequent memory allocation and deallocation which might decrease your PC performance So if you are monitoring a high speed communication link but still want to keep an eye on the serial data transferred try using the Plain Text Output format Control Characters ASCII 0 31 For communication data containing both printing ASCII text as well as non printing Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference control characters it is sometimes helpful to see the names of the occurring control characters in the ASCII mode display window Docklight provides an optional display settings to allow this You can also suppress the control characters except CR and LF for cases when this would clutter your display Display Modes Communication Window Modes By default Docklight will display four representations of the serial data streams ASCII HEX Decimal and Binary You may deactivate some of these modes to increase Docklight s overall performance For example the Binary representation of the data is rarely required Disabling Binary mode for the communication window will considerably increase processing speed Even when turned off for the com
164. r character delay Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced Function character F11 setting RTS and DTR Character Value RTS DTR Decimal Mode o Jw ow 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 Parity Decimal Mode No parity Odd parity 64 Mark Set parity bit to logic 1 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 SwitchPa
165. r other users who are not familiar with Docklight You can prepare the appropriate display representation e g HEX mode only and make sure other users will receive the same display output as you did NOTE Communication needs to be stopped see StopCommunication before using SaveProgramOptions or LoadProgramOptions Example Example SaveProgramOptions L StopCommunication L SaveProgramOptions myFavoriteSettings L Quit o o g Now make some changes in the Docklight Options or change the communication window e g by selecting the Decimal tab Then run the following script Example LoadProgramOptions DL LoadProgramOptions myFavoriteSettings Docklight will now revert to the display settings used before 10 2 2 13 SetChannelSettings Change the current communication channel settings provide a new COM port number or TCP IP address or change the serial port settings baud rate parity settings Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Serial port settings can be changed on the fly while the communication channel is open For other changes e g the COM port number itself StopCommunication must be called before using SetChannelSettings NOTE Return Value Boolean Syntax result DL SetChannelSettings newSettings channelNo dontTest The SetChannelSettings method syntax has these parts newSettings Required Stri
166. r s vu eae ER te an 10 2 1 10 StartCommunication zu HS 10 2 1 11 STOPCOMMUNI CATION u 10 2 1 12 Startl gging e PH 10 2 1 13 StopL gging eE 9 10 2 1 14 MEI DIgic M 10 2 2 Methods Advanced 10 2 2 1 Cale e oT IP ERE 10 2 2 2 ConvertSequenceData 10 2 2 3 GetChannelSettings sess tentes 10 2 2 4 GetChannelStatus 10 2 2 5 GetCommWindowData 10 2 2 6 GetEnvironment nsssssssnssnssnssnnnnnnnnsansannannannannannannannsnnsonsnnsnnnn 10 2 2 7 GetHandshakeSignals 10 2 2 8 GetReceiveComments 0c cc ccecsvcsnasstsnas saste stent cst cssesvesucadehusnacnscnachssnssnsceesescesbedbesbecsechechochecsocenccnessoenbent 10 2 2 9 IM PUTBOX2 sine en A en casvescascusecceluetibvinssee E T E E 10 2 2 10 LoadProgramOptlOns i cscsscscecdserescsecidecscsesssccsdetscsiesesesessiceisssssseotsaesaaceessevnndsncccccsessscstesteedscoveesverncaneaes 10 2 2 11 dE IeEnatbruidi 10 2 2 12 SaVEPrOogra MO PtlONS e M 10 2 2 13 SetChannelSettings 5 5 ee nn de eR REOR GE as Rer ka oe eec ERR EEXRRE ren 10 2 2 14 SetCoritentsEII ter aureo ee een css ta RERO IS EN EE eU RE cre ey ien tre I 10 2 2 15 SetHandshake
167. racter inside a Receive Sequence to specify a minimum silent time where no further characters should be received This is useful for detecting pauses in the data stream that indicate the beginning end of a telegram especially for protocols where there is no dedicated start or end character Preconditions e Docklight is ready to run a test as described in testing a serial device or a protocol implementation e The Docklight project already contains one or several Send Sequences but an additional delay at certain character positions is required Sending Data With Inter Character Delays As an example we use a microcontroller application which understands a get command In ASCII Mode the Send Sequence would be glelt r r is a terminating CR Carriage Return character The following steps describe how to add an additional delay of 20 milliseconds between each character and avoid buffer overflows on the microcontroller side Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced A Modifying the existing Send Sequence 1 Open the Edit Send Sequence dialog 2 Switch Edit Mode to Decimal Our get example looks like this in decimal mode 103 101 116 013 3 Insert a delay function character between the first and the second character Press F9 or open the context menu using the right mouse button and choose Function character amp delay The
168. re defined in the Send Sequences list This is a simple example for Testing a serial device or a protocol implementation The sample project uses the communication settings listed below This should work for most standard modems Communication Mode Send Receive COM Port Settings 9600 Baud No parity 8 Data Bits 1 Stop Bit Getting started Use the Windows Device Manager to find out which COM Port is a modem device This demo project may be used with any AT compatible modem available on your PC e g a built in notebook modem or a GSM or Bluetooth modem driver than can be accessed through a virtual COM port TIP For a simple test without specialized hardware add your mobile phone as Bluetooth Device on your Windows PC Then find your phone in the Windows Devices and Printers list Right click on it choose Properties and go to the Hardware tab In the Device Functions list it should mention the modem related COM Ports Go to the Project Settings dialog and make sure you have selected the same COM Port for Send Receive on comm channel Press the Start Communication button in the toolbar Try sending any of the predefined modem commands by pressing the E Send button You should now receive a response from your modem e g OK if your command was accepted a model identification number etc The response will vary with the modem model After sending several sequences the Docklight communication window could look like this
169. referencing the sequence It is not the data that will be sent out through the serial port See 2 Sequence below 2 Sequence The character sequence that will be transmitted through the serial port TIP For transmitting larger blocks of data that exceed the maximum sequence size use the DL UploadFile script command TIP Special Function Characters are available for creating inter character delays set handshake signals and parity bits or setting a break state 3 Additional Settings e Repeat Check the Send periodically option to define a sequence that is sent periodically A time interval between 0 01 seconds and 9999 seconds can be specified NOTE The Windows reference time used for this purpose has only limited precision Time intervals 0 03 seconds will usually not be accurate e Checksum Perform automatic calculation of any type of checksum including any type of CRC standard such as MODBUS CCITT CRC32 TIP See Calculating and Validating Checksums for a general overview and Checksum Specification for the text format used to define a checksum Wildcards Wildcards can be used to introduce parameters into a Send Sequence that you wish to insert manually each time the sequence is sent See section Sending commands with parameters for details and examples Control Character Shortcuts Using keyboard shortcuts is a great help when editing a sequence that contains both printing characters letters A z digits
170. rent working directory If filePathName is an empty string a file dialog will be displayed to choose a file representation Optional String value to define the format of the filePathName file A ASCII default filePathName is a text file that is sent out directly no further parsing H HEX filePathName contains HEX sequence data e g 5F 54 65 73 74 D Decimal filePathName contains Decimal sequence data e g 095 084 101 115 B Binary filePathName contains Binary sequence data e g 01011111 01010100 R Raw Data filePathName is a binary file that needs that is sent out unmodified Remarks File upload is only possible in Communication Mode Send Receive If filePathName does not exist Docklight reports an error and the script execution is stopped The A ASCII default representation allows sending text files without further Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting modification For raw binary data files that need to be sent unmodified use the R Raw Data option It is not to be confused with the B Binary representation used by Docklight to display data with O s and 1 s only You can use the UploadFile method to transfer the contents of a Docklight Log file Please make sure that your log file is in plain text mode see Log File Settings and the file contains the raw data only with no additional comments a
171. reordered by dragging a sequence to a new position with the left mouse button pressed A context menu right mouse button is available to cut copy or paste entire Send Sequences to from the Clipboard See Editing and Managing Sequences and Dialog Edit Send Sequence for more information 3 Receive Sequences Define edit and manage your Receive Sequences here Double click on the blank field at the end of a list to create a new sequence The Receive Sequence list supports the same reordering and clipboard operations as the Send Sequence list You can also copy a Send Sequence to the clipboard and paste it into the Receive Sequence list See Editing and Managing Sequences and Dialog Edit Receive Sequence for more information 4 Communication Window Displays the outgoing and incoming communication on the serial port Various display options are available for the communication data including ASCII HEX Decimal Binary display time stamps and highlighting see Options If serial communication is stopped all data from the communications window may be copied to the clipboard or printed You may also search for specific sequences using the Find Sequence function See How Serial Data is Processed and Displayed for more information 5 Script Editor Edit your Docklight script code here A context menu right mouse button is available to cut copy paste or delete sections of code Find and replace functions are also available For advan
172. rite more than one file at a time you can open up to 4 input files and 4 output files simultaneously using additional global objects besides Filelnput and FileOutput The list of available objects is Object Name Filelnput Open up to 4 different files for reading See Reading Files Filelnput2 Filelnput3 Filelnput4 Open up to 4 different files for writing See Writing Files FileOutput4 Example Multiple file output Create 4 text files DL AddComment Writing 4 text files simultaneously FileOutput CreateFile filel txt FileOutput2 CreateFil Tile e2 txt FileOutput3 CreateFil E31le3 txt FileOutput4 CreateFil file4 txt Write simultaneously For i 1 To 10 FileOutput WriteLine File 1 Text line amp CStr i FileOutput2 WriteLine File 2 Text line amp CStr i i i FileOutput3 WriteLine File 3 Text line amp CStr FileOutput4 WriteLine File 4 Text line amp CStr Next Close all 4 files FileOutput CloseFile FileOutput2 CloseFile FileOutput3 CloseFile FileOutput4 CloseFile DL AddComment Done 10 5 Debug Object Script Debugging EST Docklight Scripting offers additional debugging features through the Debug object Method Prope Debug Mode newValue Sets the script debug mode newValue 0 No Debugging all Debug methods are ignored newValue 1 Debug Mode The Debug
173. rityDemo ptp sample project folder Extras ParitySwitch_9BitProtocols in your Samples directory Function character F11 detecting handshake signal changes 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 Handshake Signal Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced DeimalMode o 4 CD High 000000000 O NOTE See also DL GetHandshakeSignals for the extended set of signal states supported in Tap Pro Tap RS485 applications Example Receive Sequence definitions in Decimal Edit Mode Receive Sequence Description Decimal Mode 001 triggers when CTS high all other signals low 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 dete
174. rmat and a more complex example on how to manipulate channel settings during script runtime Example Example GetChannelSettings iw L AddComment Comm Channel 1 Settings amp DL GetChannelSettings The following command will only work if Docklight Communication Mode is Monitoring receive only DL AddComment Comm Channel 2 Settings amp DL GetChannelSettings 2 The example could produce the following output in the Docklight Communication Window Comm Channel 1 Settings COM1 9600 NONE 8 1 OFF 63 Comm Channel 2 Settings SERVER 10001 10 2 2 4 GetChannelStatus Retums the current communication channel status closed open waiting for TCP connection or error Return Value Integer Syntax result DL GetChannelStatus channelNo The GetChannelStatus method syntax has these parts Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting channelNo Optional Integer that specifies the communication channel if Communication Mode Monitoring is used Default value is 1 Channel Remarks GetChannelStatus returns the following values result Descri Buon ee Sto Communication EN c c TCP server or TCP client mode Connection established TCP server or TCP client mode Waiting for connection COM port with RTS CTS hardware flow control Waiting for handshake signal 3 Channel error e g after a
175. rogramOptions filePathName The LoadProgramOptions method syntax has these parts Pat Description O filePathName Required String containing the file path directory and file name of the Docklight settings file to load If no directory is specified Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting Docklight uses the current working directory If filePathName is an empty string a file dialog will be displayed to choose a file Remarks See the SaveProgramOptions method for more information on saving and loading Docklight program options 10 2 2 11 PlaybackLogFile Opens an existing Docklight Log File HEX Decimal or Binary representation and plays back re sends the data from one communication direction of this log file Starts the communication if not already running see StartCommunication Return Value Void Syntax DL PlaybackLogFile filePathName dataDirection timelnterval The PlaybackLogFile method syntax has these parts Partt Description O j Required String containing the file path directory and file name of the log file If no directory is specified Docklight uses the current working directory If filePathName is an empty string a file dialog will be displayed to choose a file dataDirection Optional String value Specifies which of the two communication channels recorded TX or RX COM1 or rather COM2
176. rom the use of programs and source code that may accompany it In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document Contact E Mail Support docklight fuh edv de Flachmann amp Heggelbacher Waldkirchbogen 27 D 82061 Neuried Germany http www fuh edv de Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Introduction Introduction 2 Introduction 2 1 Docklight Overview e Docklight is a testing analysis and simulation tool for serial communication protocols RS232 RS485 422 and others It allows you to monitor communications between two serial devices or to test the serial communication of a single device Docklight is easy to use and works on almost any standard PC running Windows 10 Windows 8 Windows 7 Windows Vista or Windows XP Docklight s key functions include e simulating serial protocols Docklight can send out user defined sequences according to the protocol used and it can react to incoming sequences This makes it possible to simulate the behavior of a serial communication device which is particularly useful for generating test conditions that are hard to reproduce with the original device e g problem conditions logging RS232 data All serial communication data can be logged using two different file formats Use plain text
177. s FB Hex 251 Decimal 22 06 2015 11 228 232 5608 TX 54 65 73 T4 4E UD FB NOTE Calculating and Validating Checksums and the MODBUS protocol example describe how to calculate and validate common CRCs and other checksums without DL OnSend DL OnReceive code This processing happens before the sequence data is passed to the DL OnSend procedure But if you want to modify your Send Sequence data before sending and require a checksum on the modified data the above example is the correct solution 10 3 2 Sub DL OnReceive Evaluating Receive Sequence Data To analyze the Receive Sequence data e g check the actual values received for a wildcard area or perform additional tasks after receiving the sequence the following procedure can be defined in a Docklight script Sub DL OnReceive my script code End Sub After detecting a new Receive Sequence and performing the predefined Actions add comment send a sequence the DL OnReceive procedure is called by the Docklight script engine Inside the DL OnReceive procedure the following functions are available to read out the Receive Sequence data result DL OnReceive GetSize Retums the received data size number of characters result DL OnReceive GetName Retums the name of the corresponding Receive Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting result DL OnReceive G
178. s and warning in the documentation 6 4 Calculating and Validating Checksums a 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 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced 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 the DL CalcChecksum method on how to calculate checksums using script code Preconditions You know the checksum specification for the protocol messages e Which area of the sequence data is guarded by a checksum e Where is the checksum located Usually at the end of the sequence e 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 Send Sequences that include a checksum 1 Create a new Send Sequence Enter a Name for the sequence 2 Enterthe Sequence part of your message in the Sequence section We use a very simple message as an example here 01
179. s left out AddComment will produce a line break only timeStampAfterComme Optional Boolean value nt False Default No additional time stamp True Add a time stamp after the comment The time stamp is added when processing the next serial data character not immediately after printing the comment This is similar to how the Additional time stamp option in the Receive Sequence dialog works lineBreakAndPadding Optional Boolean value True Default Additional space characters are added before and after the text to separate it from the communication data A line break is added after the comment False No additional spaces or line break This is especially useful in combination with the Communication Filter option when you want to create the actual screen output entirely with the AddComment method Remarks You cannot use ASCII control characters like decimal code 08 Backspace to emulate terminal functions display formatting The only exception is decimal code 07 Bell which can be use to produce a beep signal depending on your Windows sound scheme Example Example AddComment DL ClearCommWindows Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting DL AddComment Hello World Additional line break DL AddComment Use the amp operator to concatenate strings and other variables rl 10 r2 20 DL AddComment Result
180. se tn nasse tana sena 70 9 12 Dialog Expert Options ana na 71 9 13 Keyboard Console M 72 9 14 Checksum Specification M 72 10 Reference Scripting 75 10 1 VBScript BaSiCS de 76 10 1 1 Copyright Notice c 77 10 1 2 Control StrUCtUT S une ass XM unie atq Dua C ta M vv EPa pa Ue EdUE 77 10 1 2 1 Decision truct res R 77 10 1 2 2 LOOP Str ctures u nn en nn enter nein 78 10 1 3 Variables Arrays Constants and Data Types cccccccccccssssssssececeesesssssssseseeeeees 79 10 1 4 Operatots nal ea nahen Lee a Ve ue Ae R Ras 81 10 1 5 Date Time Functions nennen 82 10 1 6 Miscellaneous nen 84 10 2 Docklight Script Commands The DL Object eere eee ee enne ee eee 85 10 2 1 Methode me 86 10 2 1 1 AGA COMIMENE ROTER m 86 10 2 1 2 Clear COMMW indOWSs rc meet terne rre tree ie Rr e ier sinn pereo e ner 87 10 2 1 3 e ues eoru c 87 Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Table of Contents 10 2 1 4 GetDocklightTimeStamp 10 2 1 5 OpenProject rrt nr rn 10 2 1 6 10 2 1 7 10 2 1 8 10 2 1 9 SendS qUeric8 custo reete etiem erige ien nere ur eerta tre ier A Ra Peer Ein a rech e eret ag eb
181. settings COM ports baud rate Options Select general program options e g display mode date time stamp Expert Options Select expert program options intended for advanced users and specific applications e g high monitoring accuracy Scripting Menu E gt Run Continue Script Execute the code in the script editor Ein Stop Script Stop a running script Eil Break Script Interrupts a running script New Script Close the current Docklight script and create a new one Open Script Close the current Docklight script and open another script Save Script Save Script As Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Save the current Docklight script Show Editor Hide Editor Show Hide the script editor window Ifthe script editor is hidden the communication window expands to full height Customize External Editor Use an external editor instead of Docklight s built in editor 9 2 Dialog Edit Send Sequence pl M M M M M M isill This dialog is used to define new Send Sequences and edit existing ones See also Editing and Managing Sequences Index The index of the sequence displayed below The first sequence has index 0 zero 1 Name Unique name for this sequence e g Set modem speaker volume This name is for
182. sting log file s Docklight will then insert a start logging stop logging message when opening closing the log files This is so that when in append mode it is still possible to see when an individual log file session started or ended Representation A separate log file may be created for each data representation ASCII HEX Choose at least one representation The log files will have a txt or htm file extension Docklight additionally adds the representation type to the file name to distinguish the different log files E g if the user specifies Test1 as the base log file name the plain text ASCII log file will be named Test1 asc txt whereas the plain text HEX log file will be named Test1 hex txt High speed logging If you are monitoring a high speed communication link or if you are running Docklight on a slow computer Docklight may not be able to catch all the transmitted data or may even freeze no response to any user input In this case try disabling the communication window output while logging the data to a file Docklight will run much faster since the display formatting uses considerable CPU time 9 5 Dialog Find Sequence pem E ALLLLLLLIX Menu Edit gt 4 Find Sequence in Communication Window The Find Sequence function searches the contents of the communication window The search is performed in the communication window tab that is curre
183. string the transmission of the original Send Sequence is effectively suppressed DL OnSend Poke charNo value Set the character at position charNo to value value is the new character as an integer number from 0 255 See also DL OnSend Peek result DL OnSend Peek charNo Returns one character of the send data as an integer value from 0 255 charNo is the position within the send data Valid charNo range 1 DL OnSend GetSize Syntax 2 result DL OnSend Peek charNo Syntax 2 representation Returns a string instead of an integer value representation specifies the format A ASCII H HEX D Decimal or B Binary Remarks Using the DL OnSend GetSize DL OnSend Peek and DL OnSend Poke functions checksum calculations and other algorithms can be easily implemented See the example below The DL OnSend procedure is only executed while the script is running While executing the DL OnSend code no further communication processing and display updates are performed To avoid performance and timing problems keep the execution time low Avoid nested loops for example and do not perform time consuming calculations See Timing and Program Flow for some insight on how Docklight handles send data events and executes the DL OnSend code section Example Example DL OnSend event code Predefined Send Sequences 0 Test TestX lt CR gt lt NUL gt Endless loop to prevent the s
184. t View DTE perspective looking into the male connector 94 99 94 9 95 9g 9 g 99 m M42 On M15 M16 ar ag M19 on 994 2 953 934 955 E Mo Protective Shielding Ground Transmit Data 3 RX Receive Data Request To Send Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix l8 DSR Data Set Read Signal Ground is DCD Data Carrier Detect o Reseved Ho Reseved o Unassigned O 9 SRTS Secondary Request To Send gp DTR Fon Terminal Read RL SQ Remote Loopback Signal Qualify Detector 22 Ri Ring indicator 25 Unassigned RS232 D RJ45 pinout View Top View Front ul NN Pin No Signal Name Description Signal Ground Receive Data 6 TX Transmit Data 8 RTS Request To Send Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Appendix 12 4 Standard RS232 Cables RS232 Connections When connecting two serial devices different cable types must be used depending on the characteristics of the serial device and the type of communication used Overview of RS232 SUB D9 interconnections serial device 1 serial device 2 flow control recommended cable handshaking no handshake simple null modem cable null modem cable with partial handshaking hardware flow control simple null modem cable
185. t procedure is executed once for each new Send Sequence This applies to both sequences sent by clicking the Send button and DL SendSequence calls The DL OnSend event procedure is only entered after the current line of script code has been executed Send requests are buffered in the meantime The sequence diagram below shows the resulting timing behavor for an example with Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting one manual send request sequence1 and a second Send Sequence triggered by Transmit Data Communications Handler Window script code DL SendSequence sequence2 OnSend Docklight Script Queue Engine sequence Send button i pressed manual send i j DL SendSequence sequence2 m call DL OnSend for sequence H process OnSend events return modified sequence data transmit sequence gt imeline call DL OnSend for sequence2 return modified sequence data Sub DL OnReceive Timing display sequence1 display sequence2 H Similar to DL OnSend the DL_OnReceive event procedure is not executed immediately after Docklight has detected a new Receive Sequence match Instead the events are buffered and executed after the current line of script code has been executed The sequence diagram below shows the timing for an example
186. tesArray Split baudRatesStr For i 0 To UBound baudRatesArray Tweak the serial port settings DL SetChannelSettings baudRatesArray i NONE 8 1 DL AddComment DL AddComment DL AddComment Testing with settings amp DL GetChannelSettings Send a modem test command and allow some waiting time for the answer DL StartCommunication DL SendSequence ATI3 Chr 13 Chr 10 DL Pause 200 DL StopCommunication Next After running the script on a computer with a built in modem on COM3 the Docklight communication window could look like this Searching for first COM port available on this PC Using COM port COM3 9600 NONE 8 1 Testing with settings COM3 9600 NONE 8 1 28 01 2008 16 28 36 26 TX ATIS lt CR gt lt LE gt 28 01 2008 16 28 30 26 RX ATI3 CR lt CR gt lt LF gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LE gt OR lt CR gt lt LE gt Testing with settings COM3 14400 NONE 8 1 28 01 2008 16 28 37 46 TX ATIS lt CR gt lt LE gt 28 01 2008 16 28237 46 RX ATII lt CR gt lt CR gt lt LF gt Agere SoftModem Version 2 1 46 lt CR gt lt LF gt lt CR gt lt LF gt OK lt CR gt lt LF gt Testing with settings COM3 57600 NONE 8 1 28 01 2008 16 28 38 60 TX ATI3 lt CR gt lt LE gt Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting 28 01 2008 162298238 060 RX ATISSCR lt CR gt lt L
187. ting options are activated in the Display Settings You do not have to use the font style or font weight attribute to create these effects HTML Footer Template Adds additional footer text and closes the HTML document Data Element Template For every new piece of log file information channel 1 data channel 2 data or a comment text anew lt span gt tag with different text color is added to the HTML log file The template code for the header footer and data parts contains Docklight specific wildcards which must not be deleted Wildcard BACKCOLOR Display Settings HEADERMSG FOOTERMSG a chunk of the log file data channel 1 data channel 2 data or a comment text A TEXTCOLOR The text color to apply for DATA as selected in the Display Settings When generating a log file Docklight replaces the wildcards with the current display settings and the actual communication data 9 12 Dialog Expert Options Menu Tools Expert Options Expert Options are additional settings for specialized applications with additional requirements e g high time tagging accuracy Performance Communication Driver Mode Use External High Priority Process mode to work around a common problem for any Windows user mode application unspecified delays and timing inaccuracies can be introduced by the Windows task process scheduling especially if you are running other applications besides Docklight External High Priority Process m
188. tion A ASCII H HEX D Decimal or B Binary These functions return the actual Docklight date DL OnReceive GetDateTime time stamp when this Receive Sequence was triggered The result is stored in two separate milliseconds VBScript standard data types DL OnReceive_GetMilliseconds myDateTime VBScript Date value with the Date Time in 1 seconds resolution milliseconds Integer value with the corresponding milliseconds information from 0 999 Remarks Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting The DL OnReceive GetData method is a good way to analyze the actual data received when you are using ASCII protocols with printing characters only If you require the HEX or decimal value of individual characters you may use the DL OnReceive Peek function as a convenient alternative See the DL OnSend event procedure for a related example The DL OnReceive procedure is only executed while the script is running While executing the DL OnReceive code no further communication processing and display updates are performed To avoid performance and timing problems keep the execution time low Avoid nested loops for example and do not perform time consuming calculations DL OnReceive procedures are not executed while a Pause or a WaitForSequence method is blocking the program flow If a Receive Sequence is detected the DL OnRece
189. tml org German and French for a quick overview on these topics HTML Header Template The HTML document header Here you can change the font applied to the log file data using the following CSS style attributes CSS Style Attribute Description and Example font family Defines one or several fonts or font categories that the HTML browser should use to print a text If the browser does not support the first font it will try the second one a s o The last font usually defines a generic font category that every browser supports Examples Font family Courier New Courier monospace font family Times New Roman Times serif Font family arial helvetica sans serif Specifies the font size Both absolute and relative sizes are possible Examples for absolute font sizes Font size 12pt font size xx small Font size x small Font size small Font size medium Font size large Font size x large Font size xx large Examples for relative font sizes relative to the parent HTML element Font size smaller font size larger font size 90 NOTE Use the semicolon as a separator between two different CSS style attributes e g font family sans serif font size small Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference NOTE Docklight will insert additional lt u gt underline lt i gt italic and lt b gt bold HTML tags if such format
190. toring the project Before running the actual test it is recommended to store the communication settings and sequences defined This is done using the menu File gt El Save Project E Running the test Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Start Docklight by choosing Run gt Start Communication then activate the serial devices 1 and 2 and perform a test run Docklight will display all communication between serial device 1 and serial device 2 Docklight uses different colors and font types to make it easy to distinguish between data transmitted by device 1 or device 2 The colors and font types can be chosen in the Display tab of the Tools gt Options dialog TIP The amp Snapshot Function allows you to locate a rare sequence or error condition in a communication protocol with a large amount of data TIP See the sections How to Increase the Processing Speed and How to Obtain Best Timing Accuracy to learn how to adjust Docklight for applications with high amounts of data or increased timing accuracy requirements 5 4 Catching a Specific Sequence and Taking a Snapshot of the Communication ETE NIA EC A H 4 t When monitoring serial communications between two devices you might want to test for a rare error and the interesting parts would be just the serial communication before a
191. ts 12 Appendix 142 12 1 ASCII Character Set Tables is un sen nk GE Xa dle 143 12 2 HOt KEYS REID QU D ILLI 145 12 3 RS232 Connectors 7 PINGUt seen 147 12 4 standard RS232 Cables ne ee ae 149 12 5 Docklight Monitoring Cable RS232 SUB D9 cesse eene eene eene eene 151 12 6 D cklieht Tap e n 152 12 7 Docklight Tap Pro Tap 485 a5 153 13 Glossary Terms Used 154 13 1 hisdem seve 155 13 2 IL ae 155 13 3 Character et 155 13 4 js s 155 13 5 DEE a er 156 13 6 jj mer 156 13 7 Flow Control etc Cr 156 13 8 e e P 156 13 9 LN Nem etc erm 156 13 10 MODBUS iscsi cata ios aa sn Suia 157 13311 Mu ltidrop Bus MDB ne nee 157 EEBCMEB Fondue ecc 157 13 13 LCTDCHUTSMT S I EDDIE 157 13 14 RS232 T 157 13 15 BS022 o 158 13 16 000 c NaN S aani 158 13 17 Send o a aan 159 13 18 SEQUENCE EE E peut 159 13 19 Sequence Index anna anne Keen 159 13 70 Serial Device Server nun ae nen 159 CV NEN Ioco ec 160 1322 TOP a
192. tware Flow Control Uses dedicated ASCII control characters XON XOFF to control data transmission Software flow control requires text based communication data or other data that does not contain any XON or XOFF characters 13 8 HID HID Human Interface Device is a device class and API used for USB and Bluetooth devices Docklight Scripting supports HID access via VID PID vendor ID product ID or the full Windows USB device path It allows basic transfer of HID Input and Output Reports A common application besides standard Windows keyboard mouse integration are Embedded Devices 13 9 LIN Local Interconnect Network A low cost serial communication bus targeted at distributed electronic systems in vehicles especially simple components like door motors steering wheel controls climate sensors etc See also http www lin subbus org Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Glossary Terms Used 13 10 MODBUS e MODBUS is an application layer messaging protocol that provides client server communications between devices connected on different types of buses or networks It is commonly used as MODBUS over Serial Line in RS422 485 networks but can be implemented using TCP over Ethernet as well MODBUS TCP Two different serial transmission modes for MODBUS are defined RTU mode for 8 bit binary transmissions and
193. u can build your own automated testing tools and create e time controlled test jobs e g sending a diagnostics command every 5 minutes and reporting an error if the device response is not OK repeated test cycles e g endurance testing for a motion control drive system automatic device configuration scripts e g resetting a RS232 device to factory defaults before delivery fault analysis tools for service and maintenance tasks e g running a set of diagnostics commands and performing automatic fault analysis protocol testers with automatic checksum calculations e g CRC Cyclic Redundancy Codes Docklight startup scripts e g automatically starting a COM port logging task at PC startup Docklight Scripting uses the VBScript engine allowing you to write your tests in a simple well known scripting language Docklight s basic functions and features are made available through a small and convenient set of Docklight script commands TIP For getting started have a look at the Docklight modem testing script which demonstrates the usage of Docklight script commands for an automated modem test A simple demonstration for the TCP IP capabilities can be found in the TCP client server sample 2 3 Typical Applications Docklight is the ideal tool to support your development and testing process for serial communication devices Docklight may be used to e Test the functionality or the protocol implementation of a serial device You
194. uence to the Send Sequence list Repeat steps 1 5 to define other commands needed to perform your test NOTE To distinguish a wildcard from a question mark ASCII character decimal code 63 the wildcard is shown on a different background color within the sequence editor C Sending a command to the serial device 1 Use the E Send button to open the serial communication port and send one command to the serial device Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Working with Docklight Advanced 2 The communication pauses and the Send Sequence Parameter dialog pops up allowing you to enter the parameter value In our example an exposure time e g 025 3 Confirm by pressing Enter The sequence is now sent to the serial device It is possible to define commands with several parameters using several wildcard areas within one sequence The Send Sequence Parameter dialog will then appear several times before sending out a sequence NOTE If you are using Wildcard you must provide exactly one character for each when sending the sequence For variable length parameters use Wildcard matches zero or one character NOTE You cannot use a Send Sequence with wildcards as an automatic answer for a Receive Sequence see Action NOTE If your Send Sequence requires a checksum you can define it as described in Calculating and Validating Checksums The checksum is ca
195. uences list i e add new sequences or delete existing ones Swap Send and Receive Sequence Lists Convert all Send Sequences into Receive Sequences and vice versa 8 Find Sequence in Communication Window Find a specific sequence within the data displayed in the communication window See the Find Sequence function Clear Communication Window Delete the contents of the communications window This applies to all four representations ASCII HEX Decimal Binary of the communication window Run Menu gt Start communication Open the communication ports and enable serial data transfer Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference E Stop communication Stop serial data transfer and close the communication ports Tools Menu A Start Communication Logging Create new log file s and start logging the incoming outgoing serial data See logging and analyzing a test Stop Communication Logging Stop logging and close the currently open log file s Start Snapshot Mode Wait for a trigger sequence and take a snapshot See Catching a specific sequence amp Stop Snapshot Mode Abort a snapshot and reenable the communication window display d Keyboard Console On Enable the keyboard console to send keyboard input directly Keyboard Console Off Disable the keyboard console Show Notepad Show the notepad window Project Settings Select the current project
196. umSpec Format for the full format specification 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 AddCommen DL AddComment Simple checksum Mod 256 for 123456789 DL AddComment CalcChecksum amp DL CalcChecksum MOD256 123456789 A ct ct ct
197. ur Script Samples directory 5 6 Checking for Sequences With Random Characters Receive Sequence Wildcards Bo ec gt cm p j zzzoao apzjiEsmm gt r_cr i_ _ 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 lt CR gt 07 30 2012 10 22 10 558 RX temperature 85F lt CR gt 07 30 2012 10 24 12 087 RX temperature 93F lt CR gt 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 tjelm plelrlaltjulrjlej Flr 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
198. ve three elements in the Receive Sequences list that would respond to the same command with three different answers During the test you may decide which answer should be sent by checking or unchecking the list elements using the Active column E Storing the project Before running the actual test it is recommended that the communication settings and sequences defined be stored This is done using the menu File gt El Save Project F Running the test Start Docklight by choosing Run gt Start Communication Docklight will now respond to all commands received from the connected serial device The on screen data transfer display allows you to monitor the communications flow All protocol information can be logged to a text file for further analysis See section Logging and analyzing a test TIP Using the notepad window F12 key menu Tools Show Notepad you can easily take additional notes or copy amp paste parts of the communication log for further documentation 5 3 Monitoring Serial Communications Between Two Devices Docklight Tap Device 2 Docklight PC Preconditions e A Docklight Monitoring Cable or a Docklight Tap is required to tap the RS232 TX signals of both serial devices and feed them into Docklight while not interfering with the communications between the devices For a Docklight Monitoring Cable setup two COM ports must be available on your PC for monitoring Each port will rece
199. where two different Receive Sequences are detected in one go and the DL OnReceive code is executed at a later point Docklight Scripting V2 1 User Manual 08 2015 Copyright 2015 Flachmann und Heggelbacher GbR Reference Scripting new receive data Receive Data Communications OnReceive Docklight Script Handler Window Queue Engine display sequence1 add to queue display sequence2 add to queue process OnReceive n call DL OnReceive for sequencel r timeline call DL OnReceive for sequence2 10 4 Filelnput FileOutput Objects for Reading and Writing Files r Docklight Scripting provides additional objects than can be used to read a file with text or binary data or create you own custom output file Object Name Open existing files for sequential input reading the file either character by character or line by line See Reading Files Create a new file or append data to an existing file Both binary data as well as text files can be created See Writing Files 10 4 1 Filelnput Reading Files The global FileInput object provides an easy interface to process existing files e g for transmitting them on the serial line using additional checksums and formatting Methods and properties available for FileInput Method Prope Filelnput OpenFile filePathName Opens an existing file for input rawData rawData False default
200. words can be used in the Edit Receive Sequence gt 3 Action gt Comment text box to create Docklight comment texts with dynamic data e g the actual data received Is Replaced By Time stamp for the data received Docklight channel no data direction 1 or 2 for the data received RX The channel name or channel alias that corresponds to the data direction _C E g RX TX or COMS Receive Sequence List Index see the Dialog Edit Receive Sequence Receive Sequence Name _A The actual data that triggered this Receive Sequence Use ASCII representation Same as 96 A but in HEX representation Same as 96 A but in Decimal representation Same as 96 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 ofthe sequence length 1 Use HEX representation Example For a Receive Sequence as described above t e m p le rja t u rje 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 Docklight Scripting V2 1 User Manual
201. x Function Displays a prompt in a dialog box waits for the user to input text or click a button and returns the contents of the text box TIP Use the Docklight specific DL InputBox2 method for a dialog box that always appears on the same screen as the Docklight Scripting main window Syntax InputBox prompt title default xpos ypos helpfile context prompt Required String expression displayed as the message in the dialog box The maximum length of prompt is approximately 1024 characters depending on the width of the characters used If prompt consists of more than one line you can separate the lines using a carriage return character Chr 13 a linefeed character Chr 10 or carriage return plus linefeed character combination Chr 13 amp Chr 10 between each line Optional String expression displayed in the title bar of the dialog box If you omit title the application name is placed in the title bar default Optional String expression displayed in the text box as the default response if no other input is provided If you omit default the text box is displayed empty Xpos Optional Numeric expression that specifies in twips the horizontal distance of the left edge of the dialog box from the left edge of the screen If xpos is omitted the dialog box is horizontally centered ypos Optional Numeric expression that specifies in twips the vertical distance of the upper edge of the dialog box from the t
202. ys a prompt in a dialog box waits for the user to input text or click a button and returns the contents of the text box This dialog will always appear on the same screen as the Docklight Scripting main window It does not support the rarely useful optional arguments xpos ypos helpfile and context of the VBScript InputBox method Return Value String Syntax result DL InputBox2 prompt title default Required String expression displayed as the message in the dialog box The maximum length of prompt is approximately 1024 characters depending on the width of the characters used If prompt consists of more than one line you can separate the lines using a carriage return character Chr 13 a linefeed character Chr 10 or carriage return plus linefeed character combination Chr 13 amp Chr 10 between each line Optional String expression displayed in the title bar of the dialog box If you omit title the application name is placed in the title bar Optional String expression displayed in the text box as the default response if no other input is provided If you omit default the text box is displayed empty Example DL InputBox2 Function MyInput DL InputBox2 Pleas nter text My Title Example Text DL AddComment MyInput print the user input 10 2 2 10 LoadProgramOptions Loads the Docklight program options from a file created using SaveProgramOptions Return Value Void Syntax DL LoadP

Download Pdf Manuals

Related Search

Related Contents

Carri & Eazi Chef Quick Guide.Nov 2011.p.indd  Pumps activprime AP6 AP8 rev 0 manual  Painel de Integração AM-PI01 MANUAL DE INSTALAÇÃO  IstruzIonI per l`uso  Structuring Documentation in Any Way Using Reference Packages    SB-2-246-H JGHV-531 HIGH VOLUME LOW  Profibus_Manual_DIS  Extron electronic 4C User's Manual  manuel d`utilisation kit de table large 4730300 à  

Copyright © All rights reserved. Failed to retrieve file