# Intent MCU Simulator

> Intent MCU Simulator is an original, open-source browser workbench for supported ATmega328P projects, one bounded RP2040 Pico GPIO0/UART0 profile, one bounded ESP32-C3 GPIO2/UART profile, and one bounded STM32F429ZI PB0/USART3 profile.

Canonical application: https://lab.teachthecompany.com/
Source and setup: https://github.com/finnandrehotvedt/intent-mcu-simulator
Licence: Apache-2.0 for project-owned source; third-party components keep their own terms.
Current source release: 1.1.0-rc.149
Machine-readable release changes: /release-changes.json (strict static
intent-mcu-release-changes@1 metadata; no Apply, Build, Run, replay or verdict authority).
Offline support matrix: /offline-support-matrix.json (strict static
intent-mcu-offline-support-matrix@1 facts; loaded-tab local files do not add a service worker, offline compiler or Run authority).
Manual physical verification checklist: /physical-checklist.html (23 finite
profile-owned items; current-tab records are unverified user statements, not
device measurements, automatic verdicts, safety evidence or certification).

Local files: Download copy and ordinary Open are the reliable all-browser
actions. Supported secure desktop browsers may additionally offer explicit
Open & connect, Save connected file and Save copy. Native handles remain in
memory only and no server project storage exists.

Controller support: /controllers.html distinguishes compiler-accepted source,
executed runtime behavior and educational circuit models. It lists exact GPIO,
ADC, PWM, UART, timer, interrupt, language, header and library boundaries.
Current trustworthy build diagnostics can navigate to source; stale or unknown
locations remain readable and inert.

Component support: /components.html contains the exact 88-model by 4-profile
matrix. It distinguishes Simulated, Partial, authoring-only and Unavailable
cells, retains the AVR project-v2 versus candidate-v3 boundary, and never
treats one controller's board or parts as interchangeable with another profile.

## Supported public workflow

- Start with an empty project, one of twenty-four ready-made AVR examples, or either paired UART/LED example on each bounded Pico, ESP32-C3 and STM32 profile.
- The thermostat starter compiles the visible source and runs four reset-isolated virtual-time scenarios: below, equal, above and disabled. Pass requires executed D13, matching UART and complete ordered input evidence; its known-bad equality variant must fail exactly at 30 C.
- The partial X49 instrument compares only the exact AVR thermostat baseline 0 with candidate +1 C through one explicit temporary same-origin build and two fresh dedicated workers. Other offsets are calculated previews only. Accepted evidence is transient and retires on authority drift; physical evidence is absent.
- In the general AVR editor, choose among 66 executable models plus 15 authoring-only symbols and connect compatible named pin anchors manually. DHT11, DHT22, DS18B20 and the BME280 I2C environment sensor are executable only on AVR.
- Representable named-rail shorts, known output contention, supply-role mismatch, ground, polarity, resistance and bounded ideal-current faults fail closed with corrective actions. Arbitrary circuit solving and physical-safety claims are excluded.
- Edit source and compile it through the isolated, fixed AVR toolchain.
- Load and run the accepted artifact in the deterministic virtual MCU worker.
- Inspect GPIO, LEDs, buttons, potentiometers, serial bytes, logic traces, and pin state.
- On the AVR profile, inspect complete current-paused-worker USART0 TX byte
  events with cycle, byte, integer model baud and exact frame duration. This
  read-only X46 slice does not prove framing, RX, physical signals, I2C or SPI.
