frank-386 README

The project's README from github.com/rh1tech/frank-386. As one markdown file: README.md.

FRANK 386

Official page: frank.rh1.tech — hub for all FRANK boards and firmware.

i386 PC Emulator for RP2350 (Raspberry Pi Pico 2) with VGA/HDMI output, SD card storage, PS/2 and USB keyboard/mouse, NES gamepad, and audio output.

Based on Tiny386 by Chunhui He.

Features

Screenshots

FRANK 386 in Action

Screenshot 1 Screenshot 2 Screenshot 3 Screenshot 4 Screenshot 5

Supported Boards

This firmware is designed for RP2350-based boards with integrated VGA/HDMI, SD card, and keyboard input:

Hardware Requirements

Note: When USB HID is enabled, the native USB port is used for keyboard/mouse input. USB serial console (CDC) is disabled in this mode; use UART for debug output.

Board Configurations

Four GPIO layouts are supported: M1, M2, PC (Olimex), and Z2 (Waveshare).

VGA / HDMI

Signal M1 GPIO M2 GPIO
Base 6 12
Range 6-13 12-19

SD Card (SPI mode)

Signal M1 GPIO M2 GPIO
CLK 2 6
CMD 3 7
DAT0 4 4
DAT3/CS 5 5

PS/2 Keyboard

Signal M1 GPIO M2 GPIO
CLK 0 2
DATA 1 3

PS/2 Mouse

Signal M1 GPIO M2 GPIO
CLK 14 0
DATA 15 1

NES/SNES Gamepad

Signal M1 GPIO M2 GPIO
CLK 14 20
DATA 16 26
LATCH 15 21

I2S Audio

Signal M1 GPIO M2 GPIO
DATA 26 9
BCLK 27 10
LRCLK 28 11

SD Card Setup

Directory Structure

Create a 386/ directory on your SD card:

SD Card Root/
└── 386/
    ├── config.ini      # Configuration file
    ├── bios.bin        # SeaBIOS ROM (required)
    ├── vgabios.bin     # VGA BIOS ROM (required)
    ├── dos622.img      # Hard disk image
    ├── boot.img        # Floppy image
    └── ...             # Other disk images

BIOS Files

Download SeaBIOS and VGA BIOS from the SeaBIOS releases or use bios.bin/vgabios.bin from sdcard/386.

Configuration File (config.ini)

Create 386/config.ini:

[pc]
mem=8M
bios=bios.bin
vga_bios=vgabios.bin

[frank-386]
cpu_freq=504
psram_freq=166

Preparing Disk Images

Floppy Images (.img):

Hard Disk Images (.img):

CD-ROM Images (.iso):

Loading Disk Images

At Boot: Configure disk images in config.ini as shown above.

At Runtime (Disk Manager):

  1. Press Win+F12 to open the Disk Manager
  2. Use arrow keys to select a drive (A:, B:, C:, D:, E:)
  3. Press Enter to browse disk images in the 386/ directory
  4. Select an image file to insert, or eject the current disk
  5. Press Escape to close the Disk Manager

Changes made via Disk Manager are saved to config.ini automatically.

Controls

Keyboard Shortcuts

Shortcut Action
Win+F12 Open Disk Manager
Win+F11 Open Settings Menu
Ctrl+Alt+Delete System reset (sent to guest OS)

Settings Menu (Win+F11)

Configure emulator settings at runtime:

Settings are saved to config.ini and take effect after restart.

Disk Manager (Win+F12)

Manage disk images without restarting:

Building

Prerequisites

  1. Install the Raspberry Pi Pico SDK (version 2.0+)
  2. Set environment variable: export PICO_SDK_PATH=/path/to/pico-sdk
  3. Install ARM GCC toolchain

Build Steps

# Clone the repository
git clone https://github.com/rh1tech/frank-386.git
cd frank-386

# Build with default settings (M2 board, 378MHz, PS/2 keyboard)
./build.sh

# Build for M1 board
./build.sh -M1

# Build with USB keyboard support
./build.sh --usb-hid

# Custom build
./build.sh -b M1 -c 504 -p 166 --debug

Build Options (build.sh)

Option Description
-b, --board <M1|M2|PC|Z2> Board variant (default: M2)
-c, --cpu <MHz> CPU speed: 378 (default), 504
-p, --psram <MHz> PSRAM speed: 133 (default), 166
--usb-hid Enable USB keyboard (disables USB serial)
--hdmi Force HDMI output
--debug Enable debug output
-clean Clean build directory first

