The installation process depends on what devices you own.

Recommended:

• I own a flash cartridge
• I own a WonderWitch cartridge (installation via WonderWitch program)

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

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

• Using Tera Term and ExtFriend on Windows (Japanese)
• Using lrzsz on Linux
• Using minicom on Linux

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.

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

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.

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.

* Source code