GBC Infrared Port Technical Documentation 0.2
July 16th, 2017
Shonumi aka D.S. Baxter


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

The Game Boy Color came with an infrared port on the very top of the handheld. Previously, where IR communications had to be done with special cartridges (like the HuC-1 variants), the Game Boy itself now had the hardware built-in. Contrary to many misconceptions, this feature was used in a number of games and accessories. The IR port essentially sends out signals and is also capable of receiving them, allowing for fast, wireless, line-of-sight transmission.


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

- GBC comes with one IR port. Capable of sending and receiving an IR signal (two separate diodes).
- Turning on the IR light does drain battery, hence not recommended to leave it on when not in use
- IR port can communicate with non-GBC devices, e.g. anything that sends an IR signal (TV remotes, Wiimotes, freaking household lamps, etc)


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

This list represents all the games that have been verified to use the IR port. While exhaustive, this list is probably not complete. There are likely more Japanese exclusives that need to be added. It's dubious whether or not Animorphs actually is a "Ubi Key" game. The back boxart doesn't have the "IR Compatible" logo, and the manual makes no mention of IR communication.

The North American version of Disney's Aladdin claims to have infrared support on the box, supposedly for Ubi Key functionality, however, no such option is accessible in the game. Additionally, European variants omit the GBC IR logo from their boxes. It's possible that games like Animorphs, Aladdin had its IR features stripped.

