ComChan (Communication Channel)

A Blazingly Fast Serial Monitor for Embedded Systems and Serial Communication

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)
cargo install comchan --features ratty

Verify the installation:

comchan --version

From AUR

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

# Using yay
yay -S comchan

# Using paru
paru -S comchan

From source

Build from source for the latest development version:

You can do either of the following

cargo install --git https://github.com/Vaishnav-Sabari-Girish/ComChan.git

OR

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

# Build and run
cd ComChan
cargo run --release -- --version

CLI Usage

Blazingly Fast Minimal Serial Monitor with Plotting

Usage: comchan [OPTIONS]

Options:
      --completions <COMPLETIONS>     Generate Shell completions [possible values: bash, zsh, fish, elvish, power-shell, nu]
  -p, --port <PORT>                   Serial port to connect to
  -r, --baud <BAUD>                   Baud Rate of the Serial Monitor
  -d, --data-bits <DATA_BITS>         
  -s, --stop-bits <STOP_BITS>         
      --parity <PARITY>               
      --flow-control <FLOW_CONTROL>   
  -t, --timeout <TIMEOUT_MS>          
      --reset-delay <RESET_DELAY_MS>  
  -l, --log <LOG_FILE>                Log Serial data into a file
      --list-ports                    List all available ports
      --auto                          Auto-detect USB serial port
  -v, --verbose                       
      --plot                          Launch the serial plotter
      --plot-points <PLOT_POINTS>     
  -c, --config <CONFIG_FILE>          Path to config file
      --generate-config               
      --zephyr                        Enables Zephyr Shell mode
      --export-limit <EXPORT_LIMIT>   Max points to keep in memory for export per sensor
      --plot-title <PLOT_TITLE>       Set the plot title for the exported SVG file
      --simulate                      Simulate Serial Data with no need for hardware (Use for testing ComChan)
      --csv <CSV_FILE>                Export numeric data to a CSV file while streaming serial data
      --replay <REPLAY_FILE>          Replay a previous session from its *.log or *.csv file
  -x, --hex                           Display incoming serial data in hex dump format
      --hex-pretty                    Display incoming serial data in a clean, buffered hex-dump format
      --obj <OBJ_FILE>                Path to .obj file
      --braille <BRAILLE>             Select a built-in Braille 3D model (cube, tetrahedron, octahedron) or provide a path to a custom .wrfm file
      --dark                          Exports the plot in Dark Mode
  -h, --help                          Print help
  -V, --version                       Print version

---

Common Commands

Basic Serial Monitor

Monitor serial output from your device:

comchan -p <port> -r <baud_rate>
# OR
comchan --port <port> --baud <baud_rate>

Example:

comchan -p /dev/ttyUSB0 -r 9600

Hex Dump Mode

Analyze raw binary data from industrial equipment (like Modbus RTU), custom SPI/I2C bridge payloads, or corrupted serial transmissions:

# Raw Mode: Print incoming fragmented USB bytes exactly as they arrive
comchan --auto --hex

# Pretty Mode: Buffer the incoming bytes into clean, 16-byte aligned frames
comchan --auto --hex-pretty

[!NOTE] Both hex dump modes can be safely tested locally by passing the --simulate flag!

Verbose Mode

Get detailed information about the serial connection (now uses local timestamps):

comchan -p <port> -r <baud_rate> -v

Log Mode

Save raw serial output to a log file:

comchan -p <port> -r <baud_rate> -l <log_file_name>

View example log file

CSV Data Streaming

Continuously stream parsed numeric sensor data into a clean, multi-column CSV file on-the-fly. This works perfectly alongside both standard and plotter modes.

comchan --auto --baud 115200 --csv sensor_data.csv

View example CSV file

[!NOTE] Works with --simulate (Simulate Mode) too

Serial Plotter & 2D Graphs

Visualize sensor data in real-time, with optional SVG exports:

comchan --port <port> --baud <baud_rate> --plot

Want to export the plot?

comchan -r 115200 --plot    # In the Serial plotter window press CTRL+S

The exported plot will look like this

Light mode

Dark Mode

Add a title and memory limit (Both are optional):

comchan -r 115200 --plot --plot-title "Plot Title" --export-limit 5000

3D Spatial Telemetry Dashboard

If you are streaming IMU data (Pitch, Yaw, and Roll), ComChan can render a real-time 3D dashboard directly in your terminal. The 3D view is equipped with a static global reference frame (X/Y/Z axes) overlay that remains perfectly stationary while your hardware telemetry dictates the object rotation.

While running in --plot mode, simply press Tab or 2 to switch from the 2D Line Chart to the 3D Telemetry view.

ComChan features a Graceful Degradation Pipeline for 3D graphics:

• GPU-Accelerated 3D: If compiled with --features ratty and run inside the ratty terminal emulator, it bypasses the standard grid and injects true, shaded 3D .obj models via the Ratty Graphics Protocol (RGP).
• CPU Braille Wireframe: If running in standard modern terminals (WezTerm, Kitty, Foot, Alacritty)—or if launched inside Ratty without the required compile-time feature flag—it safely falls back to a zero-dependency, math-driven Braille wireframe rendering engine.

