Add documentation for the Applesauce.

README.md

@@ -4,11 +4,8 @@ FluxEngine
 (If you're reading this on GitHub, the formatting's a bit messed up. [Try the
 version on cowlark.com instead.](http://cowlark.com/fluxengine/))
 
-**Breaking news!** As of 2022-09-09, there's new [filesystem
+**Breaking news!** As of 2024-10-01, the FluxEngine client software works
-support](doc/filesystem.md). Read (and sometimes write) files directly from
+(to a point) with [Applesauce](doc/applesauce.md) hardware.
-(and to) your disks, with eight different file systems! It works in the GUI,
-too, which is available for Linux (and other Unix clones), Windows and OSX. See
-the details below.
 
 <div style="text-align: center">
 <a href="doc/screenshot.jpg"><img src="doc/screenshot.jpg" style="width:60%" alt="screenshot of the GUI in action"></a>
@@ -35,12 +32,14 @@ Don't believe me? Watch the demo reel!
 </div>
 
 **New!** The FluxEngine client software now works with
-[Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) hardware. So, if you
+[Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) and
-can't find a PSoC5 development kit, or don't want to use the Cypress Windows
+[Applesauce](https://applesaucefdc.com/) hardware. So, if you can't find a PSoC5
-tools for programming it, you can use one of these instead. Very nearly all
+development kit, or don't want to use the Cypress Windows tools for programming
-FluxEngine features are available with the Greaseweazle and it works out-of-the
+it, you can use one of these instead. Very nearly all FluxEngine features are
-box. See the [dedicated Greaseweazle documentation page](doc/greaseweazle.md)
+available with the Greaseweazle and it works out-of-the box; the Applesauce is a
-for more information.
+bit less supported but still works. See the [dedicated Greaseweazle
+documentation page](doc/greaseweazle.md) or the [Applesauce
+page](doc/applesauce.md) for more information.
 
 Where?
 ------

doc/applesauce.md

@@ -0,0 +1,72 @@
+Using the FluxEngine client software with Applesauce hardware
+===============================================================
+
+The FluxEngine isn't the only project which does this; another one is the
+[Applesauce](https://applesaucefdc.com/), a proprietary but feature-rich
+off-the-shelf imaging device. Its native client (which is a lot better than
+FluxEngine) only works on OSX, so if you want to use it anywhere else,
+the FluxEngine client works.
+
+The Applesauce works rather differently to the FluxEngine hardware or the
+[Greaseweazle](greaseweazle.md), so there are some caveats.
+
+ - Rather than streaming the flux data from the device to the PC, the Applesauce
+   has a fixed buffer in RAM used to capture a complete image of a track. This is
+   then downloaded later. The advantage is that USB bandwidth isn't an issue; the
+   downside is that the buffer can only hold so much data. In fact, the Applesauce
+   can only capture 1.25 revolutions or 2.25 revolutions, nothing else. When used
+   with the FluxEngine the capture time will be ignored apart from used to
+   determine whether you want a 'long' or 'short' capture.
+
+ - The current (v2) firmware only supports reading, not writing (via clients
+   other than the official one, of course). The new (v3) firmware will support
+   writing, but it's not out yet, so for the time being the FluxEngine client is
+   read only.
+
+ - You can only do synchronous reads, i.e., reads starting from the index mark.
+
+Other than this, the FluxEngine software supports the Applesauce almost
+out-of-the-box --- just plug it in and nearly everything should work. The
+FluxEngine software will autodetect it. If you have more than one device plugged
+in, use `--usb.serial=` to specify which one you want to use.
+
+I am aware that having _software_ called FluxEngine and _hardware_ called
+FluxEngine makes things complicated when you're not using the FluxEngine client
+software with a FluxEngine board, but I'm afraid it's too late to change that
+now. Sorry.
+
+What works
+----------
+
+Supported features with the Greaseweazle include:
+
+  - simple reading of disks, seeking etc
+  - erasing disks
+  - hard sectored disks
+  - determining disk rotation speed
+  - normal IBM buses
+
+I don't know what happens if you try to use an Apple Superdrive or a Apple II
+disk with FluxEngine. If you've got one, [please get in
+touch](https://github.com/davidgiven/fluxengine/issues/new)!
+
+What doesn't work
+-----------------
+
+  - voltage measurement
+  - writing
+
+Who to contact
+--------------
+
+I want to make it clear that the FluxEngine code is _not_ supported by the
+Applesauce team. If you have any problems, please [contact
+me](https://github.com/davidgiven/fluxengine/issues/new) and not them.
+
+In addition, the Applesauce release cycle is not synchronised to the
+FluxEngine release cycle, so it's possible you'll have a version of the
+Applesauce firmware which is not supported by FluxEngine. Hopefully, it'll
+detect this and complain. Again, [file an
+issue](https://github.com/davidgiven/fluxengine/issues/new) and I'll look into
+it.
+

doc/using.md

@@ -50,9 +50,9 @@ file while changing the decoder options, to save disk wear. It's also much faste
 
 ### Connecting it up
 
-To use, simply plug your FluxEngine (or [Greaseweazle](greaseweazle.md)) into
+To use, simply plug your FluxEngine (or [Greaseweazle](greaseweazle.md) or
-your computer and run the client. If a single device is plugged in, it will be
+[Applesauce](applesauce.md)) into your computer and run the client. If a single
-automatically detected and used.
+device is plugged in, it will be automatically detected and used.
 
 If _more_ than one device is plugged in, you need to specify which one to use
 with the `--usb.serial` parameter, which takes the device serial number as a