Terminal-Based Serial Plotter (2D)

Relevant source files

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

• src/plotter.rs
• src/config.rs
• src/monitor.rs
• src/export.rs
• README.md
• crates/ratatui-wireframe/src/widget.rs

The Terminal-Based Serial Plotter is a high-performance visualization component of the ComChan project designed to render real-time sensor data directly within a terminal environment. It provides a 2D line chart interface for monitoring numeric telemetry from serial ports, BLE streams, RTT probes, or simulated hardware.

This module allows users to toggle seamlessly between a standard Serial Monitor and the plotting interface using hotkeys. It leverages the ratatui library for its Terminal User Interface (TUI) and uses Braille characters to achieve high-resolution graph rendering within a text-based grid.

Sources: src/plotter.rs:1-40, README.md:145-165

System Architecture and Data Flow

The plotter operates on a centralized state management pattern via the PlotterState struct. Data is ingested from various sources, parsed into numeric values, and stored in a sliding window buffer for real-time rendering.

The diagram above illustrates the flow of raw serial data into the internal receive buffer, followed by parsing and state updates for the TUI.
Sources: src/plotter.rs:72-120, src/plotter.rs:360-440

Core Components

PlotterState

The PlotterState struct is the primary data structure managing the lifecycle of the plotting session. It tracks sensor values, historical data points for the 2D chart, and telemetry metadata.

Field	Type	Description
sensors	HashMap<String, SensorData>	Map of sensor names to their current and historical values.
x	f64	The current horizontal offset (sample count).
global_y_min/max	f64	Bounds used for auto-scaling the Y-axis.
export_data	HashMap<String, Vec<(f64, f64)>>	Un-trimmed data buffer for SVG export.
active_tab	ActiveTab	Toggles between 2D Chart and 3D Telemetry views.

Sources: src/plotter.rs:72-105

Data Ingestion and Parsing

The plotter utilizes a "drain loop" mechanism to pull all available bytes from the OS serial buffer before rendering a frame. This prevents the UI from lagging during high-frequency data bursts.

// DRAIN LOOP: Pull all available data from the OS buffer before rendering
let mut drain_iters = 0;
const MAX_DRAIN_SIZE: usize = 10; 

loop {
    if drain_iters >= MAX_DRAIN_SIZE { break; }
    drain_iters += 1;
    match p.bytes_to_read() {
        Ok(avail) if avail > 0 => match p.read(&mut serial_buf) {
            Ok(n) if n > 0 => {
                let chunk = String::from_utf8_lossy(&serial_buf[..n]);
                state.receive_buf.push_str(&chunk);
                // ... line processing ...
            }
            // ... error handling ...
        }
    }
}

Sources: src/plotter.rs:442-475

2D Chart Visualization

The 2D visualization is implemented using the ratatui::widgets::Chart widget. Key features include:

• Auto-scaling: The Y-axis dynamically adjusts based on the global_y_min and global_y_max values found in the current dataset.
• Braille Rendering: Uses symbols::Marker::Braille to represent data points, allowing for sub-character precision in the terminal.
• Multi-series Support: Each detected sensor is assigned a unique color and rendered as a separate line series.

Sources: src/plotter.rs:524-580

Interaction and Control

The plotter supports interactive commands to manage data flow and visualization.

Key	Action	File Reference
Space	Pause/Resume data ingestion	src/plotter.rs:336
c	Clear all historical data and reset axes	src/plotter.rs:348
Ctrl+S	Export current view to SVG	src/plotter.rs:358
Ctrl+P	Hot-swap back to Serial Monitor mode	src/plotter.rs:326
Tab	Toggle between 2D Chart and 3D Dashboard	src/plotter.rs:343

Sources: src/plotter.rs:315-390

Data Export and Logging

The system supports two primary methods for persistent data storage:

1. Continuous CSV Streaming: If configured via --csv, numeric data is written to a file in real-time as it is parsed.
2. SVG Export: Users can capture the current 2D plot as a high-quality vector graphic. This supports both light and dark modes, adjusting grid colors and background fills accordingly.

Summary

The Terminal-Based Serial Plotter (2D) provides a lightweight yet powerful tool for real-time telemetry. By integrating state-of-the-art TUI widgets with robust serial communication handling, it enables developers to visualize complex embedded system data without leaving the terminal environment. Its ability to handle multiple input streams—including BLE and RTT—makes it a versatile component in the ComChan toolchain.

Sources: src/plotter.rs:645-665, README.md:14-25