Trs80-tool NPM

trs80-tool

Command-line tool for manipulating TRS-80 files.

Installation

If you have Node installed, you can install trs80-tool using npm:

% npm install -g trs80-tool

and update it later to new versions:

% npm update -g trs80-tool

You can also download stand-alone binaries of the latest version:

File formats

The trs80-tool program supports these file formats:

.BAS: This is a Basic program. It's typically tokenized (token words like PRINT are stored as a single byte), but the tool supports reading Basic programs that are in text (non-tokenized) format. When writing a file with a .BAS extension, the file is always tokenized.
.ASC: This is also a Basic program, but always in text (non-tokenized) format. The extension is mostly useful when writing a Basic file, because it tells the converter to use the non-tokenized format.
.WAV: This is a cassette's audio stream. It can be at any sampling rate, either 8 or 16 bits per sample, and either mono or stereo.
.CAS: This is a cassette stored in a compact form where each bit on the cassette is stored as a bit in the file. It includes synchronization headers and bytes, as well as start bits (for high-speed cassettes). This is a decent archival format for cassettes.
.CMD: This is a machine language program as stored on a floppy disk.
.3BN: This is a machine language program as stored on a cassette. The name comes from "Model 3 BiNary". This is typically not used, and instead these files are stored within .CAS files.
.JV1: This is a floppy disk format for the Model I. It's very simple, capturing the basic sector data. It does not capture enough information for copy-protected floppies. It's named after Jeff Vavasour.
.JV3: This is a floppy disk format for the Model III. It's very simple, capturing the basic sector data and IDAM structure. It does not capture enough information for copy-protected floppies. It's slightly more capable than .JV1 because it can encode a mix of FM and MFM signals on the same track.
.DMK: Another floppy disk format, capturing more information from the floppy, such as some bits between sectors. Named after David M. Keil.
.SCP: SuperCard Pro raw flux floppy disk format.
.LST: This is an assembly language listing file, generated by disassembling a .CMD or .3BN file using the convert command.

Usage

The tool takes a command as its first argument:

% trs80-tool COMMAND args ...

Global flags are:

--version         Show the tool's version number.
--help            Show the usage message.
--color=COLOR     Force color mode (off, 16, 256, 16m, or auto).

By default trs80-tool detects the color capabilities of the terminal and sets the --color flag automatically. You can override this, either to turn off color (if it bothers you) or to force it on (when piping into a pager). For example:

% trs80-tool --color=16 hexdump in.cmd | less

`dir`

The dir command shows the contents of an archive file. Archives files are files that can contain other files. These are cassette files (in WAV or CAS format) and floppy disks (in JV1, JV3, DMK, or SCP format).

% trs80-tool dir FILE

The output format depends on the type of archive. Cassette files show baud rates, whereas floppy disks show creation date and type of file.

`info`

The info command takes a list of filenames and displays a one-line description of the contents of the file, such as its type (system program, Basic program) and, if known, the embedded filename.

% trs80-tool info in1.cmd in2.bas in3.cas in4.wav

The --verbose flag displays some information (like floppy geometry) for some file types:

% trs80-tool info --verbose in1.dmk in2.dsk

`convert`

The convert command converts a list of input files to an output file or directory. There are several different ways to use this command.

A single file can be converted to another format:

% trs80-tool convert in.cmd out.3bn    (diskette to cassette format)
% trs80-tool convert in.bas out.asc    (de-tokenize Basic program)

Several files can be put into an archive:

% trs80-tool convert in1.bas in2.3bn in3.cmd out.wav

This creates a cassette audio file containing the three files. Note that the .CMD file will be converted to .3BN format.

Archive files can be extracted if the destination is a directory:

% mkdir out
% trs80-tool convert in.wav out    (decode cassette and extract files)
% trs80-tool convert in.cas out
% trs80-tool convert in.dmk out

Archive files can be converted to other archive formats:

% trs80-tool convert in.dmk out.wav
% trs80-tool convert in.wav out.cas

When writing a cassette format, the baud rate of the input file will be used, if it's known:

% trs80-tool convert in1.cas in2.cas in3.cas out.wav

(The baud rate can be guessed from the .CAS file contents.) If the baud rate can't be guessed, 500 baud (low-speed) will be used:

