PalmBoy v.3.3b

Morphing Palm to GB and back.

News button. News about PalmBoy. It will be updated time after time.

Quick links:

Download Compatibility list Frequently Asked Questions How to convert Known patches Cookies received palm.gb_emu@gmx.de

User poll:

Please spend a moment and vote for your favorite feature to be implemented next or send me other comments:

Here is the priority list of the user poll by the 2001-08-30.

Priority Feature
1. (highest) Compatibility with "Liberty" databases
2. Mapping of keys
3. Emulation of GB link
4. Save state for all games
5. Frameskip
6. Battery state indicator
7. Sound (Oh NO!)
(lowest) Others, too small to count

History:

Somewhen in 1999 my friend Till Harbaum came along and showed me his new toy - a "Palm III" PDA. Chatting began and carelessly I promissed to write a Gameboy emulator if I had such a PDA. He took me at my word and when he got his new "Palm IIIx" I had to start the work.

As an old Atari ST fanatic I decided to port some Pilot tools to this outdated system. The second main cause to develop on the ST was that their CPUs are equivalent. So I'm making STemBoy as core development project. To create PalmBoy I copied the emulator kernel and added the user interface and support functions.

This went until v.3.14159 which was made between december 2000 and february 2001. Then my Atari ST broke down and I got a Linux box. So I decided to change the PalmOS parts from assembler to C and leave STemBoy alone.

PalmBoy is put under the GNU General Public License.


WARNING:

To get the emulation as fast as possible nearly no checks are made and the memory protection had to be switched off. This leads to a potentially very dangerous program - every single byte of your Pilots databases and programs in RAM can be overwritten! Serious and heavy testing revealed no data losses, but it's a very good idea to hotsync your databases before trying the emulator with new games until you gain confidence in the combination of emulator and emulated game.


Download:

palmboy.zip Archive with compiled program and utilities, no games, 212KB.

palmboyg.zip Archive with some converted free games, 42KB.

grayhack.zip Hack for adjusting the levels of gray, 16KB.

freedom.zip Liberty/axxPac to PalmBoy converter, 28KB.

tools.zip Converters (Source/Linux/DOS/Mac/Windows), 116KB. New: graphical front end by Paul Chandler written in Tcl/Tk. You need a Tcl/Tk installation to use it, the primary HTTP site is www.scriptics.com/software/download.html. This program can be used on any system!

palmboy.tgz Archive with source code and compiled program, 264KB.

sokoban.zip Original archive with unconverted game and doc by Emil Brink, 31KB.

I recommend using X-Master for the Hacks.

Readily converted games:

There are more readily converted games made by the german online Palmtop Magazin. They wrote some comments about playability, too.

Sources of pure (to be converted) Gameboy games:

Look for free games at Kojote's homepage, there are lots of free games and demos - not only for GB.

Visit the games and demos collection of Anders Granlund , or search free Gameboy ROMs at EmuUnlim , at the Vintage Gaming Network , or at Classic ROMs. Don't ask me about commercial ROMs!

Call for help / ideas for contributions:

There is a report about problems when PalmBoy runs on a QCP 6035 Kyocera Smartphone. Does anybody else has such experiences, and likes to help fixing the problem? Please drop me a note...

Another fine thing would be an adapter to read GB cartridges right into your handheld. This is some nice project for learning about hardware design and software development of small microcontrollers. Another part is the Palm software for this adapter.

Mail palm.gb_emu@gmx.de if you did or plan to do something!


Screen snapshot:

Just the snapshot.

This snapshot shows PalmBoy running SokoBan by Emil Brink. Because the Pilot has only six hard buttons I had to emulate "SELECT" and "START" on the screen.


Supported accessories:


FAQ

I didn't expect that much feedback. So here are the Frequently Asked Questions and their answers. And NO! I will not compare to other GB emulators because I don't like flame wars... Just read the reviews, other emulators might be better depending on your expectations.

Where do I find those famous games like "Tetris"?!
Oh, I don't know! If you don't own the cartridge you aren't allowed to play the game on emulators as well. Please try some free games, follow the links mentioned above!

Now I've got some GB files - how to get them into PalmBoy?
See below at the notes about conversion. Before any data can be hotsynced into your device, it has to be put into a PDB (Palm DataBase) file.

When I start the converter it just flashes shortly in a window but I can't read the output. How do I use it?
You are surely a Windows-only user. Please open a DOS box where you can enter commands, refer to your documentation. Then read below. You may try the graphical front end, too.

When I try to convert "XXX" the converter complains about the cartridge, why?
There are only some cartridge types supported. Maybe your special game will never be supported, maybe some next version will support it.

PalmBoy is sooo slooowww! What could I do?
Get some overclock utility and try again. If that doesn't help, buy a real Gameboy! Now seriously: I'm working to make it faster, but don't expect more than some percent...

