152 lines
8.1 KiB
Markdown
152 lines
8.1 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
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.
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```text
|
|
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.
|