View source for Greasweazle

== Usage Overview (Yann Serra Tutorial) ==
The following condensed guide is based on a tutorial by Yann Serra, contributed to the Greaseweazle project documentation in April 2023.<ref name="yann">{{cite web|url=https://github.com/keirf/greaseweazle/wiki/Yann-Serra-Tutorial|title=Yann Serra Tutorial|publisher=GitHub|date=2023-04-13|access-date=2025-08-11}}</ref>

=== Hardware Compatibility ===
Greaseweazle supports standard Shugart and IBM floppy drives:
* **3.5-inch** and **5.25-inch** drives with a 34-pin connector
* **3-inch Amstrad** drives (26-pin, via adapter)
* **8-inch** drives (50-pin, via adapter)  
Commodore (non-Amiga) and Apple Macintosh drives are not directly supported, but their media can often be read/written using a compatible standard-interface drive.  
Certain GCR formats (Apple II/Mac, Commodore 64) may require trial-and-error to find a drive with correct bitcell timing.

=== Drive Cabling ===
* **IBM standard**: Two drives per cable with a twist; end = drive A, middle = drive B.
* **Shugart standard**: Flat cable; drive ID set via jumpers (DS0/DS1/DS2). Supports up to three drives.

=== Access Levels ===
1. **Sector-level** – Block-mode images (.img, .adf, .st) containing user-accessible data.
2. **Track-level** – Includes format metadata (.imd, .edsk) preserving sector layout, gaps, and copy-protection markers.
3. **Flux-level** – Captures raw magnetic transition data (.scp, .hfe) for exact reproduction.

=== Basic Commands ===
Read disk to image:
<pre>
gw read --format=amiga.amigados MyAmigaDisk.adf --drive=A
</pre>
Write image to disk:
<pre>
gw write --format=amiga.amigados MyAmigaDisk.adf --drive=A
</pre>
Omitting <code>--format</code> and <code>--drive</code> uses defaults based on file extension and drive A.

=== Supported Disk Profiles ===
Greaseweazle includes predefined format profiles covering dozens of platforms (Acorn, Amiga, Atari ST, Commodore, IBM PC, Macintosh, MSX, NEC PC-98, ZX Spectrum, and others). Each profile defines:
* Physical geometry (cylinders, heads, RPM)
* Encoding type (FM, MFM, GCR)
* Sector size and count
Preferred image suffixes depend on the format (e.g., <code>.adf</code> for AmigaDOS, <code>.st</code> for Atari ST, <code>.img</code> for IBM PC).  
For the full list, see the [https://github.com/keirf/greaseweazle/wiki/Yann-Serra-Tutorial tutorial source].

=== Troubleshooting Common Errors ===
* **No Index** – Incorrect drive ID, no power, or cable inserted incorrectly.
* **Track 0 Not Found** – Insufficient drive power or incorrect drive selection.
* **Flux Overflow/Underflow** – USB connection interference; try a different port/cable.
* **Verify Failure** – Possible disk surface damage; clean disk and drive heads.

=== Advanced Use Cases ===
* **Meta-profiles** (<code>ibm.scan</code>, <code>raw.125</code>, etc.) and **meta-images** (.edsk, .imd) for arbitrary sector geometries.
* Reading 48-TPI disks with 96-TPI drives using <code>--tracks=…:step=2</code>.
* Flux-level archiving for copy-protected or unknown formats with <code>--adjust-speed</code> and <code>--raw</code>.
* Handling “flippy” 5.25-inch disks with drives supporting <code>--fake-index</code>.

=== External Tools ===
Greaseweazle flux/image files can be processed with third-party utilities such as:
* **Disk Utilities** – Converts between .scp/.dfi and .ipf.
* **HxC Floppy Emulator** – Converts many exotic formats to/from .hfe/.scp.
* **SamDisk** – Works with additional meta-image formats (.sad, .sbt, .mbd, etc.).
* **a8rawconv** – Converts Atari 8-bit formats.
* **Fluxengine** – Alternative imaging tool supporting additional formats.

=== Custom Profiles ===
Format profiles are stored in <code>diskdefs.cfg</code>. Users can define new profiles in a custom configuration file and load them with:
<pre>
gw read --diskdefs=MyFormats.cfg --format=my.disk.format MyDisk.img
</pre>