Break out the assembly instructions into a separate page.

doc/building.md

@@ -0,0 +1,160 @@
+Building the hardware
+=====================
+
+This page documents what you need to do to actually build one. Do not fear, I
+know several people with mediocre soldering skills who've done it (I count
+myself as one of those).
+
+## Bill of materials
+
+This is the physical stuff you'll need.
+
+  - One or more floppy disk drives. Both 3.5" and 5.25" work. One FluxEngine
+    will even run both drives (but not at the same time, obviously). You'll
+    also need the appropriate cabling to plug the drives into a PC.
+
+  - A [Cypress PSoC5LP CY8CKIT-059 development
+    board](http://www.cypress.com/documentation/development-kitsboards/cy8ckit-059-psoc-5lp-prototyping-kit-onboard-programmer-and),
+    which is a decently fast ARM core wrapped around a CLDC/FPGA soft logic
+    device. You can get one directly from Cypress via the link above for $10,
+    but shipping can be extortionate depending where you are. You can also
+    find them on eBay or Amazon for about $20.
+
+  - **Either** a 17-way header pin strip **or** [a
+    34-way IDC motherboard
+    connector](https://eu.mouser.com/ProductDetail/Amphenol-FCI/86130342114345E1LF?qs=%2Fha2pyFadug%252BpMTyxmFhglPPVKuWXYuFpPNgq%252BsrzhDnXxo8B28k7UCGc7F%2FXjsi)
+    (or one of the other myriad compatible connectors; there's a billion).
+
+  - A suitable power supply. 3.5" floppy drives use 5V at about an amp
+    (usually less) --- sadly, too much to power from USB. 5.25" floppy drives
+    also require 12V. An old but decent quality PC power supply is ideal, as
+    it'll frequently come with the right connectors.
+
+  - a Windows machine to run the Cypress SDK on. (The FluxEngine client
+    software itself will run on Linux, Windows, and OSX, but you
+    have to build the firmware on Windows.)
+
+  - Basic soldering ability.
+
+  - (Optional) Some kind of box to put it in. I found an old twin 5.25"
+    Hewlett Packard drive enclosure and ripped all the SCSI guts out; this
+    both provides a good, solid box to house both my 3.5" and 5.25" drives
+    in, but provides an ideal power supply too. Bonus!
+
+
+## Assembly instructions
+
+All you need to do is attach your chosen connector to the board. You'll need
+to make sure that pin 2 on the cable is connected to pin 2.7 on the board,
+and pin 34 to pin 1.7 on the board (and of course all the ones in between).
+Apart from grounding the board (see below), this is literally all there is to
+it.
+
+The pads are small, but soldering them isn't too bad with a needle-nosed
+soldering iron tip.
+
+### If you're using a connector
+
+Line it up like this.
+
+<div style="text-align: center">
+<img src="closeup1.jpg" style="width:80%" alt="closeup of the board with
+connector attached">
+</div>
+
+Note the following:
+
+  - You're looking at the back of the board (the side without the big square
+    chips). The connector sticks out of the front.
+
+  - The notch on the connector goes at the top.
+
+  - The top row of pins on the connector overhang the edge of the board: they remain unconnected.
+
+Also, be aware that some floppy disk cables don't have a projection on the
+motherboard end to fit into that notch, and so will plug in either way round.
+That's fine, but some of these get round this by missing a hole for pin 5.
+That way they'll only plug into the connector one way round, because the
+connector is missing a pin. If you have one of these cables (I do), you'll
+need to use a pair of needle-nosed pliers to pull pin 5 out of the connector.
+
+### If you're using header pins
+
+Line it up like this.
+
+<div style="text-align: center">
+<img src="closeup2.jpg" style="width:80%" alt="closeup of the board with
+connector attached">
+</div>
+
+You're now looking at the _top_ of the board.
+
+(It's also possible to put the pins on the bottom of the board, or to use a
+row of header sockets allowing you to plug the board directly onto the floppy
+disk drive; for simplicity I'm leaving that as an exercise for the reader.)
+
+### Grounding
+
+You _also_ need to solder a wire between a handy GND pin on the board and
+connect it to ground on the drive. Because the board is powered by USB and
+the drive by your external power supply, they can be at different potentials,
+and they need to be tied together.
+
+If you're using a connector, the simplest thing to do is to bend up one of
+the unconnected pins and solder a short piece of wire to a GND pin on the
+board. Alternatively you'll need to splice it into your drive's power supply
+cable somehow. (The black one.)
+
+## Building the firmware
+
+On your Windows machine, [install the Cypress SDK and CY8CKIT-059
+BSP](http://www.cypress.com/documentation/development-kitsboards/cy8ckit-059-psoc-5lp-prototyping-kit-onboard-programmer-and).
+This is a frustratingly long process and there are a lot of moving parts; you
+need to register. You want the file from the above site marked 'Download
+CY8CKIT-059 Kit Setup (Kit Design Files, Creator, Programmer, Documentation,
+Examples)'. I'm not linking to it in case the URL changes when they update
+it.
+
+Once this is done, I'd strongly recommend working through the initial
+tutorial and making the LED on your board flash. It'll tell you where all the
+controls are and how to program the board. Remember that the big end of the
+board plugs into your computer for programming.
+
+When you're ready, open the `FluxEngine.cydsn/FluxEngine.cywrk` workspace,
+pick 'Program' from the menu, and the firmware should compile and be
+programmed onto your board.
+
+**Note:** If programming doesn't work and you get a strange dialogue
+box asking about port acquisition, then this is because the device isn't
+responding to the programmer. This is normal but annoying. You should see the
+device in the dialogue. Select it and press the 'Port Acquire' button. The
+device should reset and an extra item will appear in the dialogue; select
+this and press OK.
+
+If acquiring the port doesn't work, resulting in the IDE hanging for 45
+seconds and then producing a meaningless error message, you need to reset the
+programmer (the little board hanging off the side of the bigger board).
+You'll see that the light on the programmer is pulsing slowly in a breathing
+pattern. Press and hold the little button near the light for five seconds
+until the light stays solidly on. Now you should be able to acquire
+the port and proceed normally.
+
+## Building the client
+
+The client software is where the intelligence, such as it is, is. It's pretty
+generic libusb stuff and should build and run on Windows, Linux and OSX as
+well, although on Windows I've only ever used it with Cygwin. You'll need the
+`sqlite3`, `meson` and `ninja` packages (which should be easy to come by in
+your distribution). Just do `make` and it should build.
+
+If it doesn't build, please [get in
+touch](https://github.com/davidgiven/fluxengine/issues/new).
+
+## Next steps
+
+The board's now assembled and programmed. Plug it into your drive, strip the plastic off the little USB connector and plug that into your computer, and you're ready to start using it.
+
+I _do_ make updates to the firmware whenever necessary, so you may need to
+reprogram it at intervals; you may want to take this into account if you
+build a case for it. I have a USB extension cable plugged onto the programmer
+port, which trails out the side of my drive enclosure. This works fine.

doc/index.md

@@ -168,148 +168,25 @@ How?
 
 ### Introduction
 
-The system is based around a [Cypress PSoC5LP CY8CKIT-059 development
+The system is based around an off-the-shelf Cypress development board,
-board](http://www.cypress.com/documentation/development-kitsboards/cy8ckit-059-psoc-5lp-prototyping-kit-onboard-programmer-and),
+costing about $10 plus shipping. The only hardware modification you need to
-which is a decently fast ARM core wrapped around a CLDC/FPGA soft logic
+do is to attach a floppy drive connector.
-device. You can [get one for about
-$15](https://www.mouser.com/ProductDetail/Cypress-Semiconductor/CY8CKIT-059?qs=sGAEpiMZZMuo%252bmZx5g6tFKhundMNZurhvz2tw2jO%2fk8%3d).
 
-You need no extra components --- my old prototype (pictured above) had a
+[I wrote a long, detailed set of instructions on building and programming
-17-way header soldered to one side of the board; it then pushed directly onto
+it.](building.html)
-the floppy drive connector. Then you plug it into your PC via USB and you're
-ready to go. My newer prototype has a row of pins so I can plug it into a
-floppy disk drive cable, because that lets me fit it into a properly floppy
-disk drive enclosure. What you do is up to you.
 
-### Bill of materials
+I'm going to assume you've done this.
-
-So you've decide to go against my advice and attempt to build on of these
-suckers. Well, good luck, that's all I can say.
-
-Here's the physical stuff you need.
-
-  - one (1) CY8CKIT-059 development board. See above. If your soldering is
-    like mine, you may potentially need more, but as _I_ managed to construct
-    the thing without frying it, it can't be too hard.
-
-  - one (1) standard PC floppy disk drive. You'll have to search around as
-    they're increasingly hard to find. The FluxEngine should work with any
-    standard 3.5" or 5.25" drive.
-
-  - some way of connecting the board to your drive. My prototype above uses a
-    set of headers to let me attach the board directly on the back of the
-    drive; this works fine, but the geometry's kind of awkward as part of the
-    board covered the power socket and I had to modify it. (Which is why the
-    programmer is hanging off the back.) I'd recommend soldering on pins
-    instead, and using a traditional floppy cable. That'd let you attach two
-    drives, too (although this is currently unsupported in the firmware;
-    if you want this, [get in
-    touch](https://github.com/davidgiven/fluxengine/issues/new).
-
-  - decent soldering iron skills and an iron with a fine tip --- the pads on
-    the board are very small.
-
-  - a Windows machine to run the Cypress SDK on. (The FluxEngine client
-    software itself will run on Linux, Windows, and probably OSX, but you
-    have to build the firmware on Windows.)
-
-  - optional: a floppy drive power cable. You can cut this in half, solder
-    the raw end to the FluxEngine board, and power the drive off USB --- very
-    convenient. This only works for drives which consume less than 500mA.
-    _Check the drive before trying_ (5.25" drives need not apply here).
-    Otherwise you'll need an actual power supply.
-
-### Assembly instructions
-
-<img src="closeup.jpg" style="width:100%" alt="closeup of the board">
-
-(In the picture above, the connector on the left goes off to the programmer.
-Normally that's physically attached to the board but I had to cut it off to
-make it fit on the back of a floppy disk drive. Using pins instead means this
-isn't necessary, but, well, now it's too late.)
-
-  1. **If you're using a header:** solder your 17-way header to the
-     **bottom** of the board, from 2.7 to 1.7 inclusive. (It has to be 
-     the bottom because there are components that stick out on the other side
-     and the bottom needs to go flush against the drive.)
-
-  2. **If you're using an IDC header plug:** solder it to the **top** of
-     the board, notch up, with the _top_ row of pins overhanging the edge
-     of the board (so that pin 1 is disconnected). Pin 2 should be in board
-     pin 2.7, and pin 34 in baord pin 1.7.
-
-  3. **If you're using bare pins:** solder your 17-way pin header
-     to **either side** of the board, from 2.7 to 1.7 inclusive.
-
-  4. Solder two wires to any convenient VDD and GND pins and connect these to
-     your floppy disk drive's power supply. If you're powering the floppy
-     drive from the board, connect these directly to the floppy drive. The
-     board needs to have the same ground as the floppy disk drive or weird
-     stuff could happen. Remember to check the polarity.
-
-And you're done!
-
-### Building the firmware
-
-On your Windows machine, [install the Cypress SDK and CY8CKIT-059
-BSP](http://www.cypress.com/documentation/development-kitsboards/cy8ckit-059-psoc-5lp-prototyping-kit-onboard-programmer-and).
-This is a frustratingly long process and there are a lot of moving parts; you
-may need to register. You want the file from the above site marked 'Download
-CY8CKIT-059 Kit Setup (Kit Design Files, Creator, Programmer, Documentation,
-Examples)'. I'm not linking to it in case the URL changes when they update
-it.
-
-Once this is done, I'd strongly recommend working through the initial
-tutorial and making the LED on your board flash. The FluxEngine firmware
-isn't nearly ready for fire-and-forget use and you'll probably need to tweak
-it. (If you do, please [get in
-touch](https://github.com/davidgiven/fluxengine/issues/new)).
-
-When you're ready, open the `FluxEngine.cydsn/FluxEngine.cywrk` workspace,
-pick 'Program' from the menu, and the firmware should compile and be
-programmed onto your board.
-
-**Big warning:** If programming doesn't work and you get a strange dialogue
-asking about port acquisition, then this is because the device isn't
-responding to the programmer. This is normal but annoying. You should see the
-device in the dialogue. Select it and press the 'Port Acquire' button. The
-device should reset and an extra item will appear in the dialogue; select
-this and press OK.
-
-If acquiring the port doesn't work, resulting in a long delay and a
-meaningless error message, you need to reset the programmer. You'll see that
-the light on the programmer is pulsing slowly (a breathing pattern). Press
-and hold the little button near the light for five seconds until the light
-stays solidly on. Now you should be able to acquire the port and proceed
-normally.
-
-### Building the client
-
-The client software is where the intelligence, such as it is, is. It's pretty
-generic libusb stuff and should build and run on Windows, Linux and probably
-OSX as well, although on Windows I've only ever used it with Cygwin. You'll
-need the `sqlite3`, `meson` and `ninja` packages (which should be easy to
-come by in your distro). Just do `make` and it should build.
-
-If it doesn't build, please [get in
-touch](https://github.com/davidgiven/fluxengine/issues/new).
 
 ### Using it
 
-So you have client software, programmed the firmware, and the hardware is all
+  1. Attach the FluxEngine to your floppy disk cable.
-ready. What next?
 
-  1. Attach the FluxEngine to your floppy disk drive. Pin 2.7 (on the right in
+     If you built your board using a connector, this is easy: just plug it in. If you're using pins, you need to make sure that the red strip on the cable is **to the right** (next to pin 2.7 on the board), and that the pins plug into the **lower set of holes** in the connector (so the connector overhangs the top of the board).
-     the picture above) is REDWC and connects to pin 2 on the floppy drive.
-     Pin 1.7 (on the left in the picture above) is DSKCHG and connects to pin
-     34 on the floppy drive. All the other board pins connect in the obvious
-     order. Odd pins on the floppy drive are left unconnected. You can push
-     the floppy drive connector straight onto the pins, or the FluxEngine
-     board straight onto the floppy disk drive, depending on how you're doing
-     it.
 
-     Important note if you're using a floppy disk cable: these typically have
+  2. Attach the cable to your drives.
-     [two pairs of floppy disk drive connectors with a twist between
+
+     Floppy disk cables typically have [two pairs of floppy disk drive
+     connectors with a twist between
      them](http://www.nullmodem.com/Floppy.htm). (Each pair has one connector
      for a 3.5" drive and a different one for a 5.25" drive.) Normally the
      first floppy disk drive is drive B, and the one after the twist is drive
@@ -320,8 +197,8 @@ ready. What next?
      (Or use `-s :d=1` to select drive 1 when working with disks.)
 
   2. **Important.** Make sure that no disk you care about is in the drive.
-	 (Because if your wiring is wrong and a disk is inserted, you'll
+     (Because if your wiring is wrong and a disk is inserted, you'll probably
-	 probably corrupt it.)
+     corrupt it.)
 
   3. Connect the floppy drive to power. Nothing should happen. If anything
      does, disconnect it and check step 1.