Mobile Adapter GB Technical Documentation 0.1
April 17, 2019
Original documentation by Háčky -> https://forums.glitchcity.info/index.php?topic=7509.0
Additional notes by REON Dev Team

***************************************************
1. Introduction
***************************************************

The Mobile Adapter GB was an accessory designed to allow the Game Boy Color, and later the Game Boy Advance, to connect online via cellular networks in Japan. Released on January 27, 2001, it supported a limited number of games before service was shutdown on December 14, 2002. Many of the compatible games supported features such on mail clients, downloadable bonus content, player-versus-player modes, and even online tournaments. It represented Nintendo's first official attempt at online gaming for its handhelds.
 

***************************************************
2. General Hardware Information
***************************************************

- The Mobile Adapter is a small device that essentially allows a Japanese phone to connect to the Game Boy's link port
- Model number is CGB-005
- Officially released with 3 different versions of the Mobile Adapter. Each featured distinct colors to work with different type of phones
- Each Mobile Adapter came packaged with a cartridge called the Mobile Trainer to help configure and setup the device
- Servers were formally hosted at gameboy.datacenter.ne.jp

Below, the Mobile Adapter variants are explained in further detail:

Blue 	-> Used to connect PDC phones.
Yellow	-> Used to connect cdmaOne phones.
Red	-> Used to connect DDI phones.
Green	-> Would have been used to connect PHS phones, but this version was never released.


***************************************************
3. Compatible Games
***************************************************

There are currently 22 known games that are compatible with the Mobile Adapter:

Game Boy Color : 6 Total

* Game Boy Wars 3
* Hello Kitty: Happy House
* Mobile Golf
* Mobile Trainer
* Net de Get Minigames @ 100
* Pocket Monsters Crystal Version

Game Boy Advance : 16 Total

* All-Japan GT Championship
* Daisenryaku For Game Boy Advance
* Doraemon: Midori no Wakusei Doki Doki Daikyuushuutsu!
* Exciting Bass
* EX Monopoly
* JGTO Licensed: Golfmaster Mobile
* Kinniku Banzuke ~Kongou-kun no Daibouken!~
* Mail de Cute
* Mario Kart Advance
* Mobile Pro Baseball: Control Baton
* Monster Guardians
* Morita Shougi Advance
* Napoleon
* Play Novel: Silent Hill
* Starcom: Star Communicator
* Zero-Tours

Two games were planned but later cancelled: beatmaniaGB Net Jam for the GBC and Horse Racing Creating Derby for the GBA.

The GBA game Yu-Gi-Oh! Duel Monsters 5 Expert 1 contains code for the Mobile Adapter, but despite being built with the library it does not appear to use it. This functionality may have been planned and later abandoned.


***************************************************
4. Protocol - Packet Format
***************************************************

On the GBC, the Mobile Adapter operates using the fastest available setting (64KB/s) by setting Bits 0 and 1 of the SC register (0xFF02) high. It also uses an internal clock for all transfers. Communication is comparable to that of the Game Boy Printer, where the Game Boy sends packets with header, data, command, and checksum sections. On the GBA, the Mobile Adapter operates in NORMAL8 mode using a shift clock of 256KHz. Below is a chart breaking down the Mobile Adapter packet format:

-------------------------------------------------
Section			| Length		
-------------------------------------------------
Magic Bytes : 0x99 0x66	| 2 bytes
Packet Header		| 4 bytes
Packet Data		| 0-254 bytes
Packet Checksum		| 2 bytes
Acknowledgement	Signal	| 2 bytes
-------------------------------------------------


-------------------------------------------------
Packet Header
-------------------------------------------------
Byte 1			| Command ID
Byte 2			| Unknown/Unused (0x00)
Byte 3			| Unknown/Unused (0x00)
Byte 4			| Length of Packet Data
-------------------------------------------------


-------------------------------------------------
Packet Data
-------------------------------------------------
Bytes 0-254		| Arbitrary data
-------------------------------------------------


