comchan 0.15.0

A Blazingly Fast and Minimal Serial Monitor for Embedded Applications
comchan-0.15.0 is not a library.

ComChan (Communication Channel)

Banner

A Blazingly Fast Serial Monitor for Embedded Systems and Serial Communication

Crates info License: MIT Rust

For detailed instructions with images and videos, take a look at comchan's wiki

Installation

Choose your preferred installation method:

From crates.io

[!NOTE] The easiest way to install ComChan is via cargo install

# Install from source (Standard Braille Engine)
cargo install comchan

# Install with Hardware-Accelerated 3D support (Ratty Terminal) and BLE
cargo install comchan --features ratty,ble

Verify the installation:

comchan --version

From AUR

For Arch Linux users, ComChan is available in the AUR (thanks to orhun!):

# ComChan with default features (No 3D/BLE)
## Using yay
yay -S comchan
## Using paru 
paru -S comchan

# ComChan with 3D (no BLE) 
## Using yay 
yay -S comchan-ratty
## Using paru
paru -S comchan-ratty

The Binary

# Using binstall (Has ratty and BLE)
cargo binstall comchan

# AUR 
yay -S comchan-bin
paru -S comchan-bin

[!NOTE] The binary is packaged with the ratty and ble features enabled, which means you can install the binary if your machine is unable to compile comchan with the ratty and ble features.

Using elda

comchan can also be installed using elda

elda i https://github.com/Vaishnav-Sabari-Girish/ComChan

[!NOTE] Credits for elda go to Rikona

From source

Build from source for the latest development version:

# Clone from GitHub
git clone https://github.com/Vaishnav-Sabari-Girish/ComChan.git

# Build and run with all features
cd ComChan
cargo run --release --features ble,ratty -- --version

🪄 Magic Workflow (Powered by Grimoire)

ComChan uses Grimoire as its official task runner to make building, running, and installing completely effortless. Grimoire provides interactive Terminal UI menus so you never have to memorize Cargo feature flags again!

If you have Grimoire installed (cargo install grim), you can cast these spells (tasks) directly in the cloned repository:

# Compile the project (Interactive prompt for 'ratty' / 'ble' features)
grim cast build     # You can also use grim run (cast and run are the same commands)

# Run the project locally 
grim cast run --simulate

# Install the binary directly to ~/.cargo/bin/ (Interactive feature prompt)
grim cast install

# Clean all build artifacts
grim cast clean

To view all the commands, refer to the Grimoire.toml or just run

grim sigils   # Or grim list

CLI Usage

Blazingly Fast Minimal Serial Monitor with Plotting

Usage: comchan [OPTIONS]

Options:
      --completions <COMPLETIONS>      Generate Shell completions
  -p, --port <PORT>                    Serial port to connect to (or 'BLE_STREAM' for Bluetooth)
      --ble                            Start ComChan in Bluetooth Low Energy (BLE) stream mode
  -r, --baud <BAUD>                    Baud Rate of the Serial Monitor
  -l, --log <LOG_FILE>                 Log data into a file
  -v, --verbose                        Enable verbose output
      --plot                           Launch the serial plotter
  -c, --config <CONFIG_FILE>           Path to config file
  -x, --hex                            Display incoming data in hex dump format
  -h, --help                           Print help
  -V, --version                        Print version
  # ... (and many more)

Common Commands

BLE Streaming (Nordic UART Service)

ComChan supports streaming data wirelessly from BLE-enabled embedded devices (like the nRF52 series) using the standard Nordic UART Service (NUS).

# Start ComChan in BLE mode to scan and connect to a peripheral
comchan --ble

ComChan will scan for devices, prompt you to select your target, and automatically subscribe to the NUS TX characteristic. You can seamlessly switch between the raw monitor and the plotter (--plot) using Ctrl+P while the BLE stream is active.

Basic Serial Monitor

comchan -p /dev/ttyUSB0 -r 115200

Dual Monitor Side-by-Side View

Monitor two serial ports simultaneously in a split-pane TUI. Perfect for debugging UART/CAN bridges or inter-microcontroller communication.

comchan -p /dev/ttyUSB0 /dev/ttyUSB1 -r 115200

# Test it out using the built-in simulator!
comchan --simulate -p mock1 mock2

[!TIP] The dual monitor features independent pane auto-scrolling. Press ? at any time to open the interactive help modal for shortcuts to switch active panes, scroll through history, and more. Logging (--log) and CSV streaming (--csv) will also automatically split into two separate files to prevent data mixing!

RTT & Defmt Debug Probe Mode

Bypass physical UART serial ports entirely! ComChan can stream zero-latency logs directly from your microcontroller's memory via SWD.

comchan --rtt --elf path/to/firmware.elf --chip nRF52840_xxAA

Plotter & 3D Spatial Telemetry

Visualize sensor data in real-time. Use Tab or 2 to toggle between the 2D Line Chart and the 3D Telemetry Dashboard.

comchan --port /dev/ttyUSB0 --baud 115200 --plot

Features

Current Features ✅

  • BLE Support - Stream data wirelessly via Nordic UART Service (NUS).
  • Dual Monitor Side-by-Side View - View two serial ports simultaneously in a split-pane TUI with independent scrollbars and auto-split logging.
  • Read & Write Serial Data - Monitor incoming data and send commands.
  • Instant Mode Hot-Swapping - Seamlessly toggle between Monitor and Plotter via Ctrl+P.
  • RTT & Defmt Support - Stream logs via SWD/J-Link directly from memory.
  • Auto-Recovery & Graceful Exit - Robust handling of connection drops and hardware resets.
  • Terminal-Based Serial Plotter - Visualize sensor values with auto-scaling.
  • 3D Spatial Telemetry (IMU) - Real-time 3D rotation dashboard.
  • Real-Time Session Replay - Replay previously recorded .log or .csv files.
  • Continuous CSV Streaming - Stream parsed numeric data to CSV on-the-fly.
  • Hex Dump View - Inspect raw binary payloads with --hex or --hex-pretty.
  • Export Plot to SVG - Save visualizations as high-quality SVGs.
  • Hardware Simulation - Generate mock sensor data for testing without hardware.

Stargazers over time (Graph)

Star History Chart

🧠 (mostly) Brain made

This project was NOT vibe-coded BUT AI is still involved in some parts of it.

  • Generating test code: Because it's something I always skip so I would rather have some AI generated tests than none at all.
  • Micro-improvements: I have used AI as an advisor to improve some bits of code here and there. Big refactors or new features are done by my hand though.

img

⬆ Back to Top