Nova64 Cyberdeck Platform - High-Level System Specification

1. System Overview & Core Concept

Project Name: Nova64
Architecture Model: Dual-target modular system featuring a native execution core (nova64_core) running on top of FreeRTOS.
Target Microcontroller: ESP32-P4 (RISC-V architecture) driving local display output, audio generation, custom expansion bus, and network interfaces.
Desktop Simulator / Tooling: Native C core compiled as a shared library (.dll / .so) and driven by a C# Host Application via P/Invoke. Hardware dependencies are injected at runtime via function pointer callbacks (Dependency Injection pattern).
Central Unit Input Constraint: The base display unit contains no (or only limited) built-in physical input controls (no onboard buttons or D-pad). Control inputs are provided externally via connected cartridges, expansion modules, network interfaces, or desktop simulator inputs.

Mechanical Interface: Uses a 32-pin edge-connector format (Game Boy style form factor, required PCB thickness: 1.2 mm).
Poka-Yoke Protection: Custom mechanical keying (notches/grooves) to physically prevent legacy/original Game Boy cartridges from being inserted and damaging the 3.3V logic lines.
Bus Protocols & Interfaces:
- SD Card Interface (SDMMC): Dedicated high-speed lines. Rule: SD pins must remain allocated and accessible across all slot modes. This allows loading custom cartridge software for specialized cartridges.
- USB: Native USB Host / Device capability for smart cartridges or peripherals.
- I2C, SPI & CAN-Bus: Serial buses for sensors, co-processors, and expanders.
- Cartridge pinout reference: Detailed connector numbering, signal roles, and idle states are defined in CARTRIDGE_PINOUT.md to keep this document as the single high-level system spec.
- Power Bus: Supports dual-directional power delivery (supplying power to cartridges or receiving alternative system power/charging from external battery cartridges).

Protocol: 10BASE-T1L (Single-Pair Ethernet) for long-distance, industrial-grade point-to-point and networked communication between decks/modules.
Physical Cabling: routed through audio-style connectors/cables (e.g., 3.5mm/6.3mm jacks) to fit the cyberpunk aesthetic while maintaining robust single-pair data transmission.
Audio Use: the same 10BASE-T1L connector is also intended to carry analog audio signals in some modes, requiring dedicated isolation and protection circuitry to separate audio from data and to protect the network interface.

Runtime Engine: WAMR (WebAssembly Micro Runtime) embedded directly into nova64_core.
Execution Model: Sandboxed application layer for dynamic software, games, and cartridge binaries.
Cross-Platform Parity: Uncompiled WASM bytecode runs identically on both the physical ESP32-P4 hardware and the C# Desktop Simulator.
Host Bindings: WAMR exports host functions bound to the internal nova64_core APIs, allowing sandboxed WASM applications to draw to the framebuffer, play audio, and read cartridge storage safely.

Hardware Abstraction (I/O Callbacks):
- Core engine defines function pointer contracts: display_flush, audio_output, sd_read_sector, and cartridge_status (with slot_idx support for multi-slot setups).
- System initialized via nova64_init_io().

Dual-Core Processor Allocation (ESP32-P4):
- Core 0 (System & I/O Core): Handles background FreeRTOS tasks, hardware drivers, 10BASE-T1L networking stack, audio generation, and system status bar overlays.
- Core 1 (Execution Core): Exclusively dedicated to running the WAMR WebAssembly engine and application code, guaranteeing deterministic performance and preventing OS tasks from causing frame drops.
Framebuffer Architecture:
- Uses double-buffering (RGB565 format) to prevent screen tearing during active rendering.
- Framebuffers are explicitly allocated in External PSRAM via the AXI bus, enabling direct DMA (Direct Memory Access) streaming to the MIPI-DSI controller without CPU overhead.
- Application output and system UI are composited into the target buffer before triggering the host-injected display_flush callback (or VSYNC pointer swap).
Persistent System Status Bar:
- A reserved hardware/system UI region at the top of the display rendered independently by Core 0.
- Displays active cartridge ID, 10BASE-T1L link status, battery levels, and system health metrics without interfering with running WASM applications.