- Save and reopen a project file on the learner's computer; browser recovery is separate.
- Optionally enable first-party local version history and explicitly retain up to 3 or 10 canonical project files across all four profiles. It is off by default, never auto-captures source, never uploads a version and never restores file, build, runtime or result authority; it is convenience rather than backup.
- Build submits only the active profile's bounded source to this Lab's same-origin isolated compiler for one temporary job. Successful user firmware is returned only through that short-lived private job and is not retained in a shared artifact cache; an identical later Build compiles again. Pinned tool images and curated public examples remain reusable and separate. This is not cloud project storage: there is no account or durable server project, and temporary source/output follows the bounded cleanup lifecycle.
- Existing AVR/Pico, ESP32-C3 and STM32 queue, rate, job, session and concurrency limits return a positive bounded whole-second Retry-After value. It is advisory, reserves no capacity, requires a fresh request and never causes automatic browser retry.
- Optionally generate a portable Prompt Bridge request and validate returned structured circuit data.
- Select RP2040 Pico, create or reconnect its bounded GP0/resistor/LED/GND cables from named pins, edit the two bounded source values, compile in the fixed isolated Arm toolchain, and run the source-bound UF2 in the browser worker.
- Select ESP32-C3, create or reconnect its bounded GPIO2/resistor/LED/GND cables from named pins, edit only GPIO2 mode/level and an uppercase UART marker, compile a fixed DIO flash image, and run actual Espressif QEMU CPU/UART.
- Select STM32F429ZI, create or reconnect its bounded PB0/resistor/LED/GND cables from named pins, edit the PB0 HIGH/LOW plus uppercase USART3 source values, compile a strict source-bound ELF, and run actual Renode PB0/USART3/reset replay.
- In any narrow controller profile, restore one deleted resistor or LED from Supported parts after Save/Open, then explicitly reconnect its named pins. Add never infers a cable, and Open never restores executable authority.
- In the general AVR editor, click-add or drag a selectable part to a bounded canvas position. Duplicate makes one disconnected copy with a fresh stable ID; move/rotate/delete and complete Undo/Redo preserve existing IDs and named-pin references.
- In any narrow controller profile, select a cable to add an orthogonal bend, move an eligible snapped section, or choose one of six fixed colours. Crossings remain electrically separate unless a declared junction dot says otherwise.
- CMP-019 treats a junction as graph topology rather than a component: AVR stores an explicit junction ID, while Pico, ESP32-C3 and STM32 derive the visible dot from one validated net with at least three named endpoints. A different net crossing the same drawing point remains separate, and no junction restores Build/Run authority.
- In every controller profile, open Connections in Inspector to inspect every net and named pin as text, then select, delete, reconnect, or create compatible connections with the keyboard under the same strict revision and electrical checks as the canvas.
- In the AVR profile, create the finite resistor-and-LED reusable subcircuit by binding its explicit source and ground ports to existing nets. Instance move and collapse/expand are presentation-only; deterministic expansion, delete/Undo, Save/Open, recovery and local history retain the ordinary validated graph. This is not nested, arbitrary-topology or other-profile subcircuit support.
- Open Search current project to find and activate current components, named pins, nets, files, source lines, saved requirement/test owners and AVR scenario owners. Search is transient local presentation, makes no search-service request, saves no query/result state and rejects stale project identities.
- A valid X05 proposal review also shows deterministic typed authored facts for component, property, position, net and saved-test changes plus a complete literal source-file difference. Typed facts come only from the validated project schema and catalogue units. Source remains literal text: the review does not infer what source code means or what firmware will do. This detail view adds no Apply, Build, Run or verdict authority.
- Compare experiment packages opens one local Before file and one local After file, strictly reparses both canonical v3 packages and shows compatible identity, literal source, authored circuit and retained measured-result facts. Package bytes stay in the tab only. Comparison does not Build, Run, upload, infer causality, choose a winner or create a verdict.
- The retained AVR assessment is a local, read-only recomputation over one reviewed release-owned envelope: one fixed fixture, two already-recorded workers and the first 512 paused instructions. It found the same ideal CPU/GPIO/UART observations; both UART streams were empty. Independent rebuild-byte equality is not checked, physical equivalence is not claimed, and importing or reopening the envelope grants no Build, Run, project or runtime authority.

## Important limits

