pro3_control_panel_v2/AGENTS.md

AmebaPro3 Control Panel Development Agent Specification (agents.md)

Project Overview

A Windows desktop control panel for Realtek AmebaPro3 SoC bring-up, debugging, and automation.

Target stack:

• C#
• .NET 8
• WPF (preferred over WinForms)
• Windows 11-like modern styling using native WPF only
• Phase 1: UI-only skeleton (baseline, no real hardware access)

Goals:

• Modern, clean, engineering-oriented UI
• Stable build and runtime (no third-party UI dependencies)
• Layout and component structure that supports future services (UART, J-Link, flashing)

---

UI Framework & Styling (STRICT)

Mandatory

• Framework: WPF
• Target: .NET 8 (e.g. net8.0-windows)
• No third-party UI libraries (no theme packages)
• Style target: Windows 11-like (cards, rounded corners, subtle borders, simple states)
• Styling technique: XAML ResourceDictionaries + Styles + ControlTemplates

Forbidden

• x WPF-UI / lepoco, MahApps, MaterialDesign, FluentWPF, HandyControl, etc.
• x UWP / WinUI 3
• x Windows Store dependency
• x Runtime hardware access in Phase 1

---

Architecture Principles

• UI-first development
• MVVM-friendly
• Clear separation between:
  • UI (Views + ViewModels)
  • Device services (UART/J-Link services)
  • Debug services (future)
• Every device/session has independent console and command history
• Console/log UI must stay responsive under heavy output

---

Solution Structure

• App.xaml
  • Loads theme resources (Light by default)
