sterm is a minimal serial terminal that focus on being easy to use. - This client just does its job.
pip install sterm
sterm --help
sterm /dev/ttyUSB0
sterm is a minimal serial terminal that focus on being easy to use and not sucking. - This client simply works. It has inline input and supports Unicode (utf-8). Each character typed gets directly send to the connected device without buffering. It writes whatever it receives to stdout so that also Unicode and ANSI escape sequences work as expected.
Ideal for debugging:
With the --binary
option, the received data will be output byte wise as hexadecimal numbers.
Ideal for a remote Linux shell:
With the --noecho
option, each character typed gets directly send to the connected device without buffering and echoing.
This makes the Linux console usage seamlessly like using telnet or ssh.
- Inline input
- No line buffering
- Unicode support
- ANSI Escape Sequences supported
- No GUI
There are two ways to install sterm.
A: Directly using pip
or B: from the cloned repository.
sterm requires Python 3.8+ to run.
Before you start installing sterm make sure you use the correct version.
Depending on your distribution, the you may need to use pip3
instead of pip
.
You can check your Python version by executing the following commands:
python --version
pip --version
Both should print a version number beginning with 3.
If not, you need to use pip3
to explicit use Python 3.
For a user-only installation, call pip ...
as user.
For a system-wide installation you need to be root, or call sudo pip ...
.
pip install sterm
# Download
git clone https://github.com/rstemmer/sterm.git
cd sterm
# Dependencies
pip install pyserial
# Install Package
pip install .
After installation you can check if sterm is successfully installed using whereis
.
whereis sterm
#Outpu: sterm: /usr/bin/sterm /usr/man/man1/sterm.1
There should be two files listed.
sterm
is the executable, the command you run.sterm.1
is the manual forsterm
that can be read by executingman sterm
on the command line.
On a system-wide installation, sterm is usually installed to /usr/bin. If you only installed to for a single user, it is usually installed to ~/.local/bin
During the installation process, pip
should install all dependencies recursively.
To be sure nothing is missing, you can run pip check sterm
.
It prints all missing dependencies or version conflicts.
You can install missing dependencies via pip
.
When version conflicts are listed, you can hope they do not matter or install an explicit version via pip
as well.
To execute sterm you just have to call the sterm
command in your shell.
sterm
requires one argument, the device you want to access.
All other arguments listed in the subsection below are optional.
UART-Devices are listed in the /dev directory with the prefix tty
.
Most UART-Devices are addressable via /dev/ttyUSBx or /dev/ttyACMx were x is a number depending on the order they got recognized by the Linux kernel.
sterm has two interfaces:
- The command line interface
- Escape commands
sterm [-h] [--noecho] [--escape character] [--binary] [-b BAUDRATE] [-f FORMAT] [-w logfile] DEVICE
When a command line argument is contradictory to a setting in the configuration files, the command line argument has higher priority.
- -h: Print help.
- -n: Enable noecho mode. Default is echoing each entered key to stdout.
- --escape: Define an alternative escape character. Default is escape ("\e").
- --binary: Print hexadecimal values instead of Unicode characters. (Only applied on output, input will still be UTF-8)
- -b: Baudrate. Default: 115200 baud.
- -f: Configuration-triple: xyz with x = bytelength in bits {5,6,7,8}; y = parity {N,E,O}; z = stopbits {1,2}. Default: "8N1" - 8 data bits, no parity bits and 1 stop bit.
- -w: Write received data into a file.
DEVICE is the path to the serial terminal. For example /dev/ttyS0, /dev/ttyUSB0, /dev/ttyUART0, /dev/ttyACM0, /dev/pts/42.
For details read the man-page.
The following strings can be entered while sterm is running. Just hit the escape-key and then enter the commands. They get not send to the device. Instead they are interpreted by sterm. The preceded escape character can be defined with --escape. Default is the escape key ("\e").
- exit: quit sterm
- version: print version
Send ping to UART0 and exit:
sterm /dev/ttyUART0
ping
pong
^[exit
Send hello to a serial device with 9600 baud, 7 data bits, even parity, and 2 stop bits. Then exit:
sterm -b 9600 -f 7E2 /dev/ttyS0
hello
world
^[exit
Connecting to a Linux device
sterm --noecho --escape _ /dev/ttyUSB0
~# whoami
root
~# _exit
Communicating with two sterm instances via a pseudo terminal for testing:
To test sterm from the sources, just call the test.py
script.
It runs the command line interface of sterm.
You can use socat
to create a virtual serial connection with two endings, so that you can use two sterm
processes to communicate with each other:
socat -d -d pty,raw,echo=0 pty,raw,echo=0
To build a new package from the source code, just execute the pkg-make.sh
script.
Make sure to update the version number in the sterm/cli.py
file.
This version number, as well as the README.md file gets read by the setup.py file.
vim sterm/cli.py
./pkg-make.sh
- tio A more feature rich alternative to
sterm
with a similar motivation
- @kylelobo for this README template
- The pyserial project that is the base of sterm