- The Adventures of the Smurfs				Exchange character portraits
- Animal Breeder 3					Matchmaking between animals raised by the player
- Animal Breeder 4					Exchange animals or have them marry
- Austin Powers: Oh Behave!				Trade items and messages		
- Austin Powers: Welcome to My Underground Lair!	Trade items and messages
- Bakuten Shoot Beyblade				Engage in 1-on-1 battles
- Beyblade: Fighting Tournament				Trade Beyblades + parts. Engage in 1-on-1 battles
- Boku no Camp-jou					Exchange money earned from hunting and fishing
- Bomberman B-Daman Bakugaiden V: Final Mega Tune	Obtain different armor from TV remote signals	
- Bomberman Max: Blue Champion				Combine Charaboms/Trade completed levels/Unlock hidden areas
- Bomberman Max: Red Challenger				Combine Charaboms/Trade completed levels/Unlock hidden areas
- Carl Lewis Alhletics 2000				Ubi Key -> Unlocks Decathalon mode
- Catz							Trade Petz and Toyz
- Chee-Chai Alien					Enhances IR sensor to detect artificial light sources. Catch/trade Chaliens
- Dancing Furby						Sends signal to Furby doll, Furby reacts based on dance performance
- Data Navi Pro Yakyuu					Send/Receive baseball team data
- Data Navi Pro Yakyuu 2				Send/Receive baseball team data
- Dogz							Trade Petz and Toyz
- Doki Doki Densetsu: Mahoujin Guru Guru		Fight card battles using magic circles from the game
- Donkey Kong Country					Transfer pictures to stickerbook
- Doraemon Memories - Nobita no Omoide Daibouken	Unlocks secret levels via TV remote input
- Dr. Rin Ni Kiitemite!					Do fortune-telling with a friend and exchange stickers
- Dungeon Savior					Transfer a Guardian from one game to another
- Flipper & Lopaka					Ubi Key -> Unlocks a bonus "Ubi Key Level"
- Game Boy Wars 3					Wireless multiplayer
- GB Harobots						Create new Robo Data via infrared signals
- Gran Duel: Shinki Dungeon no Hihou			Trade cards
- Gyouten Ningen Batseelor: Dakutoru Gai no Yabo	Exchange collectible stickers
- Hamster Paradise 3 (Churi)				Exchange e-mail
- Hamster Paradise 4					Exchange hamsters
- Hamtaro: Ham-Hams Unite!				Trade Hamtaro's clothes
- Harry Potter and the Sorceror's Stone			Trade "Famous Witches and Wizards" cards 
- Harry Potter and the Chamber of Secrets		Trade "Famous Witches and Wizards" cards 
- Herohero-kun						Exchange personal profiles
- Hunter x Hunter: Hunter no Keifu			Use "D-Trans" from Yu-Gi-Oh to meet Card Hunter Augu and unlock a hidden "Muuou" scenario
- Hype: The Time Quest					Ubi Key -> Unlocks a bonus level
- Inspector Gadget: Operation Madkactus			Ubi Key -> Unlocks a bonus level
- Jisedai Begoma Battle Beyblade			Trade Beyblades. "IR Kiss" functionality that copies "GB Kiss"
- Kaijin Zona						Receive randomized puzzles via IR signals
- Kakurenbo Battle Monster Tactics			Send/Receive Montaku. Wager Montaku via "takupon" game against another player
- Konchuu Hakase 2					Exchange collectible insects 
- Lego Island 2						Swap trading cards
- Lemmings VS						View Win/Loss records with other players
- Lode Runner: Dom Dom no Yabou				Exchange custom-made levels
- Looney Tunes Collector: Alert!			Wireless multiplayer for 3 minigames
- Looney Tunes: Marvin Strikes Back!			Wireless multiplayer for 3 minigames
- Love Hina Pocket					Trade custom-made stickers
- Mary-Kate and Ashley Pocket Planner			Send and receive "G-mail" messages
- Mickey's Racing Adventure				Send and receive messages. Unlocks a secret race track in Mickey's Speedway USA
- Mickey's Speedway USA					Communicates with Mickey's Racing Adventure to unlock a secret race track
- Mission Impossible					Send and receive messages, notes, addresses + custom TV remote
- NHL Blades of Steel					Trade individual hockey players
- NHL Blades of Steel 2000				Trade individual hockey players
- Papyrus						Ubi Key -> Unlocks a bonus level
- Perfect Dark						Trade multiplayer maps and other unlockables
- Playmobil Interactive: Laura				Ubi Key -> Unlocks "Catch the Hazelnuts" minigame
- Pocket Cooking					Exchange original dishes
- Pocket Family GB 2					Transfer characters and data
- Pocket Soccer						Trade individual soccer players
- Pokemon Pinball					Trade/combine Top Scores
- Pokemon Gold						Mystery Gift + Send trainer data to Viridian City Trainer House
- Pokemon Silver					Mystery Gift + Send trainer data to Viridian City Trainer House
- Pokemon Crystal					Mystery Gift + Send trainer data to Viridian City Trainer House
- Pokemon Trading Card Game				"Card Pop" to generate random cards. Trade individual cards. Trade deck configurations
- Pokemon Card GB2: Here Comes Team GR!			"Card Pop" to generate random cards. Trade individual cards. Trade deck configurations
- Qui Qui						Battle against another opponent
- Rayman						Ubi Key -> Unlocks secret level Ubi Cliff
- Return of the Ninja					Trade "Ninja Cards"
- Rugrats: Totally Angelica				Send/Receive messages, clothes, hairstyles, and accessories
- The Road to El Dorado					Ubi Key -> Unlocks a secret level similar to Levels 6 and 7
- Sakura Taisen GB					Send step-based "Points" to GBC from Pocket Sakura, or between two GBCs
- Shin Megami Tensei Devil Children White		Used for "Infrared Fusion" to strengthen some demons, obtain rare ones
- Soukoban Densetsu: Hikari to Yami no Yuni		Send/Receive custom-made levels/puzzles
- Spirou: The Robot Invasion				Ubi Key -> Unlocks a bonus level 
- Super Black Bass: Real Fight				Exchange items like lures and tackles
- Super Doll Licca-chan: Kisekae Daisakusen		Send/Receive clothes
- Super GALS! Juran					Exchange "sign cards" with personal information and messages written on them
- Super Mario Bros. DX					Trade/combine Top Scores
- Super Mimel GB: Mimel Bear no Happy Town		Send e-mails to other players from Mimel Bear and gain extra points
- Suzuki Alstare Extreme Racing				Ubi Key -> Unlocks the Extreme Championship mode
- Sweet Ange						Send/Receive mail, commemorative photos, cards, and recipes
- Taxi 2						Ubi Key -> Unlocks a special "Ubi Key" course
- Tonic Trouble						Ubi Key -> Unlocks a bonus level/demo
- Toonsylvania						Ubi Key -> Unlocks a bonus level with extra lives and items
- Tottoko Hamtaro: Tomodachi Daisakusen Dechu		Used for a "friend finding" feature, matches other players to different hamsters
- Tsuri Sensei 2					Trade items with other players
- V.I.P.						Ubi Key -> Unlocks a bonus "Ubi Key Level"
- Les Visiteurs						Ubi Key -> Unlocks a bonus "Ubi Key Level"
- Warlocked						Trade wizards
- Yu-Gi-Oh! Duel Monsters II: Dark Duel Stories		Connect to other players via "D-Trans" and receive special cards
- Zok Zok Heroes					Transmit "Cosmic Characters" from Full Changer accessory to transform hero

