BootFriend for WS

So you're a Friend who's good at booting homebrew? Sugoi~!

BootFriend is a custom "firmware" solution, in the form of a modified splash screen, compatible with the WonderSwan Color and SwanCrystal handheld consoles. It provides the following features:

In addition, the installation software can be used to fix certain console faults caused by internal EEPROM corruption:

The installation software can also be used to install other, non-BootFriend boot splashes.

If you're looking to back up the IPL of the "mono" WonderSwan, feel free to try up-n-atom's dumpipl.

Installation

The installation software has been tested on multiple consoles and effort has been put in to validate its stability. However, as I am not in a position to guarantee its operation, I am obliged to inform you that:

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Requirements:

Configuration:

Splash

Upload image (.PNG):

  • The image should be small. (<=64x64 recommended for starters)
  • The width and height should be multiples of 8.
  • The image may not have more than 4 colors in any consecutive 8x8 tile.
    • You can try tiled-palette-quant to do this automatically. Set palettes: 7, colors per palette: 4, bits per channel: 4, color index zero: unique.

Select file:

Preview

Note that none of the above configuration options need to be changed - if you don't want to customize your splash screen, you can just download the installer as-is by clicking below.

I have read and agree to the warranty disclaimer above.

Installation:

  • Select one of the options above, then follow the relevant installation guide below.
  • Different installation methods have separate guides. Please scroll down until the correct one is found.
  • The guide will often refer to "XMODEM file transfer". This is a guide on how to perform an XMODEM file transfer:
    • On Windows, you may use Tera Term to initiate an XMODEM file transfer:
      1. Setup -> Serial Port... -> select Port, Speed; set Data: 8 bit, Parity: none, Stop bits: 1 bit, Flow control: none.
      2. File -> Transfer -> XMODEM -> Send...
    • On Linux, you may use minicom in a terminal prompt to initiate an XMODEM file transfer:
      1. Run "minicom -D [device]"; for ExtFriend, the device will typically be /dev/ttyACM0.
      2. Press Ctrl+A, then O, then select "Serial port setup":
        • Set "Bps/Par/Bits" to the correct speed, then press Q to set 8N1.
        • Set Hardware and Software Flow Control to "No".
      3. Press Ctrl+A, then S, then select "xmodem".
    • Note that BootFriend uses a 38400 bps serial port speed by default.

Installation Guide (Cartridge):

  1. Flash bootfriend-inst.wsc to the cartridge.
    • If your cartridge of choice uses a multiple choice menu, it is advisable to flash the installation program in place of said menu.
  2. Launch the cartridge. Examine the information on the status bar (top row).
    • If the status bar says EEP locked, BootFriend cannot be installed. Make sure you've flashed the installer correctly.
    • The Test BootFriend option allows you to test the program serial port loader without installing the splash screen. This is useful for ensuring that your serial port adapter will work with the firmware.
      • This does not display the configured custom splash! This is only for testing the serial port loader.
    • The Disable/Enable custom splash option allows you to disable a custom splash (to fix console freezes/hangs related to them) or enable one.
      • Note that, on SwanCrystal, there is a factory-installed custom splash screen on the IEEPROM, which is slightly different from the built-in one. The built-in splash screen is identical to the WonderSwan Color.
      • If BootFriend is installed, the option is named Disable/Enable BootFriend instead - as BootFriend is a modified custom splash, disabling the custom splash also disables BootFriend's functionality.
    • The SwanCrystal TFT recovery option allows you to fix missing TFT configuration data, as explained above.
  3. Select Install BootFriend and follow the instructions.
    • The right-hand side of the status bar should now say BF v.?? - this indicates a BootFriend installation.
  4. Once done, turn off the console. You can hold Y3 on boot to check for a successful BootFriend installation.
    • Note that the bootfriend-inst.wsc cartridge disables custom splashes on boot! You'll need to flash different data, or use a different cartridge, to verify BootFriend's operation.
    • The WonderSwan Color and SwanCrystal will not turn on if no valid cartridge is present. This is a normal feature of the console.

Installation Guide (WonderWitch .fx program):

