TD-CALTERM2-001 CalTerm2 User s Guide

Transcription

1 Technical Document TD-CALTERM2-001 CalTerm2 User s Guide DAQ Electronics Division 262-B Old New Brunswick Road, Piscataway, NJ DAQ Electronics, Inc. All rights reserved. This literature is for guidance only. It does not constitute recommendations, representation, or advice, nor is it part of any contract. Our policy is one of continuous product improvement, and the right is reserved to modify the specifications contained herein without notice. All trademarks and names mentioned in this document are duly acknowledged. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 1 TD-CALTERM2-001 CalTerm2 User s Guide

2 1. OVERVIEW CalTerm2 is a serial communications program for personal computers running Microsoft Windows. It is similar to the HyperTerminal Windows utility but with enhancements to make working with DAQ instruments easier. These enhancements include sending a sequence of commands to the instrument as specified in a script file, sending a single command once or repetitively, and logging data from the instrument into a text file. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 2 TD-CALTERM2-001 CalTerm2 User s Guide

3 2. USING CALTERM2 AS A TERMINAL When you first start CalTerm2, you will see a display as in Figure 1. The window will display characters as they are received from the serial port, and optionally, characters you enter from the keyboard. Like all Windows applications, this window will accept your keyboard input only after you activate it by clicking the mouse somewhere within its boundary, after which you will see a blinking caret in the last row of the window. Figure 1. CalTerm THE STATUS BAR The status bar below the terminal window displays the status of CalTerm2 and the serial port connection. From right to left, the status panels show: 1) the serial port connection status; 2) whether or not serial port input data is being saved to a log file; 3) whether or not keyboard input is echoed to the terminal window; 4) a hexadecimal representation of the last byte sent to the serial port; and 5) general status information, including commands sent from the command file or script CONFIGURING THE TERMINAL The terminal characteristics of CalTerm2 are configured by selecting Terminal from the main menu then Configure Terminal from the drop down menu. The dialog shown in Figure 2 will then appear. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 3 TD-CALTERM2-001 CalTerm2 User s Guide

4 Figure 2. The Terminal Configuration dialog used to configure CalTerm2. The Appearance section controls the number of lines of text that will be displayed in the terminal window, the number of characters per line, and the size, color and font used to display the characters. Usually, the default values are fine. You may wish to change the Appearance if the instrument you are communicating with does not echo back characters you send to it. In that case, when you enter characters via the keyboard, you will not see the characters in the terminal window unless you place a check in the box labeled Echo Keyboard Input. Also, if the instrument you are communicating with sends ANSI cursor control sequences (ANSI escape sequences) you may wish to check the ANSI Emulation box. The Log File section allows you to select the text file to which incoming serial port data can be saved as it arrives. This can be an existing file or a new file. If you select an existing file, a warning will be issued when you close the Terminal Configuration dialog and you will be given the choice of appending new data to the existing file or deleting the file s contents and starting afresh. Note that only incoming data is saved to the file, not outgoing commands. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 4 TD-CALTERM2-001 CalTerm2 User s Guide