It should be noted that at least one game that uses the HuC-3 MBC, Pocket Family GB 2, is not in fact a "GB KISS" game. Instead, it uses the GBC's built-in IR hardware. A similar phenomenon can be seen with the Japanese release of Pokemon TCG (which used the HuC-1) versus releases for any other region (which use the GBC's native IR). Pocket Family GB 2 abandons the IR diodes on the HuC-3 PCB. At this point in time, Hudson may have finally decided to abandon GB KISS and the HuC-1 and HuC-3's IR features as they were redundant, especially for games designed to run exclusively on the GBC.

Although Hudson eventually adopted the GBC's native IR functionality over the HuC-1 and HuC-3, one of their games continued to offer GB KISS-like features. Jisedai Begoma Battle Beyblade calls its version "IR Kiss", however, it's mostly an exact copy of the standard GB KISS interface capable of sending and receiving files or messages. This remains incompatible with previous GB KISS titles due to the different positioning of the IR diodes in the GBC and HuC-1/HuC-3. As far as it is known, Hudson never developed IR Kiss after Jisedai Begoma Battle Beyblade.


***************************************************
4. IR Communication Types
***************************************************

While a number of games may use similar formats for their IR communications, there is no "standard" protocol that all games use. IR communication is entirely determined by the game's code, hence it can vary wildly depending on needs. However, all communications fall into one of several general categories as described below:

- 1-Player Init: These only require one GBC to initiate IR transfers. Both GBCs typically wait for an infrared signal. When one player presses a button, the GBC starts sending pulses. This setup is not unlike how 2-Player Serial I/O is handled (with master and slave Game Boys). Examples include Super Mario Bros. DX score exchange and the GBC-to-GBC Mystery Gifts in Pokemon Gold/Silver/Crystal. Most IR compatible games fall into this group.

- 2-Player Init: Transfers require both GBCs to initiate at roughly the same time. Examples include Pokemon Pinball score exchange, Pokemon TCG's "Card Pop", and trading/fighting Charaboms in the Bomberman games.

- Active Object Init: Transfers require the GBC to interact with another non-GBC device capable of both sending and receiving infrared signals. These objects are designed to work specifically with GBCs and send pulses in much the same manner as a GBC would. Examples include Mystery Gifts via the Pokemon Pikachu 2 and trading Points via the Pocket Sakura.

- Inactive Object Init: Transfers require the GBC to interact with another non-GBC device capable of sending infrared signals but not necessarily receiving them. These objects may not be designed to work specifically with GBCs (notable exception is the Full Changer). Communication is input-only for these cases. Examples include Zok Zok Heroes, Chee Chai Alien, the Bomberman Max games' special stages, and Mission Impossible's TV remote feature.


***************************************************
5. IR Protocol
***************************************************

Again, there is no set or established infrared protocol that games must follow. Many games vary in their approach. For example, the 2nd Generation Pokemon games use the GBC's hardware timers, while others have hardcoded values that count cycles to check timing. The simplest form is a barebones communication protocol, i.e. something like a binary Morse code where a "0" is a long ON-OFF pulse and "1" is a short ON-OFF pulse or vice versa. Properly done, data could have been short, compact, and easily converted into bytes in RAM. Sakura Taisen GB seems to follow this model in its communications with the Pocket Sakura. Not all games do this, however, and appear to be doing who knows that, opting instead for customized and specialized communications unique to each title. To illustrate this idea, it would be possible to use a table of given lengths of IR ON-OFF pulses so that individual bytes could be sent all at once instead of in a binary, bit-by-bit manner. A number of games try to send a few pulses when pressing input like the A button and wait for another GBC to echo that in response, but after the handshake, most of the IR pulses are impossible to understand without disassembling the code.

One thing to note is that 4 games in particular do share somewhat similar IR protocols, at least in regards to the initial handshake between 2 GBCs. They are Pokemon TCG 1 & 2 and Bombermax Red & Blue, all from the "2-Player Init" category above. Typically, IR capable GBC games will continually wait for an IR signal on both sides, i.e. the "1-Player Init" category. When one player presses certain input, that GBC takes the initiative and sends out a few IR pulses. That is to say, for most IR games, it only takes *just one* player to start the entire process.

