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:

Outdated/Expert:

~~I own a WonderWitch cartridge (installation via WonderWitch OS upgrade, no longer recommended)~~
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.
ExtFriend - DIY, based on the RP2040/Raspberry Pi Pico, can be built at home for about $10-$15.
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

WS Backup Tool - backup/restore boot ROM, game data and save data
WSMonitor - rudimentary debugger, allows examining the state of memory and I/O ports before boot ROM lockout. Documentation and source code is available here.

XMODEM file transfer guides

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 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 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 here.

Links

* Source code

Table of Contents