Emulating the Mobile Adapter GB
Posted by: Háčky
Date: 2016-06-14 00:46:06
(This post is necessarily going to be filled with technical minutiae, so if thats not your thing, you may want to skip the entire first half of it and skim through the rest. If that is your thing, then you dont need me to tell you what to do.)
Ive documented most of the protocol that Game Boy Color games use to communicate with the Mobile Adapter GB, and written a proof-of-concept implementation that links with BGB and enables Mobile Trainers initial setup and Pokémon Crystals Trade Corner to work. Because Ive been working with BGB, Ive not yet tested anything with Game Boy Advance games, but I would expect that the protocol is the same and it should be possible to create an implementation compatible with VBA-M in the future.
As all of this information has been determined solely from analysis of Mobile Trainer and Pokémon Crystal, I cant say whether this documentation represents how the Mobile Adapter GB hardware actually behaves, but it at least represents how these games seem to expect it to behave.
[size=12pt]Protocol description[/size]
The Game Boy Color communicates with the Mobile Adapter GB at a clock speed of 512 KiHz (bits 0 and 1 of the SC register are set and the GBC is in double-speed mode). The protocol closely resembles the one used by the Game Boy Printer, but it has been modified for two-way communication.
A communication session consists of a series of commands sent by the Game Boy Color, each followed by a response from the Mobile Adapter GB, generally using the same command ID as the command it is responding to. A session begins with the Game Boy Color sending command $10 with the body [tt]"NINTENDO"[/tt], and the Mobile Adapter GB replying with the same. The session ends when the Game Boy Color sends command $11, and the Mobile Adapter GB responds in kind.
When either device sends a packet, it begins by sending the preamble bytes $99 $66, followed by the packet data. After the packet is finished, both the sender and receiver transmit a byte containing their device ID xor $80. (The Game Boy Colors device ID is $00. Any device ID from $08 to $0F is recognized as a Mobile Adapter GB: $08 is the PDC model, $09 is the CDMA model, $0A is the unreleased DoCoMo PHS model, and $0B is the DDI PHS model. $0C0F were presumably reserved for future use.)
After the device ID, the sender sends $00 while the receiver confirms successful receipt of the packet by sending the packets command ID xor $80. If the packet checksum fails, the recipient sends $F1 instead, which instructs the other device to resend the packet. ($EE, $F0, and $F2 also appear to be error codes, but I dont know how theyre used.)
The packet itself consists of a four-byte header, followed by the body, followed by a two-byte big-endian checksum, which is the sum of each preceding byte (not including the $99 $66 preamble). The first byte of the header is the command ID, and the fourth is the length of the packet body. The second and third bytes are unused, as far as I know, and are set to $00. While a packet is being received, the recipient continuously transmits the byte $4B.
[size=12pt]Command listing[/size]
This list covers all of the commands supported by the standard library found in Pokémon Crystal. There is also at least one command, $1A (write configuration data), that is exclusively used by Mobile Trainer. Its possible that some of the missing numbers are commands that exist in the hardware but were never used by any software; for instance, I would expect that there are commands for opening and closing UDP connections.
The command numbers appear to be organized such that commands numbered $1x relate to the basic operation of the Mobile Adapter GB and its attached telephone, while commands numbered $2x are network operations.
$10: Begin session
Sent to the adapter at the start of a session. The packet body is the ASCII string [tt]"NINTENDO"[/tt]. The adapter replies with an identical packet.
$11: End session
Sent to the adapter at the end of a session. The packet body is empty. The adapter replies with an identical empty packet.
$12: Dial telephone
Instructs the adapter to dial a telephone number. The packet body contains one byte of unknown significance, followed by the telephone number written in ASCII. The adapters response has an empty body.
$13: Hang up telephone
Instructs the adapter to hang up a telephone connection. The packet body is empty. The adapter replies with an identical empty packet.
$14: Wait for telephone call
Instructs the adapter to wait for a telephone call to be received. The packet body is empty. The adapter replies with an identical empty packet (only when the call is received?).
$15: Transfer data
This command is used either to send data over a TCP connection opened with command $23, or directly to another Mobile Adapter GB. While a connection is open, the Game Boy sends this packet containing one byte of unknown significance followed by zero or more bytes of data to be transmitted. The adapter replies with one byte of unknown significance followed by zero or more bytes that it has received from the other end. This is repeated until the connection is closed. The adapter sets bit 7 of the command ID while it is connected to a server, so the replys command ID appears as $95. When the remote server has closed the connection (e.g., at the end of an HTTP response), the reply sets the command ID byte to $9F instead.
$17: Telephone status
Sent to the adapter before attempting to dial. The packet body is empty. The adapters reply has one byte: $00 means that the telephone is ready to make a call, $04 or $05 means that the line is busy (Im not sure what the difference between these values is?), and any other value seems to be an error. Some features of Mobile Trainer actually check this after dialing to make sure the line is active, but Pokémon Crystal doesnt bother.
$19: Read configuration data
Requests a portion of the adapters 192-byte configuration memory. The packet body consists of two bytes; the first is an offset and the second is the number of bytes to be read. The adapter replies with a body containing one byte of unknown significance (possibly the offset, although that would be redundant?) followed by the requested data. In practice, the configuration data is read in two chunks of 96 bytes; it should be technically possible to read the full 192 bytes at once, but reading in smaller chunks is probably more reliable.
$1A: Write configuration data
Writes to a portion of the adapters 192-byte configuration memory. The packet body consists of one byte, which is an offset, followed by the bytes to be written. The adapters reply has an empty body (or, at least, Mobile Trainer doesnt seem to care what the response is). As with the read command, Mobile Trainer chooses to write the data in two separate chunks (of 128 and 64 bytes).
$21: ISP login
Logs in to the DION service (which will then be used to connect to an Internet server). The packet body begins with the login ID and password, each prefixed by a byte denoting its length. The last eight bytes are the IPv4 addresses of two DNS servers. The adapters reply has a four-byte body, which might be an IPv4 address assigned to the adapter, although that doesnt seem to be needed for anything in-game.
$22: ISP logout
Logs out of the DION service. The packet body is empty. The adapter replies with an identical packet.
$23: Open TCP connection
Opens a TCP connection to an Internet server. The packet body consists of an IPv4 address (four bytes) and a port number (two bytes, big-endian). The adapter replies with one byte of unknown significance. The adapter sets bit 7 of the command ID while it is connected to a server, so the replys command ID appears as $A3.
$24: Close TCP connection
Closes a TCP connection to an Internet server. The packet body contains one byte of unknown significance. The adapter replies with one byte of unknown significance.
$28: DNS query
Looks up the IP address for a domain name, presumably using the DNS server addresses sent in command $21. The packet body is the domain name. The adapters reply has a four-byte body containing the corresponding IPv4 address.
[size=12pt]Configuration memory[/size]
The Mobile Adapter GB has 192 bytes of memory in which to store configuration data. This memory can be read with command $19 and written with command $1A. It is structured as follows:
$00 "MA"
$02 Set to $01 during Mobile Trainer registration
Set to $81 when registration is successfully completed
$04 Primary DNS server (210.196.3.183)
$08 Secondary DNS server (210.141.112.163)
$0C Login ID ("g_________")
$2C E-mail address ("________@____.dion.ne.jp")
$4A SMTP server ("mail.____.dion.ne.jp")
$5E POP server ("pop.____.dion.ne.jp")
$76 Configuration slot 1
$8E Configuration slot 2
$A6 Configuration slot 3
$BE Checksum (big-endian)Strings are null-terminated if shorter than the fields which contain them.
Each configuration slot may contain a telephone number to be used to connect to the ISP (eight bytes) and an identifying string (sixteen bytes). The telephone number is stored in a variant of binary-coded decimal, where $A represents the [tt]#[/tt] key, $B represents the [tt]*[/tt] key, and $F marks the end of the telephone number.
If the device ID is $08 (PDC) or $09 (CDMA), Mobile Trainer will configure it to use the telephone number [tt]#9677[/tt] and identifying string [tt]"DION PDC/CDMAONE"[/tt]. If the device ID is $0A (DoCoMo PHS) or $0B (DDI PHS), it will be configured with the telephone number [tt]0077487751[/tt] and identifying string [tt]"DION DDI-POCKET"[/tt].
These are always written to the first configuration slot; the other two slots are always empty (filled with $FF and $00), and its unclear how they would have been used. (Im guessing theyre there in case Nintendo wanted to support an ISP other than DION in the future?) Pokémon Crystal has an option within the Mobile menu, titled ぶ Choose a Mobile Center, for selecting which of these three configuration slots it will use.
If the device ID is one of the unused values $0C0F, Mobile Trainer will fill the entire configuration memory with garbage data, because bounds checking is for sissies.
The checksum, like the packet checksum, is simply the sum of the preceding 190 bytes.
[size=12pt]Mobile Trainer[/size]
Initial setup
When the Mobile Trainer cartridge is first loaded with the Mobile Adapter GB connected, a setup wizard prompts the user to enter their DION login ID, e-mail address, and password. (According to instructions published by the Nintendo Online Magazine, these credentials were provided on the ＤＩＯＮＧＢ DION Mobile GB Plan Registration Form included in the Mobile Adapter GB box. The account would expire after 15 days unless the Registration Form was filled out and mailed to KDDI.)
(Straying further from the topic, this site has some photographs of the printed matter supplied with the Mobile Adapter GB, which bizarrely includes a promotion offering baseballs signed by Kazuhiro Sasaki, then a pitcher for the Nintendo of Americaowned Seattle Mariners.)
The login ID and e-mail address are stored in the adapters configuration memory, and the user is asked to choose whether or not the password will be saved on the Mobile Trainer cartridge. After that, Mobile Trainer attempts to log in to the DION POP e-mail server ([tt]pop.____.dion.ne.jp[/tt], where the subdomain is filled in from the entered e-mail address). If the login is successful, then a welcome message is displayed, followed by the Mobile Trainer title screen.
After setup has been completed, Mobile Trainer will boot to the title screen even when the Mobile Adapter GB is not connected. (If an adapter is connected, Mobile Trainer will still check whether it has been configured, and launch the setup wizard if needed.)
[youtube]https://youtu.be/oE7J1UFYO4M[/youtube]
Other features
I havent put much effort into getting any other features of Mobile Trainer working, but they all appear to be fairly straightforward: the e-mail uses DIONs POP and SMTP servers, the account management options use a simple HTTP interface, and Nintendos mobile homepage would have used some subset of HTML (though there probably arent any complete surviving copies of the pages, there are a few screenshots in this Nintendo Online Magazine article).
However, there may be significant unused content in the Mobile Trainer ROM. The most obvious instance is some text for a debug menu thats helpfully titled ＝＝ＤＥＢＵＧＭＯＤＥ＝＝. I also found this peculiar run of text:
どまそぼ
まそぼね
mario@mario.ne.jp
つののにちびにき
だ
き
kuppa@mario.ne.jp
つにのくと！くくはにてどのへＧＯ！
GB
GAMER's Life
grave01@natird.ad.jp
のの7/147/20までのきできなくなま
くだ
ＧＢ
だな
ieve@makopi.ne.jp
くくく
だ
p@p.ne.jp
To my knowledge, Bowser didnt play baseball until 2005 on the GameCube, and I still havent heard any news about this Pocket Monsters Moss
One more thing I noticed is that after completing the initial setup, there are four options in the って Mobile Settings menu, but when Torchickens used a GameShark code to skip the initial setup, a fifth option, 話号の Change telephone number, appeared. By erasing my Mobile Trainer save file and using that GameShark code, I was able to replicate this and attempted to use this option. It read the configuration data from the adapter, then started executing from WRAM and choked on opcode $FD. Im guessing thats not the intended behavior.
[size=12pt]Pokémon Crystal[/size]
Initial connection
On startup, before the copyright screen, Pokémon Crystal tries to connect to the Mobile Adapter GB and check the telephone status with command $17. If this connection is successful (which does not require that the adapter even be configured), all of the games mobile features are unlocked except for Mobile Stadium.
(The telephone status check has no purpose: the game will recognize the adapter as connected regardless of what value it sends in response to command $17. It appears that the result of this check is used to set or clear the unlimited battle mobile adapter flag, but the flag is always cleared regardless of what value is sent by the adapter. Im guessing the debug build behaved differently.)
After the successful connection, the Mobile Profile screen will be presented the first time Continue is selected from the main menu, or whenever a new game is started.
Egg Ticket
When the Egg Ticket is redeemed at the PokéCom Center Trade Corner, the game makes an HTTP GET request for [tt]http://gameboy.datacenter.ne.jp/cgb/download?name=/01/CGB-BXTJ/tamago/index.txt[/tt]. ([tt]"CGB-BXTJ"[/tt] is the product code for the Japanese version of Pokémon Crystal; [tt]"01"[/tt] denotes the games publisher, Nintendo.) This text file should have two lines, with CRLF line endings.
The first line is the HTTP URI that will be used to download the Odd Egg data. This URI contains a sequence of up to four capital [tt]"X"[/tt]s, which the game will replace with a hexadecimal value.
(If the filenamei.e., the part of the URI after the last [tt]"/"[/tt], even if its part of the query stringstarts with a decimal digit, the game reads up to three digits from the start of the filename, interprets this as the service fee [in yen] charged for downloading this file, and prompts the user to confirm before downloading it. Since it is known that there was no service fee for the Egg Ticket event, the filename should not start with a digit, or an [tt]"X"[/tt] that will be replaced by a digit.)
The second line is a series of 16-bit values written in hexadecimal (with lowercase [tt]"a"[/tt][tt]"f"[/tt]). These represent the cumulative probabilities of each Odd Egg being obtained. The game generates a random 16-bit number, compares it to each of these values, and downloads the Odd Egg corresponding to the first value that is greater than or equal to the random number, by filling in the [tt]"X"[/tt]s in the URI with [tt]"0000"[/tt] for the first Odd Egg, [tt]"0001"[/tt] for the second, and so on in hexadecimal. Leading digits will be omitted if there are fewer than four [tt]"X"[/tt]s to replace.
If the second line of the file is blank, the Trade Corner attendant will say ま！だまのはちてま Im awfully sorry. The EGG TICKET exchange service isnt running now. Reportedly the Egg Ticket exchange service ran for the entire time that the Mobile System GB was in operation, so this text would never have been used. If the Egg Ticket service was shut down, it would have made it impossible for someone who had the Egg Ticket in their Bag to use the Trade Corner until they deposited it in their PC, which could have been confusing.
The downloaded Odd Egg file is 54 bytes, containing the 48-byte Pokémon data structure followed by the nickname, which should be EGG. The OT name な ODD is added by the game, though it goes unseen since an Eggs OT is always shown as ????? until it hatches.
For my implementation, Ive copied the Odd Egg data from the English version. But according to legend, the Odd Egg received from the mobile event had a 50% chance to be Shiny, higher than the 14% chance for the in-game event in the Western versions. Does anyone know where this information came from? The only way to verify it would have been to download [tt]index.txt[/tt] and read the probability values, and Ive seen no evidence that anyone would have known how to do that at the time.
[youtube]https://youtu.be/Er0gbOvHY5k[/youtube]
PokéCom Center Trade Corner
When a Pokémon is deposited at the Trade Corner, the game sends an HTTP GET request for [tt]http://gameboy.datacenter.ne.jp/cgb/download?name=/01/CGB-BXTJ/exchange/index.txt[/tt]. The first line of this file is a URI that will be used to log in before uploading the Pokémon data. Since the service fee for the Trade Corner was ¥10, the filename in that URI should start with [tt]"10"[/tt].
As far as I can tell, the server is supposed to send an HTTP 401 Unauthorized response with a [tt]WWW-Authenticate[/tt] header, to which the game will respond by retrying with an [tt]Authorization[/tt] header. Then the server will respond with a [tt]Gb-Auth-ID[/tt] header. I cant seem to get this process to work, so instead Ive bypassed it by having the server send the [tt]Gb-Auth-ID[/tt] on the first try.
The game POSTs a 143-byte file with the following contents:
$00 DION e-mail address (null-terminated ASCII)
$1E Trainer ID
$20 Secret ID
$22 Offered Pokémons gender
$23 Offered Pokémons species
$24 Requested Pokémons gender
$25 Requested Pokémons species
$26 Trainer name
$2B Offered Pokémons 48-byte data structure
$5B Offered Pokémons OT name
$60 Offered Pokémons nickname
$65 Mail data (filled with 00 if not holding Mail):
$65 Message
$86 Senders name
$8B Senders Trainer ID
$8D Pokémon species
$8E Item indexThe genders of the offered and requested Pokémon are encoded as: $00 = gender unknown, $01 = male, $02 = female, and (for the requested Pokémon) $03 = either male or female.
After a Pokémon is deposited in the Trade Corner, the game enforces a two-hour waiting period before the status of the trade may be checked. To check if a trade has been made, the game logs in to the DION POP e-mail server and searches for an e-mail with the header [tt]X-Game-code: CGB-BXTJ-00[/tt]. If it finds one, it will read the [tt]X-Game-result[/tt] header, which is in the format [tt]1 ttttssss oooo rrrr x[/tt], where [tt]tttt[/tt] and [tt]ssss[/tt] are the Trainer ID and Secret ID, [tt]oooo[/tt] is the gender and species of the offered Pokémon, and [tt]rrrr[/tt] is the gender and species of the requested Pokémon, all written in lowercase hexadecimal. The last character [tt]x[/tt] is either [tt]"1"[/tt] or [tt]"2"[/tt], with [tt]"1"[/tt] indicating that a trade partner has been found and [tt]"2"[/tt] indicating that the server has given up on finding one. If a trade partner has been found, the body of the e-mail will contain the last 105 bytes of the above data structure (starting from the Trainer name) for the received Pokémon, encoded in Base64.
If no e-mail with a matching [tt]X-Game-code[/tt] and [tt]X-Game-result[/tt] is found, the Trade Corner attendant will give you the option to retrieve your Pokémon. If you choose to retrieve it, the game reads a URI from the second line of [tt]exchange/index.txt[/tt] and POSTs a 38-byte file to it, which contains the first 38 bytes of the above data structure (up to the requested Pokémons species). This cancels the trade.
[youtube]https://youtu.be/0ZerrH7rYZU[/youtube]
Cable Trade Center
I wasnt planning to work on the multiplayer features at this point; I just wanted to see what commands they use so I could add them to the command listing.
I wrote my program so that when it received a command it didnt recognize, it would echo that command verbatim in response. This turned out to be entirely sufficient to make the Mobile Trade screen open and let me trade with myself!
[youtube]https://youtu.be/4Uh4sgtmDMQ[/youtube]
One notable feature of the mobile trade animations is that the Mobile Adapter GB is depicted using a palette chosen according to the device IDthe PDC adapter is shown as blue, the CDMA adapter is shown as yellow, the unreleased DoCoMo PHS adapter is shown as green, and the DDI PHS adapter is shown as red. There are also assigned palettes for the unused device IDs $0C0F: purple for $0C, black for $0D, pink for $0E, and gray/violet for $0F.
[img]http://i.imgur.com/emwzq58.png[/img][img]http://i.imgur.com/2jt6fmU.png[/img][img]http://i.imgur.com/qB3DTCH.png[/img][img]http://i.imgur.com/cwr6A5W.png[/img]
Cable Club Colosseum
I was also able to get into a battle with myself in the Colosseum, though it inevitably unraveled when the opposing Pokémon fainted and it tried to send out the fainted Pokémon as a replacement for itself (since it wasnt my Pokémon that fainted, I hadnt made a selection).
I did, however, find out what an unlimited battle mobile adapter does: it removes the 10 minute per day limit on Colosseum battles. When entering the Colosseum without the unlimited battle flag, the attendant will ask: きののはと０ふで[]ま Todays remaining time is 10 min. Would you like to battle? (or one of a few other messages if less time is left). With the unlimited battle flag, she asks instead: ではでま[]で To enter a mobile battle, you must pick a team of three POKéMON. Is that OK?
[size=12pt]Implementation[/size]
http://pastebin.com/igq4SuVd
I pilfered the BGB linking code from TheZZAZZGlitchs implementation of the Game Boy Printer protocol and wrote a script that does just enough to make these features work. Rather than connecting to a proper server, it fabricates the responses that the server should give for a limited set of commands. It completely ignores the DION login ID and password, so you can enter whatever you want in Mobile Trainers setup. The e-mail server is hard-coded to contain an e-mail matching the Pidgey-for-Pidgey trade that I made in the video; if you want to use the Trade Corner, youll have to edit that e-mail to match your Trainer ID, Secret ID, and the trade youve made.
I think the next step will be to set up a server that can run a fully functioning Trade Corner, and write a client that can connect to that server or make direct calls to other clients. Theres still the matter of getting Pokémon Crystals Pokémon News, Battle Tower, and Mobile Stadium features running, and after that, it might be interesting to get a couple of the other Mobile Adapter GB compatible games working. Eventually, it would be fun to build a ROM hack of the English version of Pokémon Crystal that restores all of its mobile functionality.