-
Notifications
You must be signed in to change notification settings - Fork 13
Cli Usage
comchan is a very powerful tool depending on how it is used.
Here are the flags for comchan (As of v0.10.0). Below the standard help output, you will find a detailed explanation of what each flag does and how it affects your workflow.
Blazingly Fast Minimal Serial Monitor with Plotting
Usage: comchan [OPTIONS]
Options:
--completions <COMPLETIONS> Generate Shell completions [possible values: bash, zsh, fish, elvish, power-shell, nu]
-p, --port <PORT> Serial port to connect to
-r, --baud <BAUD> Baud Rate of the Serial Monitor
-d, --data-bits <DATA_BITS>
-s, --stop-bits <STOP_BITS>
--parity <PARITY>
--flow-control <FLOW_CONTROL>
-t, --timeout <TIMEOUT_MS>
--reset-delay <RESET_DELAY_MS>
-l, --log <LOG_FILE> Log Serial data into a file
--list-ports List all available ports
--auto Auto-detect USB serial port
-v, --verbose
--plot Launch the serial plotter
--plot-points <PLOT_POINTS>
-c, --config <CONFIG_FILE> Path to config file
--generate-config
--zephyr Enables Zephyr Shell mode
--export-limit <EXPORT_LIMIT> Max points to keep in memory for export per sensor
--plot-title <PLOT_TITLE> Set the plot title for the exported SVG file
--simulate Simulate Serial Data with no need for hardware (Use for testing ComChan)
--csv <CSV_FILE> Export numeric data to a CSV file while streaming serial data
--replay <REPLAY_FILE> Replay a previous session from its *.log or *.csv file
-x, --hex Display incoming serial data in hex dump format
--hex-pretty Display incoming serial data in a clean, buffered hex-dump format
--obj <OBJ_FILE> Path to .obj file
--braille <BRAILLE> Select a built-in Braille 3D model (cube, tetrahedron, octahedron) or provide a path to a custom .wrfm file
--dark Exports the plot in Dark Mode
--rtt View RTT logs directly via a debug probe (bypasses UART)
--elf <ELF> The Path to the compiled .elf file (Requires --rtt)
--chip <CHIP> Target chip name for probe-rs (e.g., nRF52840_xxAA) (Requires --rtt)
-h, --help Print help
-V, --version Print version
Generates native tab-autocomplete scripts for your preferred shell. Supported shells include bash, zsh, fish, elvish, power-shell, and nu. You typically pipe the output of this command into your shell's configuration file (e.g., comchan --completions zsh > ~/.zshrc).
Specifies the exact physical or virtual serial port you want to connect to. On Linux/macOS, this usually looks like /dev/ttyUSB0 or /dev/ttyACM0. On Windows, it will be a COM port like COM3.
Sets the communication speed (baud rate) of the serial monitor. This must exactly match the baud rate configured on your connected embedded device (e.g., 9600, 115200). If omitted, comchan generally defaults to 9600.
Configures the number of data bits in each transmitted character frame. For the vast majority of serial communications, this is set to 8.
Sets the number of stop bits used to signal the end of a data packet. This is typically set to 1 or 2 depending on your hardware requirements.
Configures the error-checking parity bit. Accepted values are usually none, even, or odd.
Defines the flow control method to prevent data loss if the sender is transmitting faster than the receiver can process. Options typically include none, software (XON/XOFF), or hardware (RTS/CTS).
Determines the timeout threshold in milliseconds. This sets how long comchan will wait for incoming data before determining the read operation has timed out.
Adds an artificial delay (in milliseconds) when connecting or reconnecting to a board. This is highly useful for microcontrollers that reboot upon serial connection and need a moment before they start transmitting data.
Records raw incoming serial data directly into a specified file (e.g., test.log). This runs seamlessly in the background while you monitor the data in the terminal.
A simple utility flag that scans your system and prints out a list of all currently available serial ports. The program exits immediately after listing them.
Tells comchan to bypass the need for -p and automatically find and connect to an active USB serial device. This is perfect for quick plug-and-play workflows.
Enables verbose output mode. When active, comchan provides detailed information about the serial connection status and injects accurate local timestamps into the data stream.
Transforms the standard text monitor into a real-time, terminal-based 2D Serial Plotter. It visualizes multi-channel sensor values with automatic legends. You can seamlessly hot-swap back and forth between the text monitor and the plotter by pressing Ctrl+P without dropping your connection.
Dictates the maximum number of data points visible on the plotter's X-axis at any single moment. Adjusting this allows you to zoom in on recent data or zoom out to see broader trends.
Loads parameters from a specified .toml configuration file, allowing you to bypass typing out long strings of command-line flags every time you launch the tool.
Automatically generates a default comchan.toml configuration file in your system's designated config directory (e.g., ~/.config/comchan/ on Linux/macOS or %APPDATA%\comchan\ on Windows).
Enables a dedicated formatting mode optimized specifically for the Zephyr RTOS interactive shell, ensuring clean prompts and accurate line handling.
When using the Plotter's SVG export feature (Ctrl+S), this flag sets a hard limit on how many data points are kept in memory per sensor. This acts as a safety measure to prevent massive memory bloat during hours-long logging sessions.
Assigns a custom, human-readable title to the top of your exported SVG plot.
Boots comchan using an internal mock data generator instead of looking for physical hardware. This is highly recommended for testing out the UI, Plotter, 3D Dashboard, or CSV logging features safely before connecting a real microcontroller.
An on-the-fly parsing tool that extracts numeric sensor data from the serial stream and continuously writes it into a clean, multi-column .csv file. This works perfectly alongside both standard and plotter modes.
Allows you to play back a previously recorded session natively to analyze anomalies without needing physical hardware. While you can load .csv files, .log files are preferred as they preserve header and label integrity.
Switches the serial monitor into raw hex dump mode. Instead of ASCII text, it prints the incoming fragmented binary bytes exactly as they arrive on the bus. Highly useful for debugging industrial protocols like Modbus RTU or corrupted data lines.
A cleaner, buffered version of the hex dump. It holds the incoming raw binary data and prints it out in perfectly aligned, 16-byte frames for easier visual analysis.
When utilizing the GPU-Accelerated 3D Telemetry dashboard (compiled with --features ratty and running in the Ratty terminal), this flag injects your own custom .obj 3D model into the rendering pipeline rather than using the default cube.
When running the standard CPU Braille wireframe 3D engine, this flag allows you to change the rendered shape. You can select built-in models (cube, tetrahedron, octahedron) or provide a direct path to your own custom .wrfm wireframe file.
Forces the SVG plot export (triggered via Ctrl+S in plotter mode) to render using Dark Mode styling instead of the default Light Mode.
Bypasses physical UART serial ports entirely. This enables comchan to stream zero-latency logs directly from your microcontroller's memory via SWD using probe-rs. It supports instant attachment, survives target resets, and perfectly recreates defmt colored output.
Used in conjunction with --rtt. Specifies the path to your compiled firmware .elf file, which comchan needs to accurately decode compressed defmt logs from the target.
Used in conjunction with --rtt. Specifies the exact target MCU name (e.g., nRF52840_xxAA) so the underlying probe-rs debugger knows how to interface with the hardware.
Prints the standard help menu with all available flags and options.
Prints the current installed version of comchan.