- The verified teaching profile is a bounded ATmega328P 16 MHz, 5 V subset, not complete hardware equivalence.
- Simulation is not physical safety certification and does not replace testing on suitable physical hardware.
- X49 native evidence is an academic emulator observation for one fixed pair, not sensor calibration, tolerance, probability, damage, factory or physical-hardware evidence.
- Prompt Bridge has no hosted AI API or agent/tool connection. It creates portable text for a user-selected tool.
- An optional separate local stdio adapter exposes strict read-only machine-readable discovery for four exact profiles, named pins, API/runtime limits, parts, quotas and versions, then connects another local client to exactly seven bounded actions through an ephemeral browser pinned to this Lab origin. It opens no listener, public API, account, credential or server project and cannot Apply a patch. Runtime observations keep their documented producer/model limitations.
- Stdio action results retain the authoritative router response and separately classify validation failure, unsupported, temporarily busy, timeout, cancellation, producer-backed test failure and other execution failure. Only busy recommends a bounded delayed retry with a new request ID.
- Thermostat academic outcomes are separately passed, failed, indeterminate or unsupported. Failed requires complete contradictory producer evidence; missing or out-of-window evidence is indeterminate. Job completion, cancellation, timeout and infrastructure error remain a separate status dimension.
- Free-form AI output cannot draw wires or authorize connections. Only schema-valid, electrically accepted project data reaches the canvas and worker.
- There are no accounts, advertising, cloud project storage, physical-device uploads, or live AI calls. The optional first-party footer counter stores only aggregate page-view totals; it uses no cookies, IP addresses, visitor IDs, fingerprinting, source or project content.
- Public execution supports the tested ATmega328P profile, one bounded RP2040 Pico GPIO0/UART0 source profile, one bounded ESP32-C3 GPIO2/UART source profile, and one bounded STM32F429ZI PB0/USART3/reset-replay source profile.
- ESP32-C3 publicly compiles one strict sketch grammar and runs actual QEMU CPU/UART with reset replay. The GPIO2/LED result is a separately labelled project-owned executed-register-write model; QEMU pin state is not observed, and no broad ESP32, SDK, Wi-Fi, Bluetooth, timing, or physical-device claim is made.
- RP2040 Pico publicly accepts one exact project-owned C11 grammar, compiles it in a networkless fixed Arm GNU 14.3.1 container, validates a source-bound UF2, and executes GPIO0/UART0 in rp2040js 1.4.0. It does not claim a complete Pico SDK, PIO, DMA, USB, multicore, timing, or physical-device model.
- STM32F429ZI publicly accepts one exact project-owned C11 grammar, compiles it in a fixed networkless Arm GNU 14.3.1 container, validates a source-bound ELF32, and executes PB0/USART3 in actual Renode 1.17.0 across reset replay. Its editable named-pin external LED path remains an ideal teaching circuit; no arbitrary C/ELF, SDK, broad peripheral, timing, physical-board, programming, or full STM32 claim is made.

## Primary documentation

- Public source README: https://github.com/finnandrehotvedt/intent-mcu-simulator#readme
- Controller support: https://lab.teachthecompany.com/controllers.html
- Supported components: https://lab.teachthecompany.com/components.html
- Starter examples: https://lab.teachthecompany.com/examples.html
- Pico first project: https://lab.teachthecompany.com/examples.html#pico-first-project
- ESP32-C3 first project: https://lab.teachthecompany.com/examples.html#esp32c3-first-project
- STM32 first project: https://lab.teachthecompany.com/examples.html#stm32-first-project
- Thermostat boundary experiment: https://lab.teachthecompany.com/examples.html#thermostat-boundary-test
- X49 exact contract and limits: https://github.com/finnandrehotvedt/intent-mcu-simulator/blob/main/docs/X49-AVR-TEMPERATURE-OFFSET.md
- Help and limitations: https://lab.teachthecompany.com/support.html
- Physical verification checklist: https://lab.teachthecompany.com/physical-checklist.html
- Contribution guide: https://github.com/finnandrehotvedt/intent-mcu-simulator/blob/main/CONTRIBUTING.md
- Security policy: https://github.com/finnandrehotvedt/intent-mcu-simulator/blob/main/SECURITY.md
- Project story: https://finnandre.no/2026/10/06/intent-mcu-simulator-apen-kildekode/
- Technical overview: https://www.intentforce.no/intent-mcu-simulator-apen-kildekode/