# High Level Overview

## Purpose

The Serial Commander is a terminal user interface (TUI) for sending commands to an STM32 CAN board over a serial connection. It provides a live split-screen view of outgoing commands and incoming serial data, with editable motor and PIO parameters.

## Prerequisites

The STM32 firmware must be built with serial command reception enabled. The firmware must parse newline-terminated ASCII strings from UART/USB-CDC and handle the following command tokens:

- `<span class="editor-theme-code">speed <erpm></span>`
- `<span class="editor-theme-code">stop</span>`
- `<span class="editor-theme-code">profile <erpm> <accel> <time_ms></span>`

Without this firmware support the TUI will open and display incoming data, but sent commands will have no effect aside form rebuilding and flashing the firmware

## Core Responsibilities

The tool handles three concerns in one interface:

- **Command dispatch**<span style="white-space: pre-wrap;"> — sends formatted serial strings (</span>`<span class="editor-theme-code">speed</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">stop</span>`<span style="white-space: pre-wrap;">, </span>`<span class="editor-theme-code">profile</span>`) to the STM32 on keypress
- **Live serial monitoring**<span style="white-space: pre-wrap;"> — streams and colour-codes all incoming serial output in real time</span>
- **PIO integration**<span style="white-space: pre-wrap;"> — triggers PlatformIO build/flash operations without leaving the terminal</span>

## Architecture

Three concurrent components run during a session:

**Main TUI Loop**<span style="white-space: pre-wrap;"> — Draws the interface at 100 ms intervals, handles keypresses, and dispatches commands or parameter edits. Runs on the main thread via </span>`<span class="editor-theme-code">curses.wrapper</span>`.

**Serial Reader Thread**<span style="white-space: pre-wrap;"> — Daemon thread that continuously calls </span>`<span class="editor-theme-code">ser.readline()</span>`<span style="white-space: pre-wrap;"> and appends decoded lines to a shared </span>`<span class="editor-theme-code">rx_log</span>`<span style="white-space: pre-wrap;"> deque. Terminates automatically when the serial connection drops.</span>

**PIO Runner Thread**<span style="white-space: pre-wrap;"> — Spawned on demand when the user triggers a build. Runs </span>`<span class="editor-theme-code">pio run -t <target> -e <env></span>`<span style="white-space: pre-wrap;"> as a subprocess and streams stdout into </span>`<span class="editor-theme-code">rx_log</span>`. Does not block the TUI.

<span style="white-space: pre-wrap;">All three components share </span>`<span class="editor-theme-code">rx_log</span>`<span style="white-space: pre-wrap;"> and </span>`<span class="editor-theme-code">tx_log</span>`<span style="white-space: pre-wrap;"> as </span>`<span class="editor-theme-code">collections.deque(maxlen=200)</span>`<span style="white-space: pre-wrap;"> — thread-safe for the single-producer/single-consumer append and iteration patterns used here.</span>