How the FluxEngine works
========================

## The hardware design

It's essentially very simple, although the details are complicated. In
essence, all the firmware does is to measure the time between flux transition
pulses and send them to the PC.

There's an 8-bit counter attached to an 12MHz clock. This is used to measure
the interval between pulses. A Cypress datapath state machine thingy using
Verilog turns the timer, pulse and index information into a bytecode stream
which encodes intervals, pulses, and whether the index hole has been seen.

This is then streamed back to the PC, where offline software decodes it: it
searches for known bit patterns (which depend on the format), uses those to
determine the clock rate, and then turns the pulses into a nice, lined up bit
array and from there decodes the file system format.

Writing back to disk works the same way: bytes are streamed to the
FluxEngine, where a different datapath state machine thingy (the PSoC5LP has
24, all independently programmable) to interpret the bytecodes, generate a
stream of pulses to the disk.

The bytecode format is very simple with a six-bit interval since the previous
event in the lower six bits and the top two bits are set of a pulse or an index
hole (or both, or neither).

An HD floppy has a nominal pulse frequency of 500kHz, and we use a sample
clock of 12MHz (every 83ns). This means that our 500kHz pulses will have an
average interval of 24. This gives us more than enough resolution. At this
speed, in the 200ms that a 3.5" disk takes to rotate, we will see about
100,000 pulses. Each one is encoded as a single byte; so that revolution
generates 100kB of data.  (Extremely approximately. The actual figure varies
depending on what data is stored on the disk.)

(The clock needs to be absolutely rock solid or we get jitter which makes the
data difficult to analyse, so 12 was chosen to be derivable from the
ultra-accurate USB clock.)

Some useful and/or interesting numbers:

  - nominal rotation speed is 300 rpm, or 5Hz. The period is 200ms.
  - a pulse, as generated by the floppy drive electronics, is 150ns to 800ns
    long.
  - a 12MHz tick is 83ns.
  - MFM HD encoding uses a clock of 500kHz. This makes each recording cell 2us,
    or 24 ticks. For DD it's 4us and 48 ticks.
  - a short transition is one cell (2us == 24 ticks). A medium is a cell and
    a half (3us == 36 ticks). A long is two cells (4us == 48 ticks). Double
    that for DD.
  - pulses are detected with +/- 350ns error for HD and 700ns for DD. That's
    4 ticks and 8 ticks. That seems to be about what we're seeing.
  - in real life, pulses start going astray on a 3.5" drive after about 128
    ticks == 10us. I haven't tried with a 5.25" drive yet as I don't have a
    5.25" scratch disk.

## Why don't I use an Arduino / STM32 / ESP32 / Raspberry Pi / etc?

-I've got a _lot_ of questions on this, and multiple Github issues of people
debating it. It's complicated, but it's essentially a tradeoff between speed
and complexity.-

**Update as of 2020-01-08:**

Right. Well.

This section used to have a long explanation as to why these other platforms
were unsuitable --- essentially, they're generally missing out on either the
realtimeness to sample the data correctly (Raspberry Pi) or enough CPU to
stream the data over USB while also sampling it (Arduino).

This is correct, but it turns out that the STM32 has some built-in features
which support the FluxEngine's use case almost exactly: you can configure the
DMA engine to sample the interval between pulses and write them directly into
memory, and you can configure the PWM engine the read samples from memory and
use them to time pulses to the output. There's a bit less functionality, so you
can't do things like measure the signal voltages, and they're less convenient
as you need an adapter cable or board, but this will allow you to replicate the
FluxEngine hardware on a $2 Blue Pill.

I am _not_ planning on replacing the PSoC5 with a Blue Pill, because someone
already has: [the Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) is
a completely open source firmware package which will read and write Supercard
Pro files via a standard Blue Pill or via a prebuilt board. It's supported by
the FluxEngine client software, and you should, mostly, be able to use
Greaseweazle hardware interchangeably with FluxEngine hardware. See the
[dedicated page](greaseweazle.md) for more information.


