tty_term – Terminal Serial/Socket Communication Tool

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.

Features

• 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)
• 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

Requirements

• Linux (or POSIX system with termios)
• C23 compiler (GCC or Clang)
• Libraries:
• ncurses
• readline
• usefull_macros (≥0.3.5) – snippets_library

Installation

git clone --depth=1 https://github.com/eddyem/tty_term.git
cd tty_term
mkdir build && cd build
cmake ..
make
sudo make install

By default the program is installed into /usr/local/bin.
Use -DDEBUG=ON with CMake to build a debug version with extra logging.

Usage

ttyterm [options]

You must specify the device/socket path with -n (or --name).
All other options are optional.

Command‑line options

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

User Interface

The screen is divided into three areas:

1. Message window (top, scrolling) – displays received data in the selected display mode.
2. Status bar (middle) – shows connection details, current display mode, and whether you are in
   Insert (editing) or Scroll mode.
3. Command line (bottom) – where you type data to send.

Keyboard Controls

Global (always active)

The action of F2-F6 keys depends on current mode: Insert — change input mode,
Scroll — change output mode.

Insert mode (for typing commands)

• Regular typing works as in readline (supports line editing, history, arrow keys).
• Enter sends the current line.
• Ctrl+D on an empty line quits.
• Escape sequences are supported when input mode is Text (see below).

Scroll mode (navigation)

Data Display Modes

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

Input Modes and Data Formatting

The input mode determines how the text you type is converted into raw bytes before
transmission.

Text mode (default after F2)

• Most characters are sent as their ASCII/UTF‑8 bytes.
• Escape sequences (C‑style) are recognised after a backslash \:

• After processing escapes, the configured EOL sequence (e.g. \r\n) is automatically appended
  to every line you send.

Raw mode (F3 for display, but also used as input)

Input is a sequence of numbers, each representing one byte.
Numbers can be:

• Decimal: 65 (space‑separated)
• Hexadecimal: 0x41 or 0X41
• 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.

Hex mode (F4 for display, also used as input)

Input must consist of hexadecimal digits (pairs are merged into bytes).
Spaces are ignored.
Example: 41420D0A → sends four bytes: A, B, CR, LF.

Modbus RTU modes (F5 – raw, F6 – hex)

• 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

Logging

If -d <filename> is given, all data is appended to that file.
Received lines are prefixed with <, sent lines with >.

Notes

• The program uses the library usefull_macros for low‑level terminal/socket operations and
  logging.
• Debug builds (cmake -DDEBUG=ON) produce a debug.log file 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.

License

GNU General Public License version 3 (or later).
See the LICENSE file or https://www.gnu.org/licenses/gpl-3.0.html.

Author

Edward V. Emelianov edward.emelianoff@gmail.com
Project page: https://github.com/eddyem/tty_term