Add a bunch of docs and help

README.adoc

@@ -5,9 +5,12 @@ BlueSCSI & ArdSCSino are hardware that reproduces SCSI devices (hard disks) with
 
 `BlueSCSI` created by https://github.com/erichelgeson[erichelgeson] is a fork of `ArdSCSino-stm32` which adds:
 
+* Usability Improvements
 * Mac specific functionality
-* Passive SCSI termination
+* Enable/Disable Passive SCSI termination
 * An alternative power source if not able to be powered by the SCSI bus
+* Documentation
+* Open Hardware (KiCad & Grebers)
 
 `ArdSCSino-stm32` created by https://github.com/ztto/ArdSCSino-stm32[ztto] is the STM32 version of `ArdSCSino`
 
@@ -28,16 +31,18 @@ If your computer is not listed below - it may be compatible but there is no guar
 
 #### Tested by Me
 
-SE, SE/30, Classic, Classic II, Color Classic, LC I/II/III, LC 475, LC 575
+SE, SE/30, Classic, Classic II, Mac II's, Color Classic, LC I/II/III, LC 475, LC 575
+
+#### Partially Compatible
+
+Mac Plus (1.0-c and above) - Only System 7 currenty works.
+
+PowerPC - Some have had luck booting but is not recommended. 
 
 #### Reported by others
 
 https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=663077[IIcx], https://68kmla.org/forums/topic/61045-arduino-scsi-device-work-in-progress/?do=findComment&comment=664446[PowerBook 100 (with custom adapter)]
 
-### Incompatible 
-
-Plus, PowerPC (SCSI-2?)
-
 ## Performance
 
 Tested on a Color Classic with https://macintoshgarden.org/apps/scsi-director-pro-40[SCSI Director Pro 4]
@@ -77,7 +82,7 @@ y - LUN id usually 0.
 
 `HD99_712 foo bar fizz buzz bang.hda` Over 32 chars and invalid SCSI/LUN/Block size
 
-If no image files are found PC13 will pulse on and off. Check the log file for any errors.
+If no image files are found PC13 will pulse on and off. Check the LOG.txt on the root of the SD card for any errors.
 
 ### Premade Images
 
@@ -113,25 +118,29 @@ To enable termination place the two jumpers on the TERM block. Termination shoul
 
 ## Troubleshooting
 
-### Log Files
+### Check Log Files
 
 If your device is not working - check the `LOG.txt` in the root of the SD card.
 
-### Verify you are not using a fake
-
-https://github.com/keirf/Greaseweazle/wiki/STM32-Fakes[How to tell if your STM32 is fake]
-
 ### Performance is slower than expected
 
+Use ExFat instead of FAT32
+
 Try a different SD card. Cheap/old SD cards can affect performance.
 
-## Development
+### Version Specific
+
+<<docs/troubleshooting-1.0-b.adoc,Version 1.0-b>>
+
+<<docs/troubleshooting-1.0-c.adoc,Version 1.0-c>>
+
+## Development (Advanced)
 
 Below is for users who wish to edit or develop on the BluePill - normal users should not need to worry about this.
 
-### Setup PlatformIO
+### Setup PlatformIO IDE
 
-Open the project in https://platformio.org/[PlatformIO] and everything is pre-configured.
+Open the project in https://platformio.org/platformio-ide[PlatformIO IDE] and everything is pre-configured.
 
 ## Flashing
 
@@ -139,7 +148,7 @@ When flashing you have two options:
 
 Flash by setting up the IDE and re-compiling and programming. If you are a developer and plan to contribute this method is what you should use.
 
-You may also flash the `.bin` file directly from STM32CubeProgrammer. If you are not a developer and just wish to get the code to the BluePill, use this (as development environment setup can be a bit tricky!)
+You may also flash the `.bin` file directly from https://www.st.com/en/development-tools/stm32cubeprog.html[STM32CubeProgrammer]. Use this method if you are not a developer and just wish to get the code to the BluePill.
 
 ### Using STLink v2 (prefered)
 
@@ -162,9 +171,11 @@ See the https://docs.platformio.org/en/latest/boards/ststm32/bluepill_f103c8.htm
 
 ### Using USB HID
 
-Note: I have not been able to get this method to work.
+Note: I have not been able to get this method to work. Please contribute to this document if you do.
 
-## Making Gerber files
+## Notes
+
+### Making Gerbers for JLCPCB
 
 https://support.jlcpcb.com/article/44-how-to-export-kicad-pcb-to-gerber-files
 

docs/1.0b-to-1.0c.adoc

@@ -0,0 +1,27 @@
+# BlueSCSI 1.0-b to 1.0-c
+:toc: macro
+
+## Introduction
+
+1.0-c was a small change to fix an issue with machines that provide low or no `TERMPOWER` over the SCSI bus. If you recived a Fully Assembled BlueSCSI after April 1st, 2021 then this was done for you. If you have a kit labled 1.0-b you can make these modifications to become a 1.0-c.
+
+## Steps
+
+### Disconnect `TERMPOWER` from 220 Pull Up Jupmer
+
+Use a cutting tool to cut the small trace between the `TERMPOWR` and 220 Pull Up Jumper pictured below.
+
+Make sure continiutiy from `TERMPOWER` to the diode still flows correctly but is disconnected from the jumper.
+
+image::images/1.0-b-bodge-1.jpg[]
+
+### Connect 5V to 220 Pull Up Jupmer
+
+Now we will provide pull up from the 5v provided by the BluePill.
+
+image::images/1.0-b-bodge-2.png[]
+
+### Complete!
+
+Thats it! 5v to the Pull Up resistors will now work when powered externally.
+

docs/troubleshooting-1.0-b.adoc

@@ -0,0 +1,26 @@
+# Troubleshooting 1.0-b
+:toc: macro
+
+NOTE: If your BlueSCSI was shipped after April 3rd, 2021 please refer to the 1.0-c troubleshooting guide.
+
+## Green LED Flashes on and off
+
+This indicates BlueSCSI could not find any files on the SD card or communicate with the SD card.
+
+Ensure your files are named properly (case sensitive) following the naming convetion in the readme.
+
+If you recived a kit - verify all connections and that the outside of the SD holder is grounded.
+
+## LOG.txt is empty
+
+This indicates the BlueSCSI could communicate with the SD Card but found no files. Check your naming convention.
+
+## Slow performance
+
+Ensure you are using a good SD card. SD card quality can vary widely. 
+
+Format your card as ExFat - users have seen quite a jump in performance.
+
+## (Kit Only) Verify you are not using a fake
+
+https://github.com/keirf/Greaseweazle/wiki/STM32-Fakes[How to tell if your STM32 is fake]

docs/troubleshooting-1.0-c.adoc

@@ -0,0 +1,24 @@
+# Troubleshooting 1.0-c
+:toc: macro
+
+## Review the LOG.txt
+
+There should logs that indicate what BlueSCSI did at startup.
+
+## Green LED Flashes on and off 3x
+
+This indicates BlueSCSI could not find any files on the SD card or communicate with the SD card.
+
+Ensure your files are named properly (case sensitive) following the naming convetion in the readme.
+
+If you recived a kit - verify all connections and that the outside of the SD holder is grounded.
+
+## Slow performance
+
+Ensure you are using a good SD card. SD card quality can vary widely. 
+
+Format your card as ExFat - users have seen quite a jump in performance.
+
+## (Kit Only) Verify you are not using a fake
+
+https://github.com/keirf/Greaseweazle/wiki/STM32-Fakes[How to tell if your STM32 is fake]