====== WS Backup Tool ======

This utility allows you to:

  * Backup the console IPL / boot ROM,
  * Backup and restore cartridge data,
  * Backup, restore and erase cartridge save data (SRAM and EEPROM supported),
  * Reflash self-reflashable cartridges, like the WonderWitch (experimental).

===== Downloads =====

  * **[[https://wonderful.asie.pl/ws/bootfriend/ws-backup-tool-v0.2.1.bfb|WS Backup Tool v0.2.1]]** (11th June 2024)
  * [[https://wonderful.asie.pl/ws/bootfriend/ws-backup-tool-v0.2.0.bfb|WS Backup Tool v0.2.0]] (9th April 2024)
  * [[https://github.com/asiekierka/ws-backup-tool|Source code]]
  * [[https://github.com/asiekierka/ws-backup-tool/blob/main/COPYING|License]] (GPLv3+)

===== Instructions =====

If [[project:homebrew:wsbootfriend#loading_bfb_programs|loading the .bfb program]] was successful, you should be greeted with the following option screen:

{{ :project:homebrew:wsbackuptool:main.png?nolink |}}

You shouldn't need to change the serial port speed from the 38400 bps default, but if you experience connection stability issues, feel free to change it to 9600 bps.

==== Console IPL / boot ROM backup ====

To create a console IPL / boot ROM backup:

  - Initiate an [[project:homebrew:wsbootfriend#xmodem_file_transfer_guides|XMODEM download]] on your PC. 
  - Select the ''Transfer IPL...'' option.
  - Wait for the XMODEM download to finish.

==== Cartridge backup ====

{{ :project:homebrew:wsbackuptool:cart_backup.png?nolink |}}

To create a cartridge backup:

  - Select the ''Cart Backup...'' option.
  - Ensure that the cartridge configuration (ROM, SRAM, EEPROM size; ROM access width, speed) is correct.
    * The tool will try to auto-detect cartridge configuration based on its [[https://ws.nesdev.org/wiki/ROM_header|header]]. Most of the time, you should not need to change any option.
  - Initiate an [[project:homebrew:wsbootfriend#xmodem_file_transfer_guides|XMODEM download]] on your PC. 
  - To back up cartridge data, select ''Backup ROM...''. To backup up save data, select the ''Backup SRAM...'', or ''Backup EEPROM...'' option, depending on cartridge.
    * Most cartridges will only have SRAM or EEPROM, but not both.
  - Wait for the XMODEM download to finish.

==== Cartridge restore ====

{{ :project:homebrew:wsbackuptool:cart_restore.png?nolink |}}

To restore cartridge save data from a backup:

  - Select the ''Cart Restore...'' option.
  - Ensure that the cartridge configuration (SRAM, EEPROM size; ROM access width, speed) is correct.
    * The tool will try to auto-detect cartridge configuration based on its [[https://ws.nesdev.org/wiki/ROM_header|header]]. Most of the time, you should not need to change any option.
  - Select the ''Restore SRAM...'', or ''Restore EEPROM...'' option, depending on cartridge.
    * Most cartridges will only have SRAM or EEPROM, but not both.
  - Initiate an [[project:homebrew:wsbootfriend#xmodem_file_transfer_guides|XMODEM upload]] on your PC. 
  - Wait for the XMODEM upload to finish.

==== Cartridge erase ====

To erase cartridge save data:

  - Select the ''Cart Erase...'' option.
  - Ensure that the cartridge configuration (SRAM, EEPROM size; ROM access width, speed) is correct.
    * The tool will try to auto-detect cartridge configuration based on its [[https://ws.nesdev.org/wiki/ROM_header|header]]. Most of the time, you should not need to change any option.
  - Select the ''Erase SRAM...'', or ''Erase EEPROM...'' option, depending on cartridge.
  - Wait for the erase process to finish.

==== Cartridge flashing ====

To flash cartridge data:

  - Make sure your cartridge is //self-flashable// (supports the 2003 mapper's flashing protocol - port 0xCE), and that its flash chip is supported (see below).
  - Select the ''Cart Flash (Expert)'' option.
  - Set the ''Size'' to the size of the data you want to flash to the cartridge.
    * Only data padded to a multiple of 64 kilobytes is supported.
  - Set the ''Mode'' based on the flash chip used (see below)
  - Select the ''Write Flash...'' option.
  - Initiate an [[project:homebrew:wsbootfriend#xmodem_file_transfer_guides|XMODEM upload]] on your PC. 
  - Wait for the XMODEM upload to finish.
  - Check the status message at the bottom.
    - If it says ''Header bootable'', the cartridge will boot a WSC/SC correctly.
    - If it says ''Header not bootable'', the cartridge will **not** boot a WSC/SC correctly. As the 2003 mapper does not support hot swapping, you **must** either reflash the cartridge without turning off the console, or risk having to use an external device to reflash it.

Supported flash chips:

  * generic flash chips using AAh/55h/A0h ("Regular" mode)
  * Fujitsu MBM29DL400/MBM29DL800 ("WonderWitch" mode)
  * Micron JS28Fxxx29EWx ("WSFM" mode)
  * MX29L3211 ("MX29L3211" mode)

===== Changelog =====

=== v0.2.1 (11th June 2024) ===

  * Added support for flashing MX29L3211 chips.
  * Fixed accelerated writing of MBM29DLx00 and JS28Fxx29EWx chips.
  * Added "Header bootable"/"Header not bootable" warning.

=== v0.2.0 (9th April 2024) ===

  * Improve SRAM chip detection.
  * Allow zeroing SRAM/EEPROM size values.

=== v0.1.9 (20th February 2024) ===

  * Allow pressing ''B'' to move to the end of the menu.
  * Improve flashing code.
  * Update toolchain.