jterm - Serial terminal written in Python

This tool is useful when communicating with devices over a serial port or a TCP socket.

By vendoring a modified version of py_linenoise (original by Jason Harris; see jakeru/py_linenoise for the fork jterm is based on) this tool allows the user to type commands and receive data at the same time.

It has been used by me (Jakob Ruhe) for quite some time but in April 2025 published version 1.0.0 of this tool.

Features

• If an interface cannot be opened, this tool will continuously retry to open it up until a configurable amount of maximum time (or forever, which is the default).
• User may type commands while receiving data at the same time.
• Basic command line editing support (backspace, arrow keys).
• Command history is kept between sessions.
• Type a few letters and press Ctrl+p (or up arrow) to search in history.
• Data sent and received are always logged with date and time in a new log file for each session.
• Support for slow devices by introducing a configurable delay between each byte sent.
• ANSI Colors are kept on stdout but not included in the log file.
• Profiles (--profile) keep command history and logs separate per device or project.

Future improvements

• ✓ DONE: Profile support to separate history files and logs. Added in June 2025.
• ✓ DONE: Navigation using ctrl+arrow to jump between words. Added in June 2025.
• ✓ DONE: Multiline prompt. Added in June 2025.
• Configuration files.
• Wait for prompt before sending next command.
• Word completion.

Installation

Clone this repository. The destination path (~/jterm in this example) can be whatever you prefer.

git clone https://github.com/jakeru/jterm.git ~/jterm

Install other dependencies

This application requires pyserial.

Pyserial is a common package and you may therefore consider installing it system-wide.

Otherwise you can create a Python Virtual Environment for this application and install the package in it.

In the following sections, both methods are explained. Choose one of them.

Install pyserial system wide

In Ubuntu, this is the preferred way to install pyserial system wide:

apt install python3-serial

Use your favorite search engine to find out about how to install the package system wide on other platforms.

Install pyserial using a Python virtual environment

cd ~/jterm
python3 -m venv env
source env/bin/activate
pip install -e .

This installs pyserial (declared as a dependency in pyproject.toml) and jterm itself in editable mode, which also makes a jterm console command available inside the virtual environment, in addition to ./jterm.py.

Run

If the dependencies are installed system wide you may run the application like this:

~/jterm/jterm.py

If you have created a Python Virtual Environment for it, you can either first activate it, or run jterm like this:

~/jterm/env/bin/python3 ~/jterm/jterm.py

Usage

To connect to a serial port with a specific baudrate (default is 115200 bps):

jterm /dev/ttyACM0 --baudrate 9600

To connect to a TCP socket, prefix the target with socket:// (the same convention pySerial's own miniterm tool uses):

jterm socket://:1234
jterm socket://example.com:1234

Logs are saved into ~/.jterm/logs/<profile> using the current date and time as filename, where <profile> is default unless --profile is given. The parameter --log can be specified to choose a different filename for the log. Command history is likewise kept per profile, in ~/.jterm/history/<profile>.txt. For more options, supply the --help argument when launching jterm.

Requirements

Python 3.8 or newer.

Development

Install the development dependencies (ruff for formatting/linting, pytest for the unit tests) with:

pip install -e .[dev]

Then, from the repository root:

ruff format .        # format the code
ruff check . --fix   # lint, and auto-fix what can be
pytest                # run the unit tests

License

MIT, see LICENSE.