Greasweazle: Difference between revisions

From RetroWikipedia
Jump to navigation Jump to search
← Older edit
VisualWikitext
No edit summary
No edit summary
 
(One intermediate revision by the same user not shown)
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), ongoing revisions
  | type        = Floppy disk flux-level interface
  | cpu          = STM32F103 / STM32F730 / AT32F4xx (varies by model)
  | connectors  = USB-C or Micro-USB; 34-pin floppy ribbon; 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–software system designed for imaging and writing floppy disks at the magnetic flux level. Developed by [[Keir Fraser]], it supports a broad 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:
Its openness, affordability, and compatibility have made it a recognised 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 began in 2018 as a personal project by Keir Fraser, known in retro-computing circles for developing open hardware and firmware for disk imaging. Initial versions used low-cost STM32F103 “Blue Pill” boards before evolving into custom PCBs with improved electrical protection, faster microcontrollers, 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 fostered a community of contributors and users, including preservationists, hobbyists, and computing historians.
 
== Specifications ==
 
=== Hardware Models ===
* '''F1 (Blue Pill)''': STM32F103 MCU; entry-level design.
* '''F7''': STM32F730 MCU; adds 12&nbsp;V support and faster USB transfer rates.
* '''V4 / V4.1''': AT32F4xx MCU; USB-C, input protection, multiple-drive support, jumperless firmware updates.<ref name="gw-wiki" />
 
=== Host Software ===
* Command-line tool <code>gw</code> implemented in Python&nbsp;3.
* Compatible with Windows, macOS, Linux, and Raspberry&nbsp;Pi.
* Released under the Unlicense.<ref name="gw-main" />
 
=== Disk Interface Support ===
* 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 and writes MFM, FM, and GCR encoded formats, subject to drive compatibility.<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]] (April&nbsp;2023) offers structured guidance on using the system.<ref name="yann" />


=== 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 an image 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 are inferred from the 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, including Acorn, Amiga, Atari&nbsp;ST, Commodore, IBM&nbsp;PC, Macintosh, MSX, NEC&nbsp;PC-98, and ZX Spectrum. Each profile specifies geometry, encoding, and a recommended image suffix.
* 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 ===
=== 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&nbsp;0 Not Found''' – Insufficient drive power or incorrect drive selection.
* **Flux Overflow/Underflow** – USB connection interference; try a different port/cable.
* '''Flux Overflow/Underflow''' – USB interference; try another port or cable.
* **Verify Failure** – Possible disk surface damage; clean disk and drive heads.
* '''Verify Failure''' – Possible disk damage; clean the disk and drive 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.) allow capturing 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 via <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** – Conversion of exotic formats to/from .hfe/.scp.
* **HxC Floppy Emulator** – Converts many exotic formats to/from .hfe/.scp.
* **SamDisk** – Meta-image format conversions.
* **SamDisk** – Works with additional meta-image formats (.sad, .sbt, .mbd, etc.).
* **a8rawconv** – Atari 8-bit image conversions.
* **a8rawconv** – Converts Atari 8-bit formats.
* **Fluxengine** – Alternative imaging software.
* **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 with <code>--diskdefs</code>.
<pre>
 
gw read --diskdefs=MyFormats.cfg --format=my.disk.format MyDisk.img
== Importance in Preservation ==
</pre>
Greaseweazle is widely used in retro-computing preservation workflows due to:
* '''Openness''' – Both hardware and software use permissive licences.
* '''Affordability''' – Uses commodity microcontrollers and standard cables.
* '''Compatibility''' – Supports many legacy formats across diverse computing platforms.
* '''Community resources''' – Documentation, tutorials, and forums assist users in data recovery.<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 a widely used usage tutorial.
* Community contributors via GitHub, wiki, and forums.
 
== Appendix: Supported Disk Profiles ==
{{Collapse top|title=Click to show/hide full disk profile table from Yann Serra Tutorial}}
Adapted from the [[Yann Serra Tutorial]], the following table lists selected supported disk profiles with geometry, encoding, and preferred suffixes.
 
{| 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 for 3.5", 5.25", 8", and 3" formats are available in the official tutorial.''
{{Collapse bottom}}
 
== References ==
<references />

Latest revision as of 22:00, 11 August 2025











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




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

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

Background

Greaseweazle began in 2018 as a personal project by Keir Fraser, known in retro-computing circles for developing open hardware and firmware for disk imaging. Initial versions used low-cost STM32F103 “Blue Pill” boards before evolving into custom PCBs with improved electrical protection, faster microcontrollers, and USB-C connectivity.[3] The project has since fostered a community of contributors and users, including preservationists, hobbyists, and computing historians.

Specifications

Hardware Models

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

Host Software

  • Command-line tool gw implemented in Python 3.
  • Compatible with Windows, macOS, Linux, and Raspberry Pi.
  • Released under the Unlicense.[1]

Disk Interface Support

  • 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 and writes MFM, FM, and GCR encoded formats, subject to drive compatibility.[4]

Usage

A widely referenced Yann Serra Tutorial (April 2023) offers structured guidance on using the system.[4]

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 an image back: 

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

Defaults are inferred from the file extension and cable position.

Supported Profiles

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

Troubleshooting

  • No Index – Incorrect drive ID or power issue.
  • Track 0 Not Found – Insufficient drive power or incorrect drive selection.
  • Flux Overflow/Underflow – USB interference; try another port or cable.
  • Verify Failure – Possible disk damage; clean the disk and drive heads.

Advanced Use

  • **Meta-profiles** (ibm.scan, raw.250, etc.) allow capturing 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 via --fake-index on compatible drives.

Third-Party Tools

  • **Disk Utilities** – .scp ↔ .ipf conversion.
  • **HxC Floppy Emulator** – Conversion of exotic formats to/from .hfe/.scp.
  • **SamDisk** – Meta-image format conversions.
  • **a8rawconv** – Atari 8-bit image conversions.
  • **Fluxengine** – Alternative imaging software.

Custom Profiles

Profiles are stored in diskdefs.cfg and can be extended with --diskdefs.

Importance in Preservation

Greaseweazle is widely used in retro-computing preservation workflows due to:

  • Openness – Both hardware and software use permissive licences.
  • Affordability – Uses commodity microcontrollers and standard cables.
  • Compatibility – Supports many legacy formats across diverse computing platforms.
  • Community resources – Documentation, tutorials, and forums assist users in data recovery.[5]

Key People

  • Keir Fraser – Project founder and lead developer.
  • Yann Serra – Contributor of a widely used usage tutorial.
  • Community contributors via GitHub, wiki, and forums.

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

Adapted from the Yann Serra Tutorial, the following table lists selected supported disk profiles with geometry, encoding, and preferred 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 for 3.5", 5.25", 8", and 3" formats are available 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=15432"