CLI Options & Usage Guide

Relevant source files

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

• README.md
• src/config.rs
• src/monitor.rs
• src/plotter.rs
• src/dual_ports.rs
• Grimoire.toml

ComChan is a high-performance serial monitor and plotter designed for embedded systems development. It provides a Terminal User Interface (TUI) for monitoring raw serial data, visualizing numeric telemetry in real-time, and debugging via RTT/defmt or Bluetooth Low Energy (BLE).

The tool is built in Rust and leverages clap for command-line argument parsing, allowing users to override file-based configurations directly from the terminal. Sources: README.md:1-15, src/config.rs:135-140

Configuration Management

ComChan utilizes a tiered configuration system where command-line arguments override settings found in a comchan.toml file. The application searches for configuration files in the current directory, standard platform-specific config directories (e.g., ~/.config/comchan/), or a path specified via the --config flag. Sources: src/config.rs:245-275, src/config.rs:356-385

Config File vs. CLI Priority

The following diagram illustrates how the MergedConfig struct is generated at runtime:

The merge_config_and_args function ensures that if a user provides a flag (like --baud 115200), it supersedes any value defined in the persistent configuration file. Sources: src/config.rs:356-405

Primary CLI Options

ComChan's interface is divided into connection settings, display modes, and output logging.

Connection & Port Settings

Option	Shorthand	Description	Default
--port	-p	Serial port(s) to connect to. Supports up to 2 for dual view.	auto
--baud	-r	Baud rate for the serial connection.	9600
--data-bits	-d	Number of data bits (5, 6, 7, 8).	8
--stop-bits	-s	Number of stop bits (1, 2).	1
--parity	N/A	Parity checking: none, odd, or even.	none
--flow-control	N/A	Flow control: none, software, or hardware.	none
--ble	N/A	Enable Bluetooth Low Energy (BLE) stream mode.	false

Sources: src/config.rs:141-168, src/config.rs:109-130

Operational Modes

Users can switch between different visualization engines using specific flags:

• Plotter Mode (--plot): Launches the real-time 2D line chart and 3D telemetry dashboard. Sources: src/config.rs:175, src/plotter.rs:350
• Dual Monitor Mode: Automatically triggered when two ports are provided to the --port argument (e.g., -p /dev/ttyUSB0 /dev/ttyUSB1). Sources: src/dual_ports.rs:147-155
• RTT/Defmt Mode (--rtt): Bypasses serial ports to read logs directly from a debug probe using an ELF file (--elf) and chip name (--chip). Sources: src/config.rs:222-231, src/monitor.rs:281-295
• Hex Dump (--hex / --hex-pretty): Displays incoming data as hexadecimal values rather than ASCII text. Sources: src/config.rs:207-212, src/monitor.rs:460-485

Data Flow & Processing

When ComChan starts, it initializes the selected communication backend (Serial, BLE, or RTT) and pipes the data into a processing loop.

Advanced Usage Examples

1. BLE Telemetry

To scan for and connect to a Nordic UART Service (NUS) device for wireless plotting:

comchan --ble --plot

Sources: README.md:120-125

2. Dual Serial Bridge Monitoring

To monitor two different microcontrollers interacting at a specific baud rate with logging enabled:

comchan -p /dev/ttyUSB0 /dev/ttyUSB1 -r 115200 --log bridge_debug.log

Sources: README.md:134-140, src/dual_ports.rs:150-165

3. 3D Wireframe Visualization

To view IMU data using a custom wireframe model:

comchan --plot --braille my_model.wrfm

Supported built-in models include cube, tetrahedron, and octahedron. Sources: src/config.rs:34-50, src/plotter.rs:445-460

Task Runner Integration (Grimoire)

ComChan includes a Grimoire.toml file to simplify build and installation processes, abstracting complex Cargo feature flags into interactive commands.

Command	Description
grim cast build	Compiles the project with interactive feature selection (ratty, ble).
grim cast run --simulate	Runs ComChan using internal data simulation for testing.
grim cast install	Installs the binary to ~/.cargo/bin/.

Sources: Grimoire.toml:5-45, README.md:85-105

Conclusion

The ComChan CLI is designed for flexibility, providing developers with multiple ways to interface with embedded hardware. Whether performing raw hex analysis in the standard monitor or visualizing spatial movement in the 3D plotter, the system relies on a robust configuration merging logic to maintain consistent behavior across different environments and platforms.