# 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 **Desktop Host Application** via FFI. 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). --- ## 2.1 Storage & Volume Model * **Internal System Store:** A dedicated internal non-removable storage volume holds the app launcher, system UI assets, status bar content, and core system resources. * The launcher and persistent status bar always load from internal storage so they remain available even when no cartridge is present. * This internal store is the trusted root for firmware updates, system apps, and a shared application bundle repository. * **External Cartridge Volumes:** Each cartridge slot can expose storage as a removable volume, such as SDMMC media, flash-backed smart cartridge storage, or USB mass-storage from an attached peripheral. * Cartridge insertion is detected dynamically; the runtime exposes each detected volume through the storage manager. * Volumes are treated as detachable devices separate from the internal system store. * **Namespace:** A custom volume namespace is preferred for clarity and platform identity. * Example mapping: `SYS:` = internal system store, `EXA:` = cartridge slot 0, `EXB:` = cartridge slot 1, etc. * **Access Semantics:** * The app launcher and status overlay use the internal volume as their primary source. * WASM applications may access external cartridge volumes via the exposed volume API, with explicit slot or volume identifier selection. * Cartridges may support read-only system assets, writable data partitions, or secure application storage depending on their hardware capabilities. --- ## 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 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()`. --- ## 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.