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.
The overall format of all cbmctrl actions is:
Synopsis: cbmctrl [global_options] ACTION [action_args]
Some options that are related to cbmctrl in general of which affect the oervall behaviour of all actions
One of a bunch of different subcommands that direct cbmctrl what to do
Arguments that are required for the subcommand action to work
cbmctrl understands the following global options
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
Output version information as well as the built date and time
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.
Future extension, unused at the moment
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.
Do not convert data between CBM and PC side. The opposite to --petscii.
cbmctrl understands the following subcommand actions
Reset all drives on the IEC bus
Detect all drives on the IEC bus
Lock the parallel port for OpenCBM (cbm4linux/cbm4win) use
Unlock the parallel port from exclusive usage
Perform a listen on the IEC bus
Perform a talk on the IEC bus
Perform an unlisten on the IEC bus
Perform an untalk on the IEC bus
Perform an open on the IEC bus
Same as open, but with ASCII to PETSCII conversion. Its use is deprecated, use the global option --petscii with open instead.
Perform a close on the IEC bus
Get a stream of raw data from an IEC bus device
Put a stream of raw data to an IEC bus device
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.
Give the status of a specified drive
Issue a command to a specified drive
Same as command, with ASCII to PETSCII conversion Its use is deprecated, use the global option --petscii with command instead.
Output the directory of a disk in a specified drive
Download memory contents from a floppy drive
Upload memory contents to a floppy drive
Wait for a disk to be changed in a specified drive
Many of the cbmctrl subcommands understand the following common arguments:
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.
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.
cbmctrl understands the following actions:
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.
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).
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.
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.
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
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
Ends communication with listening devices after a listen command. This corresponds to the C64 kernel routine $ffae.
Ends communication with talking devices after a talk command. This corresponds to the C64 kernel routine $ffab.
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.
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 the file associated with secondary address secadr on device device.
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.
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.
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.
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.
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.
Like command, but converts the data from ASCII to PetSCII before sending it. Its use is deprecated, use command with --petscii instead.
Read directory from disk in device device, print on standard out.
The output depends upon if --petscii or --raw is specified.
You can also specifiy a filespec that filters out what you want to show. Note that the filter is sent to the device and processed there. It's use of wildcards is limited. Please note also that the command-line processes wildcards on its own. Thus, to be sure that the filespec is processed correctly, include it in quotation marks!
In order to specify the drive to use on a dual-drive floppy (i.e., 8050, 8250), you can append the number as file spec.
Examples:
cbmctrl dir 8 cbmctrl dir 8 0 cbmctrl dir 8 1 cbmctrl dir 8 "ABC*" cbmctrl dir 8 "1:ABC*" cbmctrl dir 8 "250/cmd_dir/:ABC*"
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.
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.
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.
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
cbmctrl download 8 0xc000 0x4000 1541.rom
Write file buffer2.bin to drive 9, address 0x500:
cbmctrl upload 9 0x500 buffer2.bin