tcad-bodeplot/uart_example/implementation_plan_Single_web_uart_terminal.md

Implementation Plan - Web UART Terminal

This plan details the implementation of a modern, responsive, and feature-rich Web UART Terminal application. The design will match the dark-themed UI provided in the user's reference image and support the Web Serial API for real-time serial communication with hardware.

User Review Required

Important

Browser Compatibility: The Web Serial API is supported in Chromium-based browsers (Chrome, Edge, Opera). It is not supported by default in Firefox or Safari. A friendly warning banner will be displayed to users accessing the page from unsupported browsers. Local Server Requirement: The Web Serial API requires a secure context (HTTPS) or localhost to work. To facilitate this, we will configure a simple dev environment using Vite so you can run it locally with npm run dev (serving at http://localhost:5173).

Proposed Changes

We will create a self-contained, lightweight, and high-performance Vanilla HTML/CSS/JS application within the /home/roy/zData/WTPCode/pec930/pec930_pfc_llc/ui/uart_terminal directory.

UI & Dev Environment Configuration

---

[NEW] package.json

• Define a project package with vite as a dev dependency.
• Include scripts for local development (npm run dev) and building (npm run build).

[NEW] vite.config.js

• A basic configuration file for Vite to ensure it runs correctly and resolves static assets.

[NEW] index.html

• Create the HTML skeleton of the UART Terminal.
• Match the layout in the screenshot:
  • Header: App Title, Theme Toggle button.
  • Action Control: Connect/Disconnect button (circle with play/stop icon), Download button (square download icon).
  • Info Banner: "Not connected" warning banner, dynamically changing based on serial connection status.
  • Serial Settings Grid: Dropdowns for Baud Rate, Data Bits, Stop Bits, Parity.
  • Received Data Section: Section title, controls (Scroll: Auto-scroll/None, Display: Auto/Hex/Text), console output textarea/container.
  • Send Data Footer: Form input with keyboard shortcut tooltip, Send Format dropdown (ASCII/Hex), Send button, and Clear Terminal (trash) button.
• Embed all required SVG icons inline for zero external dependencies and fast load times.
• Include a Google Font link (e.g., "Inter" for UI typography, "JetBrains Mono" for the terminal console).

[NEW] index.css

• Implement a premium design system using CSS custom properties (variables) for HSL colors.
• Support Dark Mode (default) and Light Mode.
• Incorporate subtle animations (transitions on hover/active, pulsing connection status, smooth modal fades).
• Implement responsive grids and flex layouts, ensuring pixel-perfect alignment with the reference image.
• Design custom scrollbars for the terminal output.

[NEW] app.js

• Implement core UART logic via Web Serial API:
  • Request serial port and open connection using selected settings (Baud Rate, Data Bits, Stop Bits, Parity).
  • Background reading loop with cancellation support.
  • Writing loop supporting ASCII/Hex conversion.
• Implement helper utilities:
  • Hex parser (validating and converting hex string inputs like AA BB CC or AABBCC to Uint8Array).
  • Hex formatter (representing received bytes as spaced hex strings e.g. 00 12 AF).
• Implement UI interactions:
  • Terminal text appending with Auto-scroll capability.
  • Download log: converts terminal content to a .txt blob and triggers a browser download.
  • Clear log: clears the screen and reset states.
  • Keyboard shortcuts (e.g. Ctrl+Enter to send, Ctrl+Tab to insert tab in input, etc.).
  • Theme toggling with localStorage persistence.

[NEW] README.md

• Instructions on installing dependencies (npm install) and launching the development server (npm run dev).
• Quick notes on Web Serial browser compatibility and security requirements.

Verification Plan

Manual Verification

1. Launch the local dev server using npm run dev.
2. Access the app via Chrome or Edge browser.
3. Verify that the UI matches the reference screenshot (dark theme, layouts, styling, icons, font sizes).
4. Verify the theme toggle (switching from dark to light mode and back).
5. Verify inputs:
   • Check if serial configuration dropdowns have correct options.
   • Verify that clicking "Connect" triggers the browser's Serial Port prompt.
   • Verify Hex transmission (e.g., inputting 48 45 4C 4C 4F in Hex mode sends HELLO).
   • Verify Text transmission.
   • Test "Clear" (trash bin) and "Download" buttons.
   • Test auto-scroll behaviour with mock data.