• Themes/Colors.Light.xaml / Themes/Colors.Dark.xaml
• Themes/Controls.xaml (Button/TextBox/TabControl/List styles)
• Views/MainWindow.xaml
• Views/Pages/MainPage.xaml
• Views/Pages/JLinkPage.xaml
• Views/Controls/ConsolePanel.xaml (reusable)
• ViewModels/*
• Services/Uart/*
• Scripts/uart_bridge.py

---

Styling Contract (native WPF)

• Font: Segoe UI Variable (fallback: Segoe UI)
• Buttons: height 36, radius 10, consistent padding
• Inputs: radius 10, clear focus border
• Cards: radius 12, subtle border, optional very light shadow
• Accent color used only for primary actions / selected tab / selected nav

---

Main Application Layout

MainWindow.xaml

Purpose: Host top navigation + page content.

Root Layout:

• Grid
  • Row 0 = Auto (TopBar)
  • Row 1 = * (PageContent)
  • Row 2 = Auto (StatusBar)

Row 0: TopBar (Auto, ~56px)

• Left: App title TextBlock ("AmebaPro3 Control Panel")
• Right: ListBox navigation for page switching
  • Tab 1: Panel (MainPage)
  • Tab 2: Debugger (JLinkPage)
• Optional theme toggle or window buttons

Row 1: PageContent

• ContentControl bound to CurrentPageViewModel

Row 2: StatusBar (Auto, ~28px)

• Left: Selected device + connection status text
• Right: Last RX time, RX bytes, TX bytes

Naming (important):

• Main container: MainRootGrid
• Page host: MainContentHost

---

Pages

1) MainPage.xaml (Panel)

Purpose: Combine Flash Image, Arduino control, and AmebaPro3 UART in a split layout.

Root Layout:

• Grid with two columns
  • Column 0 (Left, wider): * (AmebaPro3 UART)
  • Column 1 (Right, narrower): ~480 (Flash + Arduino)
  • Column gap: 12

Column 0: AmebaPro3 UART (largest area)

• A single ConsolePanel instance configured for AmebaPro3
• Header controls inside ConsolePanel:
  • COM port dropdown
  • Baud rate input (default 1500000)
  • Connect / Disconnect button
  • Optional TeraTerm launch button

Column 1: Right stack

• Grid with rows and a splitter:
  • Row 0 = Auto (Flash Card)
  • Row 1 = 8 (Spacing)
  • Row 2 = * (Arduino Card)

Flash Image Card (Row 0, Auto)

Card container: Border (CardStyle) Contents:

• Section title: TextBlock "Flash Image"
• Grid with rows:
  • Bootloader file picker (TextBox readonly + Browse button)
  • Application file picker (TextBox readonly + Browse button)
  • Flash Image primary button (full width)

Control names:

• BootloaderPathTextBox, BrowseBootloaderButton
• AppPathTextBox, BrowseAppButton
• FlashImageButton

Arduino Controller Card (Row 2, *)

Card container: Border (CardStyle) Contents (top to bottom):

1. Connection row:
   • COM dropdown + Baud textbox (default 115200) + Connect button
2. Mode buttons (uniform size, aligned, share whole row width):
   • Reset, Download Mode, Normal Mode, Test Mode
3. Test mode selector:
   • ComboBox "Test 1" to "Test 7"

Control names:

• ArduinoComComboBox, ArduinoBaudTextBox, ArduinoConnectButton
• ArduinoResetButton, ArduinoDownloadButton, ArduinoNormalButton, ArduinoTestModeButton
• ArduinoTestSelectComboBox

---

2) JLinkPage.xaml (Debugger)

Purpose: Multi-AP debugging for AmebaPro3.

Root Layout:

• Grid with columns:
  • Column 0 = * (Main AP console workspace)
  • Column 1 = 280 (AP selector pane)
  • Column gap: 12

Top area (inside Column 0, Row 0 Auto):

• J-Link selection row:
  • ComboBox for J-Link serial number
  • Refresh button (optional)
  • Connect button (Phase 1 dummy)

Workspace area (Column 0, Row 1 *):

• ContentControl showing selected AP view
• Each AP view contains one ConsolePanel configured for that AP

Right AP selector pane (Column 1):

• Card container + ListBox (navigation style)
• Items:
  • Cortex M33 - Processor NP
  • Cortex M33 - Processor MP
  • Cortex M23 - Processor FP
  • Cortex CA32 - Processor AP

AP selector control name:

• ApSelectorListBox

AP sessions:

• Each AP has independent ConsolePanel state (log + history + command input)

Debugger command buttons (inside ConsolePanel CommandButtons slot):

• Halt, Continue, Step In, Step Over, Step Out
• File picker that lets user load multiple commands from file
• Command logic should support all JLink basic commands

Notes:

• When AP connected, Phase 2+ should not halt CPU by default
• Designed to integrate Segger J-Link + GDB later

---

Reusable UI Components

ConsolePanel.xaml (Core component)

Must be reusable across:

• AmebaPro3 UART
• Arduino UART (optional)
• J-Link AP sessions

ConsolePanel Layout (codex-ready)

Root: Grid

• Row 0 = Auto (Header, ~48px)
• Row 1 = * (Log viewer)
• Row 2 = Auto (GridSplitter)
• Row 3 = * (History list, min ~140px)
• Row 4 = Auto (CommandButtons slot)
• Row 5 = Auto (Actions row)
• Row 6 = Auto (Input row, ~44px)

Row 0: Header

• Left: Title + status text
• Right: header content slot (page-specific controls)

Row 1: Log viewer

• Must support horizontal + vertical scrolling
• Read-only
• Monospace option
• Performance: use a virtualization-friendly approach
• Can scroll up, down, left, right
• ListBox/ItemsControl virtualized lines (one line per item)

Row 3: Command history

• ListBox (virtualized)
• Behaviors:
  • Latest command at bottom
  • No duplicate command entries
  • Up/Down navigates history
  • Single click selects and fills command input
  • Double click sends command

Row 5: Actions row

• Clear, Save, Load Commands

Row 6: Input row

• Grid with columns:
  • Column 0 = * command input TextBox
  • Column 1 = 8 spacing
  • Column 2 = Auto send Button
• Press Enter triggers Send
• After send: clear input

Optional slot: CommandButtons area (for debugger step/halt/continue)

• Placed between history and actions row

ConsolePanel Public Bindings (ViewModel properties)

• string Title
• bool IsConnected
• ObservableCollection<string> LogLines
• ObservableCollection<string> History
• string CurrentCommand
• ICommand SendCommand
• ICommand ClearLog
• ICommand SaveLog
• ICommand LoadCommandFileCommand
• UIElement CommandButtonsContent (optional)

---

Phase Roadmap

Phase 1 (Baseline)

• UI-only
• All pages render correctly
• Dummy content / placeholder logs
• No hardware access

Phase 2 (In progress)

• UART service (AmebaPro3) using Python + pyserial bridge (Scripts/uart_bridge.py)
• Optional TeraTerm launch integration
• Implement history behaviors

Phase 3

• J-Link session management
• Multi-AP GDB integration
• Session lifecycle control

Phase 4

• Flash pipeline
• C++ integration (Prefer)
• Python tool integration
• Automation & scripting

---

Coding Rules for Agents

• Keep UI logic independent
• No blocking calls on UI thread
• One function = one job
• Prefer clarity over cleverness
• Engineering tool mindset

---

Summary

This project is a professional SoC control panel focused on:

• Clarity
• Stability (no UI library dependencies)
• Expandability
• Multi-device / multi-session workflows

UI correctness and structure come before any hardware logic.