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