Greasweazle: Difference between revisions

From RetroWikipedia
Jump to navigation Jump to search
← Older editNewer edit →
VisualWikitext
No edit summary
No edit summary
Line 1: Line 1:
== Usage Overview (Yann Serra Tutorial) ==
<!-- Side-by-side infoboxes -->
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>
<div style="float:right; display:flex; flex-direction:row; gap:10px; align-items:flex-start; margin:0 0 10px 10px;">
  <div>
  {{Infobox hardware
  | name        = Greaseweazle
  | image        = Greaseweazle_V4.1.jpg
  | caption      = Greaseweazle V4.1 unit
  | developer    = Keir Fraser
  | release_date = 2018 (initial), latest hardware revisions ongoing
  | type        = Floppy disk flux-level interface
  | cpu          = STM32F103 / STM32F730 / AT32F4xx (varies by model)
  | connectors  = USB-C or Micro-USB, 34-pin floppy ribbon connector, power connector
  | licensing    = Open hardware & software (Unlicense for host tools)
  | website      = [https://github.com/keirf/greaseweazle GitHub repository]
  }}
  </div>
  <div>
  {{Infobox software
  | name                    = Greaseweazle Host Tools
  | developer              = Keir Fraser
  | latest_release_version  = 1.6
  | latest_release_date    = 28 September 2024
  | operating_system        = Windows, macOS, Linux
  | platform                = Cross-platform (via Python)
  | license                = Unlicense
  | website                = [https://github.com/keirf/greaseweazle GitHub repository]
  }}
  </div>
</div>


=== Hardware Compatibility ===
'''Greaseweazle''' is an open-source hardware and software system for imaging and writing floppy disks at the magnetic flux level. Developed by [[Keir Fraser]], it supports a wide range of disk formats and is widely used in data recovery, retro-computing preservation, and digital archiving.<ref name="gw-main">{{cite web|url=https://github.com/keirf/greaseweazle|title=Greaseweazle Main Repository|publisher=GitHub|access-date=2025-08-11}}</ref> 
Greaseweazle supports standard Shugart and IBM floppy drives:
The project’s openness, affordability, and broad compatibility have made it a key alternative to proprietary solutions such as KryoFlux.<ref name="decromancer">{{cite web|url=https://decromancer.ca/greaseweazle/|title=Greaseweazle Overview|publisher=Decromancer|access-date=2025-08-11}}</ref>
* **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 ===
== Background ==
* **IBM standard**: Two drives per cable with a twist; end = drive A, middle = drive B.
Greaseweazle originated in 2018 as a personal project by Keir Fraser, known in retro-computing circles for his work on open hardware and firmware for disk imaging. Early iterations were based on inexpensive STM32F103 "Blue Pill" boards before evolving into dedicated PCBs with enhanced electrical protection, higher performance MCUs, and USB-C connectivity.<ref name="gw-wiki">{{cite web|url=https://github.com/keirf/greaseweazle/wiki|title=Greaseweazle Documentation|publisher=GitHub Wiki|access-date=2025-08-11}}</ref> 
* **Shugart standard**: Flat cable; drive ID set via jumpers (DS0/DS1/DS2). Supports up to three drives.
The project has since built a community of contributors and users, including preservationists, hobbyists, and software historians.
 
== Specifications ==
 
=== Hardware Models ===
* '''F1 (Blue Pill)''': STM32F103 MCU; low-cost entry model.
* '''F7''': STM32F730 MCU; adds 12 V support and faster USB transfer.
* '''V4 / V4.1''': AT32F4xx MCU; USB-C, input protection, multiple drive support, jumperless firmware updates.<ref name="gw-wiki" />
 
=== Host Software ===
* Command-line utility <code>gw</code> written in Python 3.
* Works on Windows, macOS, Linux, and Raspberry Pi.
* Distributed under the Unlicense.<ref name="gw-main" />
 
=== Disk Interface Support ===
* Works with standard Shugart- and IBM-interface drives:
** 3.5-inch and 5.25-inch (34-pin)
** 3-inch Amstrad (26-pin, via adapter)
** 8-inch (50-pin, via adapter)
* Reads/writes MFM, FM, and GCR encoded formats (with drive compatibility caveats).<ref name="yann">{{cite web|url=https://github.com/keirf/greaseweazle/wiki/Yann-Serra-Tutorial|title=Yann Serra Tutorial|publisher=GitHub Wiki|access-date=2025-08-11}}</ref>
 
== Usage ==
A widely referenced [[Yann Serra Tutorial]] (contributed April 2023) provides a structured guide to operation.<ref name="yann" /> Key points include:


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


=== Basic Commands ===
=== Basic Commands ===
Read disk to image:
Reading an AmigaDOS disk:
<pre>
<pre>
gw read --format=amiga.amigados MyAmigaDisk.adf --drive=A
gw read --format=amiga.amigados MyDisk.adf --drive=A
</pre>
</pre>
Write image to disk:
Writing back:
<pre>
<pre>
gw write --format=amiga.amigados MyAmigaDisk.adf --drive=A
gw write --format=amiga.amigados MyDisk.adf --drive=A
</pre>
</pre>
Omitting <code>--format</code> and <code>--drive</code> uses defaults based on file extension and drive A.
Defaults can be inferred from file extension and cable position.


=== Supported Disk Profiles ===
=== Supported 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:
The <code>gw</code> tool includes predefined profiles for dozens of systems: Acorn, Amiga, Atari ST, Commodore, IBM PC, Macintosh, MSX, NEC PC-98, ZX Spectrum, and more.
* Physical geometry (cylinders, heads, RPM)
Each profile specifies geometry, encoding, and recommended image suffix.
* 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 ===
=== Troubleshooting ===
* **No Index** – Incorrect drive ID, no power, or cable inserted incorrectly.
* **No Index** – Incorrect drive ID or power issue.
* **Track 0 Not Found** – Insufficient drive power or incorrect drive selection.
* **Track 0 Not Found** – Insufficient drive power or wrong drive selection.
* **Flux Overflow/Underflow** – USB connection interference; try a different port/cable.
* **Flux Overflow/Underflow** – USB interference; change port or cable.
* **Verify Failure** – Possible disk surface damage; clean disk and drive heads.
* **Verify Failure** – Disk surface damage; clean disk and heads.


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


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


=== Custom Profiles ===
=== 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:
Profiles are stored in <code>diskdefs.cfg</code> and can be extended by the user via <code>--diskdefs</code>.
<pre>
 
gw read --diskdefs=MyFormats.cfg --format=my.disk.format MyDisk.img
== Importance in Preservation ==
</pre>
Greaseweazle has become a staple in retro-computing preservation workflows due to:
* **Openness** – Both hardware and software are under permissive licenses.
* **Low cost** – Uses commodity microcontrollers and standard cables.
* **Broad compatibility** – Supports dozens of legacy formats across multiple computing platforms.
* **Community knowledge base** – Extensive guides, including the Yann Serra tutorial, help non-experts recover and preserve data.<ref name="hn">{{cite web|url=https://news.ycombinator.com/item?id=39961245|title=Discussion on Greaseweazle and retrocomputing|publisher=Hacker News|access-date=2025-08-11}}</ref>
 
== Key People ==
* **Keir Fraser** – Project founder and lead developer.
* **Yann Serra** – Contributor of the widely cited usage tutorial.
* Community contributors via GitHub issues, pull requests, and Wiki edits.
 
== Appendix: Supported Disk Profiles ==
{{Collapse top|title=Click to show/hide full disk profile table from Yann Serra Tutorial}}
The following is adapted from the [[Yann Serra Tutorial]] and lists supported disk profiles, geometry, encoding, and preferred image suffixes.
 
<!-- Example condensed table format; full list would follow this pattern -->
{| class="wikitable sortable"
! System !! Profile !! Sides !! Cyls !! RPM !! kbit/s !! Sect/trk !! Bytes/sect !! Encoding !! Size (KB) !! Suffix
|-
| Acorn BBC || acorn.adfs.320 || 1 || 80 || 300 || 250 || 16 || 256 || MFM || 320 || .adm
|-
| Amiga || amiga.amigados || 2 || 80 || 300 || 250 || 11 || 512 || AMFM || 880 || .adf
|-
| Atari ST || atarist.720 || 2 || 80 || 300 || 250 || 9 || 512 || MFM || 720 || .st, .msa
|-
| IBM PC || ibm.1440 || 2 || 80 || 300 || 500 || 18 || 512 || MFM-HD || 1440 || .img, .dsk
|-
| Macintosh 68K || mac.800 || 2 || 80 || VAR || 375 || 12-8 || 512 || GCR || 800 || .dsk
|-
| ZX Spectrum || zx.trdos.640 || 2 || 80 || 300 || 250 || 16 || 256 || MFM || 640 || .mgt, .dsk
|-
| NEC PC-98 || pc98.2hs || 2 || 81 || 300 || 500 || 9 || 1024 || MFM-HD || 1458 || .hdm, .xdf
|}
''(Full extended tables, including 3.5", 5.25", 8", and 3" formats, are documented in the official tutorial.)''
{{Collapse bottom}}
 
== References ==
<references />

Revision as of 21:59, 11 August 2025











Greaseweazle
File:Greaseweazle V4.1.jpg
Greaseweazle V4.1 unit
DeveloperKeir Fraser
Release date2018 (initial), latest hardware revisions ongoing
TypeFloppy disk flux-level interface
CPUSTM32F103 / STM32F730 / AT32F4xx (varies by model)
ConnectorsUSB-C or Micro-USB, 34-pin floppy ribbon connector, power connector
LicensingOpen hardware & software (Unlicense for host tools)
WebsiteGitHub repository




{{#if:Windows, macOS, Linux|<td styl_

Greaseweazle is an open-source hardware and software system for imaging and writing floppy disks at the magnetic flux level. Developed by Keir Fraser, it supports a wide range of disk formats and is widely used in data recovery, retro-computing preservation, and digital archiving.[1] The project’s openness, affordability, and broad compatibility have made it a key alternative to proprietary solutions such as KryoFlux.[2]

Background

Greaseweazle originated in 2018 as a personal project by Keir Fraser, known in retro-computing circles for his work on open hardware and firmware for disk imaging. Early iterations were based on inexpensive STM32F103 "Blue Pill" boards before evolving into dedicated PCBs with enhanced electrical protection, higher performance MCUs, and USB-C connectivity.[3] The project has since built a community of contributors and users, including preservationists, hobbyists, and software historians.

Specifications

Hardware Models

  • F1 (Blue Pill): STM32F103 MCU; low-cost entry model.
  • F7: STM32F730 MCU; adds 12 V support and faster USB transfer.
  • V4 / V4.1: AT32F4xx MCU; USB-C, input protection, multiple drive support, jumperless firmware updates.[3]

Host Software

  • Command-line utility gw written in Python 3.
  • Works on Windows, macOS, Linux, and Raspberry Pi.
  • Distributed under the Unlicense.[1]

Disk Interface Support

  • Works with standard Shugart- and IBM-interface drives:
    • 3.5-inch and 5.25-inch (34-pin)
    • 3-inch Amstrad (26-pin, via adapter)
    • 8-inch (50-pin, via adapter)
  • Reads/writes MFM, FM, and GCR encoded formats (with drive compatibility caveats).[4]

Usage

A widely referenced Yann Serra Tutorial (contributed April 2023) provides a structured guide to operation.[4] Key points include:

Access Levels

  1. **Sector-level**: User-visible data in block-mode images (.img, .adf, .st, etc.).
  2. **Track-level**: Preserves formatting, sector layout, and copy-protection metadata (.imd, .edsk).
  3. **Flux-level**: Captures raw magnetic transitions (.scp, .hfe) for exact reproduction.

Basic Commands

Reading an AmigaDOS disk: 

gw read --format=amiga.amigados MyDisk.adf --drive=A

Writing back: 

gw write --format=amiga.amigados MyDisk.adf --drive=A

Defaults can be inferred from file extension and cable position.

Supported Profiles

The gw tool includes predefined profiles for dozens of systems: Acorn, Amiga, Atari ST, Commodore, IBM PC, Macintosh, MSX, NEC PC-98, ZX Spectrum, and more. Each profile specifies geometry, encoding, and recommended image suffix.

Troubleshooting

  • **No Index** – Incorrect drive ID or power issue.
  • **Track 0 Not Found** – Insufficient drive power or wrong drive selection.
  • **Flux Overflow/Underflow** – USB interference; change port or cable.
  • **Verify Failure** – Disk surface damage; clean disk and heads.

Advanced Use

  • **Meta-profiles** (ibm.scan, raw.250, etc.) capture arbitrary sector geometries.
  • Reading 48-TPI disks with 96-TPI drives via --tracks=…:step=2.
  • **Flux-level** archiving with --adjust-speed and --raw for copy-protected media.
  • Support for certain “flippy” 5.25-inch disks using --fake-index on compatible drives.

Third-Party Tools

  • **Disk Utilities** – .scp ↔ .ipf conversion.
  • **HxC Floppy Emulator** – Exotic format conversions to/from .hfe/.scp.
  • **SamDisk** – Additional meta-image conversions.
  • **a8rawconv** – Atari 8-bit conversions.
  • **Fluxengine** – Alternative imaging command.

Custom Profiles

Profiles are stored in diskdefs.cfg and can be extended by the user via --diskdefs.

Importance in Preservation

Greaseweazle has become a staple in retro-computing preservation workflows due to:

  • **Openness** – Both hardware and software are under permissive licenses.
  • **Low cost** – Uses commodity microcontrollers and standard cables.
  • **Broad compatibility** – Supports dozens of legacy formats across multiple computing platforms.
  • **Community knowledge base** – Extensive guides, including the Yann Serra tutorial, help non-experts recover and preserve data.[5]

Key People

  • **Keir Fraser** – Project founder and lead developer.
  • **Yann Serra** – Contributor of the widely cited usage tutorial.
  • Community contributors via GitHub issues, pull requests, and Wiki edits.

Appendix: Supported Disk Profiles

Greaseweazle Host Tools
DeveloperKeir Fraser
Latest release 
   1.6(28 September 2024)
Operating system
Click to show/hide full disk profile table from Yann Serra Tutorial

The following is adapted from the Yann Serra Tutorial and lists supported disk profiles, geometry, encoding, and preferred image suffixes.

System Profile Sides Cyls RPM kbit/s Sect/trk Bytes/sect Encoding Size (KB) Suffix
Acorn BBC acorn.adfs.320 1 80 300 250 16 256 MFM 320 .adm
Amiga amiga.amigados 2 80 300 250 11 512 AMFM 880 .adf
Atari ST atarist.720 2 80 300 250 9 512 MFM 720 .st, .msa
IBM PC ibm.1440 2 80 300 500 18 512 MFM-HD 1440 .img, .dsk
Macintosh 68K mac.800 2 80 VAR 375 12-8 512 GCR 800 .dsk
ZX Spectrum zx.trdos.640 2 80 300 250 16 256 MFM 640 .mgt, .dsk
NEC PC-98 pc98.2hs 2 81 300 500 9 1024 MFM-HD 1458 .hdm, .xdf

(Full extended tables, including 3.5", 5.25", 8", and 3" formats, are documented in the official tutorial.)

References

  1. ↑ 1.0 1.1 "Greaseweazle Main Repository". GitHub. Retrieved 2025-08-11.
  2. ↑ "Greaseweazle Overview". Decromancer. Retrieved 2025-08-11.
  3. ↑ 3.0 3.1 "Greaseweazle Documentation". GitHub Wiki. Retrieved 2025-08-11.
  4. ↑ 4.0 4.1 "Yann Serra Tutorial". GitHub Wiki. Retrieved 2025-08-11.
  5. ↑ "Discussion on Greaseweazle and retrocomputing". Hacker News. Retrieved 2025-08-11.
Retrieved from "https://retrowikipedia.com/index.php?title=Greasweazle&oldid=15431"