Introduction to ComChan

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CHANGELOG.md
• src/config.rs
• src/monitor.rs
• src/plotter.rs
• src/dual_ports.rs
• src/export.rs
• Cargo.toml
• BRAILLE.md

ComChan (Communication Channel) is a high-performance, minimal serial monitor designed for embedded systems and serial communication. It is written in Rust and emphasizes speed, providing a terminal-based interface (TUI) for monitoring, plotting, and analyzing data from various sources including physical UART ports, Bluetooth Low Energy (BLE), and SWD/J-Link via RTT/Defmt.

The system facilitates real-time data visualization through a 2D line plotter and a 3D spatial telemetry dashboard. It supports advanced debugging workflows such as dual-monitor side-by-side views for inter-microcontroller communication, hex-dump inspection for raw binary payloads, and session replays for post-processing recorded data.

Sources: README.md:1-24, Cargo.toml:1-15, src/config.rs:114-120

Core System Architecture

ComChan is structured as a modular CLI application that transitions between different execution modes based on user input and configuration. The system utilizes ratatui for its terminal interface and crossterm for terminal manipulation.

Data Flow Overview

The application follows a central processing loop that ingests data from a selected transport layer, parses it, and then routes it to a specific visualization or logging component.

The diagram illustrates how incoming data streams are handled by the parser before being directed to the active visualization mode.
Sources: src/monitor.rs:170-175, src/plotter.rs:310-315, src/dual_ports.rs:90-100

Operational Modes

Mode	Purpose	Key Features
Normal Monitor	Standard serial communication	Read/Write UART, Hex dump, RTT support
Dual Monitor	Debugging two ports at once	Split-pane TUI, independent scrolling
Plotter	Data visualization	2D Line Chart, 3D Wireframe, SVG Export
Replay	Post-mortem analysis	Replay .log or .csv files in real-time

Sources: README.md:120-155, src/config.rs:120-180

Configuration and Argument Parsing

The application utilizes a hierarchical configuration system where command-line arguments override settings defined in a comchan.toml file. The MergedConfig struct serves as the single source of truth for all modules during runtime.

Configuration Fields

Parameter	Type	Default	Description
baud	u32	9600	Baud rate for serial communication
port	Option<Vec<String>>	None	Path(s) to serial device(s)
hex_mode	bool	false	Enable raw hex dump view
plot	bool	false	Launch directly into plotter mode
braille	BrailleModel	Cube	3D model for telemetry

Sources: src/config.rs:80-110, src/config.rs:250-290

Telemetry and 3D Visualization

A standout feature of ComChan is its ability to visualize 3D orientation (Pitch, Yaw, Roll) using a CPU-rendered Braille wireframe engine or hardware-accelerated rendering.

3D Model Processing

ComChan supports built-in primitives and custom models. If the ratty feature is enabled, the system can render standard .obj files; otherwise, it defaults to a zero-dependency Braille engine using .wrfm files.

This sequence shows the transformation of raw sensor readings into visual terminal output.
Sources: src/plotter.rs:550-580, BRAILLE.md:1-20, crates/ratatui-wireframe/src/widget.rs:50-80

Built-in Models

• Cube: Default standard wireframe for general movement.
• Tetrahedron: Triangular pyramid useful for indicating directional heading.
• Octahedron: Symmetrical diamond shape for complex spatial rotations.

Sources: BRAILLE.md:10-35, src/config.rs:20-40

Data Persistence and Exporting

ComChan provides robust logging and exporting capabilities to ensure data can be analyzed outside the TUI environment.

Export Systems

1. Logging: Raw serial data is appended to log files with local timestamps.
2. CSV Streaming: Numeric data parsed from incoming lines is streamed to CSV files on-the-fly.
3. SVG Export: 2D plots can be exported to high-quality SVG files, supporting both light and dark modes.

Sources: src/export.rs:15-50, src/export.rs:115-130, README.md:148-150

pub fn write_row(&mut self, parsed_data: &[(String, f64)]) -> std::io::Result<()> {
    if parsed_data.is_empty() { return Ok(()); }
    if !self.header_written {
        // ... header logic ...
    }
    write!(self.writer, "{}", get_timestamp())?;
    // ... write sensor values ...
    self.writer.flush()?;
    Ok(())
}

Sources: src/export.rs:133-155

Conclusion

ComChan serves as a versatile tool for embedded developers, combining the utility of a standard serial monitor with sophisticated visualization capabilities. By supporting a wide array of transport protocols and rendering techniques, it enables comprehensive real-time debugging and data analysis within a lightweight, terminal-based workflow.

Sources: README.md:160-170, CHANGELOG.md:100-115