CoolTerm

CoolTerm
Help and Reference

Contents

Overview ↑

CoolTerm is an easy-to-use terminal for communication with hardware connected to serial ports for macOS, Windows, and Linux.

CoolTerm is a simple serial port terminal application 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:

Quick Start ↑

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, Chart, and VT100 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 Data 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 cannot be displayed in Plain Text, such as, for example, when the received data is 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.

VT100 mode can be used with equipment that uses ANSI formatting and control sequences to display data.

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

Saving displayed data

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-lit TX LED indicates that transmit flow is halted due to hardware or software flow control being active. A red-lit 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

Session

Connection

Macros

View

Preferences ↑

Misc. Settings ↑

Misc. Settings

Restore previous sessions

If checked, CoolTerm will try to restore all open terminal windows from the previous session at startup.

Enable Notifications

If checked, CoolTerm will generate notifications for certain events, such as the addition or removal of serial ports from the system.

NOTE: On Windows systems, Windows PowerShell is required in order for notifications to be generated.
NOTE: On Linux systems, libnotify is required in order for notifications to be generated. Some systems may also require notification-daemon.

Suppress Serial Port Warnings

If enabled, CoolTerm will not warn the user when CoolTerm is started on a system with no serial ports, or when connection settings with references to non-exisiting serial ports are loaded.

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.

Alternate Menu Shortcuts

Allows the selection of an alternate set of shortcut keys for menu items where the standard shortcut keys can't be accessed easily.
The keys in the available sets apply to the following menus, in order:

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.

Avoid Plain Text Flicker (Linux only)

If checked, avoids flicker in Plain Text View Mode on certain Linux platforms (such as Raspberry Pi, for example) by only appending new data to the text display rather than refreshing the text display with the entire receive buffer contents.
NOTE: This may cause certain Data Handling options (such as handing BS or DEL characters and filtering/handling of ANSI escape sequences, etc) to not function properly.

Print plain text as styled text

If checked, CoolTerm will print the plain text view contents in styled fashion as they are shown. This is useful when keyword formatting is enabled.
If unchecked, standard plain text printing will be used.
This feature works natively on macOS. On Windows and Linux platforms, stylized printing is achieved by means of exporting the plain text contents to HTML and printing from the default web browser.

Print VT100 text in color

If checked, CoolTerm will print VT100 view contents using ANSI colors. If unchecked, CoolTerm will print in black.

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.

Conn. Options ↑

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.

Disable this option if you are using Windows and experience unusual delays or app freezes when opening the connection options or when opening the quick menu in the bottom left corner of the CoolTerm window. Note that such long delays are most likely due to one of the installed serial devices (or bluetooth devices with serial profile) prolonging the serial device enumeration.

Skip save Prompt for unsaved Settings

If checked, CoolTerm will not ask whether or not to save unsaved settings when closing terminal windows.

Automatically save unsaved Settings

When enabled, and Skip save Prompt for unsaved Settings is turned on, CoolTerm will attempt to automatically save the current settings.

NOTE: if the current settings have not previously been saved to a settings file, CoolTerm can't automatically save the settings.

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 recommended to disable this setting unless the selected serial port is always available.

Include Window Position and Size

If 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.

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 an 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 application 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 by default to new terminal windows.

Alternatively, a connection settings file named default.cooltermsettings can also be placed inside the same directory in which the CoolTerm executable resides. If a default.cooltermsettings 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 default to specific connection settings.

Specific settings can be imported from existing connection settings files via the File > Import... menu item. Selecting this menu item will open a file dialog to select the file from which to import settings. Select the specific items to import by selecting the corresponding check boxes in the list of parameters. Settings that are different from the current setting are listed in red. The list can be filtered to only show the differences to the current 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 ↑

