rtcom-core 0.1.2

Core library for rtcom (Rust Terminal Communication): serial device abstraction, event bus, and session orchestration.
Documentation

rtcom

CI crates.io docs.rs License

Rust Terminal Communication — a modern, safe, cross-platform serial terminal for embedded and hardware engineers. Written in Rust, aiming for feature parity with tio while adding a native Windows backend, a first-class library API, and a pluggable architecture for future protocol decoding, scripting, and network sharing.

Features (v0.1)

  • Async serial I/O built on tokio-serial (Linux / macOS / BSD).
  • UUCP-style lock files so two rtcom instances cannot race the same device.
  • Interactive command key (^A by default, configurable via --escape) with: ?/h help, ^Q/^X quit (picocom convention), c show config, t/g toggle DTR/RTS, \ send break, b<rate><Enter> change baud rate.
  • Picocom-style startup-time modem-line control: --lower-dtr / --raise-dtr / --lower-rts / --raise-rts. The classic "open the port without resetting the Arduino-style MCU" recipe is --lower-dtr --lower-rts.
  • CR/LF mappers (--omap / --imap / --emap) following picocom's crlf / lfcr / igncr / ignlf rule names.
  • Clean shutdown on SIGINT / SIGTERM / SIGHUP (termios restored, lock file removed, exit code 128 + signum).
  • Structured diagnostics via tracing (honours RUST_LOG; -v / -vv / -vvv raises the default level).
  • End-to-end tests via socat-allocated pseudo-terminals — the full pipeline is regression-guarded.

Quick start

# Connect to a USB-serial dongle at 115200 8N1 (default)
rtcom /dev/ttyUSB0

# Change baud + parity + enable LF->CRLF on send
rtcom /dev/ttyUSB0 -b 9600 -p even --omap crlf

# Print the full option list
rtcom --help

Installation

From crates.io

cargo install rtcom-cli --locked

--locked pins the dependency versions shipped in Cargo.lock, which keeps the MSRV contract (Rust 1.85) honest.

From source

git clone https://github.com/TrekMax/rtcom
cd rtcom
cargo install --path crates/rtcom-cli --locked

On Linux you'll need libudev-dev (or the equivalent package on your distro) for the underlying serialport crate.

Pre-built binaries

Each tagged release publishes pre-built binaries for the major platforms — grab one from GitHub Releases:

Platform Architecture Asset
Linux x86_64 rtcom-x86_64-unknown-linux-gnu
Linux aarch64 rtcom-aarch64-unknown-linux-gnu
macOS Intel rtcom-x86_64-apple-darwin
macOS Apple Silicon rtcom-aarch64-apple-darwin
macOS Universal rtcom-universal-apple-darwin
Windows x86_64 rtcom-x86_64-pc-windows-msvc.exe

Each release also ships a checksums-sha256.txt so you can verify the download.

Distribution packages

Homebrew tap, AUR, and winget packages are planned for v0.2+. In the meantime, cargo install or the GitHub Releases tarball is the canonical path.

Command keys

Once a session is running, the escape key (default ^A = Ctrl-A; override with --escape '^T' etc.) puts the parser into command mode. The next byte is matched against this table; unknown keys silently return to default mode.

Key Action
? or h Print the command-key cheatsheet
^Q or ^X Quit the session cleanly (Ctrl-Q / Ctrl-X)
c Show current serial configuration
t Toggle DTR
g Toggle RTS
\ Send a 250 ms line break
b<rate><Enter> Change baud rate (e.g. ^A b 115200 <Enter>)
The escape key again Send the escape byte verbatim to the wire
Esc Cancel command mode, return to default

vs. picocom / tio

Capability picocom tio rtcom (v0.1)
Async I/O (tokio) ❌ ❌ ✅
UUCP lock files ✅ ✅ ✅
Raw-mode cleanup on any exit path ⚠️ ⚠️ ✅
CR/LF omap/imap/emap ✅ ❌ ✅
^A <key> command parser ✅ ✅ ✅
Library API (rtcom-core) ❌ ❌ ✅
Native Windows backend ❌ ❌ 🚧 v0.8
Structured logging / tracing ❌ ❌ ✅
Built-in xmodem / ymodem ❌ ❌ 🚧 v0.6

🚧 = on the roadmap.

Workspace layout

Crate Role
rtcom-core Serial device trait, event bus, session orchestrator, mappers, UUCP lock (library)
rtcom-cli rtcom binary: argument parsing, TTY setup, signal handling, main loop

Architecture

Event-driven, single-task Session wired through a tokio::broadcast bus. See docs/architecture.svg and the CLAUDE.md design document for the full rationale.

Contributing

The development plan is maintained in CLAUDE.md; §8 covers the TDD + commit-per-phase workflow the project enforces, §9 the coding conventions. Bug reports and PRs welcome — please open an issue to discuss larger changes before sending code.

Running the full test suite locally:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features

License

Apache-2.0. See LICENSE.