The Mystery Gift IR Protocol
HIGH means: IR LED is turned on
LOW means: IR LED is turned off
There are two message types:
1. Hello Message
HIGH for 126 µs
LOW for 537 µs
HIGH for 126 µs
2. Data Message
This message is used to send a stream of bytes. For every byte, the bits are sent in MSB-first order.
HIGH for 126 µs
LOW for 725 µs
for every bit B that should be sent:
HIGH for 52 µs
if B is 0: LOW for 120 µs
elseif B is 1: LOW for 299 µs
HIGH for 109 µs
LOW for 620 µs
How Data Is Sent
One party is the master (M), the other one is the slave (S). Only the master can send data. The slave can only send acknowledgements. However, the master can initiate a change of roles.
Data is always sent by M in a block of three data messages (called data block in the following):
data message: 0x5A, [length of data]
data message: [data] ...
data message: low(checksum), high(checksum)
The checksum is just the sum over all bytes that have been sent in the first two messages (0x5A, the length of data, and every data byte).
After such a block, S sends an acknowledgement:
data message: 0x6C
The procedure to send data is as follows:
M: hello message
S: hello message
M: data block with three data messages (see above)
S: acknowledgement
M: data block with empty data, i.e. [length of data]==0 and the second message contains zero bits.
S: acknowledgement
There must be a delay of about 1–2ms between reception of a message and sending the next message. After these steps, S and M change roles, resulting in new hello messages.
When sending empty data, the first data block is left out (last step of protocol, see protocol section below):
M: hello message
S: hello message
M: data block with empty data, i.e. [length of data]==0 and the second message contains zero bits.
S: acknowledgement
As above, there must be a delay of about 1–2ms between reception of a message and sending the next message.
The Whole Protocol
The following happens two times (for first and for second payload). There must be a delay of at least 5ms between the first and the second pass. Roles are preserved, i.e. after A has received the acknowledgement for the last message of the first pass, A continues to send a hello message (first message of the second pass).
A: send 0x96
B: send region code (see table below)
A: send i-th payload
B: send 0x96
A: send region code (see table below)
B: send i-th payload
A: send empty data
If the region code received does not match the game's one, Mystery Gift fails.
region code
country
0x90
USA
0x96
ESP
0x99
ITA
0x9A
FRA
0x9F
GER
0xF3
PIKACHU (see below)
The Payload
First payload: 20 Bytes.
[version] high(ID) low(ID) name[0] name[1] name[2] name[3] name[4] name[5] name[6] name[7] name[8] name[9] name[10] [pokedex] [gift type] [item] [decoration] [status] [counter]
version: gold,crystal: 0x01; silver: 0x02; Pokémon Pikachu 2 GS: 0x03
name: terminated by 0x50; after termination character, all bytes til name[7] are 0x50; name[8..10] are 0x00 (except for pokémon pikachu 2 GS)
pokedex: number of different Pokémon catched so far
gift type: 0x00 = item, 0x01 = decoration (or item if receiver owns the decoration already)
item, decoration: 0x00 to 0x24 (only a subset is ever sent, depending on the sender's trainer ID. 0x22 to 0x24 will never be sent (very rare items/decos). however, the receiving game accepts every item/deco in the range 0x00 to 0x24 without testing legality)
status: 0x00 if everything is ok; 0xAD if the player needs to retrieve gift at Pokémon center before
counter: player's today's number of mystery gifts
for Pokémon Pikachu 2 GS: ID is 0x0000, name is "PIKACHU" (name[7..10] are 0x50), pokedex is 0x00, gift type is 0x00, decoration is 0x00, status is 0x00, counter is 0x00. item depends on the number of watts sent. only the first payload is exchanged (version field must be 0x03, otherwise communication without the second payload fails.) The number of Mystery Gifts received from Pokémon Pikachu 2 GS is not bounded (and the trainer ID is ignored).
Pokémon Pikachu 2 GS copies the region code from the receiving game. This always possible, because Pikachu always plays the role A in the protocol (it never responds to initial hello messages, but sends its own hello messages repeatedly until the game answers). Role A receives the region code of B before it needs to send its own.
Second payload: 38 Bytes. (only exchanged if [version] is not 0x03)
Team Pokémon (for Viridian City Battle Hall):
6 Bytes for each Pokémon: [level] [species] [move1] [move2] [move3] [move4]
The last Pokémon is followed by 0xFF. The remaining part of the message is filled with random bytes (uninitialized memory).
Pokémon Pikachu 2 GS
When sending watts to Pokémon GSC, Pikachu acts as described in the section above. Depending on the number of watts sent, Pikachu sends a payload with the following item to Pokémon GSC:
Watts
Item
0–99
Eon Mail (0x0D)
100–199
Berry (0x00)
200–299
Bitter Berry (0x09)
300–399
Great Ball (0x13)
400–499
Max Repel (0x15)
500–599
Ether (0x17)
600–699
MiracleBerry (0x10)
700–799
Gold Berry (0x11)
800–899
Elixir (0x16)
900–998
Revive (0x12)
999
Rare Candy (0x22)
As receiver, Pikachu plays role B in the protocol above. It identifies itself by the region code 0xF3.
Thus, a communication with Pokémon GSC fails. When another Pikachu plays role A, it detects the communication with Pikachu by the region code.
The watts are sent using a payload of length 67 bytes. Only the first two bytes are used, the remaining bytes are padded with zeros (don't ask me why!).
The amount of watts is sent as packed BCD. E.g., when sending 237 watts, the first two bytes of the payload are 0x02 0x37, followed by 65 bytes with value 0x00. Note that the maximal amount of watts that can be sent is 999. When illegal codings like 0x0A 0xFF 0x00 ... 0x00 are sent, the receiving Pikachu may start to operate glitchy until it is reset (to reset Pikachu, remove its battery and wait a few minutes before reinsertion).
The receiving Pikachu sends a payload, too. Thus, exactly one pass of the protocol is performed. The payload sent by the receiving Pikachu contains 67 random junk bytes (i.e. uninitialized memory; again: don't ask me why!).
How are items / decorations encoded?
code
item
decoration
0x00
Berry
Jigglypuff Doll
0x01
PRZCureBerry
Poliwag Doll
0x02
Mint Berry
Diglett Doll
0x03
Ice Berry
Staryu Doll
0x04
Burnt Berry
Magikarp Doll
0x05
PSNCureBerry
Oddish Doll
0x06
Guard Spec.
Gengar Doll
0x07
X Defend
Shellder Doll
0x08
X Attack
Grimer Doll
0x09
Bitter Berry
Voltorb Doll
0x0A
Dire Hit
Clefairy Poster
0x0B
X Special
Jigglypuff Poster
0x0C
X Accuracy
Super NES
0x0D
Eon Mail
Weedle Doll
0x0E
Morph Mail
Geodude Doll
0x0F
Music Mail
Machop Doll
0x10
MiracleBerry
Magna Plant
0x11
Gold Berry
Tropic Plant
0x12
Revive
NES
0x13
Great Ball
Nintendo 64
0x14
Super Repel
Bulbasaur Doll
0x15
Max Repel
Squirtle Doll
0x16
Elixir
Pink Bed
0x17
Ether
Polkadot Bed
0x18
Water Stone
Red Carpet
0x19
Fire Stone
Blue Carpet
0x1A
Leaf Stone
Yellow Carpet
0x1B
Thunderstone
Green Carpet
0x1C
Max Ether
Jumbo Plant
0x1D
Max Elixir
Virtual Boy
0x1E
Max Revive
Big Onix Doll
0x1F
Scope Lens
Pikachu Poster
0x20
HP Up
Big Lapras Doll
0x21
PP Up
Surf Pikachu Doll
0x22
Rare Candy
Pikachu Bed
0x23
Bluesky Mail
Unown Doll
0x24
Mirage Mail
Tentacool Doll
0x25–0xFF
Great Ball
Red Carpet
How are the other data encoded?
Trainer name: Every character is encoded the same way as all text in the game: https://bulbapedia.bulbagarden.net/wiki/Character_encoding_in_Generation_II
Pokémon: By the ID in the national Pokédex (Bulbasaur = 0x01, Celebi = 0xFB)
Moves: By their index number in the game: https://bulbapedia.bulbagarden.net/wiki/List_of_moves
Which Items resp. Decorations Are Sent at All?
Items/Decorations 0x22–0xFF are never sent by Pokémon GSC at all. Rare Candy can be sent by Pokémon Pikachu 2 GS. Pikachu Bed, Unown Doll, and Tentacool Doll are only sent by Pokémon Stadium 2 (however, without IR communication). Bluesky Mail and Mirage Mail are never sent by any device.
For the other items and decorations (0x00–0x21), only a subset of them is actually sent by a specific game, depending on the trainer ID. Compile and run gifts.c to find out which gifts can be sent by a game with a specific ID.
Building a Mystery Gift Station
I own only one GameBoy Color, but three Gen 2 games. So I used a Raspberry Pi to implement the protocol above.
The first time, the Raspberry sends payload with the status byte (see first payload) not zero, thus it does not send any gift. But the Raspberry Pi stores the received payload. Then I can swap the game cartridge and run mystery gift again, receiving the stored data from the first exchange. The Raspberry Pi stores the received data again, so after swapping the game cartridge back the exchange is completed. If a communication error occurs (this happens often), the Raspberry Pi just keeps the last correct data.
I have attached the circuit layout (without capacity / resistance information*) and the source code (mysterygift.c) for the mystery gift station (needs WiringPi library and Linux kernel with RT_PREEMPT). The input timing of the source code differs from the timing described above. I guess that the high-pass filter may extend the HIGH-time. Depending on the capacitor, one may need to change the appropriate values in the source. You may connect a push button at GPIO 27 for shutdown and a status LED (with resistor) at GPIO 22 (gives light while communication is active). When you add the mysterygift executable to /etc/local.rc, e.g. nohup /home/pi/mysterygift &, mystery gift becomes active at start up. The station can be shut down by the push button at GPIO 27, thus it can run without any keyboard, monitor, or network connection.
* I have chosen them by instinct, so they may be somewhat less than perfect. However, you can find details in another posting below.
Demo of Mystery Gift Station
https://www.youtube.com/watch?v=sqk3Zm-s1eI
Cheating
It is possible to manipulate the item or decoration in the first payload to obtain rare items like BLUESKY MAIL or MIRAGE MAIL.
You may either solder a Mystery Gift Station and run it with a modified version of mysterygift.c. If you own two GBC and a flashcart, you may use a ROM that does the IR communication as you like: mysterygift_eng.gbc (see posting below for versions with German, French, Spain, or Italian translation).