5 Large log files can be generated if your instrument sends large data sets, or you log for an extended time period. The Use Sequential Log Files option allows you to limit the size of the log file to the size specified in the Log File Size entry. Once the specified size is reached, the log file is closed and a new log file is started. The old log file and new log file share a common base name (e.g., MyLogFile) but with a sequence number suffix (e.g., MyLogFile_1 and MyLogFile_2). CalTerm2 keeps only the number of log files you specify in Number of Log Files To Keep and will automatically delete the oldest log file when a new log file is created once the specified number of log files is reached (e.g., if you specify Number of Log Files To Keep as 4, then MyLogFile_1 will be deleted when MyLogFile_4 is closed and MyLogFile_5 is opened so you will then have MyLogFile_2, MyLogFile_3, MyLogFile_4, and MyLogFile_5 on your disk). Log files can also be used to record unprintable characters (binary data) in hexadecimal format. Simply check the Hexadecimal Output to save the log file as hexadecimal characters. The Scripting and Command Looping section controls the time interval between commands issued in a loop or script, and how each command is terminated. Take care to avoid reducing the time interval so much that the serial port is swamped by commands. The point that this is reached depends upon the number of characters in the command, and the connection speed of the serial port. The possible command terminations are: a carriage return followed by a line feed, a line feed followed by a carriage return, just a carriage return, or just a line feed. You would normally not change this from the default. Scripts can often be made more readable by inserting comments in the script that are not sent to the instrument. Comments are indicated by starting the script line with a special character, the Comment Prefix Character. The default Comment Prefix Character is the forward slash /, (i.e., any line beginning with / is considered a comment) but you may change this if the forward slash is used to prefix legitimate commands you may wish to send to the instrument MAKING A CONNECTION The serial port must be configured and opened for use by CalTerm2. To configure the port, select Terminal from the main menu then Configure Comm Port from the drop down menu. The dialog shown in Figure 3 will then appear. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 5 TD-CALTERM2-001 CalTerm2 User s Guide

6 Figure 3. The Serial Port Configuration dialog. The Port Number entry box contains a drop down list of all serial ports available on your computer, and you should select the one that is connected to the instrument. In rare cases, the serial port you are using will not appear in this list, and you should type its name in the entry box. If you enter a nonexistent port, or a port that is already being used by another program (e.g., HyperTerminal), you will receive an error message when you press OK or Apply. Note that only one program can connect to a serial port at any time, so if another program is using the port, you must exit that program before using CalTerm2. Next select the Bits per second (i.e., Baud rate), Data bits per word, Parity, Stop bits, and Flow control mechanism. If you wish to apply this configuration and connect to this serial port automatically whenever you start CalTerm2, check the box Reconnect At Startup. The OK and Apply buttons cause CalTerm2 to attempt to configure and connect to the serial port. If you are unsure of the configuration parameters, you may wish to repetitively try different parameters using Apply, and when satisfied, press OK to close the dialog. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 6 TD-CALTERM2-001 CalTerm2 User s Guide

7 3. WORKING WITH INSTRUMENT-SPECIFIC COMMAND FILES An instrument-specific commands file is a text file that contains commands that are recognized by a particular instrument. DAQ may provide the file for a particular instrument upon request, or you can create your own with any text editor. The file contains two types of entries: generic commands and specific commands. A generic command is a command without accompanying parameters, while a specific command is a command and its parameters. For example, say an instrument returns status information for a measurement point when issued the command Status nn where nn is the point number. The generic command is Status and specific commands would be Status 1 and Status 23. These would be represented in a commands file as the three lines: [Status] Status 1 Status 23 Note the brackets used to distinguish the generic command, and that each command is on a separate line. Any number of such generic and specific commands can be placed in a commands file. If you omit the first generic command (i.e., if the first line in the file is not enclosed in brackets), CalTerm2 will behave as if you had started the file with the line [Commands] (i.e., as if you had started the file with the generic command Command ). To use a commands file, you must first open it by selecting File from the main menu then selecting Open Commands Files from the drop down menu. The commands file contents will then appear in the left panel of CalTerm2 as a tree as shown in Figure 4. The top node is the file name without any suffix, the second level nodes are the generic commands, and the lowest level nodes are the specific commands. This representation of the file contents as a tree is the reason for distinguishing between generic and specific commands, and allows you to group commands for your convenience. While I have presented the tree as organized with generic commands without parameters followed by the same commands with parameters, you may find some other organization better for you. Just place in brackets in the file whatever text you want as the second level nodes, and follow each second level node with the text you want as subordinate nodes. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 7 TD-CALTERM2-001 CalTerm2 User s Guide