Build Options (CMake)

Option Description
-DPICO_BOARD=pico2 Build for RP2350 (default)
-DBOARD=M1 Use M1 GPIO layout
-DBOARD=M2 Use M2 GPIO layout (default)
-DBOARD=PC Use Olimex PICO-PC layout
-DBOARD=Z2 Use Waveshare RP2350-PiZero layout
-DCPU_SPEED=378 CPU clock in MHz (378, 504)
-DPSRAM_SPEED=133 PSRAM clock in MHz (133, 166)
-DUSB_HID_ENABLED=ON Enable USB keyboard (disables USB serial)
-DDEBUG_ENABLED=ON Enable verbose debug logging
-DFORCE_HDMI=ON Force HDMI output

Release Builds

To build all firmware variants:

# Interactive (prompts for version)
./release.sh

# With version number
./release.sh 1.02

This creates firmware files in the release/ directory:

Flashing

# With device in BOOTSEL mode:
picotool load build/frank-386.uf2

# Or use the flash script:
./flash.sh

Troubleshooting

"0 bytes of memory" during Windows 95 setup

Use setup /im to bypass memory check.

"Protection error" during Windows 95 startup

Use patcher9x.

Enable mapdrive.com support (redirector) to map SD-card to network-attached-drive H

Set redirector = 1 in config.ini.

No keyboard input

SD card not detected

License

MIT License. See LICENSE for details.

Authors & Contributors

Mikhail Matveev & DnCraptor

Acknowledgments

This project is based on the following open-source projects:

Tiny386

Pico-286

QuakeGeneric

QEMU

MAME FM Sound Generator

inih

SeaBIOS

FatFs

FatFs Utilities

Raspberry Pi Pico SDK

frank-386 (rh1tech/frank-386)

Searching Database…

209 ·GitHub
Frank-386
What is this?FRANK 386 is an i386 PC emulator that runs as firmware on the Raspberry Pi Pico 2 (RP2350), turning the board into a tiny retro PC with VGA/HDMI video, SD-card storage, keyboard and mouse input, and sound. It is a port of Chunhui He's Tiny386.
So it's not a program I install on my computer — the Pico board itself becomes the PC?Exactly. You flash it onto an RP2350 board as firmware, and the microcontroller alone emulates the entire machine — CPU, video, sound cards and disk drives. No host computer is involved at runtime.
How do I get it running?Flash the .uf2 firmware built for your board onto the RP2350, then prepare a FAT32 SD card with a 386/ directory holding SeaBIOS and VGA BIOS files, your disk images, and a config.ini that points to them.
What hardware do I need besides the board?8MB of PSRAM is required for extended memory, plus a VGA or HDMI connector, an SD card module wired in SPI mode, and a PS/2 or USB keyboard. Audio output through an I2S DAC or PWM is optional.
How capable a PC is it, and what can it actually run?Think early-90s hardware: full i386 and partial i486/i586 emulation with an optional x87 FPU, up to 8MB of RAM, and graphics up to 640x480. Within that it boots DOS, Windows 3.x, Windows 95 and Linux.
Which boards can I flash it onto?Four GPIO layouts are supported: FRANK, Murmulator (M1 and M2 variants), Olimex PICO-PC, and Waveshare RP2350-PiZero. Release builds produce a separate .uf2 file for each board.
What sound hardware does it emulate?AdLib OPL2, Sound Blaster 16, PC Speaker, Tandy, Covox, Disney Sound Source and MPU-401 — all toggleable in the settings menu (Win+F11).
Can I swap disks without rebooting?Yes — Win+F12 opens a runtime Disk Manager for inserting and ejecting floppy (A:, B:), hard disk (C:, D:) and CD-ROM (E:) images, and changes are saved back to config.ini automatically.
Does Windows 95 run without tricks?Almost — two known quirks: pass setup /im to skip the memory check during installation, and apply patcher9x if startup stops on a protection error.
What are similar projects?tinygo, muse-gadget-sdk, Marlin, RetroPie-Setup, micropython, coyopedal, mu300-linux, zephyr
Which topics is it in?bare-metal, x86, arm, microcontroller, emulation, retrogaming, embedded-systems, emulator, cmake, virtualization, firmware, raspberry-pi
Creator
rh1tech
Size
21.8 MB
Stars
209
Updated
CommitSep 09Releasev1.05Aug 06
Age
8mo
Commits · 90 Days