CockpitVM

Status: bounded Phase 7 MVP closed for the governed wireless deploy/update/observe loop; still a research prototype, not a production-certified runtime. See docs/governance/board/2026-04-29-phase7-closeout-summary.md and docs/validation/phase-7/ for the evidence spine.

What this project is: A research-grade embedded virtual machine system built around an ARM Cortex-M4 microcontroller (STM32G474 WeAct Studio CoreBoard). It executes C-like bytecode programs delivered over Wi-Fi from a fleet backend, with a sideband co-processor bridge, on-device bootloader, and OTLP-backed observability. Development is exploratory and test-driven, building understanding of embedded systems and AI-driven development through hands-on implementation.

What this project is not: A general-purpose hypervisor, a production-certified runtime, or a commercially supported product. The single supported hardware target is the STM32G474 WeAct CoreBoard.

MVP Scope and Non-Claims

Phase 7 closed a bounded MVP: one governed bench topology can compile guest source, retain and pack a canonical CVM1 artifact, send an authenticated wireless command path through the Copilot, program bytecode through vm_bootloader, run on CockpitVM, and surface operator truth through telemetry, dashboard, sideband, and OLED evidence.

The MVP intentionally does not claim broad shared-Wi-Fi or mesh-scale fleet acceptance, OTA trust-chain / anti-rollback closure, unrestricted remote introspection, full device-policy manifest enforcement, or Phase 8 scheduler/multi-VM runtime closure.

Current Caveats

• The bounded MVP topology is validated; larger fleet-scale rollout, reconnect-storm behavior, and mesh/root-node bottlenecks require explicit post-MVP hardening.
• Direct Influx persistence is proven for the recorded run family, but persisted sink timestamps currently reflect monotonic/uptime-style semantics rather than wall-clock epoch time.
• A VM-owned sensor contract was not included in the bounded recorded MVP run; dashboard and evidence paths record that as a deliberate non-claim.
• Device-policy manifest enforcement, sideband memory verification policy hardening, recurring remote-bench gates, and OTA trust-chain / anti-rollback are Phase 8 or post-MVP workstreams.

---

System Overview

CockpitVM is a full-stack embedded VM system. Guest programs written in a C-like language are compiled by a fleet backend, packed into portable CVM1 bytecode artifacts, and delivered OTA to the device via an ESP32 co-processor acting as a Wi-Fi and sideband bridge. The STM32G474 bootloader programs the artifact into dual-bank flash, and the CockpitVM hypervisor executes it.

Guest Source (C-like)
    → Fleet Backend (compile + pack → CVM1 artifact)
        → MQTT Control Plane
            → ESP32 Copilot (Wi-Fi uplink + sideband bridge)
                → STM32G474 Bootloader (dual-bank flash programming)
                    → CockpitVM Hypervisor (bytecode execution)
                        → Host ABI (GPIO, I2C, UART, timing)
                            → STM32G474 Hardware

The CockpitVM host control plane runs persistently and independently of the guest. Sideband heartbeat, OLED operator status, bootloader posture, and fleet connectivity are host-owned services; the guest VM is a supervised workload. See docs/architecture/PHASE_7_COCKPITVM_HOST_SERVICE_MODEL.md.

---

Validated Capabilities

VM Runtime

• ExecutionEngine_v2 — O(1) direct-indexed dispatch: 256-entry function pointer table, opcode byte as array index, single indirect call per instruction (see docs/architecture/COMPONENTVM_PROGRAMMERS_MANUAL.md)
• Static memory architecture — 24KB VM allocation at compile time; per-VM isolation with VMMemoryContext (1.75KB per instance); no heap, no fragmentation
• Host ABI v1 — Frozen contract for guest-to-host calls: GPIO, I2C, UART, timing, watchdog, blackbox. Schema-backed manifest governs all opcode and host-call semantics across compiler, runtime, packer, and fleet backend (lib/vm_schema/host_abi/p5_core_manifest.json)
• Guest stdlib — Frozen core API surface for guest programs; future host calls for controlled VM access to host peripherals, including UART, I2C, SPI, USB, and CAN.
• Dual-bank flash bootloader — CockpitVM defines a bootloader with fixed header layout (little-endian, packed on wire) and programs CVM1 artifacts into the active or standby flash bank over UART; bytecode programming is exclusively bootloader-owned
• End-to-end blinky proof — Guest C source → compiler → packer → bootloader → flash → hypervisor → hardware validated on STM32G474; 500ms delays measured at 498–502ms on-device (validation record)

Testing and Validation Infrastructure

• SIL QEMU harness — Software-in-the-loop test execution against a QEMU firmware image; bootloader protocol coverage validated in SiL before HIL
• GT Lite test runner — Microkernel test framework with stack verification, register inspection, and typed VMRunResult exit classification
• Golden Triangle Framework — Hardware validation with semihosting, timing measurement, and register inspection
• HIL tooling (hilctl) — Unified session/profile/backend management for hardware-in-the-loop bench work; pyOCD-first with CMSIS-Pack-backed STM32G474 target support; session governance prevents concurrent probe ownership
• Watchdog + blackbox — On-device fault recording and extraction; reliability suites validated in native and HIL modes

Phase 7 MVP Hits

• Recorded wireless deploy/update/observe loop — Closed 7.1.16 as a bounded MVP demo package: backend compile/retain, command orchestration, Copilot publish/ACK, bootloader upload, runtime verification, dashboard truth, and explicit non-claims.
• Secure Copilot control plane — Wi-Fi AP/VLAN reachability, MQTT command signaling, TLS server authentication, and mTLS device authentication are validated for the canonical path.
• Canonical artifact spine — Schema-backed ISA SSOT, compatibility-spine test oracle, canonical CVM1 packer, backend compile retention, differential compile checks, semantic reference coverage, and negative-policy tests keep compiler/runtime/backend drift visible.
• Host-owned operator truth — OLED status is host-owned, provenance-backed, and aligned with backend, sideband, blackbox, slot, and link evidence rather than guest-owned UI behavior.
• Bench and sideband hardening — Direct-link orchestration, brokered named serial lanes, CockpitVM host-resident sideband service, cooperative host supervisor, and hilctl/SWD-lite ownership rules make the MVP evidence reproducible without hidden operator lore.
• Persistent observability path — MQTT telemetry topic fleet/devices/{device_id}/telemetry, dashboard state, backend ingest, persistent sink query, and OTLP-facing export path are tied into the release evidence.

Sideband and Fleet Infrastructure

• ESP32 Copilot — Co-processor bridge: Wi-Fi station mode, MQTT command handling, OTA upload orchestration; GPIO-remapped dedicated runtime sideband UART separate from programming contact
• Sideband protocol — Framed host↔co-processor protocol with ISR-ingress, cooperative foreground servicing, and deferred bootloader invoke under active VM load; host sideband state machine covers READY, RX_ACTIVE, PROCESSING, BOOTLOADER_REQUESTED, and DEGRADED
• Fleet backend — Remote compile endpoint, CVM1 artifact retention, MQTT command signal publication, OTLP observability export; validated end-to-end against a remote containerized fleet host
• Secure MQTT control plane — Backend publishes deterministic command signals on queue events; Copilot handles MQTT-driven commands with polling fallback; TLS and mTLS secure the canonical MVP broker path (7.1.8, 7.1.11a, 7.1.11b)
• Wi-Fi and VLAN reachability — Copilot associates to target AP in station mode, reaches fleet backend and MQTT broker from Wi-Fi VLAN, reconnect cycle validated (7.1.9 validation)
• Schema-backed ISA SSOT — Single JSON manifest is the source of truth for all opcode semantics; compatibility spine serves as a standing regression test oracle across compiler, runtime, packer, and backend (7.1.0b validation)
• Persistent observability — MQTT-to-internal telemetry ingestion, OTLP exporter path, persistent Influx sink proof, and operational dashboards for device heartbeat, VM lifecycle, upload state, slot/artifact posture, and operator truth

OLED Operator Surface

• SSD1306 128×32 I2C OLED mapped through optional Host ABI I2C group; host-owned operator status surface independent of guest execution state. Phase 7 froze the OLED operational contract and proved aligned operator truth with provenance-controlled bytecode and blackbox-backed evidence.

---

Architecture

Six-Layer Stack

Layer 6: Guest Application       (C-like bytecode programs)
Layer 5: VM Hypervisor           (CockpitVM core, ExecutionEngine_v2)
Layer 4: Host Interface          (Host ABI: gpio_pin_write, uart_begin, i2c_write, …)
Layer 3: Platform Layer          (STM32G4 adapter)
Layer 2: STM32 HAL               (Vendor library)
Layer 1: Hardware                (STM32G474 WeAct CoreBoard)

Hardware Platform

MCU:    STM32G474 WeAct Studio CoreBoard, ARM Cortex-M4F @ 168MHz
Flash:  128KB dual-bank (bootloader 16KB, hypervisor 48KB, bytecode banks 2×32KB)
RAM:    32KB (system 8KB, VM allocation 24KB — static, compile-time)
UART1:  Bootloader client / sideband to ESP32 co-processor
UART2:  Runtime Diagnostic Console (PA2/PA3, 115200)
I2C:    SSD1306 OLED (PB8/PB9)
Co-processor: ESP32-C6 (Wi-Fi station, MQTT, OTA upload, sideband bridge)

Instruction Format

typedef struct {
    uint8_t  opcode;     // 256-entry dispatch table
    uint8_t  flags;      // variants
    uint16_t immediate;  // constants / addresses
} vm_instruction_t;

Memory Layout

Flash (128KB):
  Bootloader:      16KB   — CockpitVM bootloader (sole programming owner)
  Hypervisor:      48KB   — VM runtime + host interface
  Bytecode Bank A: 32KB   — active bytecode slot
  Bytecode Bank B: 32KB   — OTA receive / standby slot

RAM (32KB — fully static, no heap):
  System:    8KB   — bootloader + hypervisor
  VM Memory: 24KB  — guest applications (compile-time allocated)

---

Quick Start

Prerequisites: PlatformIO CLI, STM32G474 WeAct Studio CoreBoard, ST-Link V2.

git clone <repository> && cd cockpit

# Build and upload firmware
~/.platformio/penv/bin/pio run --environment weact_g474_hardware --target upload

# Flash a bytecode artifact via CockpitVM's bootloader
cd tests/oracle_bootloader && source oracle_venv/bin/activate
python oracle_cli.py --flash <artifact.cvm1>

# Run SIL test suite
cd tests && ./tools/run_test smp_sos_multimodal_coordination

---

Documentation

Document	Purpose
ComponentVM Programmers Manual	ExecutionEngine_v2, dispatch, memory
Host ABI	Host interface contract
Guest Stdlib API	Guest-facing API surface
Phase 7 Host Service Model	Host vs guest ownership boundary
Hardware Integration	STM32G474 bring-up and bench setup
Traceability	SCN-* scenario traceability table
Phase 6 Release Gate	Phase 6 go/no-go checklist
Phase 7 Closeout Summary	Bounded MVP claims, non-claims, and deferrals
Phase 7 TODO	Closed wireless MVP workstreams and Phase 8 handoff
Phase 7 Release Bundle	Bounded-MVP GitHub release staging rules
Architecture Hub	Full architecture documentation