Files

8.1 KiB

Install and operate Coco 3 Plus

Existing MiSTer, passwordless SSH

Have a working MiSTer installation and key-based SSH login before running the installer. On Windows OpenSSH is available as an optional Windows feature. Test:

ssh root@YOUR-MISTER

Establish the correct host fingerprint and public-key login through your normal SSH setup. The installer uses BatchMode=yes and StrictHostKeyChecking=yes: it does not request/store passwords or accept unknown host keys silently. The default Unix user is root, as on standard MiSTer. Another account must already have permission to write the FAT volume and issue MiSTer commands.

Build ROMs/FPGA per BUILD_WINDOWS.md. Put the two separately obtained chip ROMs in roms/ssc; packaging checks their exact size and SHA-256 before remote writes. They remain ignored by Git. Then save guest work, close files and stop disk activity. Installation returns to MENU, so the current guest session is ended.

.\windows\Install-MiSTer.ps1 -Load
# Or specify the address:
.\windows\Install-MiSTer.ps1 -HostName YOUR-MISTER -Load

If no address is given, the script prompts for one. It first validates every local input and writes a local per-attempt receipt naming the planned stage, backup, destinations and temporary files. It then checks remote access, stages and verifies every payload, and returns to MENU. All supporting assets are installed and checked before activation: the uniquely addressed RBF, ROMs, configuration/path files and notices. Existing saved configuration is preserved. The volume is synced before the launcher is changed.

The launcher is the last asset installed. Its staged bytes are copied to a temporary sibling beside the destination, SHA-256 checked, and atomically renamed to _Computer/Coco 3 Plus.mgl. The installer checks the final bytes, syncs again and optionally loads the launcher. This avoids exposing a new menu entry before its supporting files are installed. Filesystem rename is not a claim of power-loss certification or a transaction covering the entire SD card.

Receipts are retained in ignored release storage as install-receipt-<attempt>.json; install-receipt.json holds the latest attempt's complete JSON record. An existing latest receipt is also preserved before a new attempt. Each phase and completed file is recorded. On failure or keyboard interruption, the receipt retains the active phase/file, error and planned recovery paths. Stage and backup files are not automatically deleted; an already-existing remote attempt directory is rejected rather than merged.

The installer does not change accounts, networking, Samba, the Linux installation or nonvolatile FPGA storage.

Only the Plus launcher, its uniquely addressed RBF, two boot ROMs and optional SSC ROM/path records are installed. The stock core and other guest media remain. Existing coco3plus_v51.CFG is kept. First installs get Audio expansions / SDC / ROM / Floppy, startup Slot4, 512K, and Sound & Speech enabled when ROMs are supplied. Existing users retain their own layout and expansion selection.

-WithoutSSC creates a base-only package without chip ROMs/path records. It does not delete SSC files already installed on a device. Its fresh configuration selects Extended palette. SSC remains unavailable until valid ROMs are supplied and its cartridge/mode is selected.

Files and copying instead of SSH

Package-Release.ps1 writes dist/coco3plus/fat and the matching dist/coco3plus.zip archive. The release also includes a corresponding-source ZIP, file checksums, notices and manifest. The FAT overlay contains:

fat/
  _Computer/Coco 3 Plus.mgl
  _Computer/.coco3plus/<RBF-hash-prefix>/coco3plus.rbf
  games/coco3plus/boot0.rom
  games/coco3plus/boot1.rom
  games/coco3plus/pic-7040-510.bin       (separate supplied input)
  games/coco3plus/sp0256-al2.bin         (separate supplied input)
  config/coco3plus.f4, coco3plus.f5     (when SSC included)
  config/coco3plus_v51.CFG             (new installs only)

Power off MiSTer before removing its card. Copy the contents of fat/ to its data-volume root, including _Computer's hidden .coco3plus child. Back up collisions and skip the supplied CFG when one already exists. Preserve the manifest next to your release archive. Copying this folder onto an unprepared card does not install Linux or make it bootable.

Guest .DSK, .VHD, .CCC, .ROM, .BIN and .CAS files belong in games/coco3plus or subfolders. A software library is optional and is not silently downloaded or redistributed by setup. Keep a pristine diagnostic disk and use writable copies for saved results.

Public source/core packages

Local complete packages can contain your own ROM inputs and must not be published as though ignored files were automatically excluded from ZIPs. Use Package-Release.ps1 -PublicPackage -Output dist/coco3plus-public for a source/core artifact that omits all boot and SSC ROMs. Supply the required ROMs before manual copy/launch. The SSH installer rejects this incomplete-ROM package and directs you to make a complete local package from your own verified inputs.

The included corresponding-source.zip is a source-review payload, not a Git checkout. It excludes historical RBFs, PDFs and Office files retained in the full repository. Build scripts need Git metadata and the full project inventory. Follow SOURCE-CHECKOUT.txt beside the archive to clone the repository and check out the exact release revision before following docs/BUILD_WINDOWS.md.

Before any SSH or target access, the installer validates format and local-ROM state, SHA-256 syntax, the canonical digest-addressed RBF, the launcher's RBF reference and coco3plus namespace, exact boot-ROM identities and default CFG. An SSC-enabled local package also needs both exact chip ROM identities and the matching 1024-byte f4/f5 path records. Incomplete or contradictory packages are rejected locally; --without-ssc remains supported with its matching CFG.

First launch and recovery

Choose Computer → Coco 3 Plus. It should reach Disk Extended Color BASIC. PRINT 1+1 should print 2. F12 → Sound & Expansion reports Sound & Speech ready after its original ROMs load automatically. F12 → Cartridges & Multi-Pak controls the four sockets and startup slot. F12 → Floppy Disks mounts images without changing the layout. Changing socket devices restarts the guest.

The MGL uses native setname=coco3plus, so settings and remembered files use the same canonical namespace. The RBF also identifies itself as Coco 3 Plus, so welcome/help strings no longer expose the retired development name. The native profile override remains coco3plus; changing the display identity does not require abandoning the existing saved settings or media.

For rollback, return to MENU and use the receipt's stage/backup paths. If failure happened before activation_attempted, the old launcher is unchanged, but some supporting files may already have been replaced: restore their backed-up versions if needed before loading the previous core. If activation was attempted, launcher_activated: null means a transport failure left its outcome uncertain; inspect the installed launcher rather than assuming it was rolled back. A null load_command_sent value means the command write was attempted but not confirmed. A true value confirms only that the MiSTer command write succeeded; it does not confirm guest startup. startup_observed remains false until separate hardware observation, which this installer does not perform.

When the old launcher needs restoration, restore _Computer/Coco 3 Plus.mgl from the remote backup directory. Its previously addressed RBF remains in place. Restore backed-up boot/SSC/path files when those inputs also need rollback. Existing saved CFG was not overwritten. On a first installation, select the preserved stock CoCo3 entry to use the original environment. Keep backup/staging folders until physical cold-start and audio checks pass.

Run python tests/test_install_mister.py to exercise launcher-last activation and deliberate pre-activation interruption on a disposable local mock target. These tests do not access a MiSTer or establish physical power-loss behavior.