A complete desktop operating system for the RP2350 microcontroller. FRANK OS turns a $4 chip into a usable computer with a mouse-driven windowed GUI, a terminal, a file manager, and a library of applications — all running on 520 KB of SRAM.
Built on FreeRTOS with DVI video output, PS/2 keyboard and mouse input, SD card storage, and optional PSRAM for application memory. Compatible with Murmulator OS 2 applications.
- A full Windows 95-style desktop running on a microcontroller — not a framebuffer demo, but a working OS with window management, menus, dialogs, and multitasking
- Loads and runs standalone ELF applications from SD card with a stable syscall API, so apps are binary-compatible across firmware updates
- Ships with 8 graphical applications including a text editor, card games, an MP3 player, a ZX Spectrum emulator, and a BASIC interpreter
- Dual-core architecture: Core 0 runs FreeRTOS (UI, input, apps), Core 1 is dedicated to real-time DVI scanline rendering
- Hard fault recovery with crash dumps that survive warm resets
FRANK OS provides a complete Windows 95-style desktop with overlapping windows, a taskbar, and a Start menu.
- Overlapping windows with title bars, borders, and minimize/maximize/close buttons
- Drag-to-move from title bar, resize from edges and corners
- Window states: normal, minimized, maximized, and fullscreen
- Z-order stacking with up to 16 simultaneous windows
- XOR-outline visual feedback during drag and resize
- System menu (Alt+Space) with Restore, Move, Size, Minimize, Maximize, Close
- 28px taskbar at the bottom of the screen
- Start button for launching applications
- Task buttons for each open window
- System tray with clock display and volume slider popup
- Scans
/fos/on the SD card at boot and lists all discovered applications - Displays 32x32 app icons with names
- Keyboard navigation with arrow keys
- Configurable background color (16-color palette)
- Desktop shortcuts (up to 24) with right-click context menu
- Shortcuts persist across reboots via
/fos/desktop.dat
- Windows 95-style centered overlay showing 32x32 icons and window titles
- Cycles through all open windows sorted by z-order
- Includes minimized and suspended windows
- Menu bars with up to 5 dropdown menus per window, 8 items each
- Alt+letter accelerators (Alt+F opens File menu, etc.)
- Right-click context menus
- Modal dialogs: message boxes (OK/Cancel/Yes/No), input dialogs
- File Open and Save dialogs with directory browsing and extension filters
- Find and Replace dialogs (modeless, Notepad-style)
- Run dialog (Win+R) with command history dropdown
- Push buttons with Win95 raised/sunken bevel style
- Scrollbars (vertical and horizontal, 16px)
- Multi-line text areas with selection, undo, and up to 32 KB of text
- Sliders for numerical input
- Text fields with cursor and keyboard editing
- Arrow (default), resize N-S, resize E-W, resize NW-SE, resize NE-SW, hourglass (wait)
- Cursor bitmaps extracted from Windows 95
.curfiles - Save-under overlay technique for flicker-free cursor movement
Four settings applets accessible from the Start menu:
| Applet | Settings |
|---|---|
| Desktop | Background color (16-color palette picker) |
| System | CPU frequency, PSRAM size, uptime, kernel info (read-only) |
| Mouse | Double-click speed (200-800ms slider with test area) |
| Frequencies | CPU clock (252/378/504 MHz), PSRAM clock (default/133/166 MHz) |
All settings persist to /fos/settings.dat on the SD card.
The Terminal runs PShell, an interactive command interpreter. It can also launch MOS2-compatible console applications directly from the SD card.
| Command | Description |
|---|---|
ls |
List directory (-a for hidden files) |
cd |
Change directory |
cat |
Display file contents (-p to paginate) |
cp |
Copy a file |
mv |
Rename a file or directory |
rm |
Remove file or directory (-r for recursive) |
mkdir |
Create a directory |
hex |
Hexdump (-p to paginate) |
cc |
Compile and run a C source file |
vi |
Edit files with vi |
tar |
Manage tar archives |
clear |
Clear the screen |
version |
Display shell version |
news |
What's new in this release |
FRANK OS ships with 9 standalone applications:
VT100 terminal emulator with multiple concurrent instances, each running its own shell session. Supports 16-color text, cursor movement, SGR escape sequences, and a 70x20 character grid (80x30 in fullscreen with Alt+Enter). Runs built-in shell commands and launches MOS2-compatible console applications from the SD card. The sdcard/mos2/ directory includes 50+ command-line utilities (hex editor, file tools, benchmarks, and more).
Full-featured text editor with menu bar, clipboard, find/replace, and syntax highlighting. Supports C, C++, and INI highlighting modes. Includes a Dev menu for compiling and running C source files directly.
Classic Klondike card game with Draw One and Draw Three modes. 45x60 pixel cards with suit symbols rendered as bitmap art. Proper cascading tableau, stock/waste pile, and four foundation piles.
Grid-based mine sweeper with three difficulty levels: Beginner (9x9, 10 mines), Intermediate (16x16, 40 mines), and Expert (30x16, 99 mines). Features a 7-segment timer, mine counter, and the classic smiley reset button.
Port of the 1983 Windmill Software arcade game. Dig through levels collecting gold while avoiding monsters. Sprite-based rendering with level progression and score tracking.
Full Zilog Z80 emulation with an ARM Thumb-2 assembly dispatcher for real-time performance on RP2350. Loads TAP tape files from SD card. Emulates the Spectrum keyboard matrix, 48 KB RAM across 3 banks, and the original ROM.
WinAmp 2.x-style MP3 player. Playlist of up to 64 tracks with shuffle and repeat modes. Transport controls (play/pause/stop/next/previous), seek bar, volume slider, and 7-segment time display. Decodes MP3 via the Helix fixed-point decoder.
PicoMite BASIC interpreter running as a windowed GUI application. Supports traditional BASIC syntax with file I/O, graphics commands, and sound.
The interactive shell that runs inside the terminal. Built-in commands for file operations, a vi text editor, a C compiler (cc), and tar archive management.
- Three view modes: large icons, small icons, and list view
- Toolbar with back, up, cut, copy, paste, and delete buttons
- Path history with 8 levels of back/forward navigation
- File operations: copy, cut, paste, delete, rename
- Scrollbar for large directories (up to 128 entries)
- Status bar showing file size and modification date
- File type associations — double-click opens files in the registered app
Applications register the file extensions they handle via .inf metadata files. When a user opens a file (from the file manager or shell), FRANK OS finds the matching app and launches it with the file path. Up to 16 apps can register, each handling up to 8 extensions.
- I2S stereo output via PIO with DMA ping-pong buffering
- 4 concurrent sound channels
- Volume control (5 levels, persisted in settings)
- Startup sound (Windows 95 WAV)
- MP3 playback (Helix fixed-point decoder)
- MOD tracker playback (HxCMod)
- MIDI/OPL FM synthesis
| Shortcut | Action |
|---|---|
| Win (alone) | Toggle Start menu |
| Win+T | Open new terminal |
| Win+E | Open file manager |
| Win+R | Open Run dialog |
| Alt+Tab | Cycle between windows |
| Alt+Space | System menu (Restore, Move, Size, Minimize, Maximize, Close) |
| Alt+F4 | Close focused window |
| Alt+Enter | Toggle fullscreen (terminal) |
| Alt+Letter | Open menu (e.g. Alt+F for File) |
- Resolution: 640x480 at 60 Hz
- Color depth: 4-bit paletted (16-color CGA/EGA palette)
- Output: DVI via RP2350 HSTX peripheral
- Rendering: Core 1 dedicated to real-time DVI scanline output via DispHSTX
FRANK OS targets the FRANK M2 board — an RP2350B-based development board with DVI output, PS/2 ports, SD card slot, and PSRAM.
- MCU: RP2350B (QFN-80, 48 GPIO)
- Flash: 4 MB
- PSRAM: QSPI (optional, auto-detected)
- Video: DVI via HSTX peripheral
- Input: PS/2 keyboard + PS/2 mouse
- Storage: SD card (SPI mode)
- Audio: I2S stereo + PWM beeper
Note: The M1 board layout is no longer supported. FRANK OS builds exclusively for the M2 GPIO layout.
| Signal | GPIO |
|---|---|
| CLK- | 12 |
| CLK+ | 13 |
| D0- | 14 |
| D0+ | 15 |
| D1- | 16 |
| D1+ | 17 |
| D2- | 18 |
| D2+ | 19 |
| Signal | GPIO |
|---|---|
| CLK | 2 |
| DATA | 3 |
| Signal | GPIO |
|---|---|
| CLK | 0 |
| DATA | 1 |
| Signal | GPIO |
|---|---|
| CLK | 6 |
| CMD/MOSI | 7 |
| DAT0/MISO | 4 |
| DAT3/CS | 5 |
| Package | GPIO |
|---|---|
| RP2350A (QFN-60) | 8 |
| RP2350B (QFN-80) | 47 |
Pin is auto-detected at runtime based on the RP2350 package variant.
| Signal | GPIO |
|---|---|
| I2S DATA | 20 |
| I2S CLK | 21 |
| Beeper | 22 |
FRANK OS is structured around FreeRTOS tasks running on Core 0 of the RP2350:
| Task | Priority | Description |
|---|---|---|
| USB | Highest | TinyUSB CDC serial console |
| Input | 3 | PS/2 keyboard/mouse polling and event routing |
| Compositor | 2 | Window manager event dispatch and screen compositing |
| Heartbeat | 1 | LED blink (system alive indicator) |
| Shell (per terminal) | -- | Command-line interpreter |
| App (per ELF) | -- | Standalone application task |
Core 1 is dedicated to the DispHSTX DVI scanline renderer.
- 520 KB SRAM — FreeRTOS heap, framebuffer (150 KB), task stacks, window state, terminal buffers
- 4 MB flash — firmware code and read-only data, sys_table at 0x10FFF000
- PSRAM (optional) — used for ELF application memory, auto-detected at boot
Apps are standalone ARM ELF binaries compiled against apps/api/frankos-app.h. They call OS services through a sys_table — a fixed-address array of 500+ function pointers. This means apps are binary-compatible across firmware versions without recompilation.
Crash dumps are saved to uninitialized SRAM and survive warm resets, allowing post-mortem debugging of hard faults.
- Raspberry Pi Pico SDK (version 2.0+)
- ARM GCC toolchain (
arm-none-eabi-gcc) - CMake 3.13+
- Python 3 (for icon tools)
picotool(for flashing)
git clone --recursive https://github.com/rh1tech/frankos.git
cd frankos
# Or if already cloned:
git submodule update --init --recursive
./build.sh./flash.sh # flash most recent build
./flash.sh path/to/firmware.elf # flash specific filecd apps
./build_apps.shCompiled apps (binaries, .inf metadata, .ico icons) are placed directly in sdcard/fos/.
- Format an SD card as FAT32
- Copy the contents of
sdcard/to the root of the card - Insert the card — it is auto-mounted at boot
- FRANK M2 board (or any RP2350B board with matching pinout)
- PS/2 keyboard and mouse
- DVI monitor
- FAT32-formatted SD card
Detailed documentation is available in the docs/ directory:
- Architecture — system design, memory map, display pipeline, task model
- Building — prerequisites, build steps, flashing, SD card setup
- App Development — how to create apps, minimal example, drawing, events, menus, dialogs
- API Reference — complete sys_table index, data types, constants, all function signatures
FRANK OS is licensed under the GNU General Public License v3.0 or later.
Portions derived from Murmulator OS 2 by DnCraptor are used under the same license.
Third-party components retain their original licenses (MIT, BSD-3-Clause, ISC, Apache-2.0) as noted in their respective source files.
Mikhail Matveev <xtreme@rh1.tech>, https://rh1.tech
- Murmulator OS 2 by DnCraptor (GPL-3.0) — application loading, system table, shell, and POSIX compatibility layer
- FreeRTOS by Amazon Web Services (MIT) — real-time kernel for task scheduling
- DispHSTX by Miroslav Nemecek (BSD-3-Clause) — DVI display driver for RP2350 HSTX
- FatFs by ChaN (BSD-style) — FAT filesystem for SD card access
- Pico SDK by Raspberry Pi Ltd. (BSD-3-Clause) — hardware abstraction for RP2350
- Helix MP3 Decoder (RealNetworks) — fixed-point MP3 decoding
- Digger Remastered by Andrew Jenner — port of the 1983 Windmill Software arcade game
- fMSX/Z80 by Marat Fayzullin — Z80 CPU emulation core