(This method is experimental. If you run into problems, please use the "OS Upgrade" method.)

  1. Transfer bootfriend-inst.fx to WonderWitch.
  2. Follow instruction steps 2-4 from the "Cartridge" installation guide.
    • Using the WonderWitch method, the original IEEPROM contents are not saved to SRAM! Please use the XMODEM backup method instead.
    • Using the WonderWitch method, it is not always possible to "unbrick" a WonderSwan with damaged IEEPROM contents. This is a limitation of the method and cannot be fixed. (Note that the "SwanCrystal TFT recovery" function should work correctly.)

Installation Guide (WonderWitch OS Upgrade):

  1. The WonderWitch installer is currently only provided as an "OS Upgrade". Therefore, the installation process is a little different from a typical WonderWitch program:
    • Start WonderWitch in Freya Monitor mode - hold B while the console is turning on.
    • Configure the serial baud rate in the Setup menu.
    • Select Send System and download a backup of the currently installed OS.
      • For downloading and uploading the OS, one can use an XMODEM transfer tool (as described in "Usage"), or TransMagic's built-in FreyaOS update functionality.
      • If you forget to do this, you can find a copy of FreyaOS 1.2.0 on Qute's website (=> ダウンロード).
    • Select Recv System and upload the bootfriend-inst-wwsystem.bin file.
  2. Follow instruction steps 2-4 from the "Cartridge" installation guide.
    • Using the WonderWitch method, the original IEEPROM contents are not saved to SRAM! Please use the XMODEM backup method instead.
    • Using the WonderWitch method, it is not always possible to "unbrick" a WonderSwan with damaged IEEPROM contents. This is a limitation of the method and cannot be fixed. (Note that the "SwanCrystal TFT recovery" function should work correctly.)
  3. Launch Freya Monitor again, and use Recv System with a copy of FreyaOS to restore the original operating system.

Changelog

BootFriend v02 (installer v04) (2023-02-21)

  • [BootFriend] Fix name color display regression.
  • [Installer] Added support for installation via FreyaOS-compatible WonderWitch program (.fx).

BootFriend v01 (installer v03) (2023-02-18)

  • [BootFriend] Minor bugfixes and size optimizations.
  • [Installer] Added support for IEEPROM custom splash backup/restore via XMODEM.
  • [Installer] Added support for IEEPROM custom splash restore via SRAM ("Cartridge" method only).

BootFriend v00 (installer v02) (2023-02-17)

  • [Installer] Corrected issue in "SwanCrystal TFT recovery" option handling.

BootFriend v00 (installer v01) (2023-02-16)

  • First release.

Usage

  • To run a .bfb program (see the "Additional software" section below), perform the following steps:
    1. Initiate an XMODEM file transfer on the PC side. This has to be done first.
    2. Turn on the BootFriend-enabled WonderSwan console.
    3. If done correctly, the PC should notify that a transfer has started, while the WonderSwan's screen should populate with dots.
      • Each dot corresponds to one block - 128 bytes - of data.
      • Letters in this process correspond to errors, some of which are recoverable and will result in an automatic attempt to retry transfer:
        • A, B, K - corrupt information in transferred block,
        • C - transfer cancelled by sending side,
        • D - received file has invalid format,
        • R - the received file's requested RAM area is out of permitted range.

Additional software ♪

WS Backup Tool

This utility allows you to use XMODEM transfers via the EXT port to:

  • Dump the WonderSwan IPL (boot ROM),
  • Backup game data and save files,
  • Restore game save files,
  • Erase game save files,
  • Reflash WonderWitch and other reflashable cartridges (experimental!).

WSMonitor

Created by trap15, this utility acts as a rudimentary hardware state monitor for the WonderSwan, allowing examining the state of memory and I/O ports. Notably, using BootFriend, one can run WSMonitor before IPL/boot ROM lockout.

Credits ♥

BootFriend is a project by myself, that is asie.

Special thanks to:

  • lidnariq, for providing the inspiration necessary to pursue this project,
  • Godzil, for figuring out the splash screen format,
  • Dox, trap15, FluBBa, Furrtek, GuyPerfect, Near, and many others who helped figure out and document the WonderSwan's mysteries,

... and viewers like you!