Skip to content

Commit 38700c7

Browse files
davidgivendavidgiven
authored
Merge pull request #137 from davidgiven/docs
Update documentation.
2 parents dce0a26 + d504d18 commit 38700c7

File tree

3 files changed

+286
-152
lines changed

3 files changed

+286
-152
lines changed

‎doc/building.md‎

Lines changed: 166 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ This is the physical stuff you'll need.
2525
connector](https://eu.mouser.com/ProductDetail/Amphenol-FCI/86130342114345E1LF?qs=%2Fha2pyFadug%252BpMTyxmFhglPPVKuWXYuFpPNgq%252BsrzhDnXxo8B28k7UCGc7F%2FXjsi)
2626
(or one of the other myriad compatible connectors; there's a billion).
2727

28+
- A floppy drive cable, preferably one with two connectors and a twist.
29+
2830
- A suitable power supply. 3.5" floppy drives use 5V at about an amp
2931
(usually less) --- sadly, too much to power from USB. 5.25" floppy drives
3032
also require 12V. An old but decent quality PC power supply is ideal, as
@@ -48,7 +50,7 @@ All you need to do is attach your chosen connector to the board. You'll need
4850
to make sure that pin 2 on the cable is connected to pin 2.7 on the board,
4951
and pin 34 to pin 1.7 on the board (and of course all the ones in between).
5052
Apart from grounding the board (see below), this is literally all there is to
51-
it.
53+
it. The actual pinout is described in detail below.
5254

5355
The pads are small, but soldering them isn't too bad with a needle-nosed
5456
soldering iron tip.
@@ -173,6 +175,7 @@ pattern. Press and hold the little button near the light for five seconds
173175
until the light stays solidly on. Now you should be able to acquire
174176
the port and proceed normally.
175177

178+
176179
## Building the client
177180

178181
The client software is where the intelligence, such as it is, is. It's pretty
@@ -181,12 +184,12 @@ well, although on Windows it'll need MSYS2 and mingw32. You'll need to
181184
install some support packages.
182185

183186
- For Linux (this is Ubuntu, but this should apply to Debian too):
184-
`ninja-build`, `libusb-1.0-0-dev`, `libsqlite3-dev`.
187+
`ninja-build`, `libusb-1.0-0-dev`, `libsqlite3-dev`.
185188
- For OSX with Homebrew: `ninja`, `libusb`, `pkg-config`, `sqlite`.
186189
- For Windows with MSYS2: `make`, `ninja`, `mingw-w64-i686-libusb`,
187-
`mingw-w64-i686-sqlite3`, `mingw-w64-i686-zlib`, `mingw-w64-i686-gcc`.
190+
`mingw-w64-i686-sqlite3`, `mingw-w64-i686-zlib`, `mingw-w64-i686-gcc`.
188191

189-
These lists are not necessarily exhaustive --- plaese [get in
192+
These lists are not necessarily exhaustive --- please [get in
190193
touch](https://github.com/davidgiven/fluxengine/issues/new) if I've missed
191194
anything.
192195

@@ -197,11 +200,167 @@ dependencies and you should be able to put it anywhere.
197200
If it doesn't build, please [get in
198201
touch](https://github.com/davidgiven/fluxengine/issues/new).
199202

203+
204+
## Connecting it up
205+
206+
You should now have a working board, so it's time to test it.
207+
208+
1. Plug the motherboard end of your floppy disk cable into the FluxEngine.
209+
210+
The **red stripe goes on the right**. The **lower set of
211+
holes connect to the board**. See the pinout below.
212+
213+
If you're using header pins, the upper row of holes in the connector
214+
should overhang the edge of the board. If you're using a floppy drive
215+
motherboard connector, you're golden, of course (unless you have one of
216+
those annoying unkeyed cables, or have accidentally soldered the
217+
connector on in the wrong place --- don't laugh, I've done it.)
218+
219+
2. Plug the drive end of your floppy disk cable into the drive (or drives).
220+
221+
Floppy disk cables typically have [two pairs of floppy disk drive
222+
connectors with a twist between
223+
them](http://www.nullmodem.com/Floppy.htm). (Each pair has one connector
224+
for a 3.5" drive and a different one for a 5.25" drive.) (Some cables
225+
are cheap and just have the 3.5" connectors. Some are _very_ cheap and
226+
have a single 3.5" connector, after the twist.)
227+
228+
FluxEngine uses, sadly, non-standard disk numbering (there are reasons).
229+
Drive 0 is the one nearest the motherboard; that is, before the twist.
230+
Drive 1 is the one at the end of the cable; that is, after the twist.
231+
Drive 0 is the default. If you only have one drive, remember to plug the
232+
drive into the connector _before_ the twist. (Or you can tell the client
233+
to select drive 1 by using `-s :d=1`.)
234+
235+
3. **Important.** Make sure that no disk you care about is in the drive.
236+
(Because if your wiring is wrong and a disk is inserted, you'll corrupt
237+
it.)
238+
239+
4. Connect the floppy drive to power. Nothing should happen. If you've
240+
connected something in backwards, you'll see the drive light up, the motor
241+
start, and if you didn't take the disk out, one track has just been wiped.
242+
If this happens, check your wiring.
243+
244+
5. Strip off the little piece of protective plastic on the USB socket on the
245+
board --- the little socket at the end, not the big programmer plug.
246+
247+
6. Connect the FluxEngine to your PC via USB.
248+
249+
7. Insert a scratch disk and do `fluxengine rpm` from the shell. The motor
250+
should work and it'll tell you that the disk is spinning at about 300
251+
rpm for a 3.5" disk, or 360 rpm for a 5.25" disk. If it doesn't, please
252+
[get in touch](https://github.com/davidgiven/fluxengine/issues/new).
253+
254+
8. Do `fluxengine test bandwidth` from the shell. It'll measure your USB
255+
bandwidth. Ideally you should be getting above 900kB/s in both directions.
256+
FluxEngine needs about 400kB/s for a DD disk and about 850kB/s for a HD
257+
disk, so if you're getting less than this, try a different USB port.
258+
259+
9. Insert a standard PC formatted floppy disk into the drive (probably a good
260+
idea to remove the old disk first). Then do `fluxengine read ibm`. It
261+
should read the disk, emitting copious diagnostics, and spit out an
262+
`ibm.img` file containing the decoded disk image (either 1440kB or 720kB
263+
depending).
264+
265+
10. Profit!
266+
267+
## Technical details
268+
269+
The board pinout and the way it's connected to the floppy bus is described
270+
below.
271+
272+
```ditaa
273+
:-E -s 0.75
274+
+-----+
275+
|||||||
276+
+----+-----+----+
277+
+cAAA +
278+
+ Debug board +
279+
+----+-----+----+
280+
+ GND|cDDD | VDD+
281+
+----+ +----+
282+
INDEX300 ---+ 3.0| | GND+--------------------------+
283+
+----+ +----+ +--+--+ |
284+
INDEX360 ---+ 3.1| | 1.7+------ DISKCHG --+34+33+--+
285+
+----+ +----+ +--+--+
286+
+ 3.2| | 1.6+------- SIDE1 ---+32+31+
287+
+----+ +----+ +--+--+
288+
+ 3.3| | 1.5+------- RDATA ---+30+29+
289+
+----+ +----+ +--+--+
290+
+ 3.4| | 1.4+-------- WPT ----+28+27+
291+
+----+ +----+ +--+--+
292+
+ 3.5| | 1.3+------- TRK00 ---+26+25+
293+
+----+ +----+ +--+--+
294+
+ 3.6| | 1.2+------- WGATE ---+24+23+
295+
+----+ +----+ +--+--+
296+
+ 3.7| | 1.1+------- WDATA ---+22+21+
297+
+----+ +----+ +--+--+
298+
+15.0| | 1.0+------- STEP ----+20+19+
299+
+----+ +----+ +--+--+
300+
+15.1| |12.0+-------- DIR ----+18+17+
301+
+----+ +----+ +--+--+
302+
+15.2| |12.1+------- MOTEB ---+16+15+
303+
+----+ +----+ +--+--+
304+
+15.3| |12.2+------- DRVSA ---+14+13+
305+
+----+ +----+ +--+--+
306+
+15.4| |12.3+------- DRVSB ---+12+11+
307+
+----+ +----+ +--+--+
308+
+15.5| |12.4+------- MOTEA ---+10+9 +
309+
+----+ +----+ +--+--+
310+
+ 0.0| |12.5+------- INDEX ---+8 +7 +
311+
+----+ +----+ +--+--+
312+
+ 0.1| |12.6+-------- n/c ----+6 +5 +
313+
+----+ +----+ +--+--+
314+
+ 0.2| |12.7+- TX --- n/c ----+4 +3 +
315+
+----+ +----+ +--+--+
316+
+ 0.3| | 2.7+------- REDWC ---+2 +1 +
317+
+----+ +----+ +--+--+
318+
+ 0.4| | 2.6+
319+
+----+ +----+ FDD socket
320+
+ 0.5| | 2.5+
321+
+----+ +----+
322+
+ 0.6| | 2.4+ TX: debug UART from board
323+
+----+ +----+
324+
+ 0.7| | 2.3+
325+
+----+ +----+
326+
+ RST| | 2.2+
327+
+----+ +----+
328+
+ GND| | 2.1+
329+
+----+ USB +----+
330+
+ VDD+-----+ 2.0+
331+
+----+-----+----+
332+
PSoC5 board
333+
```
334+
335+
Notes:
336+
337+
- `TX` is the debug UART port. It's on pin 12.7 because the board routes it
338+
to the USB serial port on the programmer, so you can get debug information
339+
from the FluxEngine by just plugging the programming end into a USB port
340+
and using a serial terminal at 115200 baud. If you solder a floppy drive
341+
connector on, then it'll end up connected to pin 4 of the floppy drive bus,
342+
which is usually not connected. It's possible that some floppy drives do,
343+
in fact, use this pin. You may wish to remove pin 4 from the floppy drive
344+
socket before attaching it to the FluxEngine to make sure that this pin is
345+
not connected; however, so far I have not found any drives for which this
346+
is necessary. If you do find one, _please_ [get in
347+
touch](https://github.com/davidgiven/fluxengine/issues/new) so I can
348+
document it.
349+
350+
- The `GND` pin only really needs to be connected to one of the floppy bus
351+
ground pins; pin 33 is the closest. For extra safety, you can bridge all
352+
the odd numbered pins together and ground them all if you like.
353+
354+
- `INDEX300` and `INDEX360` are optional output pins which generate fake
355+
timing pulses for 300 and 360 RPM drives. These are useful for certain
356+
rather exotic things. See the section on flippy disks [in the FAQ](faq.md)
357+
for more details; you can normally ignore these.
358+
200359
## Next steps
201360

202-
The board's now assembled and programmed. Plug it into your drive, strip the
203-
plastic off the little USB connector and plug that into your computer, and
204-
you're ready to start using it.
361+
You should now be ready to go. You'll want to read [the client
362+
documentation](using.md) for information about how to actually do interesting
363+
things.
205364

206365
I _do_ make updates to the firmware whenever necessary, so you may need to
207366
reprogram it at intervals; you may want to take this into account if you

‎doc/disk-brother.md‎

Lines changed: 31 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,12 @@ Apparently about 20% of Brother word processors have alignment issues which
1414
means that the disks can't be read by FluxEngine (because the tracks on the
1515
disk don't line up with the position of the head in a PC drive). The word
1616
processors themselves solved this by microstepping until they found where the
17-
real track is, but normal PC drives aren't capable of doing this.
18-
Particularly with the 120kB disks, you might want to fiddle with the start
19-
track (e.g. `:t=0-79x2`) to get a clean read. Keep an eye on the bad sector
20-
map that's dumped at the end of a read.
17+
real track is, but normal PC drives aren't capable of doing this. Particularly
18+
with the 120kB disks, you might want to fiddle with the start track (e.g.
19+
`:t=0-79x2`) to get a clean read. Keep an eye on the bad sector map that's
20+
dumped at the end of a read. My word processor likes to put logical track 0 on
21+
physical track 3, which means that logical track 77 is on physical track 80;
22+
luckily my PC drive can access track 80.
2123

2224
Using FluxEngine to *write* disks isn't a problem, so the
2325
simplest solution is to use FluxEngine to create a new disk, with the tracks
@@ -30,7 +32,7 @@ If you find one of these misaligned disks then *please* [get in
3032
touch](https://github.com/davidgiven/fluxengine/issues/new); I want to
3133
investigate.
3234

33-
Reading discs
35+
Reading disks
3436
-------------
3537

3638
Just do:
@@ -41,7 +43,7 @@ fluxengine read brother
4143

4244
You should end up with a `brother.img` which is 239616 bytes long.
4345

44-
Writing discs
46+
Writing disks
4547
-------------
4648

4749
Just do:
@@ -53,21 +55,34 @@ fluxengine write brother
5355
...and it'll write a `brother.img` file which is 239616 bytes long to the
5456
disk. (Use `-i` to specify a different input filename.)
5557

58+
Dealing with misaligned disks
59+
-----------------------------
60+
61+
While FluxEngine can't read misaligned disks directly, Brother word processors
62+
_can_. If you have access to a compatible word processor, there's a fairly
63+
simple workaround to allow you to extract the data:
64+
65+
1. Format a disk using FluxEngine (by simply writing a blank filesystem image
66+
to a disk). This will have the correct alignment to work on a PC drive.
67+
68+
2. Use a word processor to copy the misaligned disk to the newly formatted
69+
disk. The machine will happily adjust itself to both sets of alignments.
70+
71+
3. Use FluxEngine to read the data off the correctly aligned disk.
72+
73+
I realise this is rather unsatisfactory, as the Brother hardware is becoming
74+
rarer and they cope rather badly with damaged disks, but this is a limitation
75+
of the hardware of normal PC drives. (It _is_ possible to deliberately misalign
76+
a drive to make it match up with a bad disk, but this is for experts only --- I
77+
wouldn't dare.)
78+
5679
Low level format
5780
----------------
5881

5982
The drive is a single-sided 3.5" drive spinning at not 300 rpm (I don't know
6083
the precise speed yet but FluxEngine doesn't care). The 240kB disks have 78
6184
tracks and the 120kB disks have 39.
6285

63-
The Brother drive alignment is kinda variable; when you put the disk in the
64-
drive it seeks all the way to physical track 0 and then starts searching for
65-
something which looks like data. My machine likes to put logical track 0 on
66-
physical track 3. FluxEngine puts logical track 0 on physical track 0 for
67-
simplicity, which works fine (at least on my machine). If this doesn't work
68-
for you, [get in touch](https://github.com/davidgiven/fluxengine/issues/new);
69-
there are potential workarounds.
70-
7186
Each track has 12 256-byte sectors. The drive ignores the index hole so they're
7287
lined up all anyhow. As FluxEngine can only read from index to index, it
7388
actually reads two complete revolutions and reassembles the sectors from that.
@@ -138,7 +153,8 @@ mcopy -i brother.img ::brother.doc linux.doc
138153
```
139154

140155
The word processor checks the media byte, unfortunately, so you'll need to
141-
change it back to 0x58 before writing an image to disk.
156+
change it back to 0x58 before writing an image to disk. Just run
157+
`brother240tool` on the image again and it will flip it back.
142158

143159
The file format is not WP-1, and currently remains completely unknown,
144160
although it's probably related. If anyone knows anything about this, please

0 commit comments

Comments
 (0)