8 Figure 4. The commands file displayed as a tree on the left. Once you have opened a commands file in CalTerm2, you can send any specific command to the instrument once by left double clicking the command or send it repetitively by left clicking the command then pressing the Loop tool bar button. Looping of commands can be terminated by pressing the Loop tool bar button again, or by pressing the escape key or ESC tool bar button. You can also right click any specific command to pop up a menu that offers you options to edit or send the command. If you right click any generic (second level node), you will be offered only the ability to insert a specific command following the generic command. Keep this difference between generic and specific commands in mind when creating your commands file: specific commands can be sent to the instrument, generic commands cannot. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 8 TD-CALTERM2-001 CalTerm2 User s Guide

9 4. WORKING WITH SCRIPTS Script files are similar to commands files in that they are text files of commands that a particular instrument understands. Script files differ in that each line contains one complete specific command (including any parameters), and that these commands will be sent in the exact order given in the file. When you press the Run All tool bar button, each line of the file will be sent to the instrument, one after the other, with a delay between commands as configured in the terminal configuration dialog (see Configuring the Terminal above). To run the script repeatedly, press the Run Loop tool bar button, which causes the commands in the script to be sent repetitively until you press Run Loop again, the escape key or the ESC tool bar button. Script files are opened by selecting File from the main menu then Open Script from the drop down menu. The script file contents will then be displayed in a panel at the right of CalTerm2 (see Figure 5). Notice in the figure that script files are in a tabbed display, so you can have multiple script files opened at one time. Like the specific commands in the commands file, you can right click on any command in the script file and you will be presented with a popup menu that includes options to edit the command. Figure 5. The Script file displayed on the right. Script files have two additional editing options. The order of commands can be changed by simply moving the mouse pointer over a command, pressing the left mouse button, and, while keeping the left mouse button depressed, dragging the command to the desired location in the file and releasing the mouse button. Similarly, you can add a command to the script by dragging any specific command from the commands file tree over to the desired location in the script file. Consecutive commands in the script file can be selected in a group by left clicking on one command and then holding down the shift key while left clicking on another command. The two commands you clicked on and all commands in between will be selected, and can then be sent as a sequence to the instrument by pressing the Run Part tool bar button. You can also use this button to send a single selected command if you wish, but it is simpler to just double click the command and it will be sent to the instrument. As mentioned under Configuring the Terminal, scripts can include comment lines that start with a special comment prefix (the default prefix is the forward slash / ) and are not sent to the instrument. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 9 TD-CALTERM2-001 CalTerm2 User s Guide

10 Two comment lines are special in that they are interpreted as commands to CalTerm2: the Delay command, and the LogNote command. That is, when CalTerm2 see a comment line of the form 1) / Delay=xxxx 2) / LogNote xxxxx it takes special actions. For / Delay, the value following the equals symbol is interpreted as an additional delay in milliseconds that CalTerm2 should wait before sending the next command in the script. For example, if a script contained the lines: Status 1 / Delay=1000 Status 2 then CalTerm2 will send the Status 1 command, wait 1000 milliseconds, then send the Status 2 command. The /LogNote command is simply a way to insert the comment into the log file. The lines Status 1 / LogNote Asking for Status 2 Status 2 would result in CalTerm2 sending the Status 1 command, placing any response in the log file, then placing the entire comment /LogNote Asking for Status 2 in the log file, and then sending the Status 2 command. Log notes are handy to document both the script and the results in the log file. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 10 TD-CALTERM2-001 CalTerm2 User s Guide

11 5. HOTKEYS CalTerm2 responds to the following hot keys: 1) Escape (or equivalently the tool bar ESC button). Terminates sending a command repetitively (looping) or the execution of a complete or partial script. The escape character is also sent to the instrument if the terminal window has the keyboard focus (clicking in the terminal window gives it the keyboard focus and displays a blinking caret). 2) Control r. Causes the most recent command entered from the keyboard to be sent again to the instrument. Version 1.00 Dated: 10/30/2006 Author: Mark Doyle Page 11 TD-CALTERM2-001 CalTerm2 User s Guide