Skip to content

rh1tech/frank-apple

BranchesTags

Repository files navigation

FRANK Apple

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

Apple IIe Emulator for RP2040/RP2350 (Raspberry Pi Pico, Pico 2 or similar) with HDMI output, SD card, PS/2 and USB keyboard, and audio.

Screenshots

FRANK Apple start screen Apple IIe boot

Disk selection UI Apple II software running

Supported Boards

This firmware is designed for the following RP2350-based boards with integrated HDMI, SD card and PS/2 or USB HID:

  • FRANK — A versatile development board based on RP Pico 2, HDMI output, and extensive I/O options.
  • Murmulator — A compact retro-computing platform based on RP Pico / Pico 2, designed for emulators and classic games.

Both boards provide all necessary peripherals out of the box—no additional wiring required.

Features

  • Full Apple IIe emulation with 65C02 CPU
  • Native 320×240 video output via PIO (HDMI or VGA)
  • All video modes: Text, Lo-Res, Hi-Res, Double Hi-Res
  • SD card support for DSK, NIB, WOZ, and BDSK disk images
  • Disk write-back support (saves changes to .bdsk files)
  • PS/2 keyboard input
  • USB keyboard input (via native USB Host)
  • NES/USB gamepad support (via USB HID)
  • USB hub support for multiple devices
  • Audio output via I2S (external DAC) or PWM

Hardware Requirements

  • Raspberry Pi Pico (RP2040), or Raspberry Pi Pico 2 (RP2350), or compatible board
  • Video output (choose one):
    • HDMI connector (directly connected via resistors, no HDMI encoder needed)
    • VGA connector (accent resistor DAC)
  • SD card module (SPI mode)
  • PS/2 keyboard (directly connected) — OR —
  • USB keyboard (via native USB port, hub supported)
  • Audio output (choose one):
    • I2S DAC module (e.g., TDA1387 or PCM5102) — recommended for best quality
    • PWM audio — no additional hardware needed, directly to speaker/amplifier

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

Board Configurations

Two GPIO layouts are supported: M1 and M2.

HDMI (via 270Ω resistors)

Signal M1 GPIO M2 GPIO
CLK- 6 12
CLK+ 7 13
D0- 8 14
D0+ 9 15
D1- 10 16
D1+ 11 17
D2- 12 18
D2+ 13 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

I2S Audio

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

VGA (accent resistor DAC)

Signal M1 GPIO M2 GPIO
HSYNC 6 12
VSYNC 7 13
R0 8 14
R1 9 15
G0 10 16
G1 11 17
B0 12 18
B1 13 19

Note: VGA uses the same GPIO pins as HDMI. Choose the appropriate firmware based on your video output hardware.

Firmware Versions

FRANK Apple is available in multiple configurations based on your hardware setup:

Video Output Options

Option Description
HDMI Digital video via PIO-driven HDMI (no encoder chip needed)
VGA Analog video via resistor DAC VGA output

Audio Output Options

Option Description
I2S High-quality audio via external DAC (TDA1387, PCM5102, etc.)
PWM Direct PWM audio output (no additional hardware needed)

Platform Variants

Platform PSRAM Description
RP2350 + PSRAM Yes Full functionality, recommended configuration
RP2350 no-PSRAM No For boards without external PSRAM
RP2040 No Limited support, reduced functionality due to memory constraints

Firmware File Naming

Files are named: frank_apple_<board>_<video>_<audio>_<platform>_<version>.uf2

Examples:

  • frank_apple_m1_hdmi_i2s_rp2350_1_00.uf2 — M1 board, HDMI video, I2S audio, RP2350
  • frank_apple_m2_vga_pwm_rp2350_1_00.uf2 — M2 board, VGA video, PWM audio, RP2350
  • frank_apple_m1_hdmi_i2s_rp2040_1_00.uf2 — M1 board, HDMI video, I2S audio, RP2040

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

pico-extras (required for I2S audio):

The pico-extras library is included as a git submodule and provides the pico_audio_i2s library used for I2S audio output. It is fetched automatically when you clone with --recursive or run git submodule update --init --recursive (see below). No separate installation is needed.

If you are building with PWM audio (-DAUDIO_TYPE=PWM), pico-extras is not required.

Build Steps

# Clone the repository with submodules (includes pico-extras)
git clone --recursive https://github.com/rh1tech/frank-apple.git
cd frank-apple

# Or if already cloned, initialize submodules (includes pico-extras)
git submodule update --init --recursive

# Build for M1 layout with PS/2 input (default)
mkdir build && cd build
cmake -DBOARD_VARIANT=M1 ..
make -j$(nproc)

# Build for M2 layout with PS/2 input
cmake -DBOARD_VARIANT=M2 ..
make -j$(nproc)

# Build with USB keyboard support (instead of PS/2)
cmake -DBOARD_VARIANT=M1 -DPS2_KEYBOARD_ENABLED=OFF ..
make -j$(nproc)

Build Options (CMake)

