From d9bfb943a7769e240e81e37b80a1cccf8870ff01 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:26:07 +0100 Subject: [PATCH 1/3] docs/design/brief.md: the design brief, first draft MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit How EmbLink Studio should feel and behave, from the owner's answers on 2026-11-12: macOS quality (fluid, elegant, soft, professional), not VS Code and not static. The direction is Instrument and Canvas. Configuring follows MCC: a peripheral catalogue, forms with live readouts, conflicts resolved in place, and a pin manager with custom names and locks. The brief also lists a complete debugger and the open questions, Qt Quick or Widgets first among them. Accepted points move into the specification's §7. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- docs/README.md | 1 + docs/design/brief.md | 86 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/design/brief.md diff --git a/docs/README.md b/docs/README.md index 50bb0ba..27ab8d8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ | Document | What it holds | Read it when | | --- | --- | --- | | [Specification](specification.md) | What EmbLink Studio is, the decisions taken, the architecture, the core's JSON-RPC interface, the project format, the views, the stages S0 to S9 and the engineering rules | You want to know what to build, in what order, and why | +| [Design brief](design/brief.md) | How EmbLink Studio looks, feels and behaves: the direction, configuring the MCC way, the debugger. A draft, decided step by step | You design or build anything the user sees | | [Development](development.md) | Setting up a machine and an editor, the build and test commands, and how a change reaches `main` | You are about to change the code | | [Protocol schemas](../protocol/README.md) | One JSON Schema per method's parameters and result | You change a method of the core's interface | | [Contributing](../CONTRIBUTING.md) | The CLA and the DCO, the file header, formatting and licence rules | Before your first pull request | diff --git a/docs/design/brief.md b/docs/design/brief.md new file mode 100644 index 0000000..50f88e1 --- /dev/null +++ b/docs/design/brief.md @@ -0,0 +1,86 @@ + +# Design brief + +**Draft · 2026-11-12 · Owner: Junior Deogracias (teo1747)** + +How EmbLink Studio should look, feel and behave. The specification (`../specification.md`) says *what* the +product does; this brief says *how it is experienced*. Nothing here is built until the owner accepts it, and +accepted points move into the specification (§7) with their date. + +## 1. The feeling + +macOS quality: **fluid, natural, elegant, soft on the eyes, and clearly professional.** The owner's reference is +Apple Music. The product has a personality of its own. + +To avoid: + +- the mechanical feel of Windows and Android interfaces; +- looking like VS Code, or any general-purpose editor; +- a static screen: values, signals and state should visibly live. + +## 2. The direction: Instrument and Canvas + +Chosen by the owner on 2026-11-12, from three directions (Studio, Instrument, Canvas). + +- **Instrument.** Graphite tones, fine precise lines, live data that moves: values recompute as you type, signals + flow along the lines of the selected peripheral, the connected board pulses. Like a premium measuring + instrument. +- **Canvas.** The board is the centre. The chip is drawn large with its peripherals wired to their pins; you zoom + from the board to a peripheral to its registers. +- **Soft, not harsh:** rounded cards, gentle shadows, one accent colour (cyan) with green, amber and red only for + meaning (valid, warning, error). + +The first mockup of this direction is the **Configure** screen (design canvas, artboard "Direction B + C · +Configure"). + +## 3. Configuring the board, the MCC way + +The owner's reference is Microchip's MPLAB Code Configurator (MCC), its device resources and its pin manager. + +- **Peripheral catalogue.** Every peripheral of the chip (ADC, timers and PWM, UART, SPI, I2C, DMA, the external + memory interface, and so on), grouped. **Add** one, and it moves to *In this project*, is drawn on the canvas + and opens in the inspector. +- **Configuration form.** Each peripheral's parameters, with sensible defaults. **Readouts computed live** from the + clock tree, the way an engineer checks them: actual baud rate and its error, SCL frequency, ADC conversion time + and rate, SPI clock. +- **Conflicts shown and resolved in place.** A pin two peripherals want is drawn in amber on the chip and in the + list; the inspector explains it and offers the fix (for example, move SPI1 SCK from PA5 to PB3). +- **Pin manager.** All pins in a list: + - the function each pin carries, and the peripheral it belongs to; + - a **custom name** (`LED_STATUS`, `SENSOR_SDA`) that the generated code uses; + - electrical options: mode, pull-up or pull-down, speed, output type, start level; + - a **lock**, so the generator never moves that pin when it resolves a conflict. +- Every change still goes through the core into `board.yaml` and `system.yaml`, shown as a diff before anything is + written (specification §5, §6). + +## 4. A complete debugger + +Everything a professional embedded developer expects, plus what only an RTOS-aware tool can show: + +| Area | What it has | +| --- | --- | +| Control | Run, halt, step by line or by instruction, step over and out, reset, flash and restart | +| Breakpoints | On a line or a function, conditional, by hit count; data watchpoints (stop when a variable changes) | +| Code | Disassembly, with the source interleaved | +| State | Core and FPU registers; peripheral registers decoded from the SVD file, and editable; memory view (hex and typed) | +| Program | Call stack per thread, local variables, watch list, live expressions | +| RTOS | Threads and their states, objects, stacks and high-water marks, the timeline | +| Trouble | Fault analyzer, crash-record decoding, SWO/ITM console and trace | + +## 5. Open questions + +1. **Qt Quick or Qt Widgets for the frame.** A fluid, animated macOS feel is far easier in Qt Quick. The + specification chose Widgets for the frame (§11 q2), and the docking library (Qt Advanced Docking System) is + Widgets-only. Before deciding, build the same small screen both ways and compare. +2. **Light appearance.** Dark is designed first; a light appearance, as macOS offers, follows the same tokens. +3. **The other screens:** Start, Code, Debug, Verify. + +## 6. How the design proceeds + +One step at a time, each decision written here before anything is built: + +1. The feeling (§1): done. +2. The signature moments: the 3 to 5 interactions people remember. +3. How you move around: stages, the command palette, the inspector, the keyboard. +4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere. +5. The screens, each mocked up and iterated: Configure (first draft done), then Start, Code, Debug, Verify. From 7ad131479cf56d440f089d2b6034d98cc8f4463b Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:55:17 +0100 Subject: [PATCH 2/3] Design brief: RTOS configuration, MCC's pin options, feedback on the first draft MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Configure › RTOS (§3a): threads on a priority axis, objects and interrupts with who-uses-what lines, ceilings and the RAM budget computed live, the kernel settings grouped as EmbLinkRTOS's Kconfig, with checks in place. From MCC: the per-pin options and the pin grid still to bring in. The owner's feedback on 2026-11-12: the layout is good, the pin and peripheral options are too few. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- docs/design/brief.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/design/brief.md b/docs/design/brief.md index 50f88e1..0c74565 100644 --- a/docs/design/brief.md +++ b/docs/design/brief.md @@ -53,6 +53,28 @@ The owner's reference is Microchip's MPLAB Code Configurator (MCC), its device r - Every change still goes through the core into `board.yaml` and `system.yaml`, shown as a diff before anything is written (specification §5, §6). +**From MCC, still to bring in** (its Pin Manager and Pins view): per-pin *start high*, analog, direction, weak +pull-up, open-drain and interrupt-on-change; and its **pin grid**, functions in rows and pins in columns, each cell a +lock that is free, taken or locked. The first draft's pin and peripheral options are too few: the next round widens +both (owner, 2026-11-12). + +## 3a. Configuring the RTOS + +**Configure › RTOS**, beside **Configure › Hardware**. The same canvas idea, applied to `system.yaml`: + +- **Threads sit on a priority axis**, so changing a priority moves the thread. Kernel threads (the system work queue, + idle) are shown too, set by the kernel settings. +- **Objects** (queues, mutexes, semaphores, event flags, timers) sit between the threads, and lines say who sends, + receives, locks, takes, waits or runs. **Interrupts** feed them from the right. +- **Computed live:** a ceiling mutex's ceiling follows its highest user (SPEC-005 §3.4), drawn on the axis; stacks, + queue buffers and the kernel's own memory go into the RAM budget. +- **Kernel settings**, grouped as EmbLinkRTOS's `Kconfig` groups them (build, scheduler, time, threads, + synchronization, communication, interrupts, faults, observability). Each shows its option name (`EMB_TICK_NS`) + and the specification or requirement it comes from. +- **Checks in place:** a priority out of range, a queue item above `EMB_MSGQ_MAX_ITEM`, time slicing with no two + threads at one priority, a timer period that is not a whole number of ticks, no debug descriptor. +- In the Debug stage the same graph comes alive: threads light up as they run, queues fill and drain. + ## 4. A complete debugger Everything a professional embedded developer expects, plus what only an RTOS-aware tool can show: @@ -74,6 +96,7 @@ Everything a professional embedded developer expects, plus what only an RTOS-awa Widgets-only. Before deciding, build the same small screen both ways and compare. 2. **Light appearance.** Dark is designed first; a light appearance, as macOS offers, follows the same tokens. 3. **The other screens:** Start, Code, Debug, Verify. +4. **Drawing a connection:** dragging from a thread to an object to say who uses it. ## 6. How the design proceeds @@ -83,4 +106,5 @@ One step at a time, each decision written here before anything is built: 2. The signature moments: the 3 to 5 interactions people remember. 3. How you move around: stages, the command palette, the inspector, the keyboard. 4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere. -5. The screens, each mocked up and iterated: Configure (first draft done), then Start, Code, Debug, Verify. +5. The screens, each mocked up and iterated: Configure › Hardware and Configure › RTOS (first drafts done; the + layout is liked, the options need widening), then Start, Code, Debug, Verify. From 640f5a39470ca7128ca34be4ce231ccb45273dfa Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:22:39 +0100 Subject: [PATCH 3/3] =?UTF-8?q?Design=20brief:=20kernel=20settings=20get?= =?UTF-8?q?=20their=20own=20page,=20Configure=20=E2=80=BA=20Kernel?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner's feedback on 2026-11-12: the kernel configuration is too important for the inspector. A full page like macOS System Settings: categories, profile cards, every option with its Kconfig help, key, reference and default, dependencies explained, search, and an effect panel with the RAM change, the checks and the system.yaml diff. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- docs/design/brief.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/design/brief.md b/docs/design/brief.md index 0c74565..45de105 100644 --- a/docs/design/brief.md +++ b/docs/design/brief.md @@ -68,9 +68,18 @@ both (owner, 2026-11-12). receives, locks, takes, waits or runs. **Interrupts** feed them from the right. - **Computed live:** a ceiling mutex's ceiling follows its highest user (SPEC-005 §3.4), drawn on the axis; stacks, queue buffers and the kernel's own memory go into the RAM budget. -- **Kernel settings**, grouped as EmbLinkRTOS's `Kconfig` groups them (build, scheduler, time, threads, - synchronization, communication, interrupts, faults, observability). Each shows its option name (`EMB_TICK_NS`) - and the specification or requirement it comes from. +- **Kernel settings get a full page of their own: Configure › Kernel** (the owner, 2026-11-12: too important for the + inspector). Laid out like macOS System Settings: + - categories on the left (profile and build, scheduler, time, threads, synchronization, communication, timers and + work queues, devices and drivers, objects, interrupts, faults, observability), each with a count of changed + settings and a dot when one has a warning; + - the reference **profile** as large cards (tiny, base, isolated; multicore and native shown, and why they do not + apply to this chip). Settings not changed by hand follow the profile; + - every option with its help text from `Kconfig`, its key, its reference, its default, a reset, and why it is + greyed out when a dependency is missing ("Needs priority inheritance: the bus is held by a mutex"); + - search across all options, and a "changed only" filter; + - an **effect panel**: the RAM change, the checks (also across screens: the I2C driver that I2C1 needs), and the + exact `system.yaml` diff, applied only when no check is red. - **Checks in place:** a priority out of range, a queue item above `EMB_MSGQ_MAX_ITEM`, time slicing with no two threads at one priority, a timer period that is not a whole number of ticks, no debug descriptor. - In the Debug stage the same graph comes alive: threads light up as they run, queues fill and drain.