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:
Backup games and saves, as well as dump the IPL (boot ROM) with WS Backup Tool,
Verify hardware functionality as an emulator/homebrew developer with WSMonitor.
Verify BootFriend installation status and version - hold Y3 on boot.
In addition, the installation software can be used to fix certain console faults caused by internal EEPROM corruption:
Freezes/hangs on startup caused by invalid splash screen data,
Sidebar icons/"segments" not displaying on SwanCrystal units (missing TFT configuration data).
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:
WonderSwan Color or SwanCrystal console (not compatible with "mono" WonderSwans),
Alternatively, one may use ares v132 (or a recent nightly release) to test the installation procedure.
Installation device (required only for installation). Some options include:
Cartridge capable of running WonderSwan ROM images,
Official WonderWitch or WonderWitch Player cartridge (experimental, untested),
Other options may be available in the future.
Serial port adapter (optional, but highly recommended - it's one of the firmware's main features). Some options include:
ExtFriend for WS - recommended cheap DIY solution, requires Pi Pico + some DIY work,
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:
On Linux, you may use minicom in a terminal prompt to initiate an XMODEM file transfer:
Run "minicom -D [device]"; for ExtFriend, the device will typically be /dev/ttyACM0.
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".
Press Ctrl+A, then S, then select "xmodem".
Note that BootFriend uses a 38400 bps serial port speed by default.
Installation Guide (Cartridge):
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.
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.
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.
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.)
Transfer bootfriend-inst.fx to WonderWitch.
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):
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.
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.)
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:
Initiate an XMODEM file transfer on the PC side. This has to be done first.
Turn on the BootFriend-enabled WonderSwan console.
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!).
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.