Option Description
-DPICO_BOARD=pico2 Build for RP2350 (default)
-DPICO_BOARD=pico Build for RP2040 (limited support)
-DBOARD_VARIANT=M1 Use M1 GPIO layout (default)
-DBOARD_VARIANT=M2 Use M2 GPIO layout
-DVIDEO_TYPE=HDMI Video output: HDMI (default) or VGA
-DAUDIO_TYPE=I2S Audio output: I2S (default) or PWM
-DCPU_SPEED=252 CPU clock in MHz (125, 252, 378, 504)
-DPSRAM_SPEED=100 PSRAM clock in MHz (100, 133, 166) - omit for no PSRAM
-DUSB_HID_ENABLED=OFF Enable USB keyboard (disables USB serial)
-DPS2_KEYBOARD_ENABLED=ON Enable PS/2 keyboard input
-DDEBUG_LOGS_ENABLED=ON Enable verbose debug logging

Build Script (build.sh)

The easiest way to build is using the build script:

# Default build: M1, HDMI, I2S, with PSRAM, 252 MHz
./build.sh

# Custom configurations
./build.sh --board M2 --video VGA --audio PWM
./build.sh --nopsram                    # Build without PSRAM
./build.sh --rp2040                     # Build for RP2040
./build.sh --cpu 378                    # Overclock to 378 MHz

build.sh options:

Option Description
-b, --board <M1|M2> Board variant (default: M1)
-v, --video <HDMI|VGA> Video output (default: HDMI)
-a, --audio <I2S|PWM> Audio output (default: I2S)
-p, --psram <MHz> PSRAM speed in MHz (default: 100)
--nopsram Build without PSRAM support
-c, --cpu <MHz> CPU speed: 252, 378, 504 (default: 252)
--rp2040 Build for RP2040 instead of RP2350
-h, --help Show help

Release Builds

To build all 12 firmware variants with version numbering:

./release.sh 1.04

The version can also be entered interactively if omitted. This creates versioned .uf2 files in the release/ directory for each combination of board (M1/M2), video (HDMI/VGA), audio (I2S/PWM), and platform (RP2350/RP2040).

All release builds use 252 MHz CPU clock (no overclocking) for maximum stability.

Flashing

# With device in BOOTSEL mode:
picotool load build/frank_apple.uf2

# Or with device running:
picotool load -f build/frank_apple.uf2

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

SD Card Setup

  1. Format an SD card as FAT32
  2. Copy Apple II disk images to the "apple" directory (.dsk, .nib, or .woz files)
  3. Use the on-screen disk UI to select and load disk images

Supported Disk Formats

  • DSK — Standard 140KB sector-based disk images
  • NIB — Nibble-based disk images (140KB)
  • WOZ — Flux-accurate disk images (WOZ v1 and v2)
  • BDSK — FRANK Apple write-back format (created automatically when saving changes)

Note: When you modify a disk (e.g., save a game), changes are written to a .bdsk file with the same name, preserving the original disk image.

Controls

Keyboard

  • Ctrl+Alt+Delete: Warm reset
  • Open Apple (Left Alt/Left Windows): Left paddle button
  • Closed Apple (Right Alt/Right Windows): Right paddle button
  • F9: show CPU spped (kHz + %%)
  • F11: open Disk UI
  • F12: unlock CPU speed (while pressed, for short fastups)
  • ScrLock: unlock CPU speed toggle

Keyboard to joystick mapping

  • KP 6 → RIGHT
  • KP 4 → LEFT
  • KP 2 & 5 → DOWN
  • KP 8 → UP
  • Any Control → A
  • Any Alt → B
  • Ins → START
  • Del → SELECT

Gamepad (NES/USB)

  • A Button: Left paddle button (Open Apple)
  • B Button: Right paddle button (Closed Apple)
  • Start+A+B: Reset

License

MIT License. See LICENSE for details.

Acknowledgments

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

MII Emulator

  • Project: MII Apple //e Emulator
  • Author: Michel Pollet buserror+git@gmail.com
  • License: MIT License
  • Description: The core Apple IIe emulation engine, including 65C02 CPU, memory banking, video rendering, disk drive emulation (DSK, NIB, WOZ), and slot-based peripheral architecture.

Apple2TS

  • Project: Apple2TS - Apple II Emulator
  • Authors: Chris Torrence and Michael Morrison
  • License: CC BY-SA 4.0 (Creative Commons Attribution-ShareAlike)
  • Description: Reference for Apple II implementation details and emulation techniques.

Pico-Extras

  • Project: pico-extras
  • Author: Raspberry Pi (Trading) Ltd.
  • License: BSD 3-Clause
  • Description: Audio I2S library for sound output.

FatFs

  • Project: FatFs
  • Author: ChaN
  • License: FatFs License (BSD-style)
  • Description: Generic FAT filesystem module for SD card access.

Authors & Contributors

Mikhail Matveev <xtreme@rh1.tech>

DnCraptor (GitHub)

  • RP2040 platform support
  • VGA video output driver
  • No-PSRAM mode for boards without external PSRAM
  • Disk write-back support (.bdsk format)
  • Disk UI enhancements
  • Various bug fixes and improvements

About

Apple //e emulator for RP2350

rh1.tech

Topics

apple apple2 rp2350

Resources

Readme

License

View license
Activity

Stars

3 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 5

Version 1.04 Latest
Mar 26, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages