tty_term is a terminal-based application for communicating with serial ports, TCP sockets, and
UNIX domain sockets. It provides a split-screen interface with an ncurses display area for received
data and a readline-powered command line for sending data.
- Connect to:
- Serial TTY devices (with configurable baud rate, parity, data bits, stop bits)
- Network sockets (TCP client)
- UNIX domain sockets
- Multiple display modes:
- Text – printable characters shown as-is, non‑printable as
\xXX - Raw – each byte as a hexadecimal value (
XX) - Hexdump – classic hexdump format (address + hex bytes + ASCII)
- Text – printable characters shown as-is, non‑printable as
- Multiple input modes:
- Text – free text, supports C‑style escape sequences
- Raw – numbers in decimal, hex (
0x…), binary (0b…), octal (0…) - Hex – hexadecimal bytes (with or without spaces)
- Modbus RTU (raw/hex) – automatically appends CRC‑16 (Modbus)
- Scrollable output buffer, mouse wheel support
- Configurable end‑of‑line sequence (LF, CR, CR+LF, LF+CR)
- Dump all traffic to a file
- Exclusive mode for serial devices
- Linux (or POSIX system with termios)
- C23 compiler (GCC or Clang)
- Libraries:
ncursesreadlineusefull_macros(≥0.3.5) – snippets_library
git clone --depth=1 https://github.com/eddyem/tty_term.git
cd tty_term
mkdir build && cd build
cmake ..
make
sudo make installBy default the program is installed into /usr/local/bin.
Use -DDEBUG=ON with CMake to build a debug version with extra logging.
ttyterm [options]
You must specify the device/socket path with -n (or --name).
All other options are optional.
| Option | Argument | Default | Description |
|---|---|---|---|
-h, --help |
– | – | Show help |
-s, --speed |
integer | 9600 | Baud rate (serial only) |
-n, --name |
string | – | Serial device (e.g. /dev/ttyUSB0), server host:port, or socket path |
-e, --eol |
n, r, rn, nr |
n |
End‑of‑line sequence when sending in text mode |
-t, --timeout |
milliseconds (float) | 100 | Timeout for select() on read |
-S, --socket |
– | – | Treat -n as a network socket (TCP client) |
-d, --dumpfile |
filename | – | Append all received and sent data to this file |
-f, --format |
string (e.g. 8N1) |
8N1 |
Serial line format (data bits, parity, stop bits) |
-U, --unix |
– | – | Treat -n as a UNIX domain socket path |
-x, --exclusive |
– | – | Open serial device in exclusive mode |
Examples:
# Serial port at 115200, 8N1, CR+LF as EOL
ttyterm -n /dev/ttyUSB0 -s 115200 -e rn
# TCP connection to a Modbus server
ttyterm -n 192.168.1.100:502 -S
# UNIX socket
ttyterm -n /tmp/mysocket -U
# Log all communication to a file
ttyterm -n /dev/ttyACM0 -d session.logThe screen is divided into three areas:
- Message window (top, scrolling) – displays received data in the selected display mode.
- Status bar (middle) – shows connection details, current display mode, and whether you are in Insert (editing) or Scroll mode.
- Command line (bottom) – where you type data to send.
| Key | Action |
|---|---|
F1 |
Show poput help window |
F2 |
Switch input/output mode to Text |
F3 |
Switch input/output mode to Raw |
F4 |
Switch input/output mode to Hexdump |
F5 |
Switch input mode to Modbus RTU (raw) |
F6 |
Switch input mode to Modbus RTU (hex) |
Tab |
Toggle between Insert and Scroll mode |
Ctrl+C / Q / Ctrl+D |
Quit program |
| Mouse wheel | Scroll output up/down |
The action of F2-F6 keys depends on current mode: Insert — change input mode,
Scroll — change output mode.
- Regular typing works as in
readline(supports line editing, history, arrow keys). Entersends the current line.Ctrl+Don an empty line quits.- Escape sequences are supported when input mode is Text (see below).
| Key | Action |
|---|---|
↑ / Ctrl+P |
Scroll up one line |
↓ / Ctrl+N |
Scroll down one line |
PageUp / Ctrl+B |
Scroll up one page |
PageDown / Ctrl+F |
Scroll down one page |
Home |
Jump to the very top of the buffer |
End |
Jump to the very bottom (follow new data) |
← / Ctrl+L |
Scroll left (if lines exceed screen width) |
→ / Ctrl+R |
Scroll right |
Q |
Quit (same as Ctrl+C) |
-
Text (
F2): Printable ASCII characters (32–126) are shown as‑is. Line feed (\n) ends the current line. Non‑printable bytes and control characters are displayed as\xHH. -
Raw (
F3): Every byte is shown as two hexadecimal digits, separated by a space. Example:41 42 0D 0A -
Hexdump (
F4): Classic hexdump format:address hex bytes (8‑byte groups) |ASCII representation|Lines are automatically adjusted to the terminal width.
The input mode determines how the text you type is converted into raw bytes before transmission.
- Most characters are sent as their ASCII/UTF‑8 bytes.
- Escape sequences (C‑style) are recognised after a backslash
\:
| Sequence | Meaning | Byte value |
|---|---|---|
\a |
Bell (alert) | 0x07 |
\b |
Backspace | 0x08 |
\e |
Escape | 0x1B |
\f |
Form feed | 0x0C |
\n |
Line feed (LF) | 0x0A |
\r |
Carriage return | 0x0D |
\t |
Horizontal tab | 0x09 |
\v |
Vertical tab | 0x0B |
\xHH |
Hexadecimal byte | 0xHH |
\0–\377 |
Octal byte | up to 0xFF |
- After processing escapes, the configured EOL sequence (e.g.
\r\n) is automatically appended to every line you send.
Input is a sequence of numbers, each representing one byte. Numbers can be:
- Decimal:
65(space‑separated) - Hexadecimal:
0x41or0X41 - Binary:
0b01000001 - Octal:
0101(leading zero)
Spaces are ignored, text and other characters treating "as is".
Example: hel 0x6c 0x6f 0x0A
The EOL is not added automatically in raw mode.
Input must consist of hexadecimal digits (pairs are merged into bytes).
Spaces are ignored.
Example: 41420D0A → sends four bytes: A, B, CR, LF.
- Same input syntax as Raw or Hex, respectively.
- After converting the user‑typed numbers/hex, the program calculates a 16‑bit Modbus CRC‑16 (polynomial 0xA001) and appends it (low byte first).
Example (raw): 1 3 0 0 0 10
→ sends: 01 03 00 00 00 0A C5 CD
If -d <filename> is given, all data is appended to that file.
Received lines are prefixed with < , sent lines with > .
- The program uses the library
usefull_macrosfor low‑level terminal/socket operations and logging. - Debug builds (
cmake -DDEBUG=ON) produce adebug.logfile with verbose diagnostic output. - The terminal must support at least 80 columns for comfortable hexdump viewing.
- When resizing the terminal window, the output is automatically reformatted.
GNU General Public License version 3 (or later).
See the LICENSE file or https://www.gnu.org/licenses/gpl-3.0.html.
Edward V. Emelianov edward.emelianoff@gmail.com Project page: https://github.com/eddyem/tty_term