Suggestion for documentation improvement

[hpingel]

Hi David,

After assembling and flashing FluxEngine successfully I wanted to give you some feedback regarding the documentation:

For a start, the documentation you have written is very good and clear!

A few remarks:

• Although optional an FDD cable could be named in your bill of materials.
• FDD cables and their (some of their) existing variants could be illustrated and explained a tiny bit more by using pictures or descriptions or just links to other web pages explaining them. Not all users are older than the hardware they use (I am) so the nature of a floppy cable is not something everybody knows. Although I had my first PC in the 90s I forgot a lot about floppy cables.
• I was missing a section that describes how one can use two or more disk drives on one cable. Either from the cabling point of view or the device numbering when using the CLI tool.
• I was missing a section where the pin assignment between the Cypress pin headers and the backside of the disk drive is illustrated by a picture. This could be useful for users who want to solder their own cable for whatever reasons.
• I found that the additional GND pin connection is absolutely mandatory for my FluxBox to spring into life. If this is technically correct I would recommend that you emphasize that in the text. For me avoiding "different potentials" sounds like "will maybe look into that next week".
• The Assembly Instruction section shows the pins but the Connecting information are on a different page. The connecting page is not reachable via the "next page" link from the building page.

[davidgiven]

Although optional an FDD cable could be named in your bill of materials.

Yup, good point.

FDD cables and their (some of their) existing variants could be illustrated and explained a tiny bit more by using pictures or descriptions or just links to other web pages explaining them. Not all users are older than the hardware they use (I am) so the nature of a floppy cable is not something everybody knows. Although I had my first PC in the 90s I forgot a lot about floppy cables.

Hmm. Yes, I probably should, with pictures of the different connectors. It's not obvious.

I was missing a section that describes how one can use two or more disk drives on one cable. Either from the cabling point of view or the device numbering when using the CLI tool.

Cable-wise, you just plug them in. I didn't feel like this needed explicitly mentioning! The drive numbering is described in the 'Using a

I was missing a section where the pin assignment between the Cypress pin headers and the backside of the disk drive is illustrated by a picture. This could be useful for users who want to solder their own cable for whatever reasons.

The pinout mapping is trivial --- it's literally all the pins in a row, which should be clearly described at the top of 'Assembly Instructions', but a table would make things clearer.

I found that the additional GND pin connection is absolutely mandatory for my FluxBox to spring into life. If this is technically correct I would recommend that you emphasize that in the text. For me avoiding "different potentials" sounds like "will maybe look into that next week".

The sentence you quote literally ends with 'they need to be tied together'! (Also, FluxEngine...)

The Assembly Instruction section shows the pins but the Connecting information are on a different page. The connecting page is not reachable via the "next page" link from the building page.

That's because the pages are listed in alphabetical order, and 'Using' goes last, and 'Building' goes first.

I'm actually not very happy with the layout of the two pages; it'd probably be a good idea to split them into one page on the hardware (including connecting them up) and one page about using the client software.

[hpingel]

Thank you David for taking some of the stuff into consideration. Normally, I would try to offer patches with the issue but my focus was on quickly writing feedback down before forgetting my first-time-experiences with building FluxEngine while reading your docs.

My next comments may be regarding reading CBM1581 DD disks but I'm still learning about everything. I will open a separate issue for that once I have gained some "substantial" insight into the topic. :)

[hpingel]

Linux:

• As there is no udev rule at this point for 1209:6e00 access to fluxengine has to be via superuser/root. Or is a group membership sufficient for a non-root users? (Are you interested in me working on a very basic Linux Debian packaging for Fluxengine?)
• Using my normal user I get the error message "Error: cannot find the FluxEngine (is it plugged in?)"

[tingox]

Here is the udev rule I use (on Debian) - your user needs to be a menber of the 'dialout' group

tingo@kg-bsbox:~$ more /etc/udev/rules.d/98-fluxengine.rules
# FluxEngine - rules to let users in 'dialout' group access the device
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="6e00", GROUP="dialout"

[hpingel]

• When experiencing USB problems on mainboards with AMD chipsets try to plug Fluxengine into an external USB hub (just my personal experience)

• Fluxengine client software runs fine on Raspberry Pi 4 (tested with Raspbian Buster lite 32bit armhf). USB communication is fine. USB speed according to testbulktransport is very good.

[hpingel]

• Are there any reference disk images meant for testing - specifically for Amiga? (What I am currently doing für Amiga and 1581 is: I try to grab a disk image from an arbitrary location on the internet (so that it is hopfully without bad sectors) and I put it on a real DD floppy disk. Then I read it back in to compare the hash values. For Amiga I'm currently using Robert Smith's Arduino Amiga Reader/Writer to put something fresh on a very old disk.)

[davidgiven]

I do have some sample disk images, but I don't want to check them in because they're kinda huge (I've got an Amiga disk image here which is 15MB!). However, there are some decent quality Kryoflux streams on archive.org which work just fine with FluxEngine. I've verified this one:

https://archive.org/details/AmigaAppetizerAmiga.7z

I get a completely clean decode with fluxengine read amiga -s /tmp/Amiga\ Appetizer\[Amiga\]/ -o out.adf --bit-error-threshold=0.3. (Note the trailing slash on the source path.)

(I'm actually planning on changing the way Kryoflux streams work so as to add an explicit conversion step to .flux; handling them natively is annoying. But it's not there yet.)

[davidgiven]

It took a while, but I've finally done this: http://cowlark.com/fluxengine/doc/building.html