Options specific to the serial port 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 (for example 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 connection to a remote TCP server, or to accept connections from a remote TCP client. To create a connection to a remote server, set the Mode to Client and enter the remote IP Address and Port at which the remote server is accepting connections. To accept connections from remote clients, set the Mode to Server and enter the port number on which to listen for remote connections.

TCP connections support Raw communication as well as communication using the Telnet protocol.

When Raw is selected as the Protocol, CoolTerm connects directly to the remote host and passes data through without any additional processing.

When Telnet is selected, CoolTerm adds minimal support for Telnet communication. In Client mode, this enables connecting to Telnet-based services such as BBS systems. In Server mode, CoolTerm implements a bare-bones Telnet server that can accept connections from a Telnet client.

When a TCP connection is selected, serial port specific settings are ignored.

UDP Connection

This item in the Port popup menu allows binding to a Local Port and specifying a Remote Address and Remote Port for UDP data transmissions. Use a Remote Port number of 0 to send to the same port number as the locally bound port. Set the Remote Address to the Broadcast Address to send data to the entire network. Clicking on the Broadcast Address will automatically enter it into the Remote Address field.

When a UDP connection is selected, serial port specific settings are ignored.

NULL Device

This item in the Port popup menu allows the creation of a NULL device. This is an artificial device that is not connected to any physical connection. However, a terminal window using a NULL device can exchange data with other Terminals using Data Forwarding. Such a terminal can also be accessed by scripting.

Software Supported Flow Control

If enabled, CoolTerm actively halts data transmission (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 transmitting 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 connection settings. Loading such settings will restore the history.

Local Echo

If checked, locally entered data will be echoed in the terminal window.

Local Echo on new line

If checked, local echo data will be displayed on a separate line.

Wait for RX Data Inactivity

If enbled, CoolTerm will hold the local echo and wait for a duration (specified below) of receive data inactivity before adding the local echo to the display to avoid interleaving the local echo with received data. Note that in use cases where data is received continuously with no gap longer than the specified wait time, local echo data will be held up indefinitely.

Key Emulation

Enter Key Emulation

Defines what character(s) to send when the main ENTER key (or RETURN) 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. Special characters can be added via common Python escape characters as follows:

Special Characters:

    \\    Backslash
    \n    Linefeed (LF)
    \r    Carriage Return (CR)
    \t    Horizontal Tab (TAB)
    \v    Vertical Tab (VT)
    \ooo  Character with octal value ooo
    \xhh  Character with hex value hh

Selecting None results in no key presses being sent when ENTER (or RETURN) are pressed.
Note that this setting also applies to data being sent via Send String windows.

Pressing either SHIFT or ALT (or OPTION on macOS) together with ENTER or RETURN will override the Enter Key Emulation setting and type line endings as follows:

Key CombinationLine Ending
SHIFT+ENTERCR
ALT+ENTERLF
SHIFT+ALT+ENTERCR+LF

NumPad Enter Emulation

Defines what character(s) to send when the ENTER key on the number pad 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. Special characters can be added via common Python escape characters (see Special Characters).

Selecting None results in no key presses being sent when ENTER (or RETURN) are pressed.

Pressing either SHIFT or ALT (or OPTION on macOS) together with the ENTER on the number pad will override the NumPad Enter Emulation setting and type line endings per the table above.

Pressing CTRL together with any ENTER or RETURN keys bypasses any selected emulation and sends the natively assigned ASCII codes per the user's system settings.

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 key presses 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:

KeyRaw ASCIIEmulation
UP Arrow0x1EESC[A
DOWN Arrow0x1FESC[B
RIGHT Arrow0x1DESC[C
LEFT Arrow0x1CESC[D
HOME0x01ESC[H
END0x04ESC[F
PAGE UP0x0BESC[5~
PAGE DOWN0x0CESC[6~

These emulations are useful when communicating with MCUs running MicroPython or similar in REPL mode.

It is recommended to enable this option when using CoolTerm in VT100 View mode.

Depending on the platform, enabling this option will also translate function keys F1..F20 into the corresponding ANSI escape sequences.

Keyword Formatting

Enable Formatting

If checked, the keyword formatting in the list above will be applied to the data displayed in plain text mode.
NOTE: It is recommended to not use this option with large receive buffer sizes as it can impact display performance with large amounts of data.

Use the Add... button to add a new keyword to the list. Formatting options include text color as well as bold, italic, and underline text properties. Enable the Case sensitive option to make the formatting for this keyword case-dependent.
Enabling the Apply format to line ending option for a keyword will cause the formatting to be applied to not only the keyword but also the following text until the end of the line.

Double-click a keyword in the list to edit it. Select one or more keywords in the list and use the Delete button to delete them from the list. The keywords in the list can be rearranged by dragging.

Fonts

Terminal Line Font

Sets the font and size used for text in the terminal line when Line Mode is enabled.

Send String Font

Sets the font and size used for text in Send String windows.

Plain Text View↑

Data Handling

Settings in this section are applied to received data displayed in Plain Text View.

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.

Remove High Bit from 8-Bit Characters

If checked, all received characters will be displayed in ASCII View mode using only the lower 7 bits.

Convert ESC[#D to Backspaces

If checked, received ESC[#D escape sequences will be converted to 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.

Non-printable Characters (Plain Text View)

This setting applies to the display of characters with ASCII codes 0x00 to 0x1f in Plain Text View mode:

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 the 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.

Filter ANSI Escape Sequences

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[;H should not immediately be followed with more data but rather include a short delay before doing so to ensure ESC[;H 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.

Text Encoding

Sets the text encoding used to render the text in the plain text display.

Font

Font

Sets the font used for text in Plain Text mode.

Font Size

Sets the font size of the text in Plain Text mode.

Condense Line Spacings

Reduces the spacing between text lines in Plain Text mode to allow for more text to be visible.

Hex View↑

Font

Font

Sets the font used for text in Hex mode.

Font Size

Sets the font size of the text in Hex mode.

VT100 View↑

VT100 Settings

Terminal Emulation

Sets what terminal capabilities are emulated and advertised to remote systems if queried.
The options are:

Display ANSI Colors

If checked, ANSI colors are used to render text. If unchecked, all text will be rendered in the selected text color.

Color Palette

Declare Terminal as

Sets what terminal type is advertised to Telnet servers if queried.
The options are:

Display Bold Text in bright Color

If checked, a brighter color is used to render bold text.

Underline/Strikethrough Space

If checked, spaces in underlined or strike-through text will also be rendered using underlines or strike-through lines. If unchecked, spaces will be rendered as spaces with no lines.

Cursor

Sets the shape and behavior of the cursor.

Text Encoding

Sets the text encoding used to render the text in the VT100 display.

CP437 (Code page 437) is the original 8-bit character set used in IBM PC-DOS during the 1980s, often referred to as "OEM-US" or "Extended ASCII". It includes standard ASCII characters, accented letters, Greek letters, and graphical box-drawing symbols, making it essential for early text-based user interfaces.

Max. Scrollback Lines

Sets how much scroll back history is preserved. The allowed range is 100..100000.

Max. Line Overflow

Sets how many character past the right margin are preserved if automatic line wrapping is disabled. The allowed range is 0...1000.

Show Guide Column

If checked, a vertical guide line at the specified character position will be drawn.

New Line Emulation

Sets how received line termination characters are interpreted:

Line Spacing

Sets the line spacing for displayed data. The allowed range is 0.5...2.0.

Font

Font

Sets the font used for text in VT100 mode.

Font Size

Sets the font size of the text in VT100 mode.

Colorize Local Echo

If checked, local echo text will be colorized using an alternate text color, selected here.

NOTE: Enabling this option adds ANSI formatting sequences at the beginning and following the local echo text.

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, for example, when working with hardware that has a built-in self-test 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 unchecked, CoolTerm will notify the users of signal framing errors (for example if 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 unchecked, 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.

Direct RX update of text display

If checked, the plain text display will be directly appended with received data rather than refreshing the entire display with the receive buffer contents when new data arrives. This can speed up performance significantly when dealing with large amounts of data and high data rates, but can interfere with CoolTerm's ability to handle special characters or filter escape sequences.

NOTE: This applies to the plain text display only. This option has no effect on the hex or chart displays.
NOTE: While the display is being paused, the amount of received that is received will be limited to the Receive Buffer Size. Receiving more data while pause than the Receive Buffer can retain will result in loss of data.

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:

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.

Timestamp Separator

This specifies the character(s) used to separate the timestamps from the data in the received data.

Wait for line ending

If checked, and if timestamps are enabled, CoolTerm will wait for a line ending (CR, LF, CR+LF) before adding a new timestamp to the received 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.

Wait for termination string

If enabled, CoolTerm will inspect received data for the specified termination string and only timestamp and display the data when such a string is received. This is useful for devices that terminate their data with specific characters, other than standard line endings.

Termination String

This specifies the string with which CoolTerm expects the received data to be terminated if Wait for termination string is enabled. The termination string must be entered as a sequence of hex byte values.

Retain Termination String

If enabled, the received termination string will be included with the displayed data, otherwise, it will be omitted and not displayed.

NOTE: When Wait for termination string is enabled, CoolTerm will not display any received data UNTIL the specified Termination String is received.

Include timestamps in forwarded data

If checked and forwarding of received data to other terminals is enabled, CoolTerm will include the added timestamps in the data that is forwarded to other terminals.

Add labels to received and sent data

If checked, the labels specified in the respective RX and TX fields will be added to received and sent (i.e. local echo, if enabled) data.

Special characters can be added via common Python escape characters (see Special Characters).

Play sound on new data detection

If enabled, CoolTerm will play a short sound to indicate the detection of new incoming data.

Beep on receiving Bell Character

If checked, received bell characters (BEL, ASCII code 0x07) will play a terminal beep.

File Capture ↑

Capture File Options

Capture Format

This selection determines how received data is stored in the capture 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:

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. Special characters can be added via common Python escape characters (see Special Characters).

Capture Transmit Data

If enabled, the transmitted data will be captured in addition to 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 a Sent label.

Prompt for Comment

If checked, CoolTerm will prompy the user for a comment each time before a capture is started to provide the user with the means to document pertinent useful information about that log.

Default Capture File Name

Specifies a the default capture file to be used in capture file save dialogs. This setting accepts the following placeholder patterns, which will be replaced at the time the filename is created:

<name>the name of the terminal
<file>the filename of the terminal
<yyyy>4-digit year
<yy>2-digit year
<mm>2-digit month
<dd>2-digit day
<HH>2-digit hours
<MM>2-digit minutes
<SS>2-digit seconds
<sss>3-digit milliseconds

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.

Prompt for File Name

If enabled, CoolTerm will ask the user for a file name before starting the capture. If disabled, CoolTerm will use the specified file name.

Append to auto capture file

If disabled (default), a new auto capture file is created using the Auto Capture File Name setting below each time auto capture is started (i.e. each time the connection settings are loaded). If a file with the same already exists, it will be overwritten with a new one.

If this option is enabled and a capture file with the specified Auto Capture File name already exists, CoolTerm will append new data to the existing file.

If this option is enabled and a capture file with the specified name 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 use the default capture file name. This setting accepts the the same placeholder patterns as the Default Capture Filename setting above, which will replaced at the time the filename is created

NOTE: Any changes to Auto Capture settings won't take effect until the settings are reloaded or the autocapture is manually restarted.

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. Special characters can be added via common Python escape characters (see Special Characters). 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 into 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 Terminate 'Send String' Data is enabled, this String is automatically appended when sending data from Send String windows. Special characters can be added via common Python escape characters (see Special Characters).

File Transfer ↑

File Transfer Options

Bypass IAC Escaping over Telnet

When enabled, CoolTerm will not apply Telnet IAC escaping during file transfers over Telnet/TCP connections. Normally, any 0xFF byte in the transferred data is doubled to 0xFF 0xFF before sending, and incoming 0xFF 0xFF pairs are collapsed back to a single 0xFF, to comply with the Telnet protocol. Enable this option if the remote system does not perform IAC escaping during file transfers — i.e. it transmits a literal 0xFF as a single byte and expects to receive it the same way. This option has no effect on connections that are not using the Telnet protocol.

ZMODEM Options

Auto-Receive

When enabled, CoolTerm will automatically begin receiving files when a ZMODEM transfer is initiated by the remote system (via ZRQINIT or rz+CR), without requiring any action from the user. Files are saved to the folder specified by the Auto-Receive Location setting below.

Auto-Receive Location

Specifies the folder where files received via ZMODEM Auto-Receive will be saved. The folder must exist and be writable.

Send File Options

Notify after sending files

If enabled, a short notification sound will be played or a notification (if enabled in the Preferences) will be displayed upon completion of sending a file.

Forwarding ↑

Data Forwarding

Forward RX/TX data to other terminals

CoolTerm will forward all received and/or transmitted raw data to the CoolTerm windows listed in this list, provided that they are currently open and that their ports are connected.

The two Source columns on the left side of the table allow the selection for the source of the data to be forwarded at the current terminal. Selecting R will forward all data RECEIVED by the current terminal. Selecting T will forward all data SENT by the current terminal.

The two Destination columns on the right side of the table allow the selection of the destination for the forwarded data at the other terminal. Selecting R will cause all data to be forwarded to the receive buffer of the other terminal. Selecting T will cause all data to be forwarded to the transmitter of the other terminal.

Use the Add... and Delete buttons to add or remove CoolTerm windows from the list.

The most common use case is to forward data received by one device and re-transmit it using another device. For this use case, select R from the Source columns on the left and T from the Destination columns on the right side of the table.
NOTE: To fully bridge two devices, each of the two CoolTerm terminals will need to send its received data to the transmitter of the other terminal.

Another possible use case is to transmit data entered into one terminal by multiple devices. For this use case, add all other terminals to the Data Forwarding table of your main terminal and select T from the source columns on the left and select T from the destination columns on the right. All data sent or entered at the main terminal will then also be sent by all other terminals.

It is also possible for one main terminal to receive data from multiple other devices. For this use case, add the main terminal to the Data Forwarding table of all the other terminals (each connected to a different device) and select R from the Source columns and R from the Destination columns. The data received by all other terminals will then be forwarded to the receive buffer of the main terminal.

Open other ports

If checked, CoolTerm will attempt to open the port on the other terminals, should they be closed, before forwarding any data to them. If unchecked, CoolTerm will not send any data to other terminals whose ports are not open.

Macros ↑

Transmit Macro Options

Manage Macros...

Opens the Macros dialog where transmit macros can be created and edited.

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.

Prefix all transmitted data with macro

Automatically prefixes all the transmitted data with the selected macro. This applies to all means of sending data except running other transmit macros.

Postfix all transmitted data with macro

Automatically postfixes all the transmitted data with the selected macro. This applies to all means of sending data except running other transmit macros.

Toolbar ↑

Toolbar Options

Show Toolbar

Shows the toolbar in the terminal windows.

Toolbar Style

Sets the style of the toolbar. The following styles are available:

Icon Color

Sets the color of the toolbar icons as follows:

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 the ConnectionToggle button which toggles between Connect and Disconnect. Buttons named ...Menu open a popup menu to select options from, such as the ViewMenu button which opens a menu with the selection of viewer options.

The toolbar supports the following spacer types:

Window ↑

Window Options

Always keep window on top

If checked, the CoolTerm window will always stay on top of other windows.

Prevent Window Closure

If checked, CoolTerm will not allow the window to be closed by clicking the close button or the File > Close Window menu item. This is to prevent accidental closure. The only way to close the window is to quit CoolTerm.

Unpause Display on Send

If checked and the display is currently paused, CoolTerm will automatically unpause the display when new data is being transmitted by any means, including typing new data, sending files, running transmit macros, etc.

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.

Status Bar Options

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 are displayed in the CoolTerm status bar.

Reset Statistics when Port opens

If checked, the connection timer as well as the byte counts are reset when the port is opened.

Show Capture File Name

If checked, the file name of capture files is displayed in the status bar while a capture is running.

The connection status label in the status bar also serves as a macro activity indicator:

Miscellaneous ↑

Misc. Options

Skip Port Verification at Startup

If enabled, CoolTerm will not check the validity of the port selection. If disabled, CoolTerm will notify the user that the port selection is invalid and offer the option to select a new port.

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 the user attempts to close the window while the connection is still open.

Automatically reconnect after port loss

If a device has suddenly disappeared 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.
This setting also applies to TCP client connections. CoolTerm will attempt to reconnect if the connection to the server was lost.

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.

Use connection error notifications

If enabled, CoolTerm will replace all connection error message boxes with notifications.

NOTE: Notifications must be enabled via the CoolTerm Preferences in order for connection error notifications to be generated. Enabling connection error notifications while notifications are disabled in the preferences will result in no error messages being created.

Add connection errors to received data

If checked, CoolTerm will add timestamped connection error messages to the received data in the terminal window.

Add connection errors to capture file

If checked, CoolTerm will add timestamped connection error messages to the current capture file (if file capture is enabled).

Port/GUI Refresh Interval (ms)

Determines how frequently 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.

Refresh on Receive Data Event

If checked, the GUI is refreshed immediately upon any receive data events, in addition to being refreshed at the interval specified above. This is useful in use cases where timing is critical. Note that enabling this option can increase CPU load, especially in use cases where large amounts of data is receveived a high rates.
NOTE: When time stamps with millisecond resultion are enabled in the Receive setting, CoolTerm will automatically refresh on receive data events to ensure the accuracy of the timestamps.

Disable Menu Shortcuts (Windows and Linux only)

Disables the menu shortcuts in order to be able to send CTRL characters via the terminal.

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 opened 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 and Receiving Files ↑

Entire text or binary files can be transmitted or received via the Connection > Send File(s)... and Connection > Receive File(s)... menu items.

The following file transfer protocols are available for file transfers:

File transfer is only possible when the connection is open. Raw transmission is supported by all connection types. XMODEM, YMODEM, ZMODEM, and KERMIT transmissions are supported by Serial, TCP, and UDP connections.

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. Files dropped onto the terminal window are transmitted in RAW mode.

The Send Again and Receive Again menu items can be used to easily repeat the most recent file transfer transaction by bypassing the file transfer dialogs. These actions can also be invoked by holding the SHIFT key while pressing the Send Files or Receive Files buttons in the tool bar.
Note that Send Again and Receive Again will fail if any of the previously used files or locations are no longer valid.

Capturing Received Data ↑

CoolTerm is capable of capturing received data to text files.

  1. 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 append received data to an existing capture file instead, use Connection > Capture to TextFile > Append... and select an existing file.
  2. To pause capturing, use Connection > Capture to TextFile > Pause.
  3. To resume capturing, use Connection > Capture to TextFile > Resume.
  4. To pause capturing and close the capture file, use Connection > Capture to TextFile > Stop.
  5. To immediately start a file capture using the auto capture settings, use Connection > Capture to TextFile > Start Auto Capture.
    An auto capture can also be started by holding SHIFT while pressing the Start Capture button in the toolbar, or by holding SHIFT when selecting the Start... menu item from the Capture button in the toolbar.

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. When a transmit macro is running, the connection status label in the status bar turns blue and displays the name of the active macro.

Managing macros ↑

  1. Use the Macros > Manage Macros... menu item to manage your macros.
  2. Use the Add... button to add a new macro to the table of macros. Enter your macro text in 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.
  3. Double-click any row in the transmit macro table to re-open the Transmit Macro Settings window and edit an existing macro.
  4. The rows in the table can be re-ordered by dragging them.
  5. To delete a row, select the row and press the Delete button or press backspace or delete on the keyboard.

Transmit macro properties ↑

Each transmit macro has the following properties, configured in the Transmit Macro Settings window:

Label

The name for the macro. While entering a label is optional, a unique label must be specified to invoke the macro from another macro using the <txmacro> tag, or to use it in other automations.

Macro

The macro text to be sent when this macro is invoked. Python-style escape sequences are supported by transmit macros (see Special Characters below).

Enabled

When checked, the macro is active and will be sent when it is invoked. Uncheck this to disable a macro without deleting it.

Special Characters ↑

Special characters can be added via common Python escape characters as follows:

    \\    Backslash
    \a    Bell (BEL)
    \b    Backspace (BS)
    \f    Formfeed (FF)
    \n    Linefeed (LF)
    \r    Carriage Return (CR)
    \t    Horizontal Tab (TAB)
    \v    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

To include a literal < or > character in your macro text without it being interpreted as part of a tag, escape it with a backslash: \< and \>.

Example: \<break> is treated as the six literal characters <break> rather than a break tag.

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 macros 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 ↑

The <repeat n> tag (where n is the number of repetitions) can be used to repeat all or part of a macro. Omitting n repeats indefinitely until the macro is aborted via the Abort current macro menu item.

Repeating the entire macro

Place a <repeat n> tag anywhere in the macro without a closing </repeat> tag to repeat the entire macro content that follows it n times.

Example: To send "Hello World\r\n" 5 times, use: <repeat 5>Hello World\r\n

Repeating part of a macro

To repeat only a portion of a macro, enclose that portion between a <repeat n> opening tag and a </repeat> closing tag. The text outside the tags is sent once; the text inside is sent n times. Repeat blocks can be nested.

Example: The following macro sends the intro once, repeats the chorus 3 times with a 1-second pause between each repetition, then sends the outro once:

The wheels on the bus go <repeat 3>round and round.\r\n<delay 1></repeat>All 'round the town.\r\n

This produces the following output:

    The wheels on the bus go round and round.
    round and round.
    round and round.
    All 'round the town.

Invoking macros from macros ↑

A transmit macro can invoke another transmit macro inline using the <txmacro LABEL> tag, where LABEL is the label of the macro to invoke. The referenced macro is expanded in place as if its content had been written directly into the calling macro. This includes honoring any <repeat> tags, delays, and other tags defined in the referenced macro.

The <txmacro> tag can be combined freely with other tags including <repeat> blocks.

Example: Given the following two macros:

    Label=WoB    Macro=The wheels on the bus go
    Label=RnR    Macro=round and round.\r\n<delay 1>

A third macro can be composed from them:

    Label=Bus Song
    Macro=<txmacro WoB><repeat 3><txmacro RnR></repeat><txmacro WoB><txmacro RnR>All 'round the town.\r\n

Invoking Bus Song produces:

    The wheels on the bus go round and round.
    round and round.
    round and round.
    The wheels on the bus go round and round.
    All 'round the town.

Error handling

CoolTerm validates all macro references before execution begins. The macro will not run and an error will be reported if:

Adding timestamps to macros ↑

To insert the current date and/or time into the transmitted data, use the <tstamp n> tag, where the optional parameter n specifies the timestamp format:

Example: To send a timestamped log entry, use: <tstamp 2> Device ready\r\n

This produces output similar to: 14:23:07.412 Device ready

Closing the connection from a macro ↑

To close the current connection from within a macro, use the <close> tag. The connection will be closed as soon as this tag is reached during macro execution.

Example: To send a final message and then close the connection, use: Goodbye!\r\n<close>

Clearing the terminal display from a macro ↑

To clear all received data from the terminal display from within a macro, use the <clear> tag.

Example: To clear the display before sending a command, use: <clear>status\r\n

Adding random numbers to macros ↑

Random numbers can be inserted into transmitted data using the <rand> and <randint> tags.

Floating-point random numbers

The <rand> tag inserts a random floating-point number. The number of decimal digits and optional range are specified as parameters:

Specifying 0 decimal digits produces an integer-formatted result with no decimal point.

Examples:

Integer random numbers

The <randint> tag inserts a random integer:

Examples:

Adding a counter to macros ↑

An internal integer counter can be inserted into transmitted data and incremented or decremented with each use. The counter persists across macro invocations and is only reset when a <countinit> tag is encountered or when the application starts.

Initializing the counter

Using the counter

Example: To send a sequence of numbered lines, use:

<countinit 1><repeat 5>Line <count>\r\n</repeat>

This produces:

    Line 1
    Line 2
    Line 3
    Line 4
    Line 5

Waiting for received data in macros ↑

The <waitfor> tag pauses macro execution until a specific string is received from the connected device, or until an optional timeout elapses.

Syntax

STRING supports Python-style escape sequences (see Special Characters above). Use \< and \> for literal angle bracket characters (a > in STRING must be escaped, as it would otherwise close the tag prematurely), and \" for a literal double-quote inside the string.

Only data received after the <waitfor> tag is reached is searched. Any data already in the receive buffer at that point is ignored.

When a timeout occurs and the abort behavior is in effect, a warning dialog is displayed and the macro is stopped.

Examples

Send an AT command and wait up to 5 seconds for the “OK” response before sending the next command:

ATI\r\n<waitfor "OK\r\n" 5>ATZ\r\n

Reset a device and wait up to 2 seconds for the prompt character; continue sending even if the prompt does not arrive in time:

reset\r\n<waitfor "\>" 2 continue>hello\r\n

Receive Macros ↑

Receive macros monitor incoming data and automatically execute one or more actions when a specified trigger string is detected. Like transmit macros, they are tied to the connection settings and stored as part of those settings. When a receive macro is active — either because a trigger string has been fully or partially detected, or because its actions are currently being executed — the connection status label in the status bar turns green.

Managing receive macros ↑

  1. Use the Macros > Manage Macros... menu item to manage your receive macros. The receive macro table is shown in the lower half of the Manage Macros window.
  2. Use the Add... button below the receive macro table to add a new receive macro. This opens the Receive Macro Settings window where the macro properties can be configured.
  3. Double-click any row in the receive macro table to re-open the Receive Macro Settings window and edit an existing macro.
  4. The rows in the table can be re-ordered by dragging them.
  5. To delete a receive macro, select its row and press the Delete button or press backspace or delete on the keyboard.

Receive macro properties ↑

Each receive macro has the following properties, configured in the Receive Macro Settings window:

Label

An optional name for the macro, used to identify it in the receive macro table.

Trigger

The string to watch for in incoming data. When this string is detected, the macro’s actions are executed. The same Python-style escape sequences supported by transmit macros (see Special Characters above) can be used in trigger strings. For example, to trigger on “READY” followed by CR+LF, use: READY\r\n

Case Sensitive

When checked, trigger string matching is case-sensitive. When unchecked, matching is case-insensitive. This setting applies to both plain-text and RegEx triggers.

RegEx

When checked, the trigger string is interpreted as a regular expression (PCRE syntax) rather than a plain text string. This allows for flexible pattern matching, such as triggering on any line that begins with a particular prefix or contains a numeric value.

Actions

One or more actions to execute when the trigger is detected. Actions are executed in the order they appear in the list. Use the Add... button to add an action, and drag rows to reorder them. Each action has a Type and an optional Parameter. Double-click a cell to select its value from a popup menu. The available action types are:

TXMacro

Sends a transmit macro. The Parameter popup lists all available transmit macros by label; select the one to send. If the parameter is left empty, no transmit macro is sent. Instead, any currently active transmit macro is aborted. Use an empty Parameter field to create an action to abort any currently active transmit macro.

Replace

Replaces the trigger text with the string specified in the Parameter field before it is displayed in the terminal. This can be used to suppress unwanted sequences, substitute abbreviations with full text, or reformat incoming data on the fly. The replacement string supports the same Python-style escape sequences as trigger strings (see Special Characters above), so control characters and non-printable bytes can be used as replacements. To delete the trigger text without substituting anything, leave the Parameter field empty.

Note: When using RegEx mode, the Replace action substitutes the exact text matched by the regular expression. However, if the matched text is split across two consecutively received data chunks, the replacement may not be applied correctly. For plain-text triggers, CoolTerm handles this automatically by holding back any partial match at the end of a chunk until the next chunk arrives, ensuring the replacement is always applied correctly regardless of how the data is chunked during transmission.

FileCapture

Starts or stops file capture. Set the Parameter to Start to begin capturing received data to a file, or Stop to end an active capture.

When starting a capture, this action uses the Capture File Location, Prompt for File Name, Append to auto capture file, and Auto Capture File Name settings from the Capture File Options.

ClearData

Clears all received data from the terminal display. No parameter is required for this action type.

Sound

Plays a sound. The Parameter popup lists the available sounds; select the one to play.

ViewMode

Switches the terminal to the view mode specified by the Parameter. The available options are Plain, Hex, Chart, and VT100. This can be used to automatically switch the view when a connected device signals a change in the type of data it is sending, for example switching to Hex view when binary data begins arriving.

Enabled

When checked, the macro is active and its trigger will be monitored in incoming data. Uncheck this to disable a macro without deleting it.

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. Non-numerical columns are ignored.

    ...
    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
    ...

Example 5: CoolTerm will attempt to extract numerical data by removing leading and trailing non-numerical characters from potential data points. Thus, CoolTerm is capable of plotting data formatted as follows:

    ...
    Temp=20.1C, RH=45%, Wind=4mph
    Temp=20.3C, RH=44%, Wind=9mph
    Temp=20.9C, RH=42%, Wind=15mph
    Temp=21.1C, RH=39%, Wind=3mph
    Temp=20.7C, RH=43%, Wind=6mph
    ...

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.

It is possible to restrict what is being plotted by enabling Only plot lines with exactly the specified number of data points. This is helpful when the data to be plotted is interspersed with other lines that may contain numerical characters that are not part of the data to be plotted. Such lines are most often interpreted as data lines with a different number of data points. Enabling this option will ignore such lines.

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- and Y-Axis as data is received and plotted. To instead use fixed axis limits, select the Fixed option for either axis and enter the desired limits and the size of the axis divisions in the fields below.
For the X-Axis it is also possible to display an automatically moving range of x-values by selecting the Range option and entering the desired width of the range. CoolTerm will then always display the upper end of the x-values of the received data. This useful for datalogging or data with monotonically increasing x-values as this option automatically moves the x-axis limits to the most recently received data.

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.

Reset Time Reference

When plotting data with timestamps with the Time Reference option set to Elapsed Time, selecting this menu item will reset the time reference used to calculate x-axis values the current time.

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 formatting and scaling of data traces to the default settings. Math trace are not affected.

Copy Chart Data

Copies the currently displayed data to the clipboard as a TAB separated table that can be pasted into other applications such as Excel, etc. This option heeds the Chart Settings as well as the Trace Settings. Data of invisible traces will not be copied. The X-Axis Data Source selections in the Chart Settings determine the contents of the first column of the copied data. When in Chart display mode, the data can also be copied to the clipboard via the Edit > Copy menu item.
Optionally, the chart data can also be copied to the clipboard with the actual time stamps from the source data rather than the x-axis values, by selecting the Copy Chart Data with Time Stamps menu item.

Save Chart Data...

Saves the currently displayed data to a TAB separated text file. This option heeds the Chart Settings as well as the Trace Settings. Data of invisible traces will not be saved. The X-Axis Data Source selections in the Chart Settings determine the contents of the first column of the saved data.
Optionally, the chart data can also be save with the actual time stamps from the source data rather than the x-axis values, by selecting the Save Chart Data with Time Stamps... menu item.

Adding Math Traces to the Chart ↑

Math Traces, which can display mathematical functions performed on any of the Data Traces, can be added via the Trace Properties... context menu described above. Press the + button to add a new Math Trace to the list. Enter the formula to be performed by the Math Trace into the Formula text area.

Formula Syntax

Formulas can reference any of the Data Traces using T1, T2, T3, etc., where the number corresponds to the position of the trace among the received data columns (T1 is the first column, T2 is the second, and so on).

NOTE: T1, T2, etc. refer to each Data Trace's plotted values, not the raw values as received from the serial device. If a Data Trace's Scaling (set via Trace Properties..., described above) is anything other than its default, Math Trace formulas use the scaled values. In most cases this makes no difference, since the default Scaling leaves the received values unchanged, but it is worth keeping in mind when combining Data Traces that have different Scaling settings applied within the same formula.

Formulas can also reference the X-Axis value of each data point using X, which can be used just like T1, T2, etc. For example, (T1+T2*sin(X))/2 combines two Data Traces with a sine function of the X-Axis value. The value of X is whatever is plotted on the X-Axis according to the X-Axis Data Source setting in Chart Properties... (described above): the sequential data point number (0, 1, 2, ...) if set to None, the value from the chosen data column if set to Data Column, or the timestamp-derived value if set to From Timestamps. X is not case-sensitive, and cannot be used where a function requires a constant value (such as the window size of movavg() or the coefficients of filter()).

The following operators are supported, listed from lowest to highest precedence:

The comparison and logical operators are described in Comparisons, Logic, and Conditions below.

Parentheses ( ) can be used to override the default precedence. For example, sqrt(T1^2+T2^2) calculates the magnitude of a two-component vector, and (T1-T2)/2 calculates half the difference between two traces.

A formula may also consist entirely of constant values, without referencing any Data Trace. In this case, the Math Trace is plotted as a horizontal reference line across the full range of the chart. For example, a formula of 5 plots a horizontal line at y=5.

Comparisons, Logic, and Conditions

Formulas can compare values and combine the outcomes. Every comparison and logical operation produces a numeric result: 1 for true and 0 for false. When a value is tested as a condition, 0 counts as false and any other value counts as true.

Comparison operators

Logical operators

Some examples:

NOTE: not applies only to the value immediately following it, just like unary -. For example, not T1 > T2 means (not T1) > T2. To invert the outcome of a comparison, use parentheses: not (T1 > T2).

NOTE: Comparisons cannot be chained. To test whether a value lies within a range, combine two comparisons with and, for example (T1 > 0) and (T1 < 10), rather than writing 0 < T1 < 10.

NOTE: Comparing values for equality is exact. Values that are the result of calculations, or that have been scaled, may differ in their last few digits from what is displayed, in which case == may not behave as expected. In such cases, a comparison such as abs(T1 - 3.3) < 0.001 is more reliable.

A value of NaN (Not a Number, see Errors in Math Trace Formulas below) is never equal to, greater than, or less than any other value, so every comparison involving NaN yields 0, except !=, which yields 1. When tested as a condition, NaN counts as true, since it is not zero.

if(condition, value_if_true, value_if_false) — evaluates to value_if_true where condition is true (non-zero), and to value_if_false where it is false (zero). Each of the three arguments can be any expression, including another if(). Some examples:

NOTE: All three arguments of if() are evaluated for every data point, regardless of the outcome of the condition; if() then simply selects one of the results. This ensures that functions which take the history of previous data points into account, such as movavg(), filter(), delay(), or cumsum(), see every data point even when they are used in a branch that is not selected at that point. For example, in if(T1>=5, movavg(T1,10), T1), the moving average is always calculated over the 10 most recent data points of Trace 1, not just over those where Trace 1 is greater than or equal to 5. The same is true for the operands of and and or.

Available Functions

The following functions can be used in Math Trace formulas:

Basic Math

Trigonometric (angles in radians)

Temperature Conversion

Random Numbers

NOTE: A new random value is generated every time the Math Trace is evaluated. Since a Math Trace is fully recalculated from the beginning of the received data each time the chart is updated, this means a Math Trace formula containing rand() or randint() will produce a different set of values across the entire trace on every update, rather than keeping already-plotted points fixed and simply extending with new ones. This is normal, expected behavior for these two functions.

Moving Average and Filter Functions

Unlike the functions listed above, which calculate a result independently for each data point, movavg() and filter() take the history of previously received data points into account.

For both movavg() and filter(), fewer than n previous data points may be available near the beginning of the received data. In this case, the calculation is simply performed using however many data points are actually available at that point.

Delay Function

delay(expression, n) or delay(expression, n, p) — shifts expression to the right by n data points, so that the value plotted at a given position is the value expression had n data points earlier. For example, delay(T1,5) plots a version of Trace 1 delayed by 5 data points.

delay(expression, n) is convenient for large values of n, as it avoids having to specify a long coefficient vector such as filter(expression,[1,0,0,...,0]) (with n zeros following the 1) would otherwise require. In both cases, the resulting Math Trace always has the same number of data points as the Data Trace(s) it references.

Additional Windowed Functions

The following functions also take the history of previously received data points into account, following the same rule as movavg() and filter(): whenever fewer than n previous data points are available near the beginning of the received data, the calculation is simply performed using however many data points are actually available.

Derivative and Integral Functions

deriv() and integ() differ from the windowed functions above in an important way: rather than simply counting samples, they use each data point's actual X-Axis value to perform their calculation. This makes them most meaningful when the X-Axis Data Source (in Chart Properties..., described above) is set to Data Column or From Timestamps, where the spacing between data points may vary from one point to the next.

NOTE: When the X-Axis Data Source is set to None, the X-Axis values are simply sequential integers (0, 1, 2, ...), one apart. In this case, deriv() becomes equivalent to diff(), and integ() closely approximates cumsum() (though not exactly, since integ() averages each pair of adjacent values via trapezoidal integration, while cumsum() simply adds each value as-is).

NOTE: If the X-Axis Data Source is set to From Timestamps with the Time Reference set to Time of Day, data spanning midnight causes the X-Axis values to wrap around (see the note on timestamped X-Axis values above). Since deriv() and integ() rely on X-Axis values increasing monotonically, this wrap-around may produce a visible artifact in these two functions at the point where the data wraps.

Errors in Math Trace Formulas

If a Math Trace formula contains a syntax error, references an unknown function, uses the wrong number of arguments for a function, or references a Data Trace that does not exist, the entire Math Trace will not be plotted. Details about the specific error can be viewed via the Show Math Trace Errors context menu item, which becomes available whenever at least one Math Trace has an error.

If a formula produces an undefined numeric result at a particular data point, such as the square root of a negative number or the arcsine of a value outside the range of -1 to 1, the result is computed as the special value NaN (Not a Number) and retained as a genuine data point — the Math Trace still has one value for every corresponding value in the Data Trace(s) it references. However, since NaN has no finite position on the Y-Axis, it cannot actually be drawn at a particular height; in practice, this appears as a break (gap) in the plotted line at that point, the same as with Infinity described below. This is noted via Show Math Trace Errors for reference.

Dividing by zero does not produce an error that prevents plotting. Instead, the result is computed as Infinity and retained as a genuine data point — the Math Trace still has one value for every corresponding value in the Data Trace(s) it references. However, since Infinity has no finite position on the Y-Axis, it cannot actually be drawn at a particular height; in practice, this appears as a break (gap) in the plotted line at that point. This is noted via Show Math Trace Errors for reference.

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:

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 (for example 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 (for example open/closing the serial port, reading/writing data, etc.).

Refer 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 a 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 (such as 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 cannot 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/.config/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.0.1>:<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 and 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 baudrates 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/.config/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 and 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 the event that 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 30 kBaud 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 to use this technique for default (default.cooltermsettings) 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 be 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
...

NOTE: If Skip Port Verification at Startup is enabled in the Miscellaneous settings, and a generic setting with an omitted port name is loaded, CoolTerm will NOT prompt the user to select a port and simply leave the port setting unselected.

Restoring CoolTerm application defaults ↑

Hold the SHIFT key while launching CoolTerm. A dialog asking whether you want to revert to the application's default settings will appear. Click OK to proceed. This will delete the current preferences, the recent files history, and recent session history, as well as the default.cooltermsettings file (if it exists) in the application data location.