High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
ComChan is a modular, high-performance serial communication and telemetry visualization suite designed for embedded systems. It functions as a bridge between various hardware transport layers—such as standard Serial (UART), Bluetooth Low Energy (BLE), and Segger RTT/Defmt—and an interactive Terminal User Interface (TUI).
The architecture is built around three primary pillars: a unified configuration and command-line interface, a multi-threaded data ingestion engine capable of handling concurrent streams, and a reactive visualization layer that provides real-time plotting and 3D spatial telemetry.
Sources: README.md:1-12, Cargo.toml:1-15
Core System Components
The system is logically divided into input handlers, state management, and the TUI rendering engine.
Data Flow Overview
The data flow starts at the hardware or simulated source, passes through specialized readers (Serial, BLE, or RTT), and is aggregated into state structures before being rendered via ratatui.
This diagram shows how various inputs are processed through a centralized engine to feed the user interface modes.
Sources: src/config.rs:219-250, src/plotter.rs:250-320, src/dual_ports.rs:77-130
Configuration and Initialization
ComChan uses a multi-layered configuration strategy. It merges default values, external TOML configuration files, and command-line arguments into a single MergedConfig struct used throughout the application.
Configuration Merging Hierarchy
- Default Config: Hardcoded base values.
- TOML File: User-defined persistent settings (e.g.,
comchan.toml). - Command Line: Flags and options provided at execution time (highest priority).
| Component | Responsibility | Relevant Data Structure |
|---|---|---|
| CLI Parser | Parses terminal arguments using clap. | Args |
| Config Loader | Reads and deserializes .toml files. | Config |
| Merger | Reconciles Args and Config into runtime state. | MergedConfig |
Sources: src/config.rs:136-250
Multi-Threaded Input Architecture
For modes requiring concurrent processing, such as the Dual Port Monitor, ComChan utilizes Rust's multi-threading and message-passing primitives.
Dual Port Handling
In dual_mode, the application spawns independent threads for each serial port. These threads communicate back to the main UI thread via mpsc::channel.
The sequence diagram illustrates the decoupled nature of data acquisition in dual monitor mode.
Sources: src/dual_ports.rs:77-154
Visualization and 3D Engine
The Plotter mode represents the most complex part of the UI architecture, supporting both 2D time-series charts and 3D spatial orientation.
Plotter State Management
The PlotterState struct maintains sensor history, global bounds for auto-scaling, and interpolation data for smooth 3D transitions.
struct PlotterState {
sensors: HashMap<String, SensorData>,
export_data: HashMap<String, Vec<(f64, f64)>>,
active_tab: ActiveTab,
// Interpolation for 3D
display_pitch: f64,
display_yaw: f64,
display_roll: f64,
#[cfg(feature = "ratty")]
ratty_engines: Option<RattyGraphic<'static>>,
}
Sources: src/plotter.rs:80-120
3D Telemetry (ratatui-wireframe)
Spatial visualization is handled by a specialized sub-crate, ratatui-wireframe. It supports:
- Vertex Transformation: Applies rotation matrices (Pitch, Yaw, Roll) to 3D vertices.
- Projection: Projects 3D coordinates into a 2D terminal plane.
- Rendering: Uses Braille markers within a
ratatui::Canvasto achieve high-density wireframe rendering.
| Feature | Engine | Marker/Protocol |
|---|---|---|
| Standard 3D | ratatui-wireframe | Braille Marker |
| Accelerated 3D | ratatui-ratty | Ratty Graphic Protocol |
| Model Loading | wrfm / OBJ Parser | Custom/Standard Mesh |
Sources: crates/ratatui-wireframe/src/widget.rs:59-100, crates/ratatui-wireframe/src/model.rs:14-50, src/plotter.rs:465-515
Conclusion
The high-level architecture of ComChan emphasizes extensibility and responsiveness. By separating hardware communication into independent threads or optimized drain loops and utilizing a specialized wireframe engine for visualization, the system remains stable and performant even when processing high-frequency telemetry data across multiple ports or protocols.