-------------------------------------------------
Packet Checksum	
-------------------------------------------------
Byte 1			| High byte of 16-bit sum
Byte 2			| Low byte of 16-bit sum
-------------------------------------------------


-------------------------------------------------
Awknowledgement Signal
-------------------------------------------------
Byte 1			| Device ID (sender)
			| Device ID OR 0x80 (receiver)
			|
Byte 2			| Command ID (sender)
			| Command ID OR 0x80 (receiver)
-------------------------------------------------

The magic bytes are simply a pair of bytes used to identify the start of a Mobile Adapter packet. When one side starts receiving these magic bytes, the other should return the same to begin and sync communications.

Packet Data is arbitrary data and varies in length and content. On the Game Boy Color, it has a maximum size of 254 bytes. This restriction may be applied via software and appears to come from the fact that the Packet Data and Packet Checksum are lumped together, thus their total lengths must not exceed 256 bytes. Attempting to send more than 254 bytes of packet data causes communications errors in all supported GBC games. Evidence suggests GBA games can use Bytes 3 and 4 of the Packet Header to specify Packet Data size (possibly up to 64KB).  

On the GBC, data greater than 254 bytes may be broken up into multiple packets, however. For example, when sending a large binary file such as an image or executable code, multiple packets are transferred from the Mobile Adapter to the Game Boy while the TCP transfer is ongoing.

The Packet Checksum is simply the 16-bit sum of all previous header bytes and all previous packet data bytes. It does not include the magic bytes. The checksum is transmitted big-endian. After the checksum, a simple 2-byte Acknowledgement Signal is sent. 

Bit 7 of any of these bytes will be set high if the device is the receiver of packet, and Bit 7 will be set low for the sender of the packet. This essentially confirms what role the Game Boy is acting in. If it is the receiver, it is expecting to read information from the from the Packet Data from the Mobile Adapter. For exmple, with Command 0x19, the Game Boy is explicitly requesting data from the adapter, and with Command 0x1A the Game Boy is explicitly sending data to the adapter. When acting as the receiver, the device fills its Packet Data with 0x4B bytes. If the Game Boy is the sender, it is expecting to push information from its own Packet Data to the Mobile Adapter. In this case, the Packet Data the Mobile Adapter sends in response is filled with 0xD2 bytes. 

If the checksum fails, the receiving side typically immediately sends 0xF1 to indicate an error. 0xF0, and 0xF2 also appear to be failure codes, however, their meaning is currently unknown. 0xEE indicates a specific error from a previously issued command.

The device ID determines what kind of hardware each side is communicating with. Below are the possible values and their meaning:

-------------------------------------------------
Device ID	| OR Value	| Device Type
-------------------------------------------------
0x00		| 0x80		| Game Boy Color
0x01		| 0x81		| Game Boy Advance
0x08		| 0x88		| PDC Mobile Adapter (Blue)
0x09		| 0x89		| cdmaOne Mobile Adapter (Yellow)
0x0A		| 0x8A		| PHS Mobile Adapter (Green)
0x0B		| 0x8B		| DDI Mobile Adapter (Red)
-------------------------------------------------


***************************************************
5. Protocol - Flow of Communication 
***************************************************

Even though the protocol effectively enables 2-way communication between the Game Boy and a remote server, the handheld is expected to oversee all transmissions to the adapter itself. That is to say, the typical "master-slave" model often used for Game Boy serial I/O still applies in some sense. Once the server starts responding, the Game Boy has to continually initiate another transfer to the adapter (setting Bit 7 of 0xFF02 high) to keep reading any additional bytes that were sent.

It is up to the game software itself to handle secondary protocols (such as HTTP, POP3, or SMTP) which involve one side specifically acting as the sender or receiver. For example, after opening a TCP connection to an HTTP server and issuing the 0x15 command (Data Transfer), the software will determine whether the Game Boy is acting as a sender (making an HTTP request) or a receiver (receiving an HTTP response). Generally, this goes back and forth. The Game Boy sends information via its Packet Data, while the Mobile Adapter's Packet Data is filled with 0xD2 bytes at this time until the Game Boy finishes its TCP transfer. When the Game Boy's TCP transfer is done, the adapter sends any information from the server in its Packet Data while that same part of packet from the Game Boy is filled with 0x4B bytes. The chart below illustrates this concept:

--------------------------------------------------------------------------
Device		| Role		| Packet Data	| Acknowledgement Signal
--------------------------------------------------------------------------
Game Boy	| Sender	| Arbitrary	| Device ID + Command ID
Game Boy	| Receiver	| 0x4B 0x4B ... | Device ID OR 0x80 + Command ID OR 0x80
Mobile Adapter	| Sender	| Arbitrary	| Device ID + Command ID
Mobile Adapter	| Receiver	| 0xD2 0xD2 ... | Device ID OR 0x80 + Command ID OR 0x80
--------------------------------------------------------------------------

Many games appear to an follow a certain order of commands initially. This may have been part of some kind of standard library available to developers in order to connect to an ISP. The commands most commonly look like this:

------------
Command 0x10		Begin Session. First is perhaps to test the presence of the Mobile Adapter
Command 0x11		Close Session.
Command 0x10		Begin Session. Open session for configuration data
------------
Command 0x19		Read Configuration Data. Grab first 96 bytes
Command 0x19		Read Configuration Data. Grab second 96 bytes
Command 0x11		Close Session.
Command 0x10		Begin Session. Open session to read configuration data again
Command 0x19		Read Configuration Data. Grab first 96 bytes
Command 0x19		Read Configuration Data. Grab second 96 bytes
------------
Command 0x17		Check Telephone Status if not busy
Command 0x12		Dial Telephone. Should be the ISP's number stored in configuration data
Command 0x21		ISP Login
Command 0x28		DNS Query
------------

From there, the software decides what next (if anything) needs to be done after successfully connecting to the internet.

When the GBC or GBA first start communicating with the Mobile Adapter, the first byte sent in response will be garbage data. Afterwards, however, it will reply with 0xD2 as its "idle" byte until a command is finished being sent.


***************************************************
6. Protocol - Commands 
***************************************************

[[Command 0x10 - Begin Session]]
Data Sent: "NINTENDO" ASCII string. 8 bytes only, not null-terminated
Data Received: "NINTENDO" ASCII string. 8 bytes only, not null terminated

Sent to the adapter at the beginning of a session. The Game Boy sends an ASCII string containing "NINTENDO" and the adapter replies with a packet containing the same data. It must be noted that the adapter will not respond to other commands until it receives this command. If this command is sent twice, it returns an error.

----------

[[Command 0x11 - End Session]]
Data Sent: N/A. Empty Packet Data
Data Received: N/A. Empty Packet Data

Sent to the adapter at the end of a session. The Packet Data is empty, and the length is zero bytes.

----------

[[Command 0x12 - Dial Telephone]]
Data Sent: 1 unknown byte + telephone number
Data Received: N/A. Empty Packet Data

Instructs the adapter to dial a telephone number. The first byte's purpose is unknown. The second byte is "#" in ASCII, and following data is the telephone number represented in ASCII values.

----------

[[Command 0x13 - Hang Up Telephone]]
Data Sent: N/A. Empty Packet Data
Data Received: N/A. Empty Packet Data

Instructs the adapter to close a telephone connection. The Packet Data is empty, and the length is zero bytes.

----------

[Command 0x14 - Wait For Telephone Call]]
Data Sent: N/A. Empty Packet Data
Data Received: N/A. Empty Packet Data

Instructs the adapter to wait for a telephone call. The Packet Data is empty, and the length is zero bytes.

----------

[[Command 0x15 - Transfer Data]]
Data Sent: 1 unknown byte + Arbitrary Data (optional)
Data Received: 1 unknown byte + Arbitrary Data (optional)

