# 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.

---

## 2. Physical Cartridge & Expansion Slot Architecture
* **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](./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).

---

## 3. Networking Interface (10BASE-T1L)
* **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.

---

## 4. WASM Application Runtime (WAMR)
* **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.

---

## 5. Software HAL & FreeRTOS Architecture
* **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()`.

--- 

## 6. Display, Framebuffer & Core Allocation Strategy
* **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.