asie's personal wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**BootFriend** is a custom "firmware" solution compatible with the WonderSwan Color and SwanCrystal handheld consoles. It provides a custom splash screen with the following features:

  * Customize the logo through a web editor (including setting a faster boot time),
  * Load .bfb programs to RAM via serial port - this is similar to the GBA's "Multiboot" functionality,
  * Launch Pocket Challenge V2 cartridges on WonderSwan consoles in "pin-strap mode".
  * Use the installer to "unbrick" consoles with corrupted internal EEPROMs.

If you're new to BootFriend, you most likely want to follow the //Installation// section, followed by the //List of available// .bfb //programs//.

====== Installation ======

The installation process depends on what devices you own.

Recommended:

  * [[project:homebrew:wsbootfriend:flashcart|I own a flash cartridge]]
  * [[project:homebrew:wsbootfriend:witch|I own a WonderWitch cartridge (installation via WonderWitch program)]]

Outdated/Expert:

  * <del>[[project:homebrew:wsbootfriend:witchos|I own a WonderWitch cartridge (installation via WonderWitch OS upgrade, no longer recommended)]]</del>
  * [[project:homebrew:wsbootfriend:eeprom|I want to write BootFriend to the console's 93C86 EEPROM chip directly]] (desoldering/clip; experts only)

Note that using BootFriend to unbrick a WonderSwan Color which refuses to load cartridges due to a splash screen error requires using the flashcart or desoldering/clip methods specifically.

====== Loading .bfb programs ======

Loading .bfb programs requires a serial port adapter. Multiple solutions exist:

  * The official RS-232 adapter bundled with the WonderWitch.
  * [[https://github.com/WonderfulToolchain/ws-extfriend|ExtFriend]] - DIY, based on the RP2040/Raspberry Pi Pico, can be built at home for about $10-$15.
  * [[https://www.retroonyx.com/product-page/wonderswan-usb-link-cable|RetroOnyx USB Link Cable]] - $85 as of writing, high quality.

To load a .bfb program, first initiate a 38400 bps XMODEM file transfer on the PC side, then turn on the console with BootFriend installed.

===== List of available programs =====

  * [[project:homebrew:wsbackuptool|WS Backup Tool]] - backup/restore boot ROM, game data and save data
  * [[https://wonderful.asie.pl/ws/bootfriend/wsmonitor.bfb|WSMonitor]] - rudimentary debugger, allows examining the state of memory and I/O ports //before// boot ROM lockout. Documentation and source code is available [[https://bitbucket.org/trap15/wsmonitor|here]].

===== XMODEM file transfer guides =====

  * [[https://twitter.com/peca_port0/status/1631583554621820928|Using Tera Term and ExtFriend on Windows (Japanese)]]
  * [[project:homebrew:wsbootfriend:lrzsz|Using lrzsz on Linux]] 
  * [[project:homebrew:wsbootfriend:minicom|Using minicom on Linux]] 

===== Troubleshooting =====

If done correctly, the PC should notify you that a transfer has started. During this time, the handheld's screen should populate with dots. Each dot corresponds to one block - 128 bytes - of data.

If a letter appears, that signifies an error. Some errors are recoverable and will result in an automatic attempt to retry transfer; others will cause the transfer to stop.

  * A, B, K - corrupt information in transferred block,
  * C - transfer cancelled by sending side,
  * D - received file has invalid format,
  * R - the received .bfb program's requested RAM area is out of permitted range.

====== Other features ======

  * To verify BootFriend's installation status and version, hold Y3 on boot. If BootFriend is installed, the version of the firmware will be displayed on screen.
  * To launch cartridges in Pocket Challenge V2/"pin-strapped" mode, hold Y1 on boot.
  * The BootFriend installer can be repurposed to [[project:homebrew:wsbootfriend:customsplash|write any custom splash/internal EEPROM backup]] to the console.

====== Unbricking ======

There are two types of bricks which can be caused by internal EEPROM corruption:

  * Corrupt splash screen data - manifests by glitched graphics or sound in the splash screen (with the console otherwise functioning correctly) or the console failing to load a game cartridge (but executing the splash screen code). This can be fixed by using the BootFriend installer to ''Disable Custom Splash'', or by installing BootFriend in place of the custom splash.
  * Corrupt TFT panel configuration (SwanCrystal only) - manifests by panel malfunction (part of the screen not being visible, LCD segments not working, etc.) throughout operation (including outside the splash screen). A fix can be attempted by using the BootFriend installer's ''SwanCrystal TFT recovery'' option. **Note that warranty is not provided! There is no guarantee this fix will work correctly.**

====== Creating .bfb programs ======

The [[https://wonderful.asie.pl/wiki/doku.php?id=wswan:index|Wonderful toolchain]] supports building .bfb programs out of the box:

    $ wf-wswantool project new -t bootfriend my_bfb_program/

You can also create .bfb programs with any 80186-compatible assembler. The file format is documented [[https://github.com/WonderfulToolchain/ws-bootfriend/blob/main/README.md|here]].

====== Links ======

* [[https://github.com/WonderfulToolchain/ws-bootfriend|Source code]]