From 3a0c02459db5ac1d4c689698df3246b1552c61d3 Mon Sep 17 00:00:00 2001 From: David Given Date: Tue, 1 Oct 2024 21:50:33 +0200 Subject: [PATCH] Add documentation for the Applesauce. --- README.md | 21 +++++++------- doc/applesauce.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++ doc/using.md | 6 ++-- 3 files changed, 85 insertions(+), 14 deletions(-) create mode 100644 doc/applesauce.md diff --git a/README.md b/README.md index f02797ec..73665387 100644 --- a/README.md +++ b/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 -support](doc/filesystem.md). Read (and sometimes write) files directly from -(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. +**Breaking news!** As of 2024-10-01, the FluxEngine client software works +(to a point) with [Applesauce](doc/applesauce.md) hardware.
screenshot of the GUI in action @@ -35,12 +32,14 @@ Don't believe me? Watch the demo reel!
**New!** The FluxEngine client software now works with -[Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) hardware. So, if you -can't find a PSoC5 development kit, or don't want to use the Cypress Windows -tools for programming it, you can use one of these instead. Very nearly all -FluxEngine features are available with the Greaseweazle and it works out-of-the -box. See the [dedicated Greaseweazle documentation page](doc/greaseweazle.md) -for more information. +[Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) and +[Applesauce](https://applesaucefdc.com/) hardware. So, if you can't find a PSoC5 +development kit, or don't want to use the Cypress Windows tools for programming +it, you can use one of these instead. Very nearly all FluxEngine features are +available with the Greaseweazle and it works out-of-the box; the Applesauce is a +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? ------ diff --git a/doc/applesauce.md b/doc/applesauce.md new file mode 100644 index 00000000..3f7b55a7 --- /dev/null +++ b/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. + diff --git a/doc/using.md b/doc/using.md index 6008cec9..646b8676 100644 --- a/doc/using.md +++ b/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 -your computer and run the client. If a single device is plugged in, it will be -automatically detected and used. +To use, simply plug your FluxEngine (or [Greaseweazle](greaseweazle.md) or +[Applesauce](applesauce.md)) into your computer and run the client. If a single +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