Next Previous Contents

7.2 cbmctrl

cbmctrl is used to send commands to external devices. It can control all kinds of serial CBM devices like floppy drives and printers. So far, it has been successfully tested with the disk drives 1541(-II), 1571 and a MPS-1200 printer.

Command structure

The overall format of all cbmctrl actions is:

Synopsis: cbmctrl [global_options] ACTION [action_args]

global_options

Some options that are related to cbmctrl in general of which affect the oervall behaviour of all actions

action

One of a bunch of different subcommands that direct cbmctrl what to do

action_args

Arguments that are required for the subcommand action to work

Global options

cbmctrl understands the following global options

-h [ACTION], --help [ACTION]

Outputs the help screen with a short listing of all available actions. If the optional ACTION name is given also, you retrieve more information on a special action together with its arguments and parameters

-V, --version

Output version information as well as the built date and time

Actions overview

cbmctrl understands the following subcommand actions

reset

Reset all drives on the IEC bus

detect

Detect all drives on the IEC bus

lock

Lock the parallel port for OpenCBM (cbm4linux/cbm4win) use

unlock

Unlock the parallel port from exclusive usage

listen

Perform a listen on the IEC bus

talk

Perform a talk on the IEC bus

unlisten

Perform an unlisten on the IEC bus

untalk

Perform an untalk on the IEC bus

open

Perform an open on the IEC bus

close

Perform a close on the IEC bus

popen

Same as open, but with ASCII to PETSCII conversion

read

Get a stream of raw data from an IEC bus device

write

Put a stream of raw data to an IEC bus device

status

Give the status of a specified drive

command

Issue a command to a specified drive

pcommand

Same as command, with ASCII to PETSCII conversion

dir

Output the directory of a disk in a specified drive

download

Download memory contents from a floppy drive

upload

Upload memory contents to a floppy drive

change

Wait for a disk to be changed in a specified drive

Common action arguments

Many of the cbmctrl subcommands understand the following common arguments:

[DEVICE]

Advice cbmctrl to direct its communication to the IEC bus device with the number [DEVICE]. IEC bus device numbers can be denoted in the range from 0 to 30, although no Commodore device is known to use device numbers 0 to 3. Most commonly used are the numbers 4 (printer) and 8 to 11 (disk drives). Device number 31 is used to denote the UNTALK respectively the UNLISTEN command code on the IEC bus instead of the TALK respectively LISTEN command code, therefore device address 31 cannot be used in general.

[SECADR]

With several cbmctrl actions the secondary address parameter [SECADR] denotes a dedicated logical communication channel for the specifed [DEVICE] . IEC bus channel numbers can be denoted in the range from 0 to 15. Take note that for floppy disk drive devices some secondary addresses are interpreted in a special way. Secondary address 0 is used, when a program is loaded, address 1, when a program is saved. Address number 15 represents the command channel of the disk drive, so eŽectively, for bulk data transfers to and from disk drives, only the logical channel numbers 2 to 14 can be used.

Actions

cbmctrl understands the following actions:

reset

This action performs a hardware reset of all devices attached to the IEC bus. Control is returned after it is made sure that all devices are ready.

detect

This action tries to detect all devices attached to the IEC bus. For this, this subcommand accesses all possible devices and tries to read some bytes from its memory. If a devices is detected, its name is output. Additionally, this routine determines if the device is connected via a parallel cable (XP1541 companion cable, may be true for disk drives only).

lock

This command locks the parallel port for the use by OpenCBM, so that sequences of e.g. talk/read/untalk or listenwrite/unlisten are not broken by concurrent processes wanting to access the parallel port.

You should issue cbmctrl lock before doing any access to OpenCBM tools, and cbmctrl unlock after you are done.

unlock

This command unlocks the parallel port after the use by OpenCBM.

You should issue cbmctrl lock before doing any access to OpenCBM tools, and cbmctrl unlock after you are done.

listen device secadr

Tell device device to listen on secondary address secadr. Until the next unlisten command, everything output with cbmctrl write will be received by this device.

This command corresponds to the following 6502 assembly code on a C64:


lda #device
jsr $ffb1
lda #secadr
ora #$60
jsr $ff93

talk device secadr

Tell device device to talk on secondary address secadr. Until the next untalk command, data from this device can be received device by using the command cbmctrl read.