The handshake for the 4 games previously mentioned, however, requires *both* players to input at almost the same time. One has to be slightly faster or slower than the other. Each side continually sends a few IR pulses, then reads the sensor to see if anything was received. If so, the GBCs begin to sync. The idea is that one side should be sending while the other is checking, and then the handshake completes. This is why one side needs to be faster or slower to input; if they are sending IR signals at the same time, they don't see anything when reading the sensor. As a result, both GBCs cannot input at exactly the same time. Practically speaking, this is unlikely to happen under normal circumstances, since most humans can't synchronize their actions down to a handful of microseconds, so the handshake will normally succeed.

The following is just theory. This handshake is possibly an artifact of the HuC-1. Consider that the Japanese version of Pokemon TCG 1 used the HuC-1 for its IR communications, and the developers may have borrowed the "best practices" used by other HuC-1/"GB KISS" games. When bringing Pokemon TCG 1 overseas, the IR handling code was likely minimally adapted to use the GBC's IR port, with the underlying protocol remaining unchanged in most regards. Pokemon TCG 2 ditched the HuC-1 in favor of the GBC IR port, so the IR code from non-Japanese versions of Pokemon TCG 1 was copy+pasted. The Bomberman games were made by Hudson Soft, literally the same people who created the HuC-1 in the first place. They too probably used the same protocol that had worked forever in their "GB KISS" games, so they used the same handshake method as before, just on the GBC IR port now. More research into the HuC-1 itself and the games needs to be done to confirm any of this.


***************************************************
6. RP Register
***************************************************

On the GBC, the MMIO register located at 0xFF56 controls infrared communication. Simply known as "RP" (Radiation Port? Reception Port? Red Port???), it is responsible for sending and receiving IR signals. Below is a diagram of the 8-bit register:

Bit 0:		Turn IR light ON (1) or OFF (0)					(R/W)
Bit 1:		IR signal (0 = Receiving signal) (1 = Normal/No signal)		(R)
Bits 2-5:	Unused
Bits 6-7:	Signal Read Enable (0 = Disable) (3 = Enable)			(R/W)

Turning on the IR light is as simple as writing to Bit 0 of RP. Reading is a bit more complicated. Bits 6 and 7 must both be set (0xC0), to read Bit 1, otherwise Bit 1 returns 1, acting as if no signal is detected, except in edge cases detailed below in "Obscure Behavior". With signal reading enabled, Bit 1 will determine the status of any incoming IR signals. Like other Game Boy MMIO registers, unused bits read high (set to 1).


***************************************************
7. IR Signal Fade
***************************************************

The IR sensor in the GBC adapts to the current level of IR light. That is to say, if the GBC receives a sustained IR signal beyond a certain amount of time, eventually the sensor treats this as a new "normal" level of IR light, and Bit 1 of RP goes back to 1. This is called the signal "fade" because it may appear as if the signal disappears.

Signal fade time is dependent on length and has an inverse relationship with the distance between a GBC and the IR light. The closer a GBC is to the IR source, the longer the fade time. The farther away a GBC is to the IR source, the shorter the fade time. One possible explanation for everything is that the IR signal is weaker on the receiving end, so the signal is prone to get "lost" to surrounding noise. The GBC IR sensor is probably good at sending IR signals (evidenced by the Mission Impossible cheat to turn a GBC into a TV remote) but not so good at picking up signals (evidenced by Chee Chai Aliens plastic add-on to enhance IR reception).

At about 3.0 to 3.5 inches (7.62 to 8.89cm) signal fade time appears to be around 3ms. Optimal distance seems to be 2.5 to 4.0 inches (6.35 to 10.16cm) to maintain a fade time close to 3ms and avoid potential miscommunication. One oddity of note is that putting two GBCs very close together (physically touching) produced unusually short fade times, far shorter than 3ms. There may be some sort of interference at that range.


***************************************************
8. Obscure Behavior
***************************************************

The RP register has one very strange quirk. Disabling Bits 6 and 7 and then subsequently re-enabling them causes Bit 1 to go to zero under certain conditions. In other words, the IR sensor will act as if it is detecting a signal if reading the signal is disabled then enabled. It seems this behavior happens in the presence of any light; covering up the sensor during the read signal disable/enable causes the sensor to act normally. It's possible that the sensor resets itself (to its lowest level of detection???) and immediately detects any infrared sources, even from ambient/environmental light. The presence of any noise may temporarily trick the sensor into "seeing" IR light. By abusing this behavior, the GBC has some rudimentary ability to gauge the type of nearby lighting:

