Contents
Overview ↑
CoolTerm is an easy-to-use terminal for communication with hardware connected to serial ports.
CoolTerm is a simple serial port terminal application (no terminal emulation) that is geared towards hobbyists and professionals with a need to exchange data with hardware connected to serial ports such as servo controllers, robotic kits, GPS receivers, microcontrollers, etc.
The features of CoolTerm include:
- Capability of multiple concurrent connections if multiple serial ports are available.
- Display of received data in plain text or hexadecimal format.
- Sending data via keypresses as well as a Send String dialog that supports data entry in plain text or hexadecimal format.
- Sending data via copy-paste of text into the terminal window.
- Sending of text files.
- Capability of capturing received data to text or binary files.
- Display of received data as graphic chart.
- Local echo of transmitted data.
- Local echo of received data (loop-back to sender).
- Hardware (CTS, DTR) and software flow control (XON).
- Optical line status indicators.
- Capability of manually toggling line states of certain handshaking signals when hardware flow control is disabled.
- Configurable character and line delays.
- Support for transmit macros.
- Capability of saving and retrieving connection options.
- and more...
Quick Start ↑
- Use the Connection Options dialog to configure your serial port.
- Click Connect to open the serial port and use the keyboard to type the characters to be sent.
- Received data will be displayed in the terminal window. Use View Hex to view the data in the terminal window in hexadecimal format.
- Use Connection > Send String... to send strings of text. This dialog allows data to be entered as plain text or in hexadecimal format for special characters.
- Use Connection > Send Text/Binary File... to send entire text or binary files.
- Received data can be recorded to a file using Connection > Capture to Text/Binary File.
- Line states are indicated via the indicator icons in the lower right corner of the terminal window.
- Line states that can be toggled manually are indicated by a bold font type. Click the indicator to toggle the line state of such a signal.
Connection options can be saved and retrieved via the File > Save and File > Open menu items.
To open a new Terminal, use File > New.
Plain Text, Hexadecimal, and Chart Display Mode ↑
The display mode of the terminal window can be switched via the View menu or the corresponding toolbar buttons.
Plain Text is the most common display mode for a serial terminal. In this mode, received data is displayed in plain text as it is received. Certain Special Character Handling settings in the Terminal Options can be used to adjust the behavior of the display in this mode.
Hex mode is particularly useful when characters are received that can not be displayed in Plain Text, such as e.g. when the received data in binary in nature rather than human-readable text. The view offers a side-by-side view of the data in hexadecimal format as well as in plain text format.
Chart mode is useful for data logging use cases when the received data is formatted properly. Refer to the Data Plotting in Chart Mode section below for more details.
Characters to be sent can be typed via the keyboard, independent of the current display mode.
Copy and Paste
- Clipboard contents can be pasted into the terminal window regardless of the viewer mode. Pasted text will be transmitted immediately.
- Data that is selected and copied in Plain Text view mode will be copied to the clipboard in plain text format.
- Data that is selected and copied in Hex view mode will be copied to the clipboard in hexadecimal format. E.g. if the text Hello World is selected and copied in Hex view mode, CoolTerm will copy it to the clipboard as 48 65 6C 6C 6F 20 57 6F 72 6C 64.
- If the clipboard contains data in hexadecimal format, CoolTerm will paste the clipboard data as binary data in Hex view mode and as hexadecimal data in all other view modes. E.g. if the clipboard contains 48 65 6C 6C 6F 20 57 6F 72 6C 64, CoolTerm will paste it as Hello World in Hex view mode but it will paste it as 48 65 6C 6C 6F 20 57 6F 72 6C 64 in all other view modes.
Status LEDs ↑
The status LEDs display the line states of various serial port signals. A green lit LED indicates the active state of a signal. An unlit green LED indicates that the signal is inactive. A red TX LED indicates that transmit flow is halted due to hardware or software flow control being active. A red RX LED indicates that a receive signal error, such as a BREAK condition or a framing error, has occurred.
Handshake status LEDs with bold label (i.e. RTS and DTR) can be clicked to manually toggle the state of the signal. The TX LED can be clicked to manually assert/de-assert a serial BREAK signal.
CoolTerm Menus ↑
File
- New — Open a new terminal window.
- Open... — Load connection settings.
- Open Recent — Load recent connection settings.
- Close — Close the terminal window.
- Save... — Save the current connection settings.
- Save As... — Save the current connection settings using the file save dialog.
- Save As Default — Save the current connection settings as default.
- Show File Location — Reveals the location of the current settings file.
- Print... — Print the current window contents. Supports plain text, hex viewer, as well as chart display modes.
- Page Setup... — Open the page setup dialog
- Preferences... — Open the preferences dialog.
- Quit — Quit CoolTerm.
Connection
- Connect/Disconnect — Open/Close the serial port.
- Options... — Open the connection settings window.
- Reset Port — Reset the serial port. Unlock the port if XOFF is active.
- Send Break — Send a short break signal.
- Flush Serial Port — Flush the serial port transmit buffer.
- Toggle RTS — Toggles the state of the RTS signal.
- Toggle DTR — Toggles the state of the DTR signal.
- Toggle Break State — Toggles the state of the break signal.
- Send String... — Open a Send String window.
- Send Text/Binary File... — Select a file to send via a file open dialog.
- Capture to Text/Binary File — Start/Stop/Pause/Resume capture of received data to a file.
Macros
- Manage Macros... — Create and manage your transmit macros here. Macros created will appear under this menu.
View
- View Plain/Hex/Chart Switch to plain text, hex, or chart view.
- Zoom Chart — Various submenus to zoom the chart view.
- Wrap Text — Enable/Disable wrapping of text at the right hand edge of the window.
- Add Timestamps — Enable/Disable the addition of timestamps to received data.
- Pause Display — Pauses/Unpauses the terminal display.
- Clear Data — Clear the CoolTerm receive data buffer.
Preferences ↑
Misc. Settings ↑
Misc. Settings
Restore previous sessions
If checked, CoolTerm will try to restore the all open terminal windows from the previous session at startup.
Assign Macros to F-Keys
If enabled, function keys will automatically be assigned to any defined macros. If disabled, numeric keyboard shortcuts will be assigned.
Use web browser to display help
If enabled, the system's default web browser will be used to display the help topics. Otherwise, a built in help viewer will be used.
Use Home/End/PgUp/PgDown to scroll
If checked, pressing the Home, End, Page Up, or Page Down keys will scroll the window contents. If unchecked, CoolTerm will send the respective keystrokes via the serial port.
Smart Display Pausing (macOS and Windows only)
If enabled, the terminal display can be paused simply by scrolling up. Scrolling back to the bottom unpauses the display.
Disable Menu Shortcuts (Windows and Linux only)
Disables the menu short cuts in order to be able to send CTRL characters via the terminal.
Avoid Plain Text Flicker (Linux only)
If checked, avoids flicker in Plain Text View Mode on certain Linux platforms (such as e.g. Raspberry Pi) by only appending new data to the text display rather than refreshing the text display with the entrire receive buffer contents.
NOTE: This may cause certain Special Character Handling options (such as e.g. handing BS or DEL characters and filtering/handling of ANSI escape sequences, etc) to not function properly.
Connection Options Settings
Refresh Serial Ports when opening Options
When enabled, the list of serial ports is refreshed automatically when the Connection Options are opened.
Skip save Prompt for unchanged Settings
If checked, CoolTerm will not ask whether or not to save unchanged settings when closing terminal windows.
Save Settings as Default > Include Port Selection
If checked, the port selection will be saved in the default settings, and new terminal windows will select the same port.
Note that it is recommend to disable this setting unless the selected serial port is always available.
Save Settings as Default > Include Window Position and SizeIf checked, the window position and size will be saved in the default settings, and new terminal windows will open in the same location with the same size.
If unchecked, the OS will place new windows according to its default behavior.
Timestamp Format
SQL Date/Time: If selected, timestamps use the YYYY-MM-DD HH:MM:SS formats for date and time.
Local System Format, long: If selected, timestamps use the format as determined by the user's local system settings. Includes time zone information.
Local System Format, short: If selected, timestamps use the format as determined by the user's local system settings. No time zone information.
NOTE: For best compatibility of timestamps with 3rd party applications such as Microsoft Excel, SQL format should be used to timestamp received data.
Scripting ↑
Remote Control and Scripting
CoolTerm can be scripted and controlled via its Remote Control Socket, by means of a web browser connected to CoolTerms HTTP Server, or via AppleScript on macOS systems. Refer to CoolTerm Scripting for more information.
Enable Remote Control Socket
If enabled, CoolTerm listens for commands (compliant with the CoolTerm Remote Control Socket Protocol) on the specified port.
Enable HTTP Server
If enabled, CoolTerm will run a HTTP server at the specified port. A web browser can be directed to the local IP at the specified port to access and execute many of CoolTerm's functions.
Enable AppleScript (macOS only)
If enabled, CoolTerm will listen to Applescript Events.
Updates ↑
Check for Updates
Include development releases
If checked, development releases will be included when checking for available updates.
Check for updates at startup
If checked, CoolTerm will check for updates when the applications starts.
Proxy Settings
If required for the local network, necessary proxy settings to allow CoolTerm to check for updates can be configured here.
Connection Options ↑
Connection options can be saved and retrieved via the File > Save and File > Open menu items.
It is possible to define the default connection options that are applied each time a new terminal window is opened. To create customized default connection options, use File > Save As Default. These settings will be applied as default to new terminal windows.
Alternatively, a connection settings file named default.stc file can also be placed inside the same directory in which the CoolTerm executable resides. If a default.stc file exists in the CoolTerm application directory, it will take precedence over the regular default settings. This is useful when CoolTerm is used as a portable application that resides on a USB thumb drive or other removable storage, and it is desired that CoolTerm defaults to specific connection settings.
To modify the Connection Options, click the Options button in the toolbar or use the Connection > Options... menu to open the Connection Options Window. The options are divided into the following categories:
Serial Port ↑
Serial port specific options can be adjusted here. The port cannot be changed while the connection is open. Close the connection first to change the port. All other settings can be changed while the connection is open.
Serial Port Options
Select the serial Port from the popup menu and configure its settings according to the requirements (Baudrate, Data Bits, Parity, Stop Bits) of the connected hardware.
If the serial port to be used is not listed in the popup menu (e.g. in case it is a USB to Serial port adapter that was connected after CoolTerm was started) push the Re-Scan Serial Ports button. Should the serial port still not be available for selection, ensure that the proper drivers for the serial port are installed.
Additional information (such as driver names and rated speeds) about the selected port can be displayed by clicking the bevel button to the right side of the Port popup menu.
TCP Connection
This item in the Port popup menu allows the creation of a raw TCP connection to a remote TCP server. When prompted, enter the remote IP Address and Port at which the server is accepting connections.
When a TCP connection is selected, serial port specific settings are ignored.
Software Supported Flow Control
If enabled, CoolTerm actively halts data transmission of data (by buffering transmit data locally instead of passing it on to the serial port transmit buffer) when flow control conditions are detected (such as CTS being off or XOFF being active). This is the recommended setting for most use cases.
To let the serial port driver handle flow control instead, disable this option. This is the recommended setting for use cases where flow control timing is critical.
Block Keystrokes while flow is halted
If enabled, keystrokes are blocked while transmit data flow is halted due to a flow control condition, and a system beep is played instead to alert the user that keypresses are not currently being transmitted.
Disable this option to allow keystrokes while data flow is halted. Keystrokes will be buffered in the transmit data buffer and sent to the serial port once data flow resumes.
Initial Line States when Port opens
This can be used to set the initial state of the RTS and DTR status lines when the respective hardware flow control options are not enabled.
Terminal ↑
Options related to terminal behavior are adjusted here. These options are accessible regardless of the connection state of the serial port.
Terminal Options
Terminal Mode
Sets the operating mode of the terminal. In Raw Mode every key is sent via the serial port immediately as it is pressed. When in Line Mode, a command line field is visible in the terminal window. Characters typed in this field are added to a send buffer. The contents of the send buffer (i.e. one line of text) are sent when the enter key is pressed.
Line Mode supports history. i.e. the up and down arrow keys can be used to send previously typed lines. Alternatively, the square button to the right of the command line field can be pressed to show a history of previously sent lines. Select any line to add it to the send buffer.
Save History, if checked, saves the history of commands entered in Line Mode as part of the connections settings. Loading such settings will restore the history.
Enter Key Emulation
Defines what character(s) to send when the Enter key is pressed. When in Line Mode, the contents of the send buffer are terminated with the character(s) selected here before they are sent. Select Custom to enter a custom emulation string below. The emulation string must be entered as sequence of hex byte values.
Note that this setting also applies to data being sent via Send String windows.
Local Echo
If checked, locally entered data will be echoed in the terminal window.
Replace TAB key with spaces
If checked, TAB key presses are replaced with the number of spaces specified in the field below. Default is 4, with a maximum of 32.
Emulate Special Keys
If checked, certain keypresses are replaced with the corresponding ANSI escape sequences before sending. If unchecked, the raw ASCII codes will be sent for these keys. The emulated keys are as follows:
Key | Raw ASCII | Emulation |
UP Arrow | 0x1E | ESC[A |
DOWN Arrow | 0x1F | ESC[B |
RIGHT Arrow | 0x1D | ESC[C |
LEFT Arrow | 0x1C | ESC[D |
HOME | 0x01 | ESC[H |
END | 0x04 | ESC[F |
These emulations are useful when communicating with MCUs running MicroPython or similar in REPL mode.
Data Handling ↑
Settings in this sections are applied to received data.
Special Character Handling
Format TAB separated text
If enabled, text will be aligned on a specified column width in plain text view by replacing received TAB characters with spaces. The column width can be specified in the field below.
Replace Consecutive Spaces with TAB
If checked, consecutive space characters will be replaced by single TAB characters. The minimum number of consecutive spaces required for replacement can be specified below.
Filter ANSI Escape Sequences (Plain Text View)
If checked, ANSI Escape Sequences will be removed from the received data in Plain Text View mode.
Clear Display on FF (Form Feed)
If checked, the reception of a Form-Feed (FF, ASCII code 0x0C) character will clear previously received characters from the receive buffer and thus clear the screen.
Clear Display on ESC[2J (ESC CLEAR)
If checked, the reception of an ESC[2J sequence will clear previously received characters from the receive buffer and thus clear the screen.
The Filter ANSI Escape Sequences will not remove any ESC[2J sequences if this setting is enabled.
Update Display on EOT (End of Transmission)
Enabling this feature will prevent the display from updating until an End-Of-Transmission (EOT, ASCII code 0x04) character is received, at which time the display is updated with the contents from the receive buffer.
Note that EOT should not immediately be followed with more data but rather include a short delay before doing so to ensure EOT is not received by CoolTerm at the same time as subsequent data.
If Local Echo is enabled while this feature is enabled as well, locally echoed characters will cause the display to refresh immediately.
Update Display on ESC[;F (ESC END)
Enabling this feature will prevent the display from updating until an ESC[;F sequence is received, at which time the display is updated with the contents from the receive buffer.
Note that ESC[;F should not immediately be followed with more data but rather include a short delay before doing so to ensure ESC[;F is not received by CoolTerm at the same time as subsequent data.
If Local Echo is enabled while this feature is enabled as well, locally echoed characters will cause the display to refresh immediately.
The Filter ANSI Escape Sequences will not remove any ESC[;F sequences if this setting is enabled.
Home Display on ETX (End Of Text)
Enabling this feature will home the display (i.e. scrolling it to the very top) when an End-Of-Text (ETX, ASCII code 0x03) character is received.
Note that homing the display will not move the insertion point for new data to the top of the display. New received data will be appended at the bottom of the display.
Note that ETX should not immediately be followed with more data but rather include a short delay before doing so to ensure ETX is not received by CoolTerm at the same time as subsequent data.
Home Display on ESC[;H (ESC HOME)
Enabling this feature will home the display (scrolling it to the very top) when an ESC[;H sequence is received.
Note that homing the display will not move the insertion point for new data to the top of the display. New received data will be appended at the bottom of the display.
Note that ESC[;F should not immediately be followed with more data but rather include a short delay before doing so to ensure ESC[;F is not received by CoolTerm at the same time as subsequent data.
The Filter ANSI Escape Sequences will not remove any ESC[;H sequences if this setting is enabled.
Convert ESC[#D to Backspaces
If checked, received ESC[#D escape sequences will be converted the corresponding number (#) of Backspace (BS, ASCII code 0x08) characters. It is recommended to also enable Handle BS and DEL Characters if this option is enabled.
The Filter ANSI Escape Sequences will not remove any ESC[#D sequences if this setting is enabled.
Handle BS and DEL Characters
If checked, Backspace (BS, ASCII code 0x08) and Delete (DEL, ASCII code 0x7F) characters will be visually handled in Plain Text View mode. When either character is received (or typed with local echo enabled) the previous character in the Plain Text viewer is deleted.
Convert Non-printable Characters (Plain Text View)
If checked, non-printable characters (ASCII codes 0x00 to 0x1f) will be displayed as a period character in Plain Text View mode.
Handle Bell Character
If checked, received bell characters (BEL, ASCII code 0x07) will play a terminal beep.
Ignore Line Feed Character
Enabling this feature will ignore received Line-Feed (LF, ASCII code 0x0A) characters and will prevent CoolTerm from interpreting rogue LF characters as new line characters.
Combine contiguous Carriage Returns
Enabling this feature will combine contiguous received Carriage-Return (CR, ASCII code 0x0D) characters into a single CR and prevent CoolTerm from displaying multiple new line characters.
Handle CR as real Carriage Return
Instead of interpreting CR as a new line character, CoolTerm will instead move the insertion point to be beginning of the current line and overwrite the existing line with newly received characters.
NOTE: Ignore Line Feed Characters should be disabled if this option is enabled
Text Encoding
Sets the text encoding used to render the text in the plain text display.
Receive ↑
Settings with regard to received data can be adjusted here. These options are accessible regardless of the connection state of the serial port.
Receive Options
Loop back received data
If checked, all received data will be echoed back to the sender. This is a useful feature e.g. when working with hardware that has a built-in selftest which requires a loopback adapter. CoolTerm can act as such a loopback adapter and it allows for the data to be observed in the terminal window.
Ignore receive signal framing errors
If un-checked, CoolTerm will notify the users of signal framing errors (e.g. an attached device toggles a line state unexpectedly) and close the serial port. If checked, such errors will be ignored and the serial port will remain open.
Ignore break conditions
If un-checked, CoolTerm will notify the users of break conditions and close the serial port. If checked, break conditions will be ignored and the serial port will remain open.
Receive Buffer Size
The receive buffer, i.e. the amount of data being retained by the terminal window at any given time, is limited to the number of characters specified by this value. To avoid slow performance as the receive buffer fills up, this number should be kept small. The receive buffer size is limited to 2,147,483,647 (2GB) Bytes or less on systems with less available memory.
For use cases where CoolTerm is operated on a battery powered computer, it is also recommended to keep the receive buffer as small as possible in order to reduce strain on the CPU.
Add timestamps to received data
If checked, received data displayed in the terminal window will be prepended with a timestamp. This occurs each time new data is available.
Type
This specifies the timestamp type. The following types are available:
- Date and Time — The current date and time. The format is per the CoolTerm Preferences setting.
- Time — The current time only. The format is per the CoolTerm Preferences setting.
- Time + Milliseconds — The current time with millisecond resolution. The format is as follows: HH:MM:SS.sss, where sss denotes milliseconds.
NOTE: Adding timestamps with millisecond resolution will result in a higher display refresh rate to ensure the best possible timestamp accuracy if data is received at a high rate.
Wait for line ending
If checked, and if timestamps are enabled, CoolTerm will wait for a line ending (CR, LF, CR+LF) before before adding a new timestamp and captured to the recived data. CoolTerm will replace the received line endings and terminate each timestamped line with a line ending that is appropriate for the user's platform to ensure the data is displayed properly.
NOTE: This emulates the timestamp feature of the Arduino Serial Monitor.
File Capture ↑
Capture File Options
Capture Format
This selection determines how received data is stored in the capture file.
- Raw data — Raw data capture is suitable when a true representation of the received data is to be captured. Every received byte will be captured to file as it was received.
- Hexadecimal — Capturing data Hex format provides a way of recording binary data in a more human readable form.
- Plain text — Received data is processed using the Special Character Handling options before capturing to file.
Format Hexadecimal Data
If checked, data captured in hexadecimal format will be formatted such that a line break is inserted after every 16 bytes. If unchecked, data captured in hexadecimal will simply be written to the capture file without the insertion of any line breaks. Note that time stamps will force a line break regardless of this setting.
Add timestamps to captured data
This option is suited for data logging applications. If checked, received data will be prepended with a timestamp before being captured to the capture file. This occurs each time new data is available. Timestamps will only be added to captured data.
Type
This specifies the timestamp type. The following types are available:
- Date and Time — The current date and time. The format is per the CoolTerm preferences setting.
- Time — The current time only. The format is per the CoolTerm preferences setting.
- Time + Milliseconds — The current time with millisecond resolution. The format is as follows: HH:MM:SS.sss, where sss denotes milliseconds.
NOTE: Capturing timestamps with millisecond resolution will result in a higher display refresh rate to ensure the best possible timestamp accuracy if data is received at a high rate.
Wait for termination string
If enabled, CoolTerm will inspect received data for the specified termination string and only capture the data to file when such a string is received. This is useful for datalogging equipment that terminate their data with specific characters such as CR+LF. Enabling this option will capture one line of data each time the termination string is received. This can be especially useful when timestamps are enabled. Note that this option has no effect when capturing in hex format and formatting of hex data is enabled.
Retain Termination String
If enabled, the received termination string will be captured to the capture file, otherwise it will be omitted.
Termination String
This specifies the termination string CoolTerm expects to receive before capturing data to file, if Wait for termination string is enabled. The termination string must be entered as sequence of hex byte values.
Capture Transmit Data
If enabled, the transmitted data will be captured in addition the received data.
Add RX/TX Labels
If enabled, received data will be labeled with a Received label in the capture file. If Capture Transmit Data is enabled, sent data will be labeled with Sent label.
Leave File open while capturing
If checked (default), CoolTerm will maintain a lock on the capture file by leaving it open as long as capturing is in progress.
If unchecked, the file will be closed each time after writing to it, and reopened when new data arrives. This allows other applications to read the contents of the capture file while capturing is in progress. This can be useful in automated environments where received data needs to be available to other applications.
NOTE: This option should be used with caution. The capture file should only be opened as read-only by other applications so that CoolTerm can write new data to it. Writing to this file from other applications can cause CoolTerm to fail writing to the capture file and consequently abort file capture.
Autostart on open
If enabled, capturing to text file is started automatically after the connection settings are loaded. The path to where the data is stored can be set via the Capture File Location field below.
NOTE: Any changes to Auto Capture settings won't take effect until the settings are reloaded.
Append to auto capture file
If disabled (default), a new auto capture file is created each time auto capture is started (i.e. each time the connection settings are loaded). A new auto capture file name will be time stamped with the time at which the file was created.
If this option is enabled and a capture file already exists, CoolTerm will append new data to the existing file.
If this option is enabled and a capture file does not already exist, CoolTerm will create one in the specified location.
NOTE: This option should not be enabled for connection settings that are saved as default.
Auto Capture File Name
Specifies a custom file name auto capture files when Append to auto capture file is enabled. Leave this field blank to let CoolTerm choose the default auto capture file name.
When Append to auto capture file is disabled, CoolTerm will choose the Auto Capture File Name automatically.
NOTE: Any changes to Auto Capture settings won't take effect until the settings are reloaded.
Transmit ↑
Settings with regard to transmission of data can be adjusted here. These options are accessible regardless of the connection state of the serial port.
Transmit Options
Use transmit character delay
Checking this option enables a character delay specified by the value (in milliseconds) in the Delay text field below. This option guarantees a minimum time between characters to support targets with limited or no receive buffering in order to avoid data loss during transmission. This option is also recommended for targets that employ CTS flow control. At least 3ms delay between characters should be allowed for software and hardware latency on the PC side to shut off data flow when using a CTS command. The maximum character delay that can be specified is 10,000ms.
Use transmit line delay
Checking this option enables a delay specified by the value (in milliseconds) in the Delay text field below. This option guarantees a minimum time after any (or all) characters which are specified in the Delay characters text field below. The default is the Line Feed character (ASCII 10, or 0A hex). This supports targets that execute commands upon receipt of such a character and won't be able to process new data for a certain amount of time. The maximum line delay that can be specified is 10,000ms.
Match all delay characters
If checked, only occurrences of all specified delay characters (i.e. the string formed by the delay characters) will trigger a line delay. If unchecked, the occurrence of any of the specified delay characters will trigger a line delay.
Use packet delay
If checked guarantees a minimum delay (specified in milliseconds in the Delay text field below) after the transmission of each packet. The packet size can be specified under Transmit Packet Size below.
Transmit Packet Size
Determines how many bytes maximum are passed to the serial transmit buffer at any time. Large amounts of data, such as when text files are being sent, are divided in to packets of the specified value before being passed to the transmit buffer. This value also determines when CoolTerm displays a transmit progress window, which occurs when the number of bytes being sent exceeds the Transmit Packet Size.
The maximum value that can be specified is 1,048,576 (1 MB).
Wait for remote echo
If checked, CoolTerm will transmit data one byte at a time and wait for the connected device to return an echo of the transmitted byte before transmitting the next one. Use the Remote echo timeout setting to determine how long CoolTerm should wait before a timeout occurs and the next byte is sent.
This option is useful for devices that can only handle one byte at a time and confirm reception by sending back an echo of the received byte.
Remote echo timeout
Specifies the maximum amount of time (in milliseconds) to wait for a remote echo before transmitting the next character. Set this value to 0 to wait indefinitely.
Send String Options
Terminate 'Send String' Data
Enables automatic termination of strings sent via Send String windows with a configurable Termination String. When pressing Send in any Send String window, the Termination String is automatically appended to the sent data.
Termination String
If enabled, this String is automatically appended when sending data from Send String windows.
Send File Options
Notify after sending files
If enabled, a short notification sound will be played upon completion of sending a file.
Fonts ↑
Text Viewer Settings
Text Color
Sets the color of the text in all plain text fields, such as the main window, the input line (in Line Mode), as well as the Send String window.
Background Color
Sets the background color of all plain text fields, such as the main window, the input line (in Line Mode), as well as the Send String window.
FontSets the font of the text in all plain text fields, such as the main window, the input line (in Line Mode), as well as the Send String window.
Font Size, Terminal
Sets the font size of the text in the main plain text display.
Font Size, Input Fields
Sets the font size of the text in the input line (in Line Mode) as well as the Send String window.
Condense Line Spacings
Reduces the spacing between text lines in the main plain text display to allow for more text to be visible.
Hex Viewer Settings
Font
Sets the font of the text in the main hex display. It is recommended to use a mono spaced font for the hext display.
Size
Sets the font size of the text in the main hex display.
Toolbar ↑
Toolbar Options
Show Toolbar
Shows the toolbar in the terminal windows.
Show Button Labels
Enables/disables the labels for the toolbar buttons. Disabling the labels reduces the width needed for toolbar buttons with longer labels. Most suited for Linux plaforms where the button labels are located to the right of the button icon instead of below.
Toolbar Buttons
Allows for customization of the toolbar. Use the Add... and Delete buttons to modify the contents of the list. Drag rows to reorder the list. The buttons are added to the toolbar in the order they are shown in the list.
Buttons named ...Toggle are buttons that toggle between different options, such as e.g. the ConnectionToggle button which toggles between Connect and Disconnect. Buttons named ...Menu open a popup menu to select options from, such as e.g. the ViewMenu button which opens a menu with the selection of viewer options.
The toolbar supports the following spacer types:
- Space (macOS, Linux) — Inserts a blank space between buttons.
- FlexSpace (macOS, Linux) — Inserts a blank space between buttons that varies with the width of the window such that the tool buttons occupy the entire width.
- Separator (Windows, Linux) — Inserts a visible vertical line between buttons. Takes up less space than a Space (where available).
Miscellaneous ↑
Misc. Options
Automatically connect on open
If checked, the specified serial port will automatically open when these connection settings are loaded. If this option is enabled in the default connection options (see File > Save As Default), the serial port will be opened automatically whenever a new terminal is opened. Note, that each physical serial port can only be opened once, i.e. if a port is already opened, attempts to open the same port in another terminal window will cause a connection error.
Automatically disconnect on close
If checked, the serial port is closed automatically when the terminal window is being closed. If unchecked, CoolTerm will warn the user if it is attempted to close the window while the connection is still open.
Automatically run macro on open
Runs the selected macro automatically when the terminal window opens. If the port is currently closed, the macro will be paused until the port opens.
Automatically reconnect after port loss
If a device has suddenly disappeared before while the port was open, CoolTerm will attempt to re-open the port if this option is enabled. This is useful when attached microcontrollers are being rebooted.
Reconnect Delay (ms)
Determines the delay (in milliseconds) between port rediscovery and attempting to re-open the port. Values between 0 and 10,000 can be specified.
Show Connection Timer
If checked, a connection timer is displayed in the CoolTerm status bar.
Show Send/Receive Byte Counts
If checked, the byte counts for sent as well as received data is displayed in the CoolTerm status bar.
Reset Statistics when Port opens
If checked, the connection timer as well as the the byte counts are reset when the port is opened.
Port/GUI Refresh Interval (ms)
Determines how frequenlty the port is being polled for new data and the GUI is refreshed. The default of 100 should be adequate for most users. Increasing this value where timing is not critical can help with CPU power consumption on older systems or battery powered platforms. Conversely, this value can be lowered if faster polling is required. NOTE: lowering the refresh interval will increase the CPU load.
The minimum and maximum values that can be specified are 10 and 10,000 ms, respectively.
Always keep window on top
If checked, the CoolTerm window will always stay on top of other windows.
Sending Strings ↑
Strings of text can be sent via the Send String dialog windows which can be opened via the Connection > Send String... menu. Multiple Send String windows can be open at the same time. Strings can be entered in plain text as well as in hexadecimal mode.
When entering data in plain text mode, the ENTER and RETURN keys will be emulated per the Enter Key Emulation setting under Terminal Options when sending.
When entering data in hexadecimal mode, 2 hex-digits must be used for every character. It is not necessary to use spaces between characters.
The modes can be switched between Plain Text and Hex at any time.
Press the Send button to send the string to the serial port. Pressing SHIFT+ENTER or SHIFT+RETURN will also invoke the Send button.
NOTE: The serial port must be open to send strings. If the serial port is not open, the Send button is disabled.
Sending Text or Binary Files ↑
Entire text or binary files can be transmitted via the Connection > Send Textfile... menu. Transmitting files is only possible when the serial port is open. Use the file dialog opened by Connection > Send Text/Binary File... to navigate to the text file to be sent.
Files can also be sent via drag-and-drop. Drag the file to be sent and drop it onto the terminal window with which to send the file.
Capturing Received Data ↑
CoolTerm is capable of capturing received data to text files.
- Use the Connection > Capture to TextFile/Start... menu to open a file dialog.
- Specify the location and the name of the capture file and press Save. This will start the capture.
- To pause capturing, use Connection > Capture to TextFile/Pause.
- To resume capturing, use Connection > Capture to TextFile/Resume.
- To pause capturing and close the capture file, use Connection > Capture to TextFile/Stop.
Transmit Macros ↑
Macros can be managed and invoked via the Macro menu. They are tied to the connection settings, and are stored as part of those settings. Different terminals can have different sets of macros.
Managing macros ↑
- Use the Macros > Manage Macros... menu item to manage your macros.
- Use the Add... button to add a new macro to the table of macros. Enter your macro text into the left column. An optional label can be added to the right column. If a label has been entered for a macro, the label is displayed in the macros menu instead of the macro text.
- Double-click any cell in the table to edit its contents.
- The rows in the table can be re-ordered by dragging them.
- To delete a row, select the row and press the Delete button or press backspace or delete on the keyboard.
Special Characters ↑
Special characters can be added via common Python escape characters as follows:
\\ Backslash \a ASCII Bell (BEL) \b ASCII Backspace (BS) \f ASCII Formfeed (FF) \n ASCII Linefeed (LF) \r ASCII Carriage Return (CR) \t ASCII Horizontal Tab (TAB) \v ASCII Vertical Tab (VT) \ooo Character with octal value ooo \xhh Character with hex value hh
Example: To write a macro to send “Hello World” with a TAB between the words and CR+LF termination, use the following: Hello\tWorld\r\n
Adding delays to macros ↑
To add delays to a macro, use the <delay d> tag in your macro string (where d denotes the delay in seconds) anywhere you wish to add a delay.
Example: To add a 12.5 second delay between "Hello" and "World", use the following: Hello<delay 12.5> World
Controlling handshake signals with macros ↑
Handshake signals DTR and RTS can be controlled from marcos with <dtr on|off> and <rts on|off> tags, respectively. The on and off specifiers determine whether these signals are set or cleared.
Example: Many microcontroller boards can be reset by setting DTR. The following macro can be used to reset such a board: <dtr on><dtr off>.
Adding serial breaks to macros ↑
To add serial breaks (setting the TX signal to a logic '0' for more than the length of a single serial frame) to a macro, use the <break> tag in your macro string anywhere you wish to insert a serial break.
Example: To add a serial break signal between "Hello" and "World", use the following: Hello<break> World
To assert the serial break for longer than the default minimum duration, use the <break s> tag, where s denotes the duration in seconds.
Example: <break 0.5>
To set or clear the state of the break signal manually, use the <break on> and <break off> tags respectively.
Example: Setting the break signal<break on>
Adding repetition to macros ↑
To repeat a macro multiple times, use the <repeat n> tag anywhere in your macro string (where n denotes the number of repetitions). Omitting this value will repeat the macro indefinitely until it is aborted via the Abort current macro menu item. Note that the <repeat n> tag can only be added once. Subsequent tags will be ignored and interpreted as regular text.
Example: To repeat "Hello World" 5 times, use the following: Hello World<repeat 5>
NOTE: Escape < characters with a backslash to prevent < > pairs from being interpreted as special function macro tags. For example, \<break> will not be interpreted as a break tag but treated as regular text instead.
Data Plotting in Chart Mode ↑
While in Chart viewer mode, CoolTerm analyzes every line of text in the receive buffer for numerical data. It will interpret each line of text as a new data point (or a set of data points). To plot a single trace, simply send numbers as text, terminated by line endings (CR, LF, or CR+LF), from the connected serial device to CoolTerm. To plot multiple traces, send all values on the same line, separated by a TAB (ASCII code 9), a space, or a comma. Non-numeric data will be ignored. Timestamps must be in the beginning of each line, separated by --> (see example 3 below), in order to be recognized as such. Terminate each line of text with a line ending.
Examples of valid data formats
Example 1: Single trace
... 0.841470985 0.909297427 0.141120008 -0.756802495 -0.958924275 ...
Example 2: Multiple traces, TAB-separated
... 0.841 0.416 1.557 0.909 0.989 2.185 0.141 0.653 0.142 0.756 0.283 1.157 0.958 1.157 3.380 ...
Example 3: Timestamped data, space-separated
... 17:56:24 --> 8 5 0 1 9 5 17:56:25 --> 4 2 2 4 4 2 17:56:26 --> 3 6 0 2 4 9 17:56:27 --> 9 7 2 3 0 8 17:56:28 --> 0 5 0 4 2 9 ...
Example 4: Data with labels, comma-separated
... Temp(C): 20.1, RH(%): 45, Wind(mph): 4 Temp(C): 20.3, RH(%): 44, Wind(mph): 9 Temp(C): 20.9, RH(%): 42, Wind(mph): 15 Temp(C): 21.1, RH(%): 39, Wind(mph): 3 Temp(C): 20.7, RH(%): 43, Wind(mph): 6 ...
CoolTerm is not limited to a fixed number data points. Instead, CoolTerm is only limited by the Receive Buffer Size. CoolTerm will always display all the data it finds in the receive buffer and scale the display accordingly.
Chart Options ↑
Chart options can be selected via the context menu (right-click anywhere within the chart area).
Chart Properties...
Allows the customization of the chart. Properties such as the chart Title as well as axis Labels can be specified.
A simple legend, showing the trace number and the associated trace color, can be displayed in the top left corner of the chart by enabling the Show Legend option.
By default, CoolTerm automatically adjusts the limits of both the X- as well as the Y-Axis as data is being received and plotted. To instead use fixed axis limits, select the Fixed option for either axis and enter the desired limits in the fields below.
CoolTerm can either use sequential line numbers for the x-axis values, or it can extract the values for the x-axis from one of the data columns of the received data, or from timestamps.
- When None is selected, CoolTerm will treat each numeric value in a received line of data as a separate data value. The x-axis values represent a sequential number that increments with each line of received data.
- When Data Column is selected, the specified number determines which numeric value in each line of received data will be used as the x-coordinate for the other numeric values on the same line. A 1 means that the first value in each line will be used, a 2 means that the second value will be used, etc.
Note that this requires that each line of received data contains at least 2 numeric values. Selecting a number that is larger than the available number of numeric values per line will result ina blank chart. - When From timestamps is selected, and timestamps are either received from the serial device, or the Add timestamps to received data (in the Receive settings) option is enabled, CoolTerm will use the timestamps as values the for x-axis to plot the data. The times on the x-axis reflect how much time has passed since the connection was first opened. The time scale for the x-Axis can be set to either Seconds, Minutes, or Hours.
When the Time Reference is set to Elapsed Time, the time values on the X-Axis represent the amount of time that has passed since the current terminal was launched. When Time of Day is selected, the X-Axis values represent the time of day of the timestamps in the received data. Note that the date in the timestamps will be ignored with this option enabled. Data with timestamps just before and after midnight will be diplayed on opposite ends of the chart.NOTE: It is recommended to enable Wait for line ending in the Receive settings when adding timestamps to received data is enabled to ensure every timestamped line of received data consists of a complete data sample.
The timestamps must be at the beginning of each received line. Several timestamp formats are supported, such as SQL timestamps, as well as all the timestamp formats CoolTerm can use to stamp received data (see timestamp Type in the Receive settings). CoolTerm will attempt to guess the timestamp format used in the received data, taking into account local date and time formats. The following timestamp formats are supported:
- SQL Date/Time: YYYY-MM-DD hh:mm:ss
- SQL Time (with or without milliseconds): hh:mm:ss[.mmm]
- Localized Date/Time: Must comply with Unicode Format Patterns
- Localized Time: Must comply with Unicode Format Patterns
NOTE: While CoolTerm can convert localized timestamps in many localized formats to X-Axis values, doing so ran be rather CPU intensive. For use cases where it desired to display a moderate to large amount of datapoints with timestamps, it is recommended to use SQL formatted timestamps instead. Should the display refresh rate become too slow as the number of received datapoints increases, it is recommended to set the Data Source selection to none to bypass any timestamp conversions.
Trace Properties...
Allows for customization of the formatting and scaling for each trace currently being displayed. Properties such as the Label, Color, Style, and Width of each trace can be customized.
The Scaling of the trace data values can be increased or decreased in orders of magnitude (i.e. in powers of 10) by means of the up/down arrow control. This allows for the values of different traces to be brought into similar ranges for better readability.
The visibility of each trace can be set via the Visible check box. Traces whose visibility is disabled will not be plotted, and their data values won't be used to automatically scale the chart.
Restore Trace Defaults
Restores all trace formatting and scaling to the default settings.
Zooming and Scrolling ↑
The chart view can be zoomed via the View > Zoom Chart menu or with a trackpad or mouse wheel while holding CTRL or SHIFT+CTRL on the keyboard. While zoomed in, the chart can be scrolled via the scrollbars or a trackpad or mouse wheel.
CoolTerm Scripting ↑
CoolTerm supports remote control and scripting via the following means:
- CoolTerm Remote Control Socket Protocol
- HTTP Server
- AppleScript (macOS only)
Each one of these can be individually enabled or disabled via the Preferences.
CoolTerm Remote Control Socket Protocol ↑
The CoolTerm Remote Control Socket Protocol, based on TCP/IP, allows most aspects of CoolTerm, normally performed via the CoolTerm GUI, to be automated by a separate piece of software (e.g. scripting software). A listening TCP socket embedded in CoolTerm (Remote Control Socket), which is enabled via the Preferences in CoolTerm, can accept connections (default port: 51413) from the same computer on which CoolTerm is running as well as other computers that can make a TCP/IP connection to the computer on which CoolTerm is running. Another application that is connected to the Remote Control Socket can send commands to initiate actions normally performed via the GUI (e.g. open/closing the serial port, reading/writing data, etc.).
Refer the to the included Remote Control Socket Protocol.pdf document for detailed specifications.
CoolTerm scripting via Python ↑
The included Python Module CoolTerm.py fully implements the CoolTerm Remote Control Socket Protocol and offers useful Python functions to automate CoolTerm. Refer to the description included in CoolTerm.py as well as the included examples. The CoolTerm.py module can either be installed in the site-packages location of your Python installation, or it can be located in the same place as your own Python scripts using the module.
HTTP Server ↑
CoolTerm has simple, built-in, HTTP server (default port: 8080) that can be enabled via the Preferences in CoolTerm. Simply direct a web browser to http://127.0.0.1:8080 to be presented with a form that lists buttons for all available commands. The ID (ID as integer) of the CoolTerm window being addressed needs to be specified in the Window ID field. All other arguments are entered into the Data field in the form. For commands such as SetParameter where more than one argument (in addition to the ID) are needed, the arguments (e.g. ParameterName and Value) must be separated by a single space character. Commands are executed by pressing the specific push button. CoolTerm will respond with a new page to show the response.
Instead of using the built-in form, commands can also be sent to CoolTerm from custom HTML pages, using POST.
Example:
POST /?method=post&WINID=0&DATA=&CMD=Connect
AppleScript ↑
CoolTerm for Mac has supported AppleScript since its early days. Refer to the included AppleScript ReadMe.txt document for more information as well as example scripts.
Launching CoolTerm from the Command Line ↑
CoolTerm can be launched from the command line, using the paths to settings files as arguments. If launched without an argument, the default settings file will be applied. If one or more settings file paths are passed as arguments (separated by spaces), each one will be opened when CoolTerm launches.
Examples:
Mac — open CoolTerm.app setting1.stc setting2.stc setting3.stc
Win — CoolTerm.exe setting1.stc setting2.stc setting3.stc
Linux — CoolTerm setting1.stc setting2.stc setting3.stc
Configuration for Advanced Users ↑
Adding extra serial ports to the selection in Connection Options ↑
In case the system has serial ports that can not be discovered by CoolTerm, such as certain /dev/tty.xxx devices on macOS or Linux, a text file named ports.ini can be placed in the default application data location:
Mac — /Users/UserName/Library/Application Support/CoolTerm/
Win — \Users\UserName\AppData\Roaming\CoolTerm\
Linux — /home/UserName/CoolTerm/.
Additional port names (make sure to include the complete path on macOS or Linux) can be added to this file, one per line. At startup, CoolTerm will read the contents of this file and attempt to obtain handles on the listed devices. Devices with valid handles will then be accessible via the Connection Settings.
TCP connections can be added to ports.ini as well, using the following syntax: TCP:<ADDRESS>:<PORT>. Example: TCP:<127.0.01>:<1025>.
Alternatively, the ports.ini file can also be placed inside the same directory in which the CoolTerm application resides. If a ports.ini file exists in both the default application data location as well as the CoolTerm application directory, the latter will take precedence.
Adding extra baudrates to the selection in Connection Options ↑
CoolTerm only lists the baudrates that are guaranteed to work on all platforms. However, some USB adapters are known to work with higher/non-standard baudrates such as 128000, 153600, 256000, 460800, or even 921600 baud. Some users may have hardware that require lower baudrates, such as 150, 110, or 100 baud. To permanently add such baudrates to the baud rates menu in CoolTerm, create and place a baudrates.ini file in the default application data location:
Mac: — /Users/UserName/Library/Application Support/CoolTerm/
Win: — \Users\UserName\AppData\Roaming\CoolTerm\
Linux: — /home/UserName/CoolTerm/.
Additional baudrates can be added to this file, one per line. At startup, CoolTerm will read the contents of this file and the additional baudrates will then be accessible via the Connection Settings. When selecting one of these additional baudrates, CoolTerm will attempt to pass the baudrates to the driver.
Alternatively, the baudrates.ini file can also be placed inside the same directory in which the CoolTerm application resides. If a baudrates.ini file exists in both the default application data location as well as the CoolTerm application directory, the latter will take precedence.
NOTE: There is no guarantee that setting the baudrate to one of these settings will produce the desired result. In case a value is not accepted by the driver, CoolTerm will generate an Invalid Option error message. But there are other cases where the driver will accept the value, but not actually generate the correct baudrate. Such cases include some of the lower baudrates like 150, 110, and 100 baud. At the time of this writing, only Keyspan USB adapters have been found to support such settings reliably. Both FTDI and Prolific adapters produce baudrates around 30kBaud when set to one of these settings. The user is required to verify that the port is set to the correct baudrate when selecting a non-standard setting. Reports of adapters that reliably support the lower baudrates will be appreciated.
Removing serial port names from connection settings ↑
When connection settings are saved, the name of the selected serial port is stored in the settings file to ensure that the specified port is selected the next time the connection settings are loaded. However, there are times or situations when this may not be desired, such as systems where serial port adapters are only temporarily plugged in or where such adapters are changed frequently.
The settings files are human readable and can be opened with a text editor. To prevent CoolTerm from selecting the port specified in the settings, simply remove the line of text that specifies the port name (the first line) from the settings file. This will cause CoolTerm to select the first available serial port instead of selecting a specified one. This will also prevent the The serial port XXX is not available warning when the settings file is loaded and the specified port can't be found. It is recommended use this technique for default (default.stc) settings on systems where it is not guaranteed that the specified port is always available.
Example:
turn this:
Port = KeySerial1 BaudRate = 115200 DataBits = 8 ...
into this:
BaudRate = 115200 DataBits = 8 ...
It is also possible to make CoolTerm prompt the user to select a serial port when a settings file is loaded. This may useful for generic settings files for specific use cases or hardware devices where the name of the serial port is not known beforehand. To achieve this, delete the serial port name from the settings file but otherwise leave the Port = line intact.
Example:
turn this:
Port = KeySerial1 BaudRate = 115200 DataBits = 8 ...
into this:
Port = BaudRate = 115200 DataBits = 8 ...
Restoring CoolTerm application defaults ↑
Hold the SHIFT key while launching CoolTerm. A dialog asking whether you want to revert to the application default settings will appear. Click OK to proceed. This will delete the current preferences, the recent files and session history, as well as the default.stc file (if it exists) in the application data location.