tcad-bodeplot/uart_example/implementation_plan_multi.md

UART Terminal Multi-Port Implementation Plan

The goal is to modify the UART Terminal to support multiple concurrent serial port sessions. We will introduce a sidebar panel on the left to display all sessions (e.g., active/inactive state, baud rate, and custom names) and a main workspace on the right to manage the configuration and terminal log of the currently selected session.

User Review Required

Important

• Default Session: On app load, a default "Session 1" will be created and selected. This ensures that users who just want to use a single port don't have to perform any additional clicks.
• Concurrent Connections: Each session will maintain its own active connection, serial reader loop, terminal logs, and configurations. This allows the user to have multiple serial devices connected and communicating simultaneously, switching between them at will without losing context or scroll history.
• Session Renaming: Users can double-click a session name in the sidebar to rename it to something descriptive (e.g., "MCU 1", "GPS Module").

Proposed Changes

UI / Layout Configuration

[MODIFY] index.html

• Wrap the <main class="app-main"> and a new <aside class="app-sidebar"> inside a container <div class="app-layout">.
• Adjust container structure:
  • Increase .app-container max-width to 1200px to comfortably host the sidebar and terminal split.
  • Implement dynamic placeholders for the terminal output elements. Instead of a single #terminal-output div, we'll make #terminal-container host dynamically created terminal-output elements for each session, toggling their visibility based on the active session.
• Add an "Add Session" (#add-session-btn) button to the sidebar.

[MODIFY] index.css

• Increase .app-container max-width to 1200px.
• Add rules for .app-layout (CSS Grid or Flexbox layout, split 260px and 1fr).
• Add styles for the sidebar (.app-sidebar):
  • .sidebar-header (flex row, title, add-session button).
  • .session-list (flex column, scrolling).
  • .session-item (states: hover, active, status-dots, title/subtitle, hover delete button).
  • .session-rename-input (input box replacing title on double-click).
• Add support for displaying/hiding terminal sessions via class .hidden { display: none !important; }.

State & Logic Configuration

[MODIFY] app.js

• Define a PortSession class to encapsulate all states of a single UART connection:
  • ID, name, connection state, terminal DOM element, log buffers, input text cache.
  • Port options: baudRate, dataBits, stopBits, parity.
  • Terminal configs: scrollMode, displayFormat, sendFormat, sendEol.
• Maintain global variables:
  • sessions array.
  • activeSession pointer.
• Refactor connection functions (connectSerial, disconnectSerial, startReadingLoop, sendData) to execute against the active session's parameters.
• Re-route UI change listeners (Baud Rate selector, display formats, send input, etc.) to update properties on activeSession when changed.
• Build functions to:
  • Add a session (addSession()).
  • Select/Activate a session (activateSession(session)).
  • Delete/Remove a session (deleteSession(session)).
  • Sync UI selectors with active session states.

Verification Plan

Automated Tests

We will run npm run dev or a local static files server to review the layout, and use our understanding of the DOM state to ensure multiple concurrent sessions behave correctly.

Manual Verification

1. Multiple Tabs: Add 3 ports in the sidebar. Verify they are named Session 1, Session 2, Session 3.
2. Settings Persistence: Change Baud Rate in Session 1 to 9600 and Session 2 to 115200. Switch between them and verify that the dropdown value updates to reflect the active session's settings.
3. Session Renaming: Double-click "Session 1" name in the sidebar, type "Test Port", and press Enter. Verify the label changes.
4. Delete Session: Select a session and click the x delete icon. Verify it gets removed. If connected, it should disconnect safely first.
5. Console logs isolation: Verify that sending data or logs in one session does not bleed into another session's terminal panel.