--------------------------------------------------------------------------------------------
Result of 1st RP Write (0x00)	Result of 2nd RP Write (0xC0)	Type of Lighting	
--------------------------------------------------------------------------------------------
Bit 1 = 1			Bit 1 = 1			Dark
Bit 1 = 0			Bit 1 = 1			Ambient
Bit 1 = 0 (sometimes 1)		Bit 1 = 0			Bright

Writing 0x00 to RP, followed by 0xC0 will trigger these results listed above. One very important thing to note is that when enabling Bits 6 and 7 (writing 0xC0), it does take some time for the sensor to register legitimate IR light coming into the sensor. I.e. if you want to use this method to detect what kind of light a GBC is looking at, the software needs to loop for a bit until Bit 1 of RP changes. Generally a few hundred cycles in double-speed mode will suffice. If Bit 1 of RP remains 1 after the loop, it's safe to assume the lighting is either ambient or dark. This delay doesn't seem to happen when Bits 6 and 7 are never disabled (which is what most official GBC software does). Games typically write either 0xC0 or 0xC1 to RP, with a small handful setting it to 0x00 initially when setting up other MMIO registers (Pokemon G/S/C does this).

The downside to this method is that when detecting a bright IR source, the sensor quickly adjusts to this new level, and the next attempt at writing 0x00 followed by 0xC0 to RP will result in readings of dark or ambient (typically dark though). Essentially the bright result only appears briefly when transitioning from lower levels of light, then it "disappears" thanks to the short time it takes for IR signal fade. Designing a game mechanic (darkness and light) around this quirk is still possible, although it would require careful thought and planning to properly work around the observed limitations.

One suggested method: once the Bright setting is detected, switch to writing only 0xC0 to RP so that the IR sensor works normally. If IR light stops being detected, switch to alternating 0x00 and 0xC0 writes as described above to determine Dark or Ambient settings. Whether it's practical or not to do this in a game remains theoretical at this point.


***************************************************
9. Pokemon Pikachu 2
***************************************************

The Pokemon Pikachu 2 (PP2) is a virtual pet device similar in concept to Tamagotchis. The PP2 is the successor to the original Pokemon Pikachu with a number of notable changes, largely the new color screen and the ability to communicate with Pokemon Gold, Silver, and Crystal via IR signals. These signals are used for the Mystery Gift functionality. Unlike normal Mystery Gifts between two GBCs, which produce random items, the PP2 gives out consistent items based on the number of "watts" transferred. The "watts" are the PP2's form of currency generated by the unit's pedometer (via walking, or more commonly, just shaking). Players either give Pikachu watts to make it happy, or send them to another PP2, or use them to Mystery Gift with Pokemon G/S/C.

In addition to giving out predictable items via Mystery Gift, the PP2 can also Mystery Gift without time limits. Normally, when two GBCs Mystery Gift 5 times in Pokemon G/S/C, players have to wait until the following day to try again. No such restriction applies when a GBC communicates with the PP2. The two can Mystery Gift endlessly, as long as the PP2 has watts to transfer. Below is a table of watts and the items they generate:

0 - 99 Watts		Eon Mail
100 - 199 Watts		Berry
200 - 299 Watts		Bitter Berry
300 - 399 Watts		Great Ball
400 - 499 Watts		Max Repel
500 - 599 Watts		Ether
600 - 699 Watts		Miracle Berry
700 - 799 Watts		Gold Berry
800 - 899 Watts		Elixir
900 - 998 Watts		Revive
999 Watts		Rare Candy

Current analysis of the IR communications between a GBC and a PP2 indicates that the PP2 interacts with Pokemon Crystal differently in comparison to Pokemon Gold and Silver. Each transfer appears to be 2007 ON-OFF transitions long.


***************************************************
10. Pocket Sakura
***************************************************

The Pocket Sakura is another virtual pet device similar to the Pokemon Pikachu 2. Design-wise, it is a copy+paste version of the PP2, except it's pink. Interestingly enough, the Pocket Sakura was made by Media Factory, the same people behind Zok Zok Heroes and the Full Changer device. The Pocket Sakura uses a pedometer to make Sakura travel to various locations and meet other Sakura Taisen-based characters. When resting at a location, the pedometer turns steps into "points" (10 steps = 1 point), which can then be sent to a GBC running Sakura Taisen GB or another Pocket Sakura.

Each transfer appears to be 1607 ON-OFF transitions long.
