Deep Genesis: MNIST Neural Network on Sega Genesis

Training MNIST digit recognition neural network using PyTorch and running inference directly on the Sega Genesis console hardware using SGDK (Sega Genesis Development Kit).

🎮 Overview

This project demonstrates the intersection of modern machine learning and retro gaming hardware by:

1. Training: Using PyTorch to train a simple neural network on the MNIST dataset;
2. Converting: Transforming the trained weights into C header files;
3. Deploying: Running inference on the actual Sega Genesis hardware using integer arithmetic.

The neural network architecture is intentionally simple (784→40→40→10) to fit within the Genesis's memory constraints while still achieving good accuracy on digit recognition.

🔧 Requirements

Python Environment

Make sure you have the following tools installed:

• uv - Python version and dependency manager

Genesis Development

• SGDK v2.11 (Sega Genesis Development Kit);
• BlastEm emulator. (optional, for testing)

Environment Variables

Set these environment variables:

export SGDK_PATH=/path/to/sgdk
export BLASTEM_PATH=/path/to/blastem  # optional

🚀 Getting Started

1. Setup Python Environment

# Clone the repository
git clone https://github.com/Daniel-EST/deep-genesis-mnist.git
cd deep-genesis-mnist

# Install dependencies using uv (recommended)
uv sync

2. Train the Neural Network

# Train with default parameters (20 epochs, CPU)
just train

# Train with custom parameters
just train -e 50 -b 32 -d cuda

Training options:

• -e, --epochs: Number of training epochs (default: 20)
• -l, --lr: Learning rate (default: 0.001)
• -b, --batch: Batch size (default: 64)
• -d, --device: Device ("cpu", "cuda", "mps")

3. Convert Weights for Genesis

The weights are automatically converted after training, but you can also run manually:

just convert-weights

4. Build Genesis ROM

# Build the Genesis ROM
just build

# Build and run in emulator
just build && just play

5. Test Python Inference

# Test with a sample image
just predict path/to/image.png

# Use custom weights
just predict path/to/image.png -w ./data/models/custom.pt

🧠 Neural Network Architecture

The model uses a really simple fully-connected architecture:

Input Layer:    784 neurons (28×28 flattened image)
Hidden Layer 1: 40 neurons (ReLU activation)
Hidden Layer 2: 40 neurons (ReLU activation)
Output Layer:   10 neurons (digit classes 0-9)

🛠️ Available Commands

Using Just for task automation:

just build [args]               # Build Genesis ROM
just play                       # Run ROM in BlastEm emulator
just train [args]               # Train neural network
just qat [args]                 # Quantization Aware Train neural network
just quantize [args]            # Quantize neural network
just predict [args]             # Run Python inference
just convert-image [args]       # Convert image to C headers
just convert-weights [args]     # Convert weights to C headers
just clean                      # Clean build artifacts
just help                       # Show all commands

🎨 Visualization

When running on Genesis:

• Input image is displayed as a grayscale visualization;
• Logit scores for each digit (0-9) and prediction are shown.

TODO:

• Convolutional layers;
• Real-time drawing interface;
• Test on real hardware.

🙏 Acknowledgments

• SGDK by Stephane Dallongeville