# ComChan (Communication Channel)
<div align="center">
**A Blazingly Fast Serial Monitor for Embedded Systems and Serial
Communication**
</div>
[](https://crates.io/crates/comchan)
[](LICENSE)
For detailed instructions with images and videos, take a look at `comchan`'s
[wiki](https://github.com/Vaishnav-Sabari-Girish/ComChan/wiki)
## Installation
Choose your preferred installation method:
### From crates.io
> [!NOTE]
> The easiest way to install ComChan is via `cargo install`
```bash
# 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:
```bash
comchan --version
```
### From AUR
For Arch Linux users, ComChan is available in the AUR (thanks to
[orhun](https://github.com/orhun)!):
```bash
# 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
```bash
# 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`](https://github.com/Mjoyufull/Elda)
```bash
elda i https://github.com/Vaishnav-Sabari-Girish/ComChan
```
> [!NOTE]
> Credits for `elda` go to **[Rikona](https://github.com/Mjoyufull)**
### From source
Build from source for the latest development version:
```bash
# 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](https://github.com/Vaishnav-Sabari-Girish/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:
```bash
# 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`](./Grimoire.toml) or
just run
```bash
grim sigils # Or grim list
```
---
## CLI Usage
```text
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).
```bash
# 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
```bash
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.
```bash
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.
```bash
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.
```bash
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)
[](https://www.star-history.com/?repos=Vaishnav-Sabari-Girish%2FComChan&type=timeline&legend=bottom-right)
## 🧠(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.
<br>
[⬆ Back to Top](https://www.google.com/search?q=%23comchan-communication-channel)
