Using CP/M: colors, the HI example, and new software

For the published CP/M 2.2 release, start with the quickstart. The current software-install guide explains how to obtain the optional inputs and create a new disk; older examples below assume an existing locally built Infocom template disk.

These CP/M commands are the same in TSPico RAMDisk, TSPico v2.x SD mode, Fuse/Oliger and the TSRun launcher. First reach the A> prompt using the startup guide. For hardware, check the TSPico firmware/feature table before choosing a mode.

Included utilities reference

Type commands without .COM. This lists the full TSPico development/game disk; smaller images may contain a subset. Use DIR to check your disk.

Utility Purpose / example
STAT Disk free space, file sizes, device assignments. STAT or STAT *.*.
PIP File/device copying. PIP COPY.TXT=README.TXT copies a file. The current TSPico BIOS exposes A only.
ED Command-driven text editor. ED NOTES.TXT; this is not a full-screen editor.
ASM Intel 8080-syntax assembler. ASM HI produces HI.HEX and HI.PRN from HI.ASM; full Z80 syntax is not supported.
LOAD Converts Intel HEX to COM. LOAD HI creates HI.COM.
SUBMIT Runs a SUB batch file. SUBMIT DEMO builds and runs HI.
XSUB Lets SUBMIT scripts supply buffered console input to programs as well as commands to CP/M. DEMO.SUB does not need it.
DDT Dynamic Debugging Tool: inspect/change memory, disassemble, step programs, set breakpoints. DDT HI.COM loads HI; G0 returns to CP/M. Uses 8080 mnemonics.
DUMP Displays file bytes in hexadecimal. DUMP HI.COM.
COLOR Lists/selects text/background schemes and optional border color. COLOR 7 2 selects white on black with a red border.
COLUMNS Reports/selects 64 or 80 columns. COLUMNS 80 requires the supported PicoVideo 4.2 renderer.
VIDEO Read-only PicoVideo register/capability report for diagnosing display modes and firmware.
MEMTEST Small smoke test of CP/M RAM at CPU addresses 4000/6000 plus sample character output. Not a full memory/RAMDisk test. Older PicoVideo can visibly capture these banked writes.
FORMAT Initializes the current filesystem using its existing geometry. FORMAT A: erases files after confirmation; it does not change disk capacity. RAMDisk retains TPSAVE.COM.
TPSAVE Exports the live TSPico RAMDisk to SD. Run before power-off to preserve changes. RAMDisk profiles only.
TPLOAD Imports a prepared single-file CODE TAP into CP/M. TPLOAD VIDEOCOM.TAP VIDEO.COM; refuses an existing destination. Does not mount disk images.
CPMDISK TSPico v2.x SD-service profiles: select native FILES/image sources and save snapshots. Does not manage a second drive; refuses SD switching in RAMDisk mode.
TPIMPORT Alternate TSPico v2.x raw-file importer in the experimental combined profile; normal TSPico packages use TPLOAD.
HELLO Tiny startup/smoke-test program. Factory-style startup invokes it.
HI.ASM / DEMO.SUB Example source and build/run script. HI.COM is generated by ASM/LOAD; some game disks include it prebuilt.
PLANET / ZORK1 Games. Each needs its matching COM interpreter and DAT story file.
README.TXT Short disk instructions: TYPE README.TXT.

DIR, TYPE, REN, ERA, USER and SAVE are command-processor built-ins, not separate utility files. CP/M SAVE saves memory to a file; it does not persist the RAMDisk. Use TPSAVE for that. See Digital Research's CP/M 2.2 manual for the standard utilities.

Keeping diagnostics versus trimming a personal disk

Keep boot failure diagnostics, detected-protocol information, block progress and the RAMDisk save reminder. These live in the cartridge/BIOS and remain available even if disk utility files are removed.

Keep VIDEO on the normal disk: the current binary is 385 bytes, occupying one 2KiB allocation block. DDT, DUMP and MEMTEST are optional for playing games; together they occupy 10KiB on the current 320KB disk. XSUB adds another 2KiB and is optional unless a script uses it. Retain copies in the package's FILES directory before trimming a personal disk. Keeping these files does not consume TPA program memory or slow the fixed-size RAMDisk preload. The default development package retains them all.

COLOR: change the high-resolution colors

At CP/M's A> prompt:

COLOR
COLOR 6
COLOR 7

COLOR alone prints the choices. COLOR 6 selects yellow text on blue; COLOR 7 restores the default white on black.

Number Text Background
0 Black White
1 Blue Yellow
2 Red Cyan
3 Magenta Green
4 Green Magenta
5 Cyan Red
6 Yellow Blue
7 White Black

The change affects the whole console, including text already displayed and an Infocom status line. It does not change the disk files or permanently configure the machine. On detected PicoVideo 80-column mode, the utility updates the text palette as well. The normal console is 64 columns; a TSPico upgrade alone does not make it 80 columns. Keep COLOR.COM on a new disk if you want this command.

Run or rebuild HI

The game disk includes a preassembled HI.COM. At A>:

HI

