Troubleshooting & Changelog
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a technical overview of error handling, recovery mechanisms, and the historical evolution of the ComChan project. It details how the system manages communication failures across Serial, RTT, and BLE interfaces while documenting the project's progression through its versioned history.
The troubleshooting framework is built into the core monitoring and plotting loops, utilizing automated recovery strategies to maintain connection stability. The project uses git-cliff for automated changelog generation based on conventional commits, ensuring a structured record of features, bug fixes, and performance optimizations.
Sources: CHANGELOG.md, cliff.toml, README.md:144-156
Troubleshooting & Error Handling Architecture
ComChan implements a robust error handling strategy that focuses on auto-recovery and graceful degradation. Errors are propagated from the low-level communication threads (Serial, RTT, BLE) back to the main UI loop, where they are either handled via reconnection attempts or displayed to the user via status bars and modals.
Recovery Mechanisms
The system employs different recovery strategies depending on the active mode:
- Serial Monitor Recovery: Uses a polling loop to wait for the device to reappear on a specific port if a
readorwriteerror occurs. It includes a configurablereset_delay_msto wait for hardware initialization. - RTT Reconnection: If an RTT connection is lost, the system attempts to re-initialize the
RttDefmtReaderusing the provided ELF file and chip name. - BLE Lifecycle: Specifically handles disconnection events via a typed event system to prevent UI lockups during connection drops.
Sources: src/monitor.rs:374-406, src/plotter.rs:491-510, src/config.rs:434-436
Error Flow and Reporting
The following diagram illustrates how communication errors are captured and handled within the system:
The system utilizes a central last_error state in the PlotterState to display warnings without interrupting the data stream.
Sources: src/plotter.rs:88-120, src/monitor.rs:435-445
Common Configuration Errors
Many runtime issues stem from incorrect configuration parameters. The system validates these during initialization to prevent panics.
| Parameter | Validation/Constraint | Derived From |
|---|---|---|
baud | u32 value (e.g., 115200) | src/config.rs:414 |
data_bits | Validated via parse_data_bits | src/monitor.rs:171 |
stop_bits | Validated via parse_stop_bits | src/monitor.rs:172 |
parity | "none" | "odd" | "even" | src/config.rs:364 |
flow_control | "none" | "software" | "hardware" | src/config.rs:365 |
elf | Required for RTT mode | src/config.rs:218 |
Project Changelog
ComChan follows a versioned release cycle documented in CHANGELOG.md. The release process is managed using git-cliff configuration defined in cliff.toml, which groups commits into categories such as New Features, Bug Fixes, and Performance.
Sources: cliff.toml:57-66, CHANGELOG.md
Recent Release Highlights (v0.10.1 - v0.14.0)
| Version | Date | Key Improvements |
|---|---|---|
| v0.14.0 | 2026-07-06 | Monitor log indentation fixes; Binary size reduction via LTO. |
| v0.13.0 | 2026-06-30 | Scrollable sensor legend; UTF-8 panic fixes; Local readline implementation. |
| v0.12.0 | 2026-06-19 | Side-by-side dual monitor TUI; Help modals; Interactive TX input. |
| v0.11.0 | 2026-06-15 | BLE capabilities (Nordic UART Service); Typed events for BLE communication. |
| v0.10.1 | 2026-06-14 | 3D wireframe engine; RTT/defmt support; SVG export; Session replay. |
Sources: CHANGELOG.md:1-200
Evolution of Features
The project has evolved from a basic serial monitor to a comprehensive telemetry suite:
Sources: CHANGELOG.md, README.md:144-167
Implementation Details
Changelog Configuration (cliff.toml)
The project uses a Tera template to render releases. It filters commits based on conventional prefixes:
feat->:rocket: New featuresfix->:bug: Bug fixesperf->:zap: Performancerefactor->:recycle: Refactoring
Sources: cliff.toml:13-56
Reconnection Logic Example
In monitor.rs, the system handles connection loss by entering a retry loop that polls for the device without exiting the application.
// src/monitor.rs:334-345
match serialport::new(&port_name, config.baud)
.timeout(Duration::from_millis(config.timeout_ms))
.open()
{
Ok(mut p) => {
// Successful reconnection logic
}
Err(_) => {
// Retry connection every 1 second
print!("\r⏳ Waiting for device on {}...", port_name);
io::stdout().flush().ok();
continue;
}
}
Sources: src/monitor.rs:334-345
Conclusion
Troubleshooting in ComChan is a proactive process integrated into the main execution loops to ensure reliability in unstable embedded environments. The structured changelog demonstrates a consistent focus on expanding connectivity options (BLE, RTT, Dual Ports) while maintaining high performance through size optimizations and hardware acceleration.