diff --git a/README.md b/README.md index 8aa0808..7ad8a6f 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # EmbLink Studio -The IDE made for EmbLinkRTOS: a native Qt 6 desktop application (`app/`) in front of -EmbLink Studio Core, a Python engine (`core/`) that it talks to over JSON-RPC 2.0 on stdio. -Stage S0 (setup) of the specification: the application starts the core, initializes it, +The development system for EmbLinkRTOS: EmbLink Studio Core, a Python engine (`core/`) that +configures, builds, flashes and debugs, and a native Qt 6 desktop (`app/`) that makes it visible. +They talk JSON-RPC 2.0 over stdio. + +Stage S0 (setup) of the [specification](docs/specification.md): the application starts the core, initializes it, shows its log, and offers a restart if it stops. ## Build and test @@ -30,6 +32,7 @@ found; set `EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use th | `app/` | The Qt application and its tests | | `core/` | EmbLink Studio Core: `emblink-studio-core serve` | | `protocol/` | JSON Schemas of every method's parameters and result | +| `docs/` | The [specification](docs/specification.md) and the [development guide](docs/development.md) | | `third_party/components.json` | Every third-party component and its licence | | `tools/notices.py` | Checks those licences and writes the notices list for the About box | diff --git a/app/src/mainwindow.cpp b/app/src/mainwindow.cpp index 106de0c..75ca107 100644 --- a/app/src/mainwindow.cpp +++ b/app/src/mainwindow.cpp @@ -10,7 +10,7 @@ * * @details * Builds the status label, the restart button, the "Core log" dock (a QDockWidget - * until the docking framework is decided, spec section 11 question 1) and the File, + * until Qt Advanced Docking System lands, spec section 11 question 1) and the File, * View and Help menus. The About dialog shows the third-party notices bundled as the * :/NOTICES.md resource. The core is started when the window is built and stopped * when it closes. @@ -55,7 +55,7 @@ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) layout->addStretch(); setCentralWidget(central); - // QDockWidget until the docking framework is decided (spec section 11, question 1). + // QDockWidget until Qt Advanced Docking System lands (decided: spec section 11, question 1). auto *dock = new QDockWidget(tr("Core log"), this); dock->setObjectName(QStringLiteral("coreLog")); m_log = new QPlainTextEdit(dock); diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..50bb0ba --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ + +# EmbLink Studio documentation + +| 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 | +| [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 | + +## The specification is the source of truth + +When the code says "spec section 5" or "§11 q4", it means [specification.md](specification.md), section 5 or +question 4 of section 11. The specification is changed by pull request and agreed with the owner. A decision +is added to §2 with its date, and a pull request that changes behaviour updates the specification with it. + +## Where the project stands + +Stage S0 (setup) is done: the application starts the core, initializes it, shows its log and offers a restart +if it stops. CI builds and tests it on Windows, Linux and macOS. S1, the core's foundation, is next (§8). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..078e05f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,62 @@ + +# Development + +How to set up a machine, build and test EmbLink Studio, and get a change into `main`. + +## What you need + +CMake 3.21 or later, Ninja, Qt 6.8 or later, Python 3.11 or later, and clang-format 18 for C++ formatting +(`pip install clang-format==18.1.8` gives the version CI runs). On macOS, Homebrew's `qt`, `cmake`, `ninja` and +`python` are enough. + +## Build and test + +```sh +cmake --preset dev # set CMAKE_PREFIX_PATH to your Qt if CMake can't find it +cmake --build --preset dev +ctest --preset dev # Qt tests, against the real core and fake ones + +python3 -m venv core/.venv && core/.venv/bin/pip install -e "core[dev]" +core/.venv/bin/pytest core # the core's tests, including the protocol schemas +core/.venv/bin/ruff check . && core/.venv/bin/ruff format --check . +``` + +Run the application: `build/dev/app/EmbLinkStudio.app/Contents/MacOS/EmbLinkStudio` on macOS, +`build/dev/app/EmbLinkStudio` elsewhere. It runs the core from `core/src` with the Python CMake found; set +`EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use that instead. + +## The editor + +The repository's [`.clangd`](../.clangd) points clangd at `build/dev/compile_commands.json`, so any +editor that uses clangd (VS Code with the clangd extension, Qt Creator, Neovim, Emacs) finds the Qt headers +and the build's flags. Run `cmake --preset dev` once first; until that file exists, the editor reports headers +as missing. +After the first configure, restart the language server (in VS Code: *clangd: Restart language server*). + +`progress-screenshots/` is ignored by git: keep pictures of the application as it grows there, on your +machine only. + +## How a change reaches `main` + +`main` takes changes only through pull requests, and only when every CI check passes: + +1. Create a branch from `main`. +2. Commit with `git commit -s`. The DCO check requires a `Signed-off-by` line that matches the commit's author. +3. Give every new source file the header shown in [CONTRIBUTING.md](../CONTRIBUTING.md). +4. Push the branch and open a pull request. +5. Wait for the 11 checks: the core on three systems and two Python versions, the application on three + systems, clang-format, and the DCO sign-off. +6. Merge with *Squash and merge* or *Rebase and merge*. Merge commits are off, so the history stays linear. + +Release tags (`v*`) can only be created by the maintainers, and can never be moved or deleted. + +## Where things are + +| Path | What | +| --- | --- | +| `app/` | The Qt application and its tests | +| `core/` | EmbLink Studio Core: `emblink-studio-core serve` | +| `protocol/` | JSON Schemas of every method's parameters and result | +| `docs/` | The specification and this guide | +| `third_party/components.json` | Every third-party component and its licence | +| `tools/notices.py` | Checks those licences and writes the notices list for the About box | diff --git a/docs/specification.md b/docs/specification.md new file mode 100644 index 0000000..9826836 --- /dev/null +++ b/docs/specification.md @@ -0,0 +1,404 @@ + +# EmbLink Studio Specification + +**Version 0.2 · 2026-11-11 · Owner: Junior Deogracias (teo1747)** + +Changes to this document are proposed by pull request and agreed with the owner. A decision is added to §2 with its date. Code and comments cite it as "spec section N" or "§N". + +The handoff specification for EmbLink Studio's developer: what the owner has decided, what to build and in what order, and what is still open. v0.2 closes gaps found in a review of v0.1 and settles every open question (§11). + +## 1. What EmbLink Studio is + +EmbLink Studio is **the development system for EmbLinkRTOS**. It turns a board and an idea into firmware that is proven to work, and shows the RTOS at every step. It is a long-term product, grown step by step like the RTOS. + +It is two things that are one: + +1. **A tooling system, the foundation.** EmbLink Studio Core (`emblink-studio-core`) does the whole job: configure, generate, build, flash, debug, decode crashes, run tests on hardware and collect the evidence. Every action is a command, so a terminal, CI or a script does exactly what the desktop does (§4). +2. **A desktop that makes the system visible.** The Qt application holds no knowledge of its own. It draws what the tools know (pins, clocks, threads, budgets, stacks, crashes, test results) and lets a person change it safely, with a preview before anything is written. + +It is not a VS Code look-alike or a general-purpose editor: it understands the RTOS. + +- Its boards and chips, as data. +- Its threads, objects, priorities and stacks. +- Its driver classes and devices. +- Its crash records and debug descriptor. +- Its test and hardware evidence. + +**What a developer can do with it, once complete:** + +1. Create a project from a board or a template. +2. See and change the board: pins, clocks, peripherals, devices, DMA channels, flash partitions. +3. Add external parts (sensors, memories) from modules. +4. Configure the RTOS: threads, priorities, stacks, queues, mutexes, timers, and see the RAM, flash and stack budget before building. +5. Write application code. +6. Build, flash, and watch the serial console. +7. Debug with the RTOS visible: threads and their states, stack high-water marks, devices and their lifecycle. +8. Decode a crash record into a readable report. +9. Trace and time execution, and see power residency (later). +10. See the project's evidence: tests run, on which board, passed or not. + +**The test for a feature.** Does it need knowledge of EmbLinkRTOS, the hardware or the evidence? + +- **Yes** (the pin map, the budget, RTOS-aware debugging, crash decoding, evidence): it is what EmbLink Studio is for. Build it deeply. +- **No** (text editing, git, file search): reuse what exists, such as an embedded editor component, clangd and git, and do not spend years on it. + +The editor is one tool inside the system: good enough that nobody has to leave, but not the product's identity. Any other editor keeps working, since the generated names and the build's `compile_commands.json` serve it too. + +**Non-goals:** + +- A general IDE for other RTOSes or bare-metal code. +- A general-purpose code editor competing with VS Code. +- Its own compiler: it uses GCC, Clang or EmbCC, which it discovers or downloads. +- A VS Code extension. Not planned, though the core's interface (§5) would allow one later. +- Cloud features in the first releases. + +A project whose YAML has things the views don't cover yet still opens. Those fields are shown read-only with their source, and are kept byte for byte when the project is saved (§6). + +## 2. Decisions already taken + +Nineteen decisions are taken, all dated 2026-11-11: seven from v0.1, the ten answers to §11's questions, which the owner accepted as recommended, the repository going public, and the definition of what EmbLink Studio is. A new decision is added here, with its date, once the owner agrees it. + +| Date | Decision | Reason | +| --- | --- | --- | +| 2026-11-11 | **EmbLink Studio is the development system for EmbLinkRTOS:** a tooling system (the core and its commands), with a desktop that makes it visible. Features that need knowledge of the RTOS, the hardware or the evidence are built deeply; the rest is reused (§1) | Keeps the project finite: it competes on what no other tool knows, not on general editing | +| 2026-11-11 | The name is **EmbLink Studio** | Renamed from EmbStudio on 2026-11-11: Wilcom sells embroidery software as "EmbStudio", the same word in software. The distinctive part is now the project's own name (§10) | +| 2026-11-11 | A **native desktop application in Qt 6**, with no VS Code base | Full control of the interface; a product of its own; the developer knows Qt well | +| 2026-11-11 | **Step by step:** configuration first, then build, flash and debug, then the editor grows | A useful product early, with the editor (the costliest part) grown over time | +| 2026-11-11 | **The hardware model stays in EmbLinkRTOS:** the SoC and board descriptions, their schemas, the validation rules and the generator (`emb-hwgen`) | One hardware model, versioned and tested with the kernel it generates for. EmbLink Studio shows and edits it, and never re-implements its rules | +| 2026-11-11 | **EmbLink Studio Core is a Python engine behind a CLI and a JSON-RPC server**; the Qt application is its face | The RTOS's tools are Python already. Everything stays scriptable and testable without a GUI | +| 2026-11-11 | **Open core under Apache-2.0**, with a **contributor licence agreement**; paid "Pro" features possible later | The same licence as the RTOS; the agreement keeps commercial options open (§10) | +| 2026-11-11 | **No VS Code extension** for now | EmbLink Studio is the RTOS's own IDE | +| 2026-11-11 | Docking: **Qt Advanced Docking System**, linked dynamically | §11 q1 | +| 2026-11-11 | **Qt Widgets** for the frame, docks, tables, forms and the editor; **Qt Quick** for the drawn views | §11 q2 | +| 2026-11-11 | **Installers:** signed MSI (WiX), notarized universal DMG, AppImage; a signed release feed for updates | §11 q3 | +| 2026-11-11 | **The core ships with a bundled, relocatable CPython**, not PyInstaller | §11 q4 | +| 2026-11-11 | **S5 (debugging) comes before S6 (modules)** | §11 q5 | +| 2026-11-11 | **The Pro tier is decided after S7**; nothing Pro-only until then | §11 q6 | +| 2026-11-11 | **A trademark search** (classes 9 and 42) before any public announcement | §11 q7 | +| 2026-11-11 | **Platforms:** Windows 10 22H2 and 11, macOS 13 or later (universal), Ubuntu 22.04 and 24.04 | §11 q8 | +| 2026-11-11 | **The repository is `EmbLinkOs/EmbLinkStudio`** on GitHub | §11 q9 | +| 2026-11-11 | **The repository is public** from 2026-11-11, before the trademark search; outside contributions wait for the CLA (§10) | The owner's choice. Making the code visible is not an announcement: no release, post or listing comes before the search (§11 q7) | +| 2026-11-11 | **Semantic versioning**, with the supported RTOS range stated in each release | §11 q10 | + +## 3. The ecosystem around EmbLink Studio + +EmbLink Studio is one new repository. It drives three groups of code it does not own, and none of them knows about EmbLink Studio. + +```text ++---------------------- EmbLink Studio (this repository) ----------------------+ +| Qt 6 desktop application (C++) <-- JSON-RPC 2.0 over stdio --> the core | +| views, editor, docking, DAP client (Python: emblink-studio-core serve)| ++--------------------------------------------------------------+---------------+ + | runs, reads + +-------------------------+--------------------------+-------------+ + | | | | + EmbLinkRTOS EmbLinkRTOS-parts toolchains and tools + emb-hwgen: schemas, part drivers, blocks, GCC, Clang, EmbCC, + validation, generation; templates OpenOCD, pyOCD, GDB, + emb CLI, crashdec, HIL picotool, EmbSIM, QEMU + runner; kernel, CMake +``` + +| Repository | Owns | Who | +| --- | --- | --- | +| **EmbLink Studio** (new) | The Qt application; EmbLink Studio Core; the protocol schemas; the schemas of the project manifest, the lock file and the module manifest; EmbLink Studio's tests and installers | EmbLink Studio developer | +| **EmbLinkRTOS** | The kernel, the on-chip drivers, the hardware description schemas (SPEC-014), the generator, the `emb` CLI, crashdec, the HIL runner and the support matrix | Owner | +| **EmbLinkRTOS-parts** (new, later) | External part drivers and bindings, application blocks, project templates | Owner, then contributors | +| **EmbCC** | The compiler | Owner | + +The R-004 design record in EmbLinkRTOS explains the module contract and the configurator in more depth (§14). This specification takes precedence where they differ on EmbLink Studio. In particular, R-004's phase E4, a VS Code extension, is replaced by EmbLink Studio. + +## 4. Architecture + +Three layers. The rule that matters most: **all knowledge lives in the core or the RTOS's tools; the Qt application only shows and edits.** + +| Layer | Language | Responsibility | Must not | +| --- | --- | --- | --- | +| **Desktop application** | C++17 or later, Qt 6 (§9) | Windows, docking, views, the editor, the debugger interface, settings, installers | Validate hardware, compute clocks, generate code, or parse the descriptions itself | +| **EmbLink Studio Core** | Python 3.11 or later | Projects, modules and the lock file, toolchains, build, flash, monitor, debug sessions, simulation; the editing model of the configuration; calls into the RTOS's tools | Re-implement the RTOS's rules: it runs `emb-hwgen` and reads its outputs | +| **The RTOS's tools** | Python, C | Descriptions and schemas, validation, generation, `hw.json`, reports, crash decoding, test runs | Know anything about EmbLink Studio | + +**The core's executable is `emblink-studio-core`**, and its server is `emblink-studio-core serve`. v0.1 called the server `emb serve`, but the `emb` CLI belongs to EmbLinkRTOS (§3, M4.3), so two repositories would have shipped the same command. Every RPC method also has a CLI form, such as `emblink-studio-core project validate`. The core calls the RTOS's `emb` and `emb-hwgen`, and never the other way round. + +**The core runs the project's own RTOS tools.** A project pins an RTOS revision (§6), so the core runs the `emb-hwgen` from that pinned checkout, as a subprocess with JSON output. It never uses a copy bundled with EmbLink Studio. Then a project built in the IDE and on the command line uses the same generator, and one EmbLink Studio release can serve projects on different RTOS versions. The core states which range of the `hw.json` and diagnostics formats it supports, and refuses a project outside that range with a clear message. + +**Process model.** + +- The desktop starts `emblink-studio-core serve` as a child process. They talk JSON-RPC 2.0 over standard input and output, framed with `Content-Length` headers as in the Language Server Protocol. Standard error carries the core's own log, never protocol traffic. +- One core process serves one open workspace. It can work on several requests at once: a build runs while the views keep asking for data. +- If the core exits unexpectedly, the desktop shows that, keeps the views read-only, and offers a restart, which reopens the project. Nothing is lost, since all state is on disk (§6). +- **Debugging** uses the Debug Adapter Protocol (DAP). `debug.start` launches GDB's own DAP interpreter (`gdb -i=dap`, GDB 14 or later, built with Python) against the probe's GDB server (OpenOCD, pyOCD or J-Link). The core sits between them as a thin DAP proxy, and adds RTOS-aware requests (threads, stacks, devices) by reading the kernel's debug descriptor through `readMemory`. The debugger interface is written once, whatever the probe. + +**Why it is split this way:** + +- Every action is also a CLI command, so CI, scripts and tests do what the IDE does. +- The core can be tested without a GUI, and the GUI can be tested against a fake core. +- A future frontend (a VS Code extension, a web view) needs no new logic. + +## 5. The core's interface (JSON-RPC) + +The interface is versioned and described by schemas in the EmbLink Studio repository: one JSON Schema per method's parameters and result, under [`protocol/`](../protocol/). Both sides are tested against them. The method list below is the first version to agree, not the final one. + +**Lifecycle.** + +1. `initialize`: the desktop sends its `protocol_version` (semantic versioning) and capabilities; the core answers with its own and its version. The desktop refuses a core of another major version. +2. `initialized`: a notification from the desktop; after it, the core may send notifications. +3. `shutdown`: the core finishes or cancels its work and answers. +4. `exit`: a notification; the core exits with code 0 after `shutdown`, and 1 without it. + +**Methods (first version):** + +| Namespace | Methods | Notes | +| --- | --- | --- | +| `project` | `create`, `open`, `trust`, `validate`, `close`, `status` | `validate` returns every diagnostic with its file, line and path in the YAML. `trust`: see §9, Security | +| `board` | `list`, `describe`, `pins`, `clocks`, `memory` | From the generator's resolved model (`hw.json`); nothing computed in the GUI | +| `config` | `get`, `set`, `preview`, `apply`, `undo`, `redo` | Edits to the YAML through the core. `preview` returns the change as a diff and its diagnostics before anything is written. `undo` and `redo` step through applied changes (§6) | +| `devices` | `list`, `describe`, `add`, `remove` | The board's devices: their class, binding fields, DMA channels and chip selects | +| `rtos` | `threads`, `objects`, `budget` | `system.yaml`'s threads and objects; the RAM, flash and stack budget from the generator's report | +| `modules` | `list`, `search`, `add`, `update`, `remove` | Writes `emb-project.yaml` and the lock file | +| `generate` | `run`, `diff` | Runs `emb-hwgen`; `diff` shows which generated files would change | +| `build` | `configure`, `run`, `clean`, `targets` | CMake with the chosen toolchain and build configuration (§6); diagnostics as structured messages | +| `toolchain` | `list`, `detect`, `install` | Discovers GCC, Clang and EmbCC; downloads pinned versions and checks their checksums | +| `flash` | `probes`, `run` | OpenOCD, pyOCD or picotool, chosen by the board's `debug_probe` | +| `monitor` | `open`, `close`, `send` | Serial console; later the RTOS's framed channels (logs, trace, crash) | +| `debug` | `start`, `stop` | `start` returns the DAP endpoint the desktop connects to (§4) | +| `crash` | `decode` | crashdec on a crash record or a log | +| `evidence` | `runs`, `matrix` | Hardware runs and the support matrix for the boards used | +| `sim` | `start`, `stop` | EmbSIM or QEMU for the board, where supported | + +**Notifications** from the core: `progress` (long operations), `diagnostics` (a file's problems changed), `log` (output of a tool it runs), `files_changed` (the project changed on disk). + +**Long operations** (build, flash, generate, toolchain install) take a `progress_token`. The core reports `progress` against it, and the desktop can cancel with `$/cancelRequest`, as in LSP. A cancelled request answers with the error `cancelled`. + +**Errors** use JSON-RPC's error object. `code` is one of the table below, `message` is written for the user, and `data` holds the tool output that caused it and, where it applies, the file and line. + +| Code | Name | When | +| --- | --- | --- | +| -32700 to -32600 | JSON-RPC's own | Malformed message, unknown method, bad parameters | +| 1001 | `not_initialized` | A call before `initialize` | +| 1002 | `no_project` | A project call with no project open | +| 1003 | `untrusted` | An action that runs project code before `project.trust` | +| 1004 | `cancelled` | The request was cancelled | +| 1010 | `tool_failed` | A tool the core ran (generator, CMake, probe) failed; its output is in `data` | +| 1011 | `tool_missing` | A tool or toolchain is not installed | +| 1020 | `conflict` | The file changed on disk since the core read it (§6) | +| 1030 | `unsupported_rtos` | The project's RTOS revision is outside the range the core supports (§4) | + +## 6. The project + +A project is a directory under version control, and **everything EmbLink Studio shows comes from its files.** The only state kept outside them is window layout, preferences and undo history, in `.emblink-studio/`, which is not committed. + +```text +my-project/ + emb-project.yaml the project: RTOS version, modules, board, toolchain + emb-project.lock exact commits and hashes of the RTOS and the modules (written by the core) + system.yaml threads, objects, parts' use, blocks (SPEC-014 section 5) + boards/ only for a board of the project's own (laid out as A76 says) + src/ include/ the application's code + generated/ the generator's outputs: never edited, regenerated + CMakeLists.txt builds against the RTOS's CMake package + CMakePresets.json the build configurations (debug, release), shared by the IDE and the CLI + build/ build trees, one per configuration (ignored by git) + .emblink-studio/ EmbLink Studio's own preferences (ignored by git) +``` + +```yaml +# emb-project.yaml +schema_version: 0 +kind: project +name: my-project +rtos: { url: https://github.com/EmbLinkOs/EmbLinkRTOS, rev: v0.3.0 } +modules: + - { name: emblink-parts, url: https://github.com/EmbLinkOs/EmbLinkRTOS-parts, rev: v0.1.0 } +board: st/nucleo_f446re +toolchain: { family: gcc, version: 14.2.Rel1 } +system: system.yaml +``` + +**Rules:** + +- The board and SoC descriptions follow the RTOS's schemas (SPEC-014, in `hw/schemas/`). EmbLink Studio writes them through the core and never invents a field. +- If the configuration views need a board split into smaller files (pins, clocks, devices), the RTOS adds an `include:` to its schema. EmbLink Studio asks for it, and does not add a format of its own. +- Generated files are only regenerated, never edited. User code calls the names the generator writes. +- A project created by EmbLink Studio builds from the command line with the same result. Build configurations live in `CMakePresets.json`, so `cmake --preset debug` gives the IDE's debug build. + +**Editing YAML that people also write by hand:** + +- **Round-trip.** The core edits YAML with a round-trip parser (ruamel.yaml), so comments, key order, quoting and blank lines survive an edit. An edit changes only the lines it must, and a change made in the IDE reads in `git diff` as if a person had made it. Golden tests check this (§9). +- **Edits from outside.** The core watches the project's files and sends `files_changed` when one changes. Each `config.apply` carries the content hash of the file it was previewed against. If the file changed in between, the core refuses with `conflict`, and the desktop re-reads it and shows the new state. An edit made in another editor is never overwritten silently. +- **Undo.** Each `config.apply` is one step in an undo history kept by the core, per workspace and per session, and stored in `.emblink-studio/`. An undo is itself previewed and applied, with the same conflict check. Git remains the history that matters. + +## 7. What it looks like: the views + +The design is the developer's, within three principles: + +- The RTOS is visible everywhere. +- Every number shown comes from the core, with its source one click away. +- A change shows its effect (diagnostics, budget) before it is applied. + +| View | Shows and does | From | +| --- | --- | --- | +| **Start** | New project from a board or a template; recent projects | `project`, `board.list` | +| **Project** | The project's files, modules and board; its status (valid, generated, built) | `project.status` | +| **Problems** | Every diagnostic in one list (validation, generation, build), each linked to its file and line | `diagnostics` notifications | +| **Board** | The chip and the board: memory map, peripherals, the board's devices | `board.describe`, `devices.list` | +| **Pin map** | The package drawn from the SoC's pin data: each pin's function, conflicts highlighted; assign by click | `board.pins`, `config.set` | +| **Clock tree** | Oscillators, PLL and buses, with the frequencies the generator computed and the limits marked | `board.clocks` | +| **Devices and DMA** | Each device's class, binding fields, chip selects and DMA channels; add a part from a module | `devices.*` | +| **RTOS** | Threads (priority, stack, entry), objects, priority ceilings; a budget bar for RAM, flash and stack | `rtos.*` | +| **Memory and partitions** | Regions, flash partitions, and how the image uses them after a build | `board.memory`, the build report | +| **Build** | Output, size per component, warnings | `build.*` | +| **Flash and console** | Probe, flash, the serial console | `flash.*`, `monitor.*` | +| **Debugger** | Breakpoints, stepping, registers, memory, **RTOS threads and their states, stack high-water marks, devices and their lifecycle** | DAP; the RTOS's debug descriptor (A107) | +| **Crash report** | A decoded crash record: fault, thread, location, registers | `crash.decode` | +| **Evidence** | This board's hardware runs, passed or failed; the support matrix | `evidence.*` | +| **Settings** | Toolchains, probes, the core's log, preferences | `toolchain.*`, `.emblink-studio/` | +| **Trace and timing** (later) | Thread timeline, interrupt latency, power residency | The RTOS's trace (M4.3), timing tools | + +**The editor** grows in three steps: + +1. Syntax highlighting (KSyntaxHighlighting, MIT) and an "open in your editor" action. +2. C and C++ intelligence through a language-server client talking to clangd (completion, errors, go to definition), using the build's `compile_commands.json`. +3. Search, refactoring, git. + +## 8. The plan: stages + +Ten stages, each ending in something usable and demonstrated. S0 is done: CI builds and tests on Windows, Linux and macOS (2026-11-11). Acceptance is checked in CI where possible. Where a check needs real hardware, CI runs it on EmbSIM and a person runs it on the board, with the result recorded as evidence. + +| Stage | Delivers | Accepted when | Needs from the RTOS | Status | +| --- | --- | --- | --- | --- | +| **S0 Setup** | The EmbLink Studio repository, its licence files and contributor agreement, CI on Windows, Linux and macOS, a Qt application that starts and talks to a stub core | CI builds and tests on all three systems; `initialize` and `shutdown` succeed; the notices list is generated | Nothing | Done | +| **S1 Core foundation** | `emblink-studio-core serve`, `project.open` and `validate`, `board.*` from `hw.json`, `generate.run` | Opening the RTOS's `nucleo_f446re` and `pico2_w` boards shows their model; validation reports the generator's errors with their locations | JSON diagnostics from `emb-hwgen`; a versioned `hw.json` | Not started | +| **S2 Read-only views** | Board, pin map, clock tree, devices, memory, RTOS, problems | For both boards, a golden test finds every value in the views equal to `hw.json` and to the generator's `board.md` and `build_report.md` | Existing outputs | Not started | +| **S3 Editing** | `config.preview`, `apply`, `undo`; pins, devices and threads editable; live diagnostics | A pin conflict is refused with the generator's message; an edit's `git diff` touches only the lines it must; generation stays clean | `system.yaml` (E3) for threads | Not started | +| **S4 Build, flash, console** | Toolchain discovery, CMake build, flash by OpenOCD and picotool, serial console | A project is created, built, flashed and seen running on the NUCLEO-F446RE and the Pico 2 W; in CI, on EmbSIM's `nucleo_f446re` | The CMake package (A91) | Not started | +| **S5 Debugging** | DAP sessions; the RTOS-aware views; crash decoding | Breakpoints and stepping on both boards; threads and their states shown; a crash record decoded | The debug descriptor (A107), crashdec | Not started | +| **S6 Modules and parts** | `modules.*`, the parts catalog, adding a part as a device | A BME280 added from the parts module is generated, built and read on a board | The module contract and lock file (E1); EmbLinkRTOS-parts | Not started | +| **S7 Evidence and trace** | The evidence view; the trace and timing views as the RTOS provides the data | The board's hardware runs listed; a trace shown | HIL records; the trace ring (M4.3) | Not started | +| **S8 The editor** | clangd integration, search, git | Daily work is possible without another editor | Nothing | Not started | +| **S9 Release** | Signed installers (Windows MSI, macOS DMG, Linux AppImage); updates; the first public release | Installs cleanly on a new machine and opens the examples | A tagged RTOS release | Not started | + +**What the RTOS side provides, and when:** + +| EmbLink Studio needs | Status in EmbLinkRTOS | First needed | +| --- | --- | --- | +| Machine-readable diagnostics from the generator (JSON) | To add, early | S1 | +| A version field in `hw.json` and a published schema for it | To add, early | S1 | +| `hw.json` and the generated outputs for each board | Exists | S1 | +| `emb-hwgen generate` and `check` | Exists | S1 | +| The CMake package for applications outside the tree | Exists (A91) | S4 | +| crashdec, the HIL runner's records, the support matrix | Exist | S5, S7 | +| The debug descriptor and `emb devices` | Exist (A107) | S5 | +| The `emb` CLI | M4.3 | S4 | +| `system.yaml` generation: threads, objects, `emb_system_init()` | Phase E3 | S3 | +| The module contract, the project manifest and the lock file | Phase E1 (R-004) | S6 | +| The trace ring and its format | M4.3 | S7 | +| `include:` in the board schema, if the views need it | On request | S3 | + +Until the module contract and `system.yaml` exist, S1 to S3 work on what exists: the boards in the RTOS tree and their generated model. Threads become editable in S3 only once E3 lands; until then the RTOS view stays read-only. The core's project and module schemas are designed with the owner, and the RTOS adopts them in phase E1. + +## 9. Engineering rules + +- **Qt:** Qt 6.8 LTS, under the LGPL-3.0, **linked dynamically**, with no GPL-only module (Qt Charts, Qt Graphs, Qt Virtual Keyboard and Qt Creator's code are GPL or commercial). Check which 6.8 patch releases are published under the LGPL. If later LTS patches are commercial only, track the newest 6.x minor release instead. The installers ship Qt as replaceable shared libraries (frameworks on macOS), with the LGPL text and a link to Qt's sources, as the LGPL asks. +- **Widgets and Quick:** Qt Widgets for the frame, docking, tables and forms. Qt Quick, in `QQuickWidget`s, for the drawn views: pin map, clock tree, and later the trace timeline (§11). +- **Third-party libraries:** only under licences compatible with the open core: MIT, BSD, Apache-2.0, LGPL linked dynamically, MPL-2.0. **No GPL libraries** in the application. Some terminal and docking widgets are GPL, so check each one. GPL tools (GDB, OpenOCD) run as separate programs and are never linked. Toolchains are downloaded from their publishers, not bundled. +- **A notices list** of every component and its licence, C++ and Python alike, generated in CI and shown in the About box. CI fails on a licence that is not on the allowed list. +- **Tests:** Qt Test for the application; pytest for the core; JSON Schema checks of every message in both directions; golden projects (the RTOS's boards) whose generated outputs, YAML edits and builds are compared in CI; the GUI tested against a recorded core. +- **Reproducibility:** pinned dependencies, pinned toolchains with checksums, the lock file. The same project gives the same build in the IDE and on the command line. +- **Code:** clang-format for C++, ruff for Python; every commit signed off (`Signed-off-by`, the DCO). +- **Accessibility and languages:** keyboard navigation throughout; Qt's translation system from the start, even with only English at first. +- **Privacy:** no telemetry by default. Anything collected later is opt-in. + +**Security.** Opening a project can run code: CMake scripts, module hooks, the project's pinned generator. + +- **Trust.** A project opened for the first time is untrusted. The views read its files, but nothing in it runs (generate, build, flash, debug answer `untrusted`) until the person trusts it once with `project.trust`. Trust is remembered per path in the user's own settings, never in `.emblink-studio/`, so a project cannot ship its own trust. +- **Downloads.** Toolchains, and the bundled Python if §11 chooses one, are checked against SHA-256 sums pinned in the core's release. A mismatch is refused, never warned. +- **Modules** are fetched at the exact commits in the lock file, and a hash mismatch stops the build. +- **No listening sockets.** The core talks over standard input and output only. A DAP endpoint listens on the loopback address, with a one-time token. + +## 10. Licence, ownership and the name + +- **Licence:** Apache-2.0 for everything in the open core: the application, the core and the schemas. The repository carries [`LICENSE`](../LICENSE) and a [`NOTICE`](../NOTICE) file, as Apache-2.0 expects. +- **A commercial "Pro" tier** may come later. Which features it holds is the owner's decision. Candidates are advanced trace and timing analysis, power profiling, certification-report generation, and team features. The open core must stay complete for everyday work. +- **Ownership.** Every contributor, the EmbLink Studio developer included, signs the **contributor licence agreement** before their first contribution is merged. It lets the project offer the code under other terms later, the Pro tier included. A lawyer checks it before anyone signs; the Apache Software Foundation's individual agreement is a common model. A CLA bot on pull requests records who has signed. +- **The CLA and the DCO do different jobs.** The CLA grants the project rights to the code, once per contributor. The DCO sign-off on each commit says the author may submit it. Both stay. +- **Owner and developer.** They agree in writing on credit and on any future revenue from EmbLink Studio **before the developer's first merge in S0**, since most of the early code is the developer's. +- **The name.** "EmbLink Studio", "EmbLink" and "EmbLinkRTOS" are the project's names. A trademark policy says forks may use the code but not the names. Before the repository is announced in public, a trademark search checks "EmbLink Studio" against SEGGER Embedded Studio and others in the classes for software (class 9) and software services (class 42). A web search on 2026-11-11 found Wilcom selling embroidery software as "EmbStudio", the same word in class 9, so the IDE was renamed EmbLink Studio before anything was announced. A search of the registers is still to do. + +## 11. Questions settled on 2026-11-11 + +All ten questions are settled: the owner accepted each recommended answer on 2026-11-11, and §2 records them. Questions 1 to 7 came from v0.1, and 8 to 10 are new. This table keeps the reasoning. + +| # | Question | Recommended answer | Why | Decision | +| --- | --- | --- | --- | --- | +| 1 | The docking framework | **Qt Advanced Docking System** (LGPL-2.1, linked dynamically) | Tabbed, floating and split docks, and saved layouts, which Qt's own `QDockWidget` lacks. KDDockWidgets is GPL or commercial. If ADS ever fails, fall back to `QDockWidget` | Decided | +| 2 | Where Qt Widgets and Qt Quick are used | Widgets for the frame, docks, tables, forms and the editor; Quick in `QQuickWidget` for the pin map, clock tree and trace timeline | Widgets are best at dense tool UIs and text. Quick is best at drawn, zoomable, animated views | Decided | +| 3 | Installers, updates, signing | Windows: MSI built with WiX, Authenticode-signed. macOS: a universal DMG, Developer ID signed and notarized. Linux: AppImage built with linuxdeploy. Updates: an in-app check against a signed release feed at first; Sparkle and WinSparkle (both MIT) later | Standard per platform. Signing needs paid certificates (an Apple developer account, a Windows code-signing certificate), which is the owner's cost to approve | Decided | +| 4 | How the core is packaged | **A bundled, relocatable CPython** (python-build-standalone builds) with the core in a private environment, not PyInstaller | The core runs the project's pinned `emb-hwgen` (§4), and that needs a real interpreter. A frozen PyInstaller program has none. A system Python varies by machine and breaks reproducibility. Each RTOS revision's tool dependencies go in an environment keyed by the lock file's hash | Decided | +| 5 | Which comes first after S2: debugging (S5) or modules (S6) | **S5, debugging** | What it needs from the RTOS exists today (A107, crashdec). S6 waits for the module contract (E1) | Decided | +| 6 | The Pro tier: which features, and when | Decide after S7. Until then, write nothing Pro-only, and keep trace, power and reporting as separable modules | By S7 it is clear what everyday work needs, and so what must stay open | Decided | +| 7 | The trademark check on "EmbLink Studio" | A search in classes 9 and 42 before the repository is announced, by a trademark attorney if the budget allows | A rename after release costs far more than one before | Decided | +| 8 | Supported platforms | Windows 10 22H2 and 11 (x64); macOS 13 or later (Apple silicon and Intel, one universal build); Ubuntu 22.04 and 24.04 (x64). Arm64 Windows and Linux later | Within Qt 6.8's supported platforms, and what CI's hosted runners provide | Decided | +| 9 | Where the repository lives | `EmbLinkOs/EmbLinkStudio` on GitHub, beside the RTOS | One organisation and one CI system; issues can link across repositories | Decided | +| 10 | Versioning and RTOS compatibility | EmbLink Studio uses semantic versioning. Each release states the RTOS revisions it supports (§4), and the evidence view shows that range | Users must be able to tell whether a project will open before they open it | Decided | + +## 12. Changes from v0.1 + +The review of v0.1 found 15 gaps, the name among them. Four could have caused rework or a wrong build: the `emb` name clash, which generator runs, YAML round-tripping, and project trust. The rest were missing detail. + +| Gap in v0.1 | Effect if left | Fix in v0.2 | Where | +| --- | --- | --- | --- | +| The core's server was `emb serve`, but the `emb` CLI belongs to EmbLinkRTOS | Two repositories shipping one command | The core is `emblink-studio-core`, with `serve` | §4 | +| Which `emb-hwgen` the core runs was not said | A bundled generator would differ from the project's pinned RTOS, and IDE builds would differ from CLI builds | The core runs the project's pinned RTOS tools, within a stated range | §4, §11 q4 | +| No rule for YAML comments and formatting on edit | IDE edits would rewrite whole files, with noisy diffs and lost comments | Round-trip editing (ruamel.yaml) and golden diff tests | §6, §9 | +| Opening a project could run its code with no consent | A cloned project runs CMake or module code on open | Project trust and the `untrusted` error | §9 | +| Edits made outside the IDE were not handled | An IDE edit overwrites a change made in another editor | A content hash on `apply` and the `conflict` error | §5, §6 | +| No undo | Editing views without undo | `config.undo` and `redo` | §5, §6 | +| No cancellation, lifecycle or error codes | Builds that can't be stopped; each side guessing at errors | `$/cancelRequest`, `shutdown`/`exit`, an error table | §5 | +| No schema for the protocol | The C++ and Python sides drift apart | JSON Schemas in `protocol/`, tested on both sides | §5 | +| No debug adapter was named | The developer would have to pick or write one | GDB's DAP interpreter behind a thin core proxy | §4 | +| No behaviour when the core crashes | A frozen or confusing UI | Read-only views and a restart that reopens the project | §4 | +| No build configurations | Debug and release builds set by hand | `CMakePresets.json`, shared with the CLI | §6 | +| Hardware checks in S4 and S5 can't run in CI | Acceptance claims with no evidence | EmbSIM in CI, and board runs recorded as evidence | §8 | +| Qt 6.8 LTS patches may be commercial only for LGPL users | Unpatched Qt in releases | A check, and a fallback to the newest 6.x minor | §9 | +| References (A76, A91, A107, M4.3, E1, E3) were unexplained | A new developer can't follow them | Added to §13 | §13 | +| The name EmbStudio is already used by Wilcom's embroidery software | A trademark dispute, or a rename after release | Renamed EmbLink Studio, before any announcement | §2, §10 | + +Smaller changes: S2's acceptance is now an automated golden test, each stage lists what it needs from the RTOS, the Problems and Settings views were added, and Python dependencies are in the notices list. + +## 13. Terms used in the RTOS + +| Term | Meaning | +| --- | --- | +| SoC description | A YAML file describing a chip: memory, peripherals, interrupts, clocks, pins (`soc/`) | +| Board description | A YAML file describing a board: its chip, oscillators, pins, console, devices, partitions (`boards///board.yaml`) | +| System description | `system.yaml`: what a product does with the board: threads, objects, partitions | +| `emb-hwgen` | The generator: validates the descriptions and writes `generated/`, including `hw.json` (the resolved model, the core's main input). Lives in `hw/gen/` | +| Compatible | A `vendor,part` string that names the driver for a peripheral or part | +| Binding | The entry in `drivers/bindings.yaml` saying which driver, class and configuration fields a compatible has | +| Device | A peripheral or part the board uses, with its driver, configuration and dependencies (SPEC-016) | +| Driver class | The interface a kind of device has: UART, SPI, I2C, DMA, GPIO, watchdog, flash, RTC, entropy (SPEC-017) | +| Partition | A named range of flash, such as `app` or `storage` | +| Debug descriptor | A table the kernel keeps in memory, so a debugger can find threads, objects and devices (A107) | +| Crash record | What a fault leaves in memory that survives a reset; crashdec decodes it | +| HIL | Hardware in the loop: the test suite run on a real board, its records archived as evidence | +| EmbSIM | The project's own simulator of microcontrollers and boards, used in CI | +| Evidence | The records that prove a claim: test results, hardware runs, measurements | +| A*n* | An accepted amendment to the specs, listed in `docs/specs/AMENDMENTS-M*.md` | +| A76 | Boards outside the RTOS tree, found through `EMB_BOARD_ROOT` (SPEC-014) | +| A91 | Applications outside the tree: the RTOS's CMake package (`emb_add_executable()`) | +| A107 | The debug descriptor, version 1 (SPEC-015 §5), and `emb_gdb.py`, which lists threads and walks their stacks | +| M4.*n* | A milestone of the RTOS roadmap's phase M4 (`docs/architecture/07-roadmap.md`) | +| M4.3 | The milestone that brings the `emb` CLI and the trace ring (CTF) | +| E1 to E5 | The ecosystem phases of R-004. E1: the module contract, project manifest and lock file. E3: the configurator engine, generating `system.yaml`'s threads and objects with `emb_system_init()`. E2, E4 and E5 cover parts, the VS Code extension (now replaced by EmbLink Studio) and RTOS-aware debugging | + +## 14. Where to read further, in EmbLinkRTOS + +- `docs/specs/SPEC-014-hardware-description-schema.md`: the descriptions and the generator's outputs. +- `docs/specs/SPEC-016-device-and-driver-model.md` and `SPEC-017-driver-classes.md`: devices and classes. +- `docs/specs/SPEC-015-observability-formats.md` and `docs/engineering/debug-descriptor.md`: the debug descriptor and the crash record. +- `docs/specs/AMENDMENTS-M3.md`: A76, A91 and A107 in full. +- `hw/gen/`, `hw/schemas/`: the generator and its schemas. +- `boards/st/nucleo_f446re/`, `boards/rpi/pico2_w/`: two real boards and their `generated/` outputs. +- `tools/crashdec/`, `tools/descriptor/` (with `emb_gdb.py`, the base for the debugger's RTOS views), `tools/hil/`, `tools/support/`: the tools EmbLink Studio drives. +- `docs/research/R-004-ecosystem-addons-configurator-integrations.md`: modules, parts and the configurator. It is on the `docs/ecosystem-design` branch for now. This specification takes precedence where they differ on EmbLink Studio. diff --git a/protocol/README.md b/protocol/README.md index d2a01db..07d4cc8 100644 --- a/protocol/README.md +++ b/protocol/README.md @@ -4,6 +4,6 @@ One JSON Schema (draft 2020-12) per method's parameters and result, named `.params.schema.json` and `.result.schema.json`, plus `error.schema.json` for every error response. The core's tests (`core/tests/test_schemas.py`) check every -message the core sends against them. The protocol is described in the specification, §5. +message the core sends against them. The protocol is described in the [specification](../docs/specification.md), §5. Protocol version: 0.1.0. A change that breaks an existing client bumps the major version.