There is this prominent warning about possible data corruption. How much should I take care of it?
That much you like - you're the one who is responsible for the safety of your data. The chance for destroying data exists not only with PalmBoy, it may be a bad set of batteries, too. If something goes wrong in PalmBoy you'll probably notice it. So if everything's fine with your favorite game, you don't have to worry.

What does the "Feature not implemented" error mean?
Exactly that: the game tries to use a feature that I haven't implemented - not yet. I'm hoping that you're less disappointed with such a message than with a game not running.

For some reason I have to press the keys "Start" and "Select" at the same time. How can I do that?
Tap and hold one of the buttons. Then drag over to the other one, the first one will remain pressed. For Zelda users: try starting with A and B so you wont come into the wrong menus.

How can I save the state of a game?
Saving with cartridges which have RAM in their original hardware works, tested with "Zelda, Link's Awakening" and "Final Fantasy II." Some next version will allow to save any game at any state.

With PalmBoy my life is now full of joy! How could I thank you?
Take a pack of your favorite cookies and send it to my address: Bodo Wenzel, Fasanenstrasse 55, 38102 Braunschweig, Germany. At least go and tell your friends about the fun you have with PalmBoy...
Maybe you like to look at this or that link for selecting some nice sort?

I want PalmBoy to run on my "XXX"! How could I make you work on this all your time?
That's simple: spend me a "XXX", address see above.


Status, a brief history of versions:

v.3.3b (current version)

Sorry! The bugfix had to be fixed...

v.3.3

The "bug" in the MBC1 code is corrected, hopefully! There are no more changes from v.3.14159...

v.3.14159 "¶ gotchu!"

This version emulates nearly everything I planned. Additionally it supports cartridges upto 4 Megabytes - anyone with a Pilot with more than 8 Megabytes RAM? The adjustment for the grayscale can be done with Grayhack, a module for X-Master (Freeware), or HackMaster (Shareware), or EVPlug (sorry, no reliable download source known). Till wrote another tool to convert Liberty databases to PalmBoy databases and more: Real Freedom. And yes, you may now hunt those pocket monsters...

Known bug:

v.3.1 United colors of screens

Now every Palm Computing® Platform with OS 3.0 or better should be capable of running PalmBoy. By changing the way to switch into grayscale mode the flicker on some newer devices went away - but the contrast went down a bit as well. Please read below in the notes about this!
You may now use the contrast or brightness dialogues while running a GB game to adjust the screen to your taste. Battery and other alarms should now come through, but I couldn't test this really.

Known bugs, aside from missing functionality:

v.3.0a All vis(it)ors welcome!

The bug which crashed Visors is catched and smashed! For users of OS 3.5 there's another correction: Palm introduced a new event that caused PalmBoy to return to the main menu after switching off and on. This is fixed, too.

v.3.0 "Aller guten Dinge sind drei."

Third big step: the interrupts, many games should run! The last main thing left not yet emulated is the serial interface. I've some ideas for enhancements, too...

Known bugs, aside from missing functionality:

v.2.0 Intermediate version to keep you stick at it

Second big step: the screen was nearly full emulated: background, window and objects. Even the palette registers and scrolling were taken into account. Still missing were the interrupts, therefore only few (free) games were playable.

v.1.0 The appetizer

This version only rendered the background - that's why only some games worked. All unimplemented input/output operations were reported as errors, this is silently ignored in the next version.

Known bugs, aside from missing functionality:


Usage:

OK, this is a PalmOS application as they say in the Programmer's Guides - do you really need instructions? Well, just tap its icon and it will look through the Pilot collecting all present games. Then the list appears and presents you three choices to do: "Run", "Info", or "Delete". There is also a menu with version information and some help of the emulator. Please read this for latest information like the key mapping!

Tapping a game (with "Run" selected) switches on the emulated Gameboy. If one of the few runtime checks fails an error note will be written to your memo database. Please be so kind and send it to me! You "switch off" the Gameboy and return to the games list if you tap the menu button.

If you select "Info" before tapping a game in the list you will see a dialogue with some information about this game. To keep things simple there's not much shown, just the memory sizes. This may help you to decide which game to delete in case of memory shortness.

A tap on a game with "Delete" selected will prompt you for confirmation. If you do so the database containing the game will be removed from memory. Be sure about it - it can't be brought back without hotsyncing it again.

PalmBoy can't run correctly in Flash memory. There's no check about this, so please just don't try it! Converted games generally don't work out of Flash memory, too. They are listed, but can't be started. This will be changed in some future version.

PalmBoy emulates not exactly the real hardware, but most games should work. There might be problems with programming tricks leading to graphic garbage or severe slowdowns. If you get an error message please mail me the exact message and the circumstances with which it occured. If you find a way that reproduces the error you can help me most.

NOTE: If you experience crashes with memory errors, something had corrupted the internal memory organization of your device. I recommend strongly to perform a hard reset erasing all memory! This is the only way to continue with serious work without data losses...

Plans about a new user interface:

Next versions will have some luxury, as state saving, key mapping, beaming, and so on. To get this all as smooth as possible, a well designed user interface is necessary. So I'm currently experimenting with this. If you're interested in giving reasonable feedback, drop me a mail and tell me your ideas, please.


Converting GB files:

Before you're able to run a Gameboy ROM it has to be converted into a Pilot database (PDB) for PalmBoy. This is done with the converter included in the program archive. There are readily compiled executables for Intel-Linux, and DOS/Windows. The source code is included for convenience. After converting you need to hotsync the resulting PDB file into your Pilot.

Note for Mac users: now there's a converter for MacOS in the archive, too. When you launch it, you will be prompted for parameters. Please follow the tips here with your intelligence. I know you're smart, otherwise you weren't a Mac user ;-)

There are readily converted games made by the german online Palmtop Magazin.

Step by step for the non-expert:
  1. If you're using a graphical user interface you basically have to open a command shell. This can be a DOS box in Windows or a terminal in X11. Please refer to the documentation of your operating system how to do this and the following steps.
  2. Create a directory where the converted files should be created. It's more convenient if you copy the converter and the games to be converted into the same directory.
  3. Change into this directory. The command is commonly "cd".
  4. Just for fun enter "gb2pdb". The converter shows a short reminder what parameter it expects.
  5. Let's assume that you want to convert the file "tetris.gb" and you like "tetris.pdb" to be the name of the converted file.
  6. Enter "gb2pdb tetris.gb" and the converter shows some output. In this case there should be no error message and a new file "tetris.pdb" in the directory.
  7. Now you can hotsync the file "tetris.pdb" into your device.

You call the converter with one, two, or three arguments. The first is the name of the game file - they have commonly names ending with ".GB" and are just binary images of the ROM. The optional second argument is the name for the database file; if you leave it out it'll get the name of the GB file but with a PDB extension. This has nothing to do with the name of the database later in your Pilot - that one is taken from the ROM image itself as default, or as the optional third argument. Examples:

"gb2pdb ants.gb"

converts the game file "ants.gb" into the database file "ants.pdb". After hotsyncing to your Pilot you'll see the game name "Free Ants!" because the developers of Ants called it like that.

"gb2pdb /home/gb/ants.gb /home/palm/tosync.pdb PalmBoyAnts"

converts the game file "ants.gb" in the directory "/home/gb" into the database file "tosync.pdb" in the directory "/home/palm". After hotsyncing to your Pilot you'll see the game name "PalmBoyAnts".


Emulation notes:

Well, you need about ten times the power of the emulated machine on an emulating machine! If you compare a real Gameboy and PalmBoy you'll see that there is only a factor of four. The real Gameboy has several support for displaying sprites and playing sounds. The Pilot has a totally different screen memory organisation and no sprite hardware. At last his sound capabilities are poor. This leads to the following:

About the screen:

The LCD (liquid crystal display) of the non-color devices creates the gray shades by toggling fast between black and white. Because the display is so sluggish your eyes see some level of gray. But some displays have problems to keep a steady level if some columns are mostly black, the effect is called "streaking" - see Till's No Streak Hack documentation. So Palm Inc. introduced a slower pixel clock for newer devices which showed flicker switched to gray with PalmBoy prior v.3.1 because this helps only for pure black-n-white!

Starting with v.3.1 PalmBoy uses another way of switching into grayscale mode but then the contrast goes down a bit. You may have to adjust the screen a bit to get a nice appearing of all four levels. To do some experiments with different pixel clocks, just download the hack and try it!

Till did you another favor, and for v.3.14159 and later versions he wrote Grayhack, a module for X-Master or HackMaster. The module is in the archive, but you have to get X-Master or HackMaster yourself. This module is used to adjust the gray levels when your Pilot switches into the 4-level-gray mode as used by PalmBoy.

Compatibility:

Another fine tool is Real Freedom, written by Till, again! You may convert GB games running on Liberty into games running on PalmBoy, access memory cards via the axxPac, and more...


Credits:

The word "Palm" is a registered trademark of Palm, Inc.

The word "Gameboy" is a registered trademark of Nintendo

Starting the developing I had to solve some problems. Some help came from Martin Korth who wrote an excellent emulator for DOS machines: NO$GMB. If you want colors, sound, and support of more games please visit his site http://www.work.de/nocash/!

I have to thank Jeff Frohwein for collecting all sorts of software and documentation for the passioned Gameboy developer and giving it to the community. You'll find it at http://www.devrs.com/gb/...

The fine man who spent all his time for checking the playability of games is HJ.

The nice guy who made the cool morphing icon is Hendrik Lüttke.

Mac users should thank Julian Hsiao for compiling the converter for the MacOS.

The graphical front end for the converter "gb2pdb" was written by Paul Chandler.


Who to blame:

Back to The BodoTill page.

Comments about PalmBoy: palm.gb_emu@gmx.de

Back to my home page.

Other comments and such stuff go to: bodowenzel@web.de


These pages are kindly hosted by suburbia.com.au.