This command corresponds to the following 6502 assembly code on a C64:


lda #device
jsr $ffb4
lda #secadr
ora #$60
jsr $ff96

unlisten

Ends communication with listening devices after a listen command. This corresponds to the C64 kernel routine $ffae.

untalk

Ends communication with talking devices after a talk command. This corresponds to the C64 kernel routine $ffab.

open device secadr filename

Open file filename on device device. After opening, data can be read/written by sending a talk resp. listen command with the secondary address secadr.

If secadr is greater than 1, the file type and access mode must also be specified by appending ,type,mode to filename. Valid types are D, P, S, U, R (DEL, PRG, SEQ, USR, REL), valid modes are R for reading and W for writing.

Note: You cannot do an open without a filename. Although a CBM machine (i.e., a C64) allows this, this is an internal operation for the Computer only. It does not have any effect on the IEC bus.

cbmctrl open does not change any character encoding, that is, it does not convert between ASCII (used by the PC) and PETSCII (used by the CBM device). If this is needed, use cbmctrl popen instead.

popen device secadr filename

Like cbmctrl open, but converts the filename from ASCII to PetSCII before sending it to the floppy.

close device secadr

Close the file associated with secondary address secadr on device device.

read [file]

This command reads raw data from the IEC bus and outputs it into the given file, or to stdout if no file is given (or if it is a simple dash, "-").

write [file]

This command writes raw data to the IEC bus; the data is taken from the given file, or from stdin if no filename is given (or if it is a simple dash, "-").

status device

Copies input from device device, secondary address 15 (command/status channel), to the standard output stream. Note that all upper case characters are changed to lower case. Carriage return (0x0d) is also changed to the current operating system's line ending convention (0x0a on Unix oriented systems, 0x0d 0x0a on Windows oriented systems or whatever else is appropriate for your operating system).

Assuming the device number is 8, this command is similar to (in this case, no character conversions would be made)


cbmctrl lock
cbmctrl talk 8 15
cbmctrl read
cbmctrl untalk
cbmctrl unlock

command device cmdstr

Sends cmdstr to device device, secondary address 15 (command/status channel). Since there is no PetSCII->ASCII conversion, commands must be sent in upper case (kind of poor man's PetSCII conversion). This is because charset conversion would break the M-W and M-E commands.

Note: If you need PetSCII->ASCII conversion, use pcommand instead.

Assuming the device number is 8, this command is identical to (Note: This does not work on Windows, because echo there does not know the -n option.)


cbmctrl lock
cbmctrl listen 8 15
echo -n cmdstr|cbmctrl write -
cbmctrl unlisten
cbmctrl unlock

pcommand device cmdstr

Like command, but converts the data from ASCII to PetSCII before sending it.

dir device

Read directory from disk in device device, print on standard out.

download device address count [file]

Read count bytes from drive memory, starting at address via one or more M-R commands. Memory contents are written to standard output if file is ommited or equivalent to "-".

upload device address [file]

Send file to drive memory, starting at address via one or more M-W commands. If address is -1, the first two bytes from file are considered as start address. Reads standard input if file is ommited or equivalent to "-".

change device

Wait for a disc to be changed in the specified device. It waits for the current disc to be removed, for a new disc to be inserted and for the drive door to be closed. It does not return until the disc is ready to be read or written.

cbmctrl Examples

Send file contents to printer 4:


cbmctrl lock
cbmctrl listen 4 0
cbmctrl write file
cbmctrl unlisten
cbmctrl unlock

Copy file to disk drive 8:


cbmctrl lock
cbmctrl open 8 2 FILENAME,P,W
cbmctrl listen 8 2
cbmctrl write file
cbmctrl unlisten
cbmctrl close 8 2
cbmctrl unlock

Copy file from disk drive 8:


cbmctrl lock
cbmctrl open 8 2 FILENAME,P,R
cbmctrl talk 8 2
cbmctrl read file
cbmctrl untalk
cbmctrl close 8 2
cbmctrl unlock

Dump 1541 ROM:


cbmctrl download 8 0xc000 0x4000 > 1541.rom

or
cbmctrl download 8 0xc000 0x4000 1541.rom

Write file buffer2.bin to drive 9, address 0x500:


cbmctrl upload 9 0x500 buffer2.bin


Next Previous Contents