## Drive interface pinouts

For reference, here are the FDC pinouts:

```ditaa
:-E -s 0.75

                       +-- GND                       +-- GND
                       |   (entire column)           |   (entire column)
                +----+-+--+                   +----+-+--+   
     DISKCHG ---+ 34 + 33 +        DISKCHG ---+ 34 + 33 +
                +----+----+                   +----+----+
       SIDE1 ---+ 32 + 31 +          SIDE1 ---+ 32 + 31 +
                +----+----+                   +----+----+
       RDATA ---+ 30 + 29 +          RDATA ---+ 30 + 29 +
                +----+----+                   +----+----+
         WPT ---+ 28 + 27 +            WPT ---+ 28 + 27 +
                +----+----+                   +----+----+
       TRK00 ---+ 26 + 25 +          TRK00 ---+ 26 + 25 +
                +----+----+                   +----+----+
       WGATE ---+ 24 + 23 +          WGATE ---+ 24 + 23 +
                +----+----+                   +----+----+
       WDATA ---+ 22 + 21 +          WDATA ---+ 22 + 21 +
                +----+----+                   +----+----+
        STEP ---+ 20 + 19 +           STEP ---+ 20 + 19 +
                +----+----+                   +----+----+
   DIR/SIDE1 ---+ 18 + 17 +      DIR/SIDE1 ---+ 18 + 17 +
                +----+----+                   +----+----+
       MOTEB ---+ 16 + 15 +          MOTEB ---+ 16 + 15 +
                +----+----+                   +----+----+
       DRVSA ---+ 14 + 13 +            DS3 ---+ 14 + 13 +
                +----+----+                   +----+----+
       DRVSB ---+ 12 + 11 +            DS2 ---+ 12 + 11 +
                +----+----+                   +----+----+
       MOTEA ---+ 10 + 9  +            DS1 ---+ 10 + 9  +
                +----+----+                   +----+----+
       INDEX ---+ 8  + 7  +          INDEX ---+ 8  + 7  +
                +----+----+                   +----+----+
         n/c ---+ 6  + 5  +            DS4 ---+ 6  + 5  +
                +----+----+                   +----+----+
         n/c ---+ 4  + 3  +            INU ---+ 4  + 3  +
                +----+----+                   +----+----+
       REDWC ---+ 2  + 1  +          REDWC ---+ 2  + 1  +
                +----+----+                   +----+----+   
                           
              PC interface           Shugart interface
 
               Odd numbered pins are always grounded
```

### Some useful links

  - [The floppy disk user's
    guide](http://www.hermannseib.com/documents/floppy.pdf): an incredibly
    useful compendium of somewhat old floppy disk information --- which is
    fine, because floppy disks are somewhat old.

  - [The TEAC FD-05HF-8830 data
    sheet](https://hxc2001.com/download/datasheet/floppy/thirdparty/Teac/TEAC%20FD-05HF-8830.pdf):
    the technical data sheet for a representative 3.5" drive. Lots of useful
    timing numbers here.

  - [The Mitsubishi M4851 data
    sheet](http://www.bitsavers.org/pdf/mitsubishi/floppy/M4851/TJ2-G30211A_M4851_DSHH_48TPI_OEM_Manual_Nov83.pdf):
    the equivalent data sheet for a representative 5.25" drive.

  - [The DRG Business Machines YD-174 manual](https://electrickery.hosting.philpem.me.uk/comp/divcomp/doc/YE_Data_YD-174_8inchFloppyDriveTechnicalManual.pdf):
	the equivalent manual (data sheets hadn't been invented then) for a
	representative 8" drive.

  - [KryoFlux stream file
    documentation](https://www.kryoflux.com/download/kryoflux_stream_protocol_rev1.1.pdf):
    the format of KryoFlux stream files (partially supported by FluxEngine)

  
