My32Blit_C — C-API SDK & Firmware for 32Blit Console

My32Blit_C is a clean-room C port of the 32Blit SDK and firmware. It provides a lightweight, highly optimized C API for developing games and applications for the 32Blit retro console, bypassing the C++ overhead while maintaining maximum hardware performance and structural cleanliness.

---

🚀 Key Features

• Complete C-API SDK: Core modules for 2D graphics, vector math, audio synthesis, file I/O, saves, tweens, timers, and particle effects.
• Firmware Launcher & App Manager: Built-in graphical game browser, metadata parser, and dynamic application switcher.
• Hardware Drivers (BSP): Full board support package for the STM32H750VBT6 microcontroller (LTDC display driver, DMA2D accelerator, I2C, QSPI, hardware RNG, SD card FatFS port, and USB CDC/MSC stacks).
• Audio Streaming: Real-time wav/mp3 streaming and mixing on DMA-backed channels.
• Unified Standalone Build Helper: Simplify building external projects into relocatable .blit files via CMake.

---

📂 Repository Directory Structure

The repository is organized cleanly by concerns:

My32Blit_C/
├── src/
│   ├── platform/           # Microcontroller & Board Support Package (BSP)
│   │   ├── main.c          # Firmware entry point
│   │   ├── bsp/            # LCD, Audio, SD, USB, and sensor driver implementations
│   │   └── utils/          # Low-level helpers (syscalls, error handlers, FatFS port)
│   │
│   ├── sdk/                # Core SDK API Layer
│   │   ├── app.ld          # Standalone application linker script
│   │   └── engine/         # SDK interface & game engine modules (flat public headers)
│   │       ├── audio/      # Synth mixer and wav/mp3 audio streaming
│   │       ├── core/       # Input handler, API bridge symbols, and boot configuration
│   │       ├── graphics/   # Text, fonts, primitives, blend modes, surfaces, and tilemaps
│   │       ├── math/       # 2D/3D vectors, matrices, and interpolation geometry
│   │       ├── services/   # File access wrappers, save slots, tweeners, and timers
│   │       └── system/     # System overlays and application lifecycle management
│   │
│   ├── utils/              # Cross-platform utility modules
│   │   └── logger/         # Serial & USB logger with severity levels and multiple sinks
│   │
│   ├── apps/               # Integrated firmware applications
│   │   ├── launcher/       # Graphical menu, SD card scanner, and metadata viewer
│   │   └── demos/          # Default firmware demos (e.g., Snake)
│   │
│   └── test/               # Diagnostic & validation suites
│       ├── diagnostics/    # Graphics, audio stream, battery, and screen mode tests
│       ├── hw/             # Direct LED and backlight hardware tests
│       └── unit/           # Unit test modules (e.g. math tests)
│
├── cmake/                  # CMake toolchains and modules
│   ├── tools/              # Clang tools & Python discovery helpers
│   ├── microcontrollers/   # STM32H7 compiler options
│   └── stm32cubemx/        # CubeMX generated HAL & CMSIS libraries wrapper
│
├── docs/                   # Developer documentation & reference guides
│   ├── 00_index.md         # Master index & system context graph (Mermaid)
│   ├── 01_getting_started.md # Onboarding, toolchain config, hello world tutorial
│   ├── 02_architecture.md  # System boot, LCD scaling, SAI audio DMA, drivers
│   ├── 03_memory_map.md    # Linker layout, physical memory domains, cache coherency
│   ├── 04_blit_format_and_loader.md # Relocatable app wrapper, ELF relocation, loading process
│   └── 05_api_reference.md # Complete public API reference manual
│
└── standalone/             # Standalone game startup files and API bridge

---

📚 Developer Documentation

For detailed information on design, memory maps, and application development, refer to the Master Index & System Context Graph, which links all the developer manuals:

• 01. Getting Started & Game Dev Guide: Toolchain configuration, asset pipelines, Hello World game setup, and serial port logging.
• 02. Systems Architecture Reference: Hardware drivers, SAI mixing, LCD upscaling, and initialization pipeline.
• 03. Memory Architecture Map: Heap/stack placement, DTCM allocations, cache flushes, and alignments.
• 04. .blit Format & Dynamic Loader: Relocatable executables, bridge interface, and runtime loading sequence.
• 05. SDK API Reference Manual: Exhaustive reference documenting the structural declarations and function interfaces.

---

🛠️ Getting Started & Building

Prerequisites

Ensure you have the following installed on your system:

• CMake (v3.22 or higher)
• Ninja build tool
• GCC ARM Embedded Toolchain (arm-none-eabi-gcc)
• Python 3 (with virtualenv) for asset compilation and .blit metadata packaging

1. Building the Firmware

To build the RetroGo-like launcher and firmware binary:

# Create a build directory
mkdir build
cd build

# Configure the build system (using Ninja)
cmake .. -G Ninja

# Compile
ninja

This generates My32Blit_C.elf, My32Blit_C.bin, and My32Blit_C.hex in the build/ directory.

2. Building Standalone Games

External game repositories (such as My32Blit_C_Examples) reference the SDK's CMake helper at cmake/32blit-sdk.cmake. To compile and package a game:

# In your game's CMakeLists.txt:
cmake_minimum_required(VERSION 3.22)
project(my_game C ASM)

# Include the 32Blit C SDK Helper
include("/path/to/My32Blit_C/cmake/32blit-sdk.cmake")

# Define the game executable, sources, and metadata YAML
blit_executable(${PROJECT_NAME}
    "main.c;helpers.c"
    "${CMAKE_CURRENT_SOURCE_DIR}/metadata.yml"
)

Run CMake configuring against the ARM Toolchain and compile:

mkdir build
cd build
cmake .. -GNinja -DCMAKE_TOOLCHAIN_FILE="/path/to/My32Blit_C/cmake/toolchains/gcc-arm-none-eabi.cmake"
ninja

This compiles your code, attaches metadata, builds relocation tables, and outputs a flashable <game_name>.blit binary ready for your SD card.

---

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.