It prints Assembled on the TS2068!. Other profiles may include only the source and build tools; build it once if HI is not found. Required files are HI.ASM, ASM.COM and LOAD.COM. SUBMIT.COM and DEMO.SUB provide the shortcut:

TYPE HI.ASM
SUBMIT DEMO

DEMO.SUB runs these same three commands, which can also be entered manually:

ASM HI
LOAD HI
HI

ASM creates HI.HEX and HI.PRN; LOAD converts HI.HEX into HI.COM; HI executes it. The assembler's normal 000H USE FACTOR/END OF ASSEMBLY output is not an error. This is assembling on the emulated/physical Z80, not on the PC. Preserve the resulting disk with TPSAVE, Fuse Save/Save As, or TSRun download as appropriate.

The common software-installation procedure

  1. Obtain the CP/M-80 / 8080 / Z80 version and extract it on the PC. A DOS or CP/M-86 COM file does not run on this Z80 just because it has a COM extension.
  2. Collect its COM program and all required companion files. Programs may need overlays, help files, libraries or data. Give them CP/M 8.3 filenames.
  3. Create a new 320KB work disk, or use an unmounted copy of an existing disk. A fresh disk avoids filling the existing two-game collection.
  4. Use python tools/cpm_disk.py put DISK FILE... to copy the files into DSK, TAP or raw images. The command is the same for every application. It refuses duplicate names unless --replace is supplied, and checks disk capacity.
  5. Mount/open that disk, then type the program's basename at A> (omit .COM).
  6. Save the disk through the platform's normal persistence path.

Run Python/PowerShell commands below on the PC from this project's directory. Run commands labelled A> inside CP/M. Do not type Python commands at A>. Do not edit the same disk file from Python while an emulator has it mounted.

Worked example: add Zork II

1. Obtain a version-3 story

Use the Infocom catalog's Zork II section. Choose the compiled game file, not the ZIL source ZIP: zork2-r48-s840904.z3 (version-3 story, release 48 / serial 840904). Save it as build/software-example/zork2-r48-s840904.z3, creating that PC folder if needed. This exact file is the tested example (89,912 bytes; SHA256 39e3a8bda879e9296ac05c8bdcdae12a1a6fb447a1ef531838e82cfa2db210ac).

A .z3 story is data, not a CP/M executable. It needs an interpreter. This project already supplies configured PLANET.COM/ZORK1.COM interpreters, derived from the catalog's CP/M interpreter source. Simply renaming PLANET.COM to ZORK2.COM would leave its internal data filename pointing at PLANET.DAT. The preparation tool below changes that field in the fingerprinted project interpreter and produces a correctly matched pair.

2. Prepare the COM/DAT pair

On the PC:

python tools/prepare_infocom.py --story build/software-example/zork2-r48-s840904.z3 --name ZORK2 --template build/infocom-cpm.dsk --output build/newsoftware

The template is the supplied two-game disk, not a second downloaded game. Prerequisite: have the project's game build, or extract the Infocom/TSRun package containing build/infocom-cpm.dsk. A utilities-only disk does not contain an Infocom interpreter. The tool extracts its configured interpreter and creates ZORK2.COM plus ZORK2.DAT. It needs no assembler or new interpreter download. An individual project PLANET.COM/ZORK1.COM or a project TAP disk can also be the template. In an extracted TSPico package, for example, the equivalent template path is TAP/CPM/COMPAT.TAP. Use a new output folder if the pair already exists.

This helper supports version 3 only, up to 128KB, and the exact configured project interpreter. It rejects unrelated COM files and later Z-machine formats such as .z5/.z8. Changing a later story's extension will not convert it.

3. Create and populate a disk

On the PC, create a fresh disk and add the program/data pair:

python tools/cpm_disk.py create build/zork2.dsk --size 320
python tools/cpm_disk.py put build/zork2.dsk build/newsoftware/ZORK2.COM build/newsoftware/ZORK2.DAT
python tools/cpm_disk.py list build/zork2.dsk

To make this disk convenient on all our targets, also add the optional console tools and the required RAMDisk save tool from the retained builds:

python tools/cpm_disk.py put build/zork2.dsk build/profiles/oliger320/files/HELLO.COM build/profiles/oliger320/files/COLOR.COM build/profiles/tspico-ram/files/TPSAVE.COM

HELLO avoids the cartridge's automatic startup command being absent; it is not required by Zork II. COLOR supplies the color command. TPSAVE.COM is needed to export a TSPico RAMDisk; it is not needed for Fuse or persistent SD mode. For an extracted package, use the same filenames from that package's FILES directory instead of these project build paths. To use CPMDISK from within a TSPico v2.x SD image, also put CPMDISK.COM on it before mounting it.

For a TAP copy of that same disk:

python tools/tspico_ram_image.py --dsk build/zork2.dsk --output build/zork2.tap

Alternatively create build/zork2.tap with cpm_disk.py create and use exactly the same put commands with that filename; the tool detects the container from its extension. This common create/put/list procedure also applies to ordinary CP/M application COM files and their companions.

