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
- 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.
- 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.
- 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.
- 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--replaceis supplied, and checks disk capacity. - Mount/open that disk, then type the program's basename at
A>(omit.COM). - 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.