BMCoCo-Pi 0.1.0rc3 · Windows setup, Linux console and model downloads.
Using BMCoCo-Pi
This guide covers the runtime shipped with release candidate 0.1.0rc3. Windows setup and the Linux console are available. Hardware development has occurred on Pi400/Pi500; fresh Linux/Windows installations and Pi500 boot passed. Full feature-by-feature and other-model acceptance remain open.
The guest and the OSD are different
An optional external AI agent can also help operate/observe the guest through compatible host-side tools. It does not run on the Pi, and desktop XRoar-AI debugger features must not be assumed available here. See AI-agent control and the XRoar-AI connection.
The guest is the emulated CoCo or MC-10 running BASIC or software. Its RAM and unsaved program are lost on guest reset, profile Apply or power loss. The OSD is BMCoCo-Pi's local host menu, opened with F12. Opening it pauses the guest. Arrow keys navigate; Enter selects; Escape/Backspace returns. F12 resumes/closes as appropriate. Apply is separate from editing and Cancel. Do not assume a menu change is active until its Review/Apply succeeds.
F12 is a host key, not a CoCo function key. Home maps to Clear and Escape to Break in the guest. Physical keyboard mode follows the CoCo layout, not all PC printed symbols; translated mode follows supported BASIC typing conventions. MC-10 and CoCo3 have their own mappings. Text fields need a keyboard even when a gamepad can navigate menus. Bluetooth keyboards/controllers are not supported.
If guest and browser stop accepting changes, check for a local OSD, another remote owner or an unfinished file/kernel transaction before repeatedly clicking Apply. Local input can take control away from a remote operation.
The eight Web pages
Open the Pi's own address following first boot.
| Page | What to do there |
|---|---|
| Guest & machine | Pause/resume/reset; select machine, RAM, CPU and video/keyboard options |
| Media | Attach/eject disks, tapes and cartridges; configure MPI/MOOH |
| Profiles & startup | Save/load named profiles and separately choose the next startup profile |
| Controllers | Inspect/configure wired USB controller assignments, axes and buttons |
| Remote storage | Configure supported external storage backends and endpoints |
| SD files | Browse approved folders and upload/download/manage owner media |
| Screenshots | Capture/download the guest image or reopen a local saved PNG |
| System | Running build, saved idle blanking, verified kernel updates and confirmed reboot |
Only one task page is shown at a time. SD files folder shortcuts are file locations, not shortcuts to machine configuration. Switching task pages preserves form drafts without applying anything; reloading the browser drops unapplied drafts and rereads server state. Changing a field is not Apply. The controls below describe the shipped interface; some advanced features still have limited hardware coverage.
Apply, save and startup are separate
- Apply changes the live guest. Machine/media/profile Apply can reset the guest and reload media, discarding unsaved program/RAM-disk changes. Read the confirmation. Controller-only Web Apply is live without reconstruction.
- Save live profile stores committed configuration and media paths, not unsaved form drafts, running guest RAM or copies of ROM/media files.
- Load and Apply selected replaces the guest configuration and resets it.
- Use selected at next startup chooses a saved profile for a future boot; saving alone does not choose it or reboot now.
- Use CoCo2 baseline at startup restores the baseline choice. A missing or invalid startup profile/media should fall back to the CoCo2 baseline, whose ROMs are still required; this is not ROM-less recovery.
Keep referenced files in place. Ordinary file operations must not orphan a selected startup profile or overwrite an active MOOH image. A profile file is not a standalone backup of its referenced media. More about profiles.
Display and optional idle blanking
CoCo1/2 games relying on NTSC artifact colors need NTSC composite video and artifact rendering; the candidate profiles use the5-bit LUT. RGB produces black-and-white patterns in those titles. CoCo3 RGB remains a separate choice. Attract uses the active machine/video settings. Attract and returning to BASIC.
System → Display / screen blanking offers Off, 1, 5, 10, 15 and 30 minutes. It defaults Off. Choose Apply and save timeout to remember the choice on the SD card. In the OSD choose Display / screen blanking, cycle the timeout and explicitly choose Save display setting for next boots.
Blanking sends a black HDMI picture; it does not turn the TV off or stop the guest/audio/network. The first keyboard chord only wakes the display: release all keys before typing normally. Web Wake Pi display is also available. Guest screenshots still show the guest, not the black HDMI screen. Pi400 TV blank/keyboard wake is user-confirmed; physical controller/chord and settings surviving a future hardware reboot remain distinct validation items.
Controllers
Use a supported wired USB gamepad. Current bindings support two CoCo guest joystick ports plus OSD navigation, with up to four discovered controller devices. Device numbers may change after reconnection. Configure dead zone, axes, inversion and fire/menu buttons; release controls after reconnect/Apply so that the neutral-state safety gate can rearm. Save a profile separately to persist mappings. MC-10 currently supports controller OSD navigation only, not a guest joystick. Bluetooth, rumble and universal pad compatibility are not implemented/claimed. Physical pad/model/hotplug acceptance remains open.
Remote storage
Local SD is the simplest baseline. Supported configuration options include pyDriveWire HTTP+Becker, Becker/HDB-DOS and FujiNet. These need a separately running compatible service on another machine and the appropriate ROMs. Selecting a backend does not start a server or prove that it has mounted media. Use the actual service's numeric IPv4 address and ports, not a maintainer's example IP. Current bare-metal transport does not resolve arbitrary hostnames. MC-10 remote transport is not implemented; use local supported media.
MOOH requires Local SD; standalone carts and MPI are mutually exclusive, and conflicting local floppy/remote-backend choices reject rather than silently reconfigure. Keep a working Local SD profile before experimenting. No embedded FujiNet/DriveWire server or always-online requirement is implied.
Guide edition: November 2, 2026.