Next Previous Contents

6.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

-@, --adapter=<plugin>[:<bus>]

Specify the plugin to use. If you have installed more than one plugin (XA1541, XU1541, XUM1541), you can specifiy which one to use for this command. This way, you can use all three variants at the same time.

This requires an argument of the form <plugin>[:<bus>], where <plugin> is the plugin's backend name (currently: xa1541, xu1541, xum1541), and <bus> is the bus identifier, if it is supported by the backend.

-f, --forget

Future extension, unused at the moment

-p, --petscii (default for all actions but open and command)

Convert input or output parameter from CBM format (PETSCII)

When specifying texts to be sent to the floppy or when receiving texts from the floppy, convert them from/to petscii before outputting. This way, small letters on the PC side are small letters on the CBM side. The opposite is -r, --raw.

-r, --raw (default for open and command

Do not convert data between CBM and PC side.

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

popen

Same as open, but with ASCII to PETSCII conversion. Its use is deprecated, use the global option --petscii with open instead.

close

Perform a close on the IEC bus

read

Get a stream of raw data from an IEC bus device

write

Put a stream of raw data to an IEC bus device

put

Put specified data to the IEC bus device. In contrast to write, it allows you to specify the data as decimal, hexadecimal or octal values.

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 Its use is deprecated, use the global option --petscii with command instead.

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 effectively, 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 for XA1541/XM1541 cables, or the equivalent option for the XU1541 or XUM1541 cables; 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.

Depending upon if --petscii or --raw is specified, the file name is converted before being sent on the IEC bus.

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.

popen device secadr filename

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

Its use is deprecated, use open with --petscii instead.

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, "-").

If --petscii is given, the output is converted from PETSCII before being output to the file or to stdout.

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, "-"). If --petscii is given, the output is converted to PETSCII before being output to the IEC bus.

put [-e|--extended] <datastr> [<data1> ... <dataN>]

puts the specified data to the IEC bus

With this command, you can write raw data to the IEC bus. <datastr> is the string to output to the IEC bus. It must be given, but may be empty by specifying it as "".

<data1>, ..., <dataN> are additional bytes to append to the string <datastr>. Single bytes can be given as decimal, octal (0 prefix) or hexadecimal (0x prefix).

If the option -e or --extended is given, an extended format is used: You can specify extra characters by given their ASCII value in hex, prepended with `%', that is: `%20' => SPACE, `%41' => `A', `%35' => `5', and-so-on. A `%' is given by giving its hex ASCII: `%25' => `%'.

If using both --pestscii and --extended options, the bytes given via the `%' meta-character or as <data1>, ..., <dataN> are not converted to petscii.

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

The output depends upon if --petscii or --raw is specified.

command device cmdstr

Sends cmdstr to device device, secondary address 15 (command/status channel).

Depending upon if --petscii or --raw is specified, the file name is converted before being sent on the IEC bus. Be careful, though, because the --petscii conversion might break some commands like M-W and M-E. If in doubt, it is better to use --raw and use the commands in upper case (kind of poor man's PetSCII conversion).

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
cbmctrl put "cmdstr"
cbmctrl unlisten
cbmctrl unlock

Note that the command cbmctrl put "cmdstr" replaced the older variant echo -n cmdstr|cbmctrl write -, which still works.

pcommand device cmdstr

Like command, but converts the data from ASCII to PetSCII before sending it. Its use is deprecated, use command with --petscii instead.

dir device

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

The output depends upon if --petscii or --raw is specified.

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 "-" or ommited.

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 "-" or ommited.

change device

Wait for a disk to be changed in the specified device. It waits for the current disk to be removed, for a new disk to be inserted and for the drive door to be closed. It does not return until the disk 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