Custom 3D Models (Ratty GPU): By default, ComChan renders a 3D Cube. If you are using the Ratty GPU-accelerated engine, you can inject your own custom .obj models using the --obj flag:

comchan --plot --auto --obj spaceship.obj

Custom 3D Models (CPU Braille): If you are using the CPU Braille wireframe engine, ComChan defaults to rendering a 3D Cube. You can change the shape to one of the built-in models (cube, tetrahedron, octahedron) or seamlessly load your own custom .wrfm wireframe files using the --braille flag:

# Use a built-in model
comchan --plot --auto --braille octahedron

# Use a custom wireframe model
comchan --plot --auto --braille path/to/my_drone.wrfm

Session Replay

Replay a previously recorded hardware session in real-time. ComChan will read the timestamps and perfectly recreate the timing of the original run. This works in both standard monitor and plotter modes!

# Replay in standard monitor mode
comchan --replay test.log

# Replay visually in plotter mode
comchan --plot --replay sensor_data.csv

[!IMPORTANT] While you can replay both files, .log files are preferred. When replaying a .csv, ComChan skips the header line, meaning your sensor labels won't be explicitly printed, but they will be plotted (they will default to generic labels like "Channel 0", "Channel 1" in plotter mode).

Automatically Detect Serial Ports

Let ComChan find your serial device automatically:

# With default baud rate (9600)
comchan --auto

# With custom baud rate
comchan --auto --baud <baud_rate>

Generate Shell Completions

Generate autocomplete scripts for your favorite shell (bash, zsh, fish, elvish, power-shell, or nu):

comchan --completions zsh > ~/.zshrc
comchan --completions nu > ~/.config/nushell/comchan-completions.nu

Simulate Mode

Want to test ComChan, the Plotter, the 3D Dashboard, or CSV Streaming without a physical microcontroller plugged in? Use simulate mode to generate mock sensor data!

comchan --simulate --plot

Zephyr Shell Mode

If you are working with Zephyr RTOS, enable the dedicated Zephyr shell mode for a better interactive experience:

comchan --auto --zephyr

Use a Configuration File

You can use a configuration file instead of command-line flags:

# Generate default configuration file
comchan --generate-config

This creates a config file at ~/.config/comchan/comchan.toml (or %APPDATA%\comchan\comchan.toml on Windows).

Example Configuration:

# ComChan Configuration File

port = "auto"
baud = 9600
data_bits = 8
stop_bits = 1
parity = "none"
flow_control = "none"
timeout_ms = 500
reset_delay_ms = 1000
verbose = false
plot = false
plot_points = 100
zephyr = false
export_limit = 1000000
plot_title = "Sensor Data"
simulate = false
csv_file = "latest_run.csv"
replay_file = "test.log"
hex_mode = false
hex_pretty = false
obj_file = "custom_model.obj"
braille = "cube" # Can also be "tetrahedron", "octahedron", or "path/to/model.wrfm"

---

Features

Current Features ✅

• Read & Write Serial Data - Monitor incoming data and send commands to your device.
• Auto-Recovery & Graceful Exit - Automatically detects broken pipes and safely shuts down or reconnects when hardware is unplugged/replugged.
• Terminal-Based Serial Plotter - Visualize multiple sensor values in real-time with automatic legends using the --plot flag.
• 3D Spatial Telemetry (IMU) - Visualize Pitch, Yaw, and Roll data in a live 3D terminal dashboard equipped with a static global reference frame (X/Y/Z axes).
• Hardware-Accelerated 3D & Graceful Fallback - Native support for the Ratty terminal (RGP) for true shaded .obj 3D rendering (with custom --obj file support), with a zero-dependency CPU-rendered Braille wireframe fallback for standard terminals (WezTerm, Kitty, Foot, etc.) featuring customizable .wrfm models.
• Runtime & Compile-Time Terminal Detection - Automatically detects your terminal emulator and active feature flags to serve the best possible rendering engine. Accurately reports states like Ratty (GPU 3D) or Ratty (Braille) directly in the status bar.
• Real-Time Session Replay - Play back previously recorded .log or .csv files natively to analyze anomalies without needing physical hardware.
• Continuous CSV Streaming - Automatically parse and log numeric sensor data into clean, multi-column .csv files on-the-fly.
• Hex Dump View - Inspect raw binary payloads with --hex for fragmented USB bus truths, or --hex-pretty for perfectly aligned, buffered 16-byte frames.
• Export Plot to SVG - Save your visualized serial data as an SVG image, complete with custom plot titles and memory-safe export limits.
• Hardware Simulation - Test ComChan functionalities and plotting without needing physical hardware connected (--simulate).
• Zephyr Shell Support - Dedicated mode for cleanly interacting with Zephyr RTOS shells.
• Shell Completions - Native tab-autocomplete support for Bash, Zsh, Fish, Elvish, PowerShell, and Nushell.
• Auto-Detect Serial Ports - Automatically find connected serial devices (--auto).
• Configuration Files - Use .toml files instead of typing out long command-line flags every time.
• Basic Logging & Local Timestamps - Save serial output to log files with accurate local time tracking.
• Control Codes - Send CTRL+L to clear the screen and nudge the device to redraw prompts natively.

Stargazers over time (Graph)

🧠 (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.

Made with ❤️ by the ComChan Community

⬆ Back to Top