4. Open it on your target

Target Load the new disk
TSRun launcher Open disk, select zork2.dsk or zork2.tap. Both are 320KB, matching the supplied game cartridge.
Fuse/JLO Launch with tools/run_oliger.ps1 -Cartridge build/infocom-cpm.dck -Disk build/zork2.dsk; insert the printed DSK manually if the GUI requires it.
TSPico v2.x, optional SD service, image mode Copy zork2.tap to physical /TAP/CPM/ZORK2.TAP. At A>, CPMDISK MOUNT ZORK2.TAP. Keep CPMDISK.COM on the disk if you need to switch away later.
TSPico v2.x, native-files mode Copy ZORK2.COM and ZORK2.DAT into physical /TAP/CPM/FILES, then reboot or remount with CPMDISK DIR. No disk container is required.
TSPico v2.x, TAP/RAMDisk mode without SD service Copy zork2.tap as physical /TAP/CPM/SAVE/CPMRAM.TAP, preserving the old save. Restart; choose T for the TAP if an older chunk set also exists. With a service present, choose L first to reload a saved RAMDisk.
Original 1.00 RAMDisk Open the new disk in TSRun, choose Download 1.00 TAP set, and extract the chunk TAPs and CPMSTATE.TAP into /TAP/CPM/SAVE/, preserving the previous set separately. Restart the dual cartridge; it loads the set directly.

For a fresh 1.00 factory preload rather than a saved set, tspico_ram_image.py can generate the small boot volumes with --volumes; see disk tools. Do not put a single large TAP on 1.00 and assume it replaces the chunk/preload loading procedure. Firmware capability limits are in the matrix.

5. Run and save

At CP/M's A>:

ZORK2

Expect ZORK II: The Wizard of Frobozz, Version 48 / Serial number 840904, and the starting room Inside the Barrow. At the game's > prompt, LOOK repeats the room description. SAVE defaults to ZORK2.SAV: keep this disk mounted and press Enter at each of the two disk/filename prompts. RESTORE uses the saved file. QUIT, then Y, returns to CP/M.

Game SAVE creates a file inside the CP/M disk. Also preserve the outer disk: TPSAVE in RAMDisk, JLO Save/Save As in Fuse, Download DSK/TAP in TSRun. TSPico v2.x persistent SD mode already writes to its SD volume. The example was verified in native Z80 emulation from both DSK and TAP, including LOOK, SAVE and returning to A>. No claim is made here that every Infocom game works.

WordStar, dBASE II, SuperCalc and other applications

Use the same create/put/list/mount/run sequence. Extract individual CP/M-80 files from their distribution first; an Apple, Kaypro or Osborne disk image is not automatically one of our Oliger DSKs. Our tool reads this project's 160KB/320KB layouts, not arbitrary CP/M disk formats.

Application What to check before copying/running
WordStar CP/M-80 edition; keep its matching overlay/install files, not just WS.COM. Configure its terminal for compatible ADM-3A behavior and the available column width.
dBASE II CP/M-80 edition; retain its matching companion files and room for databases. CP/M-86/DOS editions will not run.
SuperCalc CP/M-80 edition; retain its support files and configure the terminal/screen size. An 80-column installation is not automatically suitable for the normal 64-column console.
Another Infocom game Choose an actual version-3 story; use prepare_infocom with a new basename, then copy that COM/DAT pair using the same disk commands.

The Retroarchive CP/M collection is an archive lead for commercial-era CP/M software; availability varies. Consult the application's own install instructions for its required files and terminal patching. Those three applications have not been validated in this port. Our TPA is 52,992 bytes (about 51.75KiB), independent of the larger RAMDisk; software needing more usable program memory, a different CPU, multiple drives, or terminal features beyond this console may need further work. Start with a separate disk and a compatible release rather than treating a successful copy as proof the application will run.

Choosing 64 or 80 columns

Run COLUMNS to see the current width, COLUMNS 64 to select the normal TS2068 console, or COLUMNS 80 for the supported PicoVideo renderer. Boot defaults to 80 when that renderer is detected, otherwise 64. This works independently of the TSPico firmware version. The screen clears; files and colors are preserved. Exit and restart applications after changing width. A warm boot keeps the choice; a cold boot selects the default again. A normal TS2068 reduced-width 80-column font is a future option. See display details.

COLOR also makes the border match the background. VIDEO prints PicoVideo register diagnostics; use it if COLUMNS 80 reports unavailable. Some PicoVideo 64-column firmware has a documented ink-calculation issue that can make COLOR 0 appear blue on white; see PicoVideo troubleshooting.

Optional border color

COLOR scheme matches the border to the background. COLOR scheme border sets it independently, for example COLOR 7 2 gives white text on black with a red border. Both arguments are single digits 0–7. Border numbers are: 0 black, 1 blue, 2 red, 3 magenta, 4 green, 5 cyan, 6 yellow, 7 white. COLOR 7 restores a matching black border. Invalid arguments leave colors unchanged. A width change selects a matching border again; rerun COLOR with both arguments to restore a custom border after switching widths.