% trs80-tool convert in1.bas in2.3bn out.wav

This can be overwritten using the --baud command-line flag:

% trs80-tool convert --baud 1500 in1.cas in2.cas in3.cas out.wav
% trs80-tool convert --baud 1500 in1.bas in2.3bn out.wav

If a system program doesn't have a built-in start address, one will be guessed by the info command:

% trs80-tool info in.cas
in.cas: System program (VCEPRN, /17408) on a low speed cassette

The start address can be set with the --start flag:

% trs80-tool convert --start 17408 in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS file
% trs80-tool info out.cas
out.cas: System program (VCEPRN) on a low speed cassette

The address auto can be used to guess an appropriate start address:

% trs80-tool convert --start auto in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS file

An assembly language listing disassembly file can be generated from .CMD and .3BN files:

% trs80-tool convert in.cmd out.lst
% trs80-tool convert in.3bn out.lst

The disassembler attempts to guess what is code and what is data. If the input program relocates itself, some entry points will be missing and code will instead be disassembled as data. You can explicitly list entry points:

% trs80-tool convert --entry 0x7059,0x7064,0x71B9,0x7263 in.cas out.lst

`hexdump`

The hexdump command displays a hex dump of the input file, with annotations. See the --color flag for how to force coloring on or off. By default the command will collapse consecutive identical lines:

% trs80-tool hexdump in.cmd

Use the --no-collapse flag to turn off this collapsing:

% trs80-tool hexdump --no-collapse in.cmd

`sectors`

The sectors command displays a table of the sectors in a floppy disk. The columns are the sectors and the rows are the tracks. For each sector a character is displayed:

- No sector.
S Single-density sector.
D Double-density sector.
X Deleted sector.
C CRC error (ID or data).

Use the --contents flag to also show the contents of the sectors.

`asm`

The asm command assembles the specified assembly language source code:

% trs80-tool asm program.asm program.cmd

It can generate .CMD, .3BN, .CAS, or .WAV files. For .CAS or .WAV files the default baud rate is 500, but can be set with the --baud flag:

% trs80-tool asm --baud 1500 program.asm program.cas

A listing file can be generated with the --listing flag:

% trs80-tool asm --listing program.lst program.asm program.cmd

`disasm`

The disasm command disassembles the specified program:

% trs80-tool disasm saucer.cmd

If the program is a .CMD or .3BN file, it is loaded into the correct place in memory. If it's a .ROM or .BIN file, it is loaded at 0x0000, but this can be change with the --org flag:

% trs80-tool disasm --org 0x8000 file.bin

The disassembler tries to guess which bytes are code and which are data by following the path of the program, starting with its main entry point. Additional entry points can be specified with the --entry flag:

% trs80-tool disasm --entry 0x0000,0x3799,0x377B ~/Downloads/model3.rom

Note that if any entry point is listed, then 0x0000 must be specified again if applicable.

`run`

Run a TRS-80 emulator in the shell:

% trs80-tool run

This is experimental and does not currently work well with games, and may not work at all in a Microsoft Windows shell.

Use the --model flag to specify the model (1, 3, or 4, defaults to 3) and the --level flag to specify the Basic level (1 or 2, defaults to 2).

% trs80-tool run --model 1 --level 1

Specify a program or floppy to load and run directly:

% trs80-tool run tdos13a.dsk

The --xray flag shows nothing in the shell but starts a web server for the X-ray debugger. This is experimental and not yet documented.

`help`

The help command shows more specific information about other commands:

% trs80-tool help dir
% trs80-tool help convert

Limitations

The tool cannot write floppy disk files.
The tool can only read TRSDOS and LDOS floppy disks.

Change log

2.3.0

Add support for TRSDOS for Model I and 4, and for LDOS.
Add run command.
Add asm command.
Add support for SCP SuperCard Pro raw flux floppy format.

2.2.0

Add sectors command.
Add --verbose flag to info command to display floppy geometry.
Add disasm command.

2.1.0

Add hexdump command.

2.0.10

Add --entry flag to help with disassembling programs that relocate themselves.

2.0.8

Can read, dir, and extract CAS files with multiple files.
The info command will display a guessed start address for system programs with no specified start address.
Added --start flag to set the start address of system files.