Making your own Applesauce Software

Created by John K. Morris
jmorris@evolutioninteractive.com

Version 0.1 – July 23, 2021 – EXTREMELY ROUGH DRAFT

This document is for people who wish to be able to connect directly up to the Applesauce hardware with their own client software. It describes the communication protocol to perform all floppy drive functionality.

The Applesauce shows up as a USB serial device with the name “Applesauce” (Product ID: 0x0483 / Vendor ID: 0x16c0 / Manufacturer: Evolution Interactive). The connection speed is 12Mb/s. It is possible that you may need a serial driver for Windows devices.

The architecture of the hardware is very straightforward. The Applesauce contains a 160K internal buffer that it uses for all binary data.

All commands to Applesauce as well as responses are human readable strings, end with a ‘\n’ character, and are case insensitive.

There is a common set of basic responses from the hardware.

“.” means ok/acknowleded

“!” mean bad

“?” command is not recognized

“+” on – sent in response to queries

“-” off – sent in response to queries

“v” no power – a command was attempted that requires the device to be powered up, but there is no power

? – always returns the string “Applesauce”. Easy way to determine if the communication channel is working.

connect – requests that the Applesauce connect to the floppy drive. This will initiate the process where Applesauce will probe all of the drive connectors to determine where and what is connected. This process will also power up the drive. Returns “.” if a drive was found and identified. “!” when it could not detect a connected drive.

disconnect – logically disconnect the Applesauce from the drive this will also power down the drive. This will always return “.”.

?vers – returns the firmware version

?pcb – returns the PCB revision number

?kind – returns a string describing the type of drive that is connected. “5.25” is a Disk II-compatible drive on the 20-pin or DB-19 port, “3.5” is an Apple 3.5 drive that uses the Sony protocol, “PC” is for a PC-compatible drive on the 34-pin port. If no drive was detected, then “NONE” is returned.

?idlog – returns a text string that describes the process used to determine the type of drive that is connected. Used to debug when drives aren’t recognized properly.

force:5.25, force:3.5, force:pc – forces Disk II 5.25“, Apple 3.5”, or PC drive mode, respectively. Should not be necessary outside of testing and debugging as autodetection will normally detect the drive – see the documentation for connect and ?kind.

?safe – returns “+” or “-” depending on the position of the Safe switch on the front of the Applesauce

The drive power is typically handled automatically by the “connect” and “disconnect” commands. But if you need to do anything special, then this is how you can manage and query the power supply.

psu:? – returns “+” or “-” indicating whether the power supply is currently turned on

psu:on – turns on the power supply. If the power is successfully turned on, then “+” is returned. If there was an electrical problem, “-” is returned.

psu:off – turns off the power supply

psu:?5v – current voltage on the +5V rail (eg: 5.02)

psu:?12v – current voltage on the +12V rail

psu:?5a – milliamp load on the +5V rail

psu:?12a – milliamp load on the +12V rail

All binary data between the Applesauce and your client happen using a 160K buffer that exists in the hardware. This interface allows you to upload and download the data.

data:>xxx – upload data to the Applesauce. “xxx” is the number of bytes that you are sending. It will respond with “.” to indicate that it is ready to receive the binary bytes or “!” if the amount of data you are sending will overflow the buffer. After uploading the bytes, Applesauce will again respond with a “.” if the transfer succeeds or “!” if it fails or times out. This will overwrite all data in the buffer.

data:<xxx – download data from the Applesauce. “xxx” is the number of bytes you want to download. It will respond with “.” to acknowledge the command, immediately followed by the binary data. If you request more data than is in the buffer, then the request will fail with “!” returned.

data:?max – will return the size of the data buffer in bytes.

data:?size – will return the number of bytes available to read in the buffer

data:clear – will discard all bytes in the buffer

data:dump – used primarily for debugging. It will print out the contents of the data buffer in hex.

drive:enable – Puts the drive into enabled mode. This is primarily for non-Disk II drives, and is safely ignored for the Disk II.

drive:disable – Takes the drive out of enabled mode.

drive:?enabled – returns “+” or “-” is the drive is currently enabled

motor:on – turns on the spindle motor. This command will wait until the spindle has achieved the proper speed. If you don’t need to have the drive wait for the proper speed, you can send the command with a “-” suffix to indicate such (motor:on-). If the motor is started successfully, a “.” will be returned, otherwise “!”.

motor:off – turns off the spindle motor

motor:? – returns “+” or “-” depending on whether the motor is currently on

motor:?tach – (for Apple 3.5 drives only) returns the RPM of the drive

head:zero – will bring the head to track 0. Returns “.” is successful and “!” if the head failed to be zeroed.

head:dirx – sets the head step direction. Passing in the “+” value will set the direction to inward (increasing track numbers) and passing “-” will set the direction as outward (decreasing track numbers).

head:step – will step the head in the direction as set with the head:dir command. Except for Disk II drives which will always step the head inward in quarter track increments.

head:phasexxx – Disk II only. Moves the head to the desired phase (or half track).

head:trackxxx – Moves the head to the desired track.

head:?track – returns the current track number where the head is located

head:?phase – Disk II only. Returns the current phase number where the head is located

head:?halfphase – Disk II only. Returns the current half phase (quarter track) number where the head is located

head:sidex – selects which head to use for reading/writing. Pass in “0” or “1” for x.

head:?side – returns the currently active head

head:?trk00 – returns “+” or “-” indicating the state of the drive track 0 sensor. “+” means the the head is located at track 0.

head:?count – returns the number of head that the drive has

sync:?avail – return “+” or “-” depending on whether there drive has a sync sensor can can provide an index signal

sync:on – indicates to Applesauce that you want all floppy commands to be aligned with a sync signal

sync:off – indicates that you want the sync signal to be ignored

sync:? – returns “+” or “-” depending on whether sync is turned on

sync:?speed – will return the speed of the drive based on sync signal or index

sync:?stable – runs a lengthy test on the sync sensor to ensure that the sync signal is steady

d35:?disk – returns “+” or “-” based on whether there is a disk currently inserted in the drive

d35:eject – triggers the eject mechanism

d35:?super – returns “+” or “-” based on whether the drive is an Apple SuperDrive

d35:?hd – SuperDrive Only. Returns “+” or “-” based on whether the inserted disk is High or Double density

d35:?mode – SuperDrive Only. Returns the current mode of the drive “gcr” or “mfm”

d35:gcr – SuperDrive Only. Sets the drive into GCR mode

d35:mfm – SuperDrive Only. Sets the drive into MFM mode

dpc:config – tells the Applesauce to fetch the PC drive parameters from the data buffer and use them

dpc:?readyxxx – waits for the ready signal from the drive. “xxx” is a timeout in milliseconds. Returns “+” or “-” if the ready signal is asserted before the timeout.

dpc:densityx – controls the DENSITY pin of the floppy drive. “x” should be “+” for HIGH or “-” for LOW.

dpc:?density – returns “+” or “-” indicating the current state of the DENSITY pin

disk:bitsxxx,yyy – will read the disk while translating fluxes to a bitstream. The bitstream will use cell windows whose size is indicated by xxx. It will fetch yyy number of bytes of bit data.

disk:read – will read the flux timings for a track. This is a quick read that will grab 1.25 disk rotations. If the sync flag is on, then the read will begin at the sync sensor or drive index.

disk:readx – will perform an extended read of flux timings, grabbing 2.25 disk rotations. If the sync flag is on, then the read will begin at the sync sensor or drive index.

disk:find

disk:?write – returns “+” or “-” depending on the state of write protect sensor (“+” if the disk is not write protected).

disk:wipe – wipes the current track, basically unformatting it

disk:wclear – clears all write commands

disk:wcmd – adds a new write command

disk:write – performs all of the uploaded write commands. Adding a “-” suffix to the command will cause the track to be completely wiped before the new data is written.

disk:pclear – clear the write precompensation table

disk:pconfig – tells the Applesauce to fetch a write precompensation table from the data buffer

disk:?noise – repeatedly returns the number of bits detected per rotation

These are primarily meant for hardware troubleshooting and are subject to change.

pins:connect – enables the '245

pins:disconnect – disables the '245

pins:?map – prints the current pin map (dependent on drive kind, see ?kind)

n below is the pin number output from the pins:?map command.

pins:i n – sets pin n to input mode

pins:o n – sets pin n to output mode

pins:r n – returns “+” or “-” depending on the state of pin n

pins:wh n – writes logic level high to pin n

pins:wl n – writes logic level low to pin n