mini uMac

Turn your ClockworkPi uConsole into a 1984 Macintosh.

mini uMac is a one-command installer that sets up classic Mac emulation on the ClockworkPi uConsole: the Macintosh 128K, 512K and Plus, fullscreen and pixel-perfect on the uConsole's screen, with an optional Mac-styled startup menu so your handheld can boot straight into System 6.

It's built on Mini vMac, the long-running 68K Mac emulator. mini uMac compiles it on your uConsole and handles the uConsole-specific parts: the sideways display, the trackball, the keyboard, and starting it all from the console.

Features

• Three classic Macs out of the box: Macintosh 128K (1984), 512K "Fat Mac" (1984) and Macintosh Plus (1986). Add an SE, Classic or Mac II with one line in config/models.conf.
• Pixel-perfect: the Mac's 512×342 screen is exactly doubled to 1024×684, centered on the 1280×720 panel. No blurry scaling.
• Works with or without a desktop: from the desktop it opens fullscreen like any app (there's an app-menu entry per Mac). From the text console it brings up its own minimal display just for the Mac, rotated correctly, and goes away when you quit.
• Mac-style startup menu (optional): pick a Mac, a shell, your own entries (desktop, dashboard, htop …), restart or shut down. It auto-starts your last choice after 10 s.
• The keyboard feels right: Alt is the Mac's ⌘ Command key, so Alt-Q is ⌘Q.
• Safe to re-run, easy to remove: unchanged Macs aren't rebuilt; ./uninstall.sh undoes everything except your ROMs and disks.

Requirements

• A ClockworkPi uConsole (CM4 or another Raspberry Pi-compatible core) running Raspberry Pi OS (Bookworm, 32- or 64-bit) or another Debian-based OS. Other Pi handhelds should work too.
• About 200 MB of free space and an internet connection for the install.
• A Mac ROM file and a System disk. These aren't included and can't be: Apple's ROMs are copyrighted. See docs/ROMS_AND_DISKS.md.

Install

On the uConsole, as your normal user (not with sudo):

git clone https://github.com/USERNAME/mini-uMac.git ~/mini-uMac
cd ~/mini-uMac
./install.sh --boot-menu

It installs the packages it needs (it asks for your sudo password once), builds the Macs (a few minutes the first time), and finishes by telling you exactly which ROMs and disks it's still missing.

Then add your files:

~/mac/roms/Mac128K.ROM         ← for the 128K and 512K
~/mac/roms/vMac.ROM            ← for the Plus
~/mac/macplus/01-System.dsk    ← a bootable System disk, one folder per Mac

and reboot once (the installer adds you to the groups that allow screen, input and sound access).

Install options

Option	What it does
(none)	Builds the Macs, installs the umac command and app-menu launchers. Your boot is unchanged.
--boot-menu	Also opens the startup menu when you log in on the console (tty1). Never over SSH, never inside a desktop.
--console-autologin	Also makes the uConsole boot to that menu instead of the desktop (console autologin; reversible). Implies --boot-menu.
--stock-keys	Keep Mini vMac's own key map (Alt = Option) instead of Alt = ⌘.
--no-deps	Don't install packages (you've already got them).

Using it

umac                # list your Macs
umac macplus        # start one
umac --check macplus  # check the ROM/disks are in place, without starting it
umac-menu           # open the startup menu

Keys
Control-Q, then Y	Quit the Mac
Alt	⌘ Command (Alt-Q = ⌘Q, Alt-O = ⌘O …)
Super	Option
Control-S	Speed: 1× (authentic) up to "all out"
Control-F	Toggle fullscreen
Control-M	Toggle pixel doubling
Control-H	Mini vMac help (hold Control for its control mode)
Trackball	The mouse

Everything you do inside the Mac is saved straight into its disk image, just like a real floppy or hard disk. To keep more than a floppy's worth, give your Plus a hard disk (see docs/ROMS_AND_DISKS.md).

The startup menu

With --boot-menu, logging in on the console shows the menu in the screenshot above. The selected entry is drawn inverted, like the Finder's menus in 1984.

• On boot it auto-starts your last choice after 10 seconds; any key stops the countdown.
• Quitting a Mac returns to the menu (with no countdown, so it never relaunches by itself).
• Shell (or Esc) drops you to the normal prompt; umac-menu brings it back.

Add your own entries by putting small files in ~/.config/mini-umac/menu.d/:

# ~/.config/mini-umac/menu.d/10-desktop.entry
LABEL="Desktop"
COMMAND="startx"

There are ready-made examples (Desktop, htop, "Update mini uMac") in examples/menu.d/.

Configuration

~/.config/mini-umac/config (created on first install):

Setting	Default
MAC_HOME	~/mac	Where roms/ and each Mac's disk folder live
ROTATE	auto	Console mode: rotate the panel to landscape (auto / normal / left / right / inverted)
MENU_TIMEOUT	10	Seconds before the menu auto-starts (0 = always wait)
MENU_DEFAULT	last	What auto-starts: last, shell, a Mac id, or a menu entry name

Which Macs to build: copy config/models.conf to ~/.config/mini-umac/models.conf, edit it, and re-run ./install.sh. Each line is one Mac:

macse | Macintosh SE (1987) | SE | 4M | MacSE.ROM | z

Uninstall

cd ~/mini-uMac
./uninstall.sh            # add --purge to also remove ~/.config/mini-umac

This removes everything the installer added (the commands, built emulators, launchers, the login hook, and console autologin if mini uMac set it up). It never deletes ~/mac, where your ROMs and everything you've saved inside your Macs live.

Troubleshooting

See docs/TROUBLESHOOTING.md. The usual suspects: a ROM with the wrong name, a sideways picture (set ROTATE=left), or a flashing "?" disk (the first disk isn't bootable). The emulator's output from the last run is in ~/.local/share/mini-umac/last-run.log.

Curious how it works under the hood? See docs/HOW_IT_WORKS.md.

Status

mini uMac is new. The installer, launcher, menu and builds are tested automatically on x86-64 and 64-bit ARM Linux (see CI). Reports from real uConsoles, both working and broken, are very welcome: please open an issue with your OS version and last-run.log.

Credits & license

• Mini vMac by Paul C. Pratt and contributors, GPL-2.0. mini uMac downloads and builds it on your device (pinned to a tested commit); it isn't redistributed here.
• mini uMac's own scripts are released under the MIT License.
• Not affiliated with Apple or ClockworkPi. Macintosh is a trademark of Apple Inc. No Apple ROMs or software are included in this repository.