CockpitVM

Status: research prototype — see docs/validation/ for current validation evidence.

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.

Known Issues

• vm_compiler header generation does not fully comply with the CVBC specification
• vm_compiler emits RET (0x09) instead of HALT (0x00) — workaround active in VM
• vm_compiler delay multiplication by 17,000 — workaround divides by 17,000 in VM
• Live STM32 sideband framed protocol: broker attaches to the correct lane and observes plain UART TX, but brokered framed requests (heartbeat, display snapshot) time out — framed RX/response on hardware is the current open bench blocker
• MQTT control plane runs without TLS/mTLS — secure transport is the next milestone (chunks 7.1.11a/b), not yet closed
• End-to-end wireless deploy/update/observe has not been recorded as a single evidence package — individual links (Wi-Fi, MQTT, fleet backend, bootloader) are proven; the assembled pipeline is not

---

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; deprecated Arduino-era opcodes rejected at artifact-check time under target-profile policy
• Dual-bank flash bootloader — Oracle bootloader with protobuf protocol programs CVM1 artifacts into the active or standby flash bank; 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

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
• MQTT control plane — Backend publishes deterministic command signals on queue events; Copilot handles MQTT-driven commands with polling fallback; publish failure is non-fatal to queue state (7.1.8 validation)
• 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 oracle across compiler, runtime, packer, and backend (7.1.0b validation)
• OTLP observability — MQTT-to-internal telemetry ingestion, OTLP exporter to Collector, operational dashboards for VM-level health and hypervisor fault trends

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 (OLED operational contract under live wireless conditions is the current active milestone)

---

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:  Oracle 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 Oracle 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 TODO	Active wireless MVP workstreams
Architecture Hub	Full architecture documentation