<h3 align="center">sterm</h3>
<div align="center">
Status: 🟢 Active - License: GPL v3
</div>
---
<p align="center"> sterm is a minimal serial terminal that focus on being easy to use. - This client just does its job.
<br/>
</p>
```bash
pip install sterm
sterm --help
sterm /dev/ttyUSB0
```
## 📝 Table of Contents
- [About](#about)
- [Getting Started](#getting_started)
- [Usage](#usage)
- [Built Using](#built_using)
- [Related Work](#related_work)
- [Acknowledgments](#acknowledgement)
## 🧐 About <a name = "about"></a>
**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.
### Core Use-Cases
*Ideal for debugging:*<br/>
With the ``--binary`` option, the received data will be output byte wise as hexadecimal numbers.
*Ideal for a remote Linux shell:*<br/>
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.
### Core Features
- Inline input
- No line buffering
- Unicode support
- ANSI Escape Sequences supported
- No GUI
## 🏁 Getting Started <a name = "getting_started"></a>
There are two ways to install _sterm_.
**A:** Directly using `pip` or **B:** from the cloned repository.
### Precondition
_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:
```bash
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 ...`.
### A: Installation using pip
```bash
pip install sterm
```
### B: Installation from Repository
```bash
# Download
git clone https://github.com/rstemmer/sterm.git
cd sterm
# Dependencies
pip install pyserial
# Install Package
pip install .
```
### Check installation
After installation you can check if _sterm_ is successfully installed using `whereis`.
```bash
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 for `sterm` that can be read by executing `man 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.
## 🎈 Usage <a name="usage"></a>
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:
1. The command line interface
2. Escape commands
### Command Line Arguments
```bash
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.
### Escape commands
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
### Examples
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:
## ⛏️ Building and Testing <a name = "built_using"></a>
### 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:
```bash
socat -d -d pty,raw,echo=0 pty,raw,echo=0
```
### Building a new Package
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.
```bash
vim sterm/cli.py
./pkg-make.sh
```
## ⛓ Related Work <a name ="related_work"></a>
- [tio](https://github.com/tio/tio) A more feature rich alternative to `sterm` with a similar motivation
## 🎉 Acknowledgements <a name = "acknowledgement"></a>
- [@kylelobo](https://github.com/kylelobo) for [this README template](https://github.com/kylelobo/The-Documentation-Compendium)
- [The pyserial project](https://github.com/pyserial/pyserial) that is the base of _sterm_
Raw data
{
"_id": null,
"home_page": "https://github.com/rstemmer/sterm",
"name": "sterm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "serial-communication serial-terminal terminal uart rs232 monitoring tty pyserial serial",
"author": "Ralf Stemmer",
"author_email": "ralf.stemmer@gmx.net",
"download_url": "https://files.pythonhosted.org/packages/f9/a0/99d5e09f44d760da3bd2bc3277b9c90d61e01c199e1079c0ab5a08d177b7/sterm-6.0.3.tar.gz",
"platform": null,
"description": "<h3 align=\"center\">sterm</h3>\n\n<div align=\"center\">\n Status: \ud83d\udfe2 Active - License: GPL v3\n</div>\n\n---\n\n<p align=\"center\"> sterm is a minimal serial terminal that focus on being easy to use. - This client just does its job.\n <br/>\n</p>\n\n```bash\npip install sterm\nsterm --help\nsterm /dev/ttyUSB0\n```\n\n\n## \ud83d\udcdd Table of Contents\n- [About](#about)\n- [Getting Started](#getting_started)\n- [Usage](#usage)\n- [Built Using](#built_using)\n- [Related Work](#related_work)\n- [Acknowledgments](#acknowledgement)\n\n\n## \ud83e\uddd0 About <a name = \"about\"></a>\n\n**sterm** is a minimal serial terminal that focus on being easy to use and not sucking. - This client simply works.\nIt has inline input and supports Unicode (utf-8).\nEach character typed gets directly send to the connected device without buffering.\nIt writes whatever it receives to *stdout* so that also Unicode and ANSI escape sequences work as expected.\n\n### Core Use-Cases\n\n*Ideal for debugging:*<br/>\nWith the ``--binary`` option, the received data will be output byte wise as hexadecimal numbers.\n\n*Ideal for a remote Linux shell:*<br/>\nWith the ``--noecho`` option, each character typed gets directly send to the connected device without buffering and echoing.\nThis makes the Linux console usage seamlessly like using telnet or ssh.\n\n### Core Features\n\n- Inline input\n- No line buffering\n- Unicode support\n- ANSI Escape Sequences supported\n- No GUI\n\n\n## \ud83c\udfc1 Getting Started <a name = \"getting_started\"></a>\n\nThere are two ways to install _sterm_.\n**A:** Directly using `pip` or **B:** from the cloned repository.\n\n### Precondition\n\n_sterm_ requires Python 3.8+ to run.\nBefore you start installing _sterm_ make sure you use the correct version.\nDepending on your distribution, the you may need to use `pip3` instead of `pip`.\nYou can check your Python version by executing the following commands:\n\n```bash\npython --version\npip --version\n```\n\nBoth should print a version number beginning with 3.\nIf not, you need to use `pip3` to explicit use Python 3.\n\nFor a user-only installation, call `pip ...` as user.\nFor a system-wide installation you need to be root, or call `sudo pip ...`.\n\n### A: Installation using pip\n\n```bash\npip install sterm\n```\n\n### B: Installation from Repository\n\n```bash\n# Download\ngit clone https://github.com/rstemmer/sterm.git\ncd sterm\n\n# Dependencies\npip install pyserial\n\n# Install Package\npip install .\n\n```\n\n### Check installation\n\nAfter installation you can check if _sterm_ is successfully installed using `whereis`.\n```bash\nwhereis sterm\n#Outpu: sterm: /usr/bin/sterm /usr/man/man1/sterm.1\n```\nThere should be two files listed.\n - `sterm` is the executable, the command you run.\n - `sterm.1` is the manual for `sterm` that can be read by executing `man sterm` on the command line.\n\nOn a system-wide installation, _sterm_ is usually installed to /usr/bin.\nIf you only installed to for a single user, it is usually installed to ~/.local/bin\n\nDuring the installation process, `pip` should install all dependencies recursively.\nTo be sure nothing is missing, you can run `pip check sterm`.\nIt prints all missing dependencies or version conflicts.\nYou can install missing dependencies via `pip`.\nWhen version conflicts are listed, you can hope they do not matter or install an explicit version via `pip` as well.\n\n\n## \ud83c\udf88 Usage <a name=\"usage\"></a>\n\nTo execute _sterm_ you just have to call the `sterm` command in your shell.\n`sterm` requires one argument, the device you want to access.\nAll other arguments listed in the subsection below are optional.\n\nUART-Devices are listed in the /dev directory with the prefix `tty`.\nMost 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.\n\n\n*sterm* has two interfaces:\n\n1. The command line interface\n2. Escape commands\n\n\n### Command Line Arguments\n\n```bash\nsterm [-h] [--noecho] [--escape character] [--binary] [-b BAUDRATE] [-f FORMAT] [-w logfile] DEVICE\n```\n\nWhen a command line argument is contradictory to a setting in the configuration files, the command line argument has higher priority.\n\n * __-h__: Print help.\n * __-n__: Enable _noecho_ mode. _Default_ is echoing each entered key to _stdout_.\n * __--escape__: Define an alternative escape character. _Default_ is escape (\"\\e\").\n * __--binary__: Print hexadecimal values instead of Unicode characters. (Only applied on output, input will still be UTF-8)\n * __-b__: Baudrate. _Default:_ 115200 baud.\n * __-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.\n * __-w__: Write received data into a file.\n\n_DEVICE_ is the path to the serial terminal.\nFor example _/dev/ttyS0_, _/dev/ttyUSB0_, _/dev/ttyUART0_, _/dev/ttyACM0_, _/dev/pts/42_.\n\nFor details read the man-page.\n\n### Escape commands\n\nThe following strings can be entered while _sterm_ is running.\nJust hit the escape-key and then enter the commands.\nThey get not send to the device.\nInstead they are interpreted by _sterm_.\nThe preceded escape character can be defined with --escape.\nDefault is the escape key (\"\\e\").\n\n * __exit__: quit sterm\n * __version__: print version\n\n### Examples\n\nSend _ping_ to UART0 and exit:\n```\nsterm /dev/ttyUART0\nping\npong\n^[exit\n```\n\nSend _hello_ to a serial device with 9600 baud, 7 data bits, even parity, and 2 stop bits. Then exit:\n```\nsterm -b 9600 -f 7E2 /dev/ttyS0\nhello\nworld\n^[exit\n```\n\nConnecting to a Linux device\n```\nsterm --noecho --escape _ /dev/ttyUSB0\n~# whoami\nroot\n~# _exit\n```\n\nCommunicating with two _sterm_ instances via a pseudo terminal for testing:\n![A picture that demonstrates the possibility of receiving ANSI escape sequences and unicode charaters](/stermscreenshot.png?raw=true \"Testrun showing some capabilities of sterm\")\n\n\n## \u26cf\ufe0f Building and Testing <a name = \"built_using\"></a>\n\n### Testing\n\nTo test _sterm_ from the sources, just call the `test.py` script.\nIt runs the command line interface of _sterm_.\n\nYou 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:\n\n```bash\nsocat -d -d pty,raw,echo=0 pty,raw,echo=0\n```\n\n### Building a new Package\n\nTo build a new package from the source code, just execute the `pkg-make.sh` script.\nMake sure to update the version number in the `sterm/cli.py` file.\nThis version number, as well as the README.md file gets read by the setup.py file.\n\n```bash\nvim sterm/cli.py\n./pkg-make.sh\n```\n\n## \u26d3 Related Work <a name =\"related_work\"></a>\n\n - [tio](https://github.com/tio/tio) A more feature rich alternative to `sterm` with a similar motivation\n\n## \ud83c\udf89 Acknowledgements <a name = \"acknowledgement\"></a>\n\n- [@kylelobo](https://github.com/kylelobo) for [this README template](https://github.com/kylelobo/The-Documentation-Compendium)\n- [The pyserial project](https://github.com/pyserial/pyserial) that is the base of _sterm_\n\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "A minimal serial / UART command line terminal that focus on being easy to use.",
"version": "6.0.3",
"project_urls": {
"Documentation": "https://github.com/rstemmer/sterm",
"Homepage": "https://github.com/rstemmer/sterm",
"Source": "https://github.com/rstemmer/sterm",
"Tracker": "https://github.com/rstemmer/sterm/issues"
},
"split_keywords": [
"serial-communication",
"serial-terminal",
"terminal",
"uart",
"rs232",
"monitoring",
"tty",
"pyserial",
"serial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e8e80a6721ebe1de574dd619a7fe7e8e4216655aebdabb3d389d6435df0f974",
"md5": "417ba895b609afb5253390ab760583b5",
"sha256": "6413c838b934a470c2a97dcc70004b3795db7686edc0935e3825f56cc34970e6"
},
"downloads": -1,
"filename": "sterm-6.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "417ba895b609afb5253390ab760583b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27577,
"upload_time": "2023-11-12T15:56:47",
"upload_time_iso_8601": "2023-11-12T15:56:47.622475Z",
"url": "https://files.pythonhosted.org/packages/3e/8e/80a6721ebe1de574dd619a7fe7e8e4216655aebdabb3d389d6435df0f974/sterm-6.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9a099d5e09f44d760da3bd2bc3277b9c90d61e01c199e1079c0ab5a08d177b7",
"md5": "db7e653b8a7645c909351305fcb0ae62",
"sha256": "221e365f48a2f118bb54883669badbfa806c76041004da0cd7dbe6f53743a556"
},
"downloads": -1,
"filename": "sterm-6.0.3.tar.gz",
"has_sig": false,
"md5_digest": "db7e653b8a7645c909351305fcb0ae62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27882,
"upload_time": "2023-11-12T15:56:50",
"upload_time_iso_8601": "2023-11-12T15:56:50.190235Z",
"url": "https://files.pythonhosted.org/packages/f9/a0/99d5e09f44d760da3bd2bc3277b9c90d61e01c199e1079c0ab5a08d177b7/sterm-6.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-12 15:56:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rstemmer",
"github_project": "sterm",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sterm"
}
JSON
