365 lines
8.4 KiB
Markdown
365 lines
8.4 KiB
Markdown
# 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.
|