Used to transfer data over TCP after the command 0x23 (Open TCP Connection) has been called. This command can communicate with a remote server or another Mobile Adapter. The Packet Data is a minimum length of 1 byte. That first byte's purpose is unknown. Generally, additional data is appended, although it is not required, such as when closing a connection. Large chunks of data greater than 254 bytes must be broken down into separate packets. While a connection is active (e.g. an HTTP request/response is in progress), the Command ID in the Acknowledgement Signal is 0x15 for the sender and 0x95 for the receiver. When a connection is closed (e.g. when an HTTP response has finished), the Command ID in the Acknowledgement Signal becomes 0x1F for the sender and 0x9F for the receiver.

----------

[[Command 0x17 - Telephone Status]]
Data Sent: N/A. Empty Packet Data
Data Received: 1 byte for current telephone status + 2 unknown bytes

Typically sent to the adapter before dialing. Also used to test the telephone status before opening a TCP connection, or to constantly ping the phone to make sure it's still active. The reply is 1 byte. 0x00 means the phone is ready to make a call or connection. 0xFF indicates a disconnected phone. 0x04 and 0x05 indicate that the line is busy (presumably set after a command like 0x12). The difference between the two line-busy values is unknown. Most software does not seem to care which one is sent, but Net de Get: Mini Game @ 100 refuses to work with 0x05.

Additionally, the Game Boy seems to set Bits 0 - 4 high for the Command ID in the Acknowledgement Signal, thus sending 0x1F to the Mobile Adapter.

----------

[[Command 0x18 - Unknown Command]]
Data Sent: 1 unknown byte
Data Received: N/A. Empty Packet Data

This command is generally sent after Command 0x10. Only GBA games have been known to use this command. The GBA sends 1 unknown byte. The response Packet Data is empty, and the length is zero bytes.

----------

[[Command 0x19 - Read Configuration Data]]
Data Sent: 1 byte offset + 1 byte read length
Data Received: 1 unknown byte + Requested Configuration Data

Requests data from the adapter's 192-byte configuration memory. The first byte sent to the adapter is the offset. The second byte sent is the length of data to read. The adapter responds with 1 unknown byte followed by configuration data from the adapter's internal memory. Although it should be possible to read the entire configuration data with one packet, most software send 2 of these commands to read 96-byte chunks.

----------

[[Command 0x1A - Write Configuration Data]]
Data Sent: 1 unknown + Configuration Data to Write
Data Received: N/A. Empty Packet Data

Writes data to the adapter's 192-byte configuration memory. The first byte sent to the adapter unknown. The following bytes are the data to be written in the adapters internal memory.

----------

[[Command 0x21 - ISP Login]]
Data Sent: 1 byte Login ID Length + Login ID + 1 byte Password Length + Password + 4 bytes DNS Address #1 + 4 bytes DNS Address #2
Data Received: 4 bytes possibly representing IP address assigned to adapter

Logs into the DION service, which in turn connects to an internet server. Both the Login ID and Password are prefixed with bytes declaring their lengths. The IPv4 DNS addresses are 4 bytes each, with a single byte representing one octet. 

----------

[[Command 0x22 - ISP Logout]]
Data Sent: N/A. Empty Packet Data
Data Received: N/A. Empty Packet Data

Logs out of the DION service.

----------

[[Command 0x23 - Open TCP Connection]]
Data Sent: 4 bytes for IP Address + 2 Bytes for Port Number
Data Received: 1 unknown byte

Opens a TCP connection at the given IP address on the given port. The IPv4 IP address is 4 bytes, with a single byte representing one octet. The port number is big-endian. Depending on which port the TCP connection opens (25, 80, 110), different protocols can be accessed on a server (SMTP, HTTP, and POP respectively). Handling the details of the protocol itself depends on software. The Mobile Adapter is merely responsible for opening the connection and handling TCP transfers such as when using Command 0x15.

----------

[[Command 0x24 - Close TCP Connection]]
Data Sent: 1 unknown byte
Data Received: 1 unknown byte

Closes an active TCP connection.

----------

[[Command 0x28 - DNS Query]]
Data Sent: Domain Name
Data Received: 4 bytes for IP Address

Looks up the IP address for a domain name, presumably using the DNS server addresses sent in Command 0x21

----------

[[Command 0x6E - Error Status]]
Data Sent: N/A. Adapter sends this in response to a failed command
Data Received: 1 byte for command that failed + 1 byte for error status

If a previously sent command fails, the adapter will respond with this instead, indicating the command that failed as well as a brief status code. The error statuses for one command do not indicate the same error for another command, so context matters when parsing the codes. The following commands and their known error status codes are listed below:

0x10: Error Code 0x01 - Sent twice
0x10: Error Code 0x02 - Invalid contents
0x12: Error Code 0x03 - Dial telephone with telephone disconnected
0x14: Error Code 0x00 - Wait for call with telephone disconnected
0x15: Error Code 0x01 - Transfer data without being connected
0x19: Error Code 0x02 - Read outside of config area
0x1A: Error Code 0x02 - Write outside of config area
0x21: Error Code 0x01 - ISP login with disconnected phone



***************************************************
7. Configuration Data
***************************************************

The Mobile Adapter has small area of built-in memory designed to store various settings for its configuration. It only uses 192 bytes but data is readable and writable via the Commands 0x19 and 0x1A respectively. These fields are filled out when running the initial setup on Mobile Trainer. The memory is laid out as describe below:

--------------------------
0x00 - 0x01		::	"MA" in ASCII. The "Mobile Adapter" header.
0x02			::	Set to 0x1 during Mobile Trainer registration and 0x81 when registration is complete
0x04 - 0x07		::	Primary DNS server (210.196.3.183)
0x08 - 0x0B		::	Secondary DNS server (210.141.112.163)
0x0C - 0x15		::	Login ID in the format gXXXXXXXXX. Mobile Trainer only allows 9 editable characters
0x2C - 0x43		::	User email address in the format XXXXXXXX@YYYY.dion.ne.jp
0x4A - 0x5D		::	SMTP server in the format mail.XXXX.dion.ne.jp
0x5E - 0x70		::	POP server in the format pop.XXXX.dion.ne.jp
0x76 - 0x8D		::	Configuration Slot #1
0x8E - 0xA5		::	Configuration Slot #2
0xA6 - 0xBD		::	Configuration Slot #3
0xBE - 0xBF		::	16-bit big-endian checksum
--------------------------

Each configuration slot may contain an 8-byte telephone number to be used to connect to the ISP and a 16-byte ID string. The telephone number is stored in a variant of binary-coded decimal, where 0x0A represents the "#" key, 0x0B represents the "*" key, and 0x0F marks the end of the telephone number. These slots may have been intended to allow users to connect online using ISPs besides DION at some point, however, Nintendo never implemented any such plans.

If the Mobile Adapter is connected to a PDC or CDMA device, the telephone number defaults to #9677 with an ID string of "DION PDC/CDMAONE". If the Mobile Adapter is connected to a PHS or DDI device, the telephone number defaults to 0077487751 with an ID string of "DION DDI-POCKET". Only the first slot is configured by Mobile Trainer; it fills the rest with 0xFF and 0x00 bytes. An unidentified device (as reported by the Device ID in the Acknowledgement Signal of a packet) causes the Mobile Adapter to overwrite all configuration data with garbage values.

The checksum is simply the 16-bit sum of bytes 0x00 - 0xBD.

All software compatible with the Mobile Adapter appears to read the configuration data first and foremost. If the data cannot be read or if there is a problem with the data, they will refuse to even attempt making an online connection. Generally, they return the error code 25-000 in that situation.

If any compatible software attempts to read or write configuration data outside the allotted 192 bytes via commands 0x19 and 0x1A, the entire I/O operation is cancelled. No data is written even if the initial offset is within the 192 bytes. No data is returned either, as both commands respond with Error Status packets.