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

-----

==== How do I connect to the Applesauce hardware? ====


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.

-----

==== Hardware Architecture ====


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

-----

==== Communication ====


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

-----

==== Fundamental Commands ====


**?** – 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

-----

==== Power Supply ====


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

-----

==== Data Buffer ====


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 Control Commands ====


**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

=== Spindle Motor ===


**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

=== Heads ===


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

**head:dir**//x// – 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:phase**//xxx// – Disk II only. Moves the head to the desired phase (or half track).

**head:track**//xxx// – 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:side**//x// – 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 Sensor / Drive Index ===

**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

=== Apple 3.5 Drive Special Commands ===


**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

=== PC Drive Special Commands ===


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

**dpc:?ready**//xxx// – 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:density**//x// – 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

-----

==== Floppy Commands (Reading and Writing) ====


**disk:bits**//xxx,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

-----

==== Direct Pin Access ====

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**