Skip to content

S1: the core opens a board, reads its model, validates and generates - #9

Merged
teo1747 merged 4 commits into
mainfrom
core/s1-foundation
Nov 12, 2026
Merged

teo1747 merged 4 commits into
mainfrom
core/s1-foundation

Conversation

@teo1747

@teo1747 teo1747 commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

The core side of S1 Core foundation (spec §8). Until the project manifest exists, the workspace is a board of an EmbLinkRTOS checkout, as the spec says S1 to S3 should work.

Methods (schemas in protocol/, a CLI form for each):

Method What it does
project.open, close, status Opens boards/<vendor>/<board>/ inside a checkout. Opening reads files and runs nothing. An emb-hwgen or hw.json outside the formats the core reads (emb-hwgen 0.x, hw.json schema 0) is refused with unsupported_rtos
board.list, describe, pins, clocks, memory The generator's resolved model, read from hw.json. Nothing is computed
project.validate Runs the checkout's own emb-hwgen and turns its lines (rule HW-002) into diagnostics with the file, line and YAML path
generate.run, diff Runs the generator; diff writes to a temporary directory and reports each file as unchanged, changed (with its diff), added or removed
project.trust Running the generator runs the checkout's code, so it waits for trust (spec §9). Trust is kept per path in the person's own settings

S1's acceptance, tested in CI against the RTOS at pinned commit a2cb045:

  • nucleo_f446re and pico2_w open and show their model: STM32F446RE at 180 MHz with PA2 on usart2_tx, and RP2350A at 150 MHz with GPIO0 on uart0_tx. Every view equals the board's hw.json.
  • A copy of the NUCLEO's description, broken three ways, reports each error at its exact line and path, for example board.yaml:25: pins.usart2.tx: PA2 af9 is not usart2_tx (PA2 offers af7 usart2_tx).

Other changes

  • PyYAML is now the core's dependency, since the generator reads YAML with it. It's listed in third_party/components.json.
  • The spec's table now records that hw.json already has its version and schema. JSON diagnostics from the generator are still to come; until then the core reads the documented line format.

Tests: 53 pass locally with the real RTOS (48, with the acceptance tests skipped, without it). Ruff is clean.

Next for S1: the desktop side, opening a board from the app and showing its model and diagnostics. S2 then builds the real views on these methods.

Found by the acceptance tests: a generator bug in EmbLinkRTOS. On Python 3.11, emb-hwgen crashes while reporting a clock error. emb_hwgen/clock.py's _mhz formats a Fraction with :g, which Python only accepts from 3.12, yet the RTOS supports 3.10+. The core reports the crash correctly as tool_failed with the traceback. The acceptance test checks the clock error on 3.12+ only until the RTOS is fixed and the pin is raised. The fix is one line: f"{float(Fraction(hz) / 10**6):g} MHz".

The core's first workspace is a board of an EmbLinkRTOS checkout, until the
project manifest exists (spec section 8: S1 to S3 work on the boards in the
RTOS tree and their generated model).

- project.open, close, status: a board directory, boards/<vendor>/<board>/, inside
  a checkout. Opening reads files and runs nothing. A checkout whose emb-hwgen or
  hw.json is outside the formats the core reads (emb-hwgen 0.x, hw.json schema 0)
  is refused with unsupported_rtos.
- board.list, describe, pins, clocks, memory: the generator's resolved model, read
  from hw.json; nothing is computed, in the core or the GUI.
- project.validate, generate.run, generate.diff: run the checkout's own emb-hwgen,
  with the core's Python, and turn its lines (HW-002) into diagnostics with the
  file, the line and the path in the YAML. diff writes nothing.
- project.trust: running the generator runs the checkout's code, so it waits until
  the checkout is trusted (spec section 9). Trust is kept per path in the person's
  own settings, never in a checkout.
- Every method has a command too: emblink-studio-core board list RTOS, project
  validate BOARD, generate diff BOARD, and the rest.
- PyYAML becomes the core's dependency: the generator reads YAML with it.

Schemas for every new method are in protocol/. Tests: a fake emb-hwgen with the
real interface and output, the protocol end to end, and S1's acceptance against
the real nucleo_f446re and pico2_w, with errors made in a copy of the NUCLEO's
description found at their lines; CI checks out the RTOS at a pinned commit for it.

Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com>
Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com>
Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com>
…'s generator is fixed

Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com>
@teo1747
teo1747 merged commit 98155a1 into main Nov 12, 2026
11 checks passed
@teo1747
teo1747 deleted the core/s1-foundation branch November 12, 2026 22:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant