Skip to content

Commit b556b65

Browse files
asiekierkaavivace
asiekierka
and
avivace
authored
Add 4-Player Adapter documentation, adapted from Dan Docs. (#328)
* Add 4-Player Adapter documentation, adapted from Dan Docs. * Final improvements Co-authored-by: Antonio Vivace <[email protected]>
1 parent f6bf1e9 commit b556b65

File tree

2 files changed

+198
-0
lines changed

2 files changed

+198
-0
lines changed

‎src/Four_Player_Adapter.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# 4-Player Adapter
2+
3+
The 4-Player Adapter (DMG-07) is an accessory that allows 4 Game Boys
4+
to connect for multiplayer via [serial data transfer](./Serial_Data_Transfer_(Link_Cable).md).
5+
The device is primarily designed for DMG consoles, with later models
6+
requiring Link Cable adapters.
7+
8+
## Communication
9+
10+
The DMG-07 protocol can be divided into 2 sections, the "ping" phase, and
11+
the "transmission" phase. The initial ping phase involves sending packets
12+
back and forth between connected Game Boys probing for their current
13+
connection status. Afterwards, the DMG-07 enters into transmission mode
14+
where the Game Boys exchange data across the network.
15+
16+
A very important thing to note is that all Game Boys transfer data across
17+
the DMG-07 via an external clock source. Apparently, the clock source is
18+
provided by the DMG-07 itself. Trying to send data via an internal clock
19+
results in garbage data.
20+
21+
### Ping Phase
22+
23+
When a "master" Game Boy (Player 1) is first connected to the adapter,
24+
setting Bit 7 of SC to 1 and setting Bit 0 of SC to 0 causes the accessory
25+
to send out "ping" packets periodically. All connected Game Boys will
26+
receive 4 bytes as part of the ping packet at a rate of about 2048 bits
27+
per second, or about 256 bytes per second. Essentially, the ping seems to
28+
run 1/4 as fast as the clock used for normal serial transfers on the DMG
29+
(1KB/s). The ping data looks like this:
30+
31+
Byte | Value | Description
32+
-----|-------|-------------
33+
1 | 0xFE | ID Byte
34+
2 | 0x?? | STAT1
35+
3 | 0x?? | STAT2
36+
4 | 0x?? | STAT3
37+
38+
3 "STAT" bytes are sent indicating the current connection status of the other
39+
Game Boys. Each byte is usually the same, however, sometimes the status can
40+
change mid-way through a ping, typically on STAT2 or STAT3. Each STAT byte
41+
looks like such:
42+
43+
Bit | Name
44+
----|------------------------
45+
7 | Player 4 Connected
46+
6 | Player 3 Connected
47+
5 | Player 2 Connected
48+
4 | Player 1 Connected
49+
0-2 | Player ID (1-4)
50+
51+
The Player ID's value is determined by whichever port a Game Boy is connected
52+
to. As more Game Boys connect, the upper bits of the STAT bytes are turned on.
53+
54+
When talking about Game Boys and the "connection", this refers to a Game Boy
55+
properly responding to STAT1 and STAT2 bytes when receiving a ping packet from
56+
the DMG-07. In this way, the Game Boy broadcasts across the Link Cable network
57+
that it is an active participant in communications. It also acts as a sort of
58+
acknowledgement signal, where software can drop a Game Boy if the DMG-07
59+
detects an improper response during a ping, or a Game Boy simply quits the
60+
network. The proper response is to send 0x88 *after* receiving the ID Byte and
61+
STAT1, in which case the upper-half of STAT1, STAT2, and STAT3 are updated to
62+
show that a Game Boy is "connected". If for whatever reason, the
63+
acknowledgement codes are not sent, the above bits are unset.
64+
65+
Some examples of ping packets are shown below:
66+
67+
Packet | Description
68+
----------------------|-------------------------------------------------------
69+
`0xFE 0x01 0x01 0x01` | Ping packet received by Player 1 with no other Game Boys connected.
70+
`0xFE 0x11 0x11 0x11` | Ping packet received by Player 1 when Player 1 has connected.
71+
`0xFE 0x31 0x31 0x31` | Ping packet received by Player 1 when Players 1 & 2 have connected.
72+
`0xFE 0x71 0x71 0x71` | Ping packet received by Player 1 when Players 1, 2, & 3 have connected.
73+
`0xFE 0x62 0x62 0x62` | Ping packet received by Player 2 when Players 2 & 3 are connected (but not Player 1).
74+
75+
It's possible to have situations where some players are connected but others
76+
are not; the gaps don't matter. For example, Player 1 and Player 4 can be
77+
connected, while Player 2 and Player 3 can be disconnected (or non-existant,
78+
same thing); most games do not care so long as Player 1 is active, as that
79+
Game Boy acts as master and orchestrates the multiplayer session from a
80+
software point of view. Because of the way the DMG-07 hardcodes player IDs
81+
based on which port a Game Boy is physically connected to, in the above
82+
situation Player 4 wouldn't suddenly become Player 2.
83+
84+
During the ping phase, the master Game Boy is capable of setting up two
85+
parameters that will be used during the transmission phase. The clock rate for
86+
the transmission phase can be adjusted, as well as the packet size each Game
87+
Boy will use. The master Game Boy needs to respond with one byte for STAT2
88+
and STAT3 respectively. The chart below illustrates how a master Game Boy
89+
should respond to all bytes in a ping packet:
90+
91+
```
92+
----------------------------
93+
DMG-07 Game Boy
94+
----------------------------
95+
0xFE <--> (ACK1) = 0x88
96+
STAT1 <--> (ACK2) = 0x88
97+
STAT2 <--> (RATE) = Link Cable Speed
98+
STAT3 <--> (SIZE) = Packet Size
99+
```
100+
101+
The new clock rate is only applied when entering the transmission phase; the
102+
ping phase runs at a constant 2048 bits-per-second. The formula for the ne
103+
clock rate is as follows:
104+
105+
```
106+
DMG-07 Bits-Per-Second --> 4194304 / ((6 * RATE) + 512)
107+
```
108+
109+
The lowest setting (RATE = 0) runs the DMG-07 at the normal speed DMGs usually
110+
transfer data (1KB/s), while setting it to 0xFF runs it close to the slowest
111+
speed (2042 bits-per-second).
112+
113+
SIZE sets the length of packets exchanged between all Game Boys. Nothing fancy,
114+
just the number of bytes in each packet. It probably shouldn't be set to zero.
115+
116+
### Transmission Phase
117+
118+
When the master Game Boy (Player 1) is ready, it should send 4 bytes
119+
(`0xAA 0xAA 0xAA 0xAA`, if those are actually required should be investigated further).
120+
This alerts the DMG-07 to start the transmission phase. The RATE and SIZE parameters
121+
are applied at this point. The protocol is simple: Each Game Boy sends a packet to
122+
the DMG-07 simultaneously, then the DMG-07 outputs each packet to all connected
123+
Game Boys. All data is buffered, so there is a 4 packet delay after each Game
124+
Boy submits their data (the delay is still 4 packets long even if some Game Boys
125+
are not connected). For example, say the packet size is 4 bytes; the flow of
126+
data would look like this when sending:
127+
128+
P1 send | P2 send | P3 send | P4 send | Transfer count
129+
--------------|---------------|---------------|---------------|-----------------------------
130+
P1 (byte 1) | P2 (byte 1) | P3 (byte 1) | P4 (byte 1) | 0
131+
P1 (byte 2) | P2 (byte 2) | P3 (byte 2) | P4 (byte 2) | 1
132+
P1 (byte 3) | P2 (byte 3) | P3 (byte 3) | P4 (byte 3) | 2
133+
P1 (byte 4) | P2 (byte 4) | P3 (byte 4) | P4 (byte 4) | 3
134+
0 | 0 | 0 | 0 | 4 (Typically supposed to be zero, but DMG-07 ignores anything here)
135+
0 | 0 | 0 | 0 | 5
136+
0 | 0 | 0 | 0 | 6
137+
0 | 0 | 0 | 0 | 7
138+
0 | 0 | 0 | 0 | 8
139+
0 | 0 | 0 | 0 | 9
140+
0 | 0 | 0 | 0 | 10
141+
0 | 0 | 0 | 0 | 11
142+
0 | 0 | 0 | 0 | 12
143+
0 | 0 | 0 | 0 | 13
144+
0 | 0 | 0 | 0 | 14
145+
0 | 0 | 0 | 0 | 15
146+
147+
And when receiving, the flow of data would look like this:
148+
149+
P1 receive | P2 receive | P3 receive | P4 receive | Transfer count
150+
--------------|---------------|---------------|---------------|-----------------------------
151+
P1 (byte 1) | P1 (byte 1) | P1 (byte 1) | P1 (byte 1) | 16
152+
P1 (byte 2) | P1 (byte 2) | P1 (byte 2) | P1 (byte 2) | 17
153+
P1 (byte 3) | P1 (byte 3) | P1 (byte 3) | P1 (byte 3) | 18
154+
P1 (byte 4) | P1 (byte 4) | P1 (byte 4) | P1 (byte 4) | 19
155+
P2 (byte 1) | P2 (byte 1) | P2 (byte 1) | P2 (byte 1) | 20
156+
P2 (byte 2) | P2 (byte 2) | P2 (byte 2) | P2 (byte 2) | 21
157+
P2 (byte 3) | P2 (byte 3) | P2 (byte 3) | P2 (byte 3) | 22
158+
P2 (byte 4) | P2 (byte 4) | P2 (byte 4) | P2 (byte 4) | 23
159+
P3 (byte 1) | P3 (byte 1) | P3 (byte 1) | P3 (byte 1) | 24
160+
P3 (byte 2) | P3 (byte 2) | P3 (byte 2) | P3 (byte 2) | 25
161+
P3 (byte 3) | P3 (byte 3) | P3 (byte 3) | P3 (byte 3) | 26
162+
P3 (byte 4) | P3 (byte 4) | P3 (byte 4) | P3 (byte 4) | 27
163+
P4 (byte 1) | P4 (byte 1) | P4 (byte 1) | P4 (byte 1) | 28
164+
P4 (byte 2) | P4 (byte 2) | P4 (byte 2) | P4 (byte 2) | 29
165+
P4 (byte 3) | P4 (byte 3) | P4 (byte 3) | P4 (byte 3) | 30
166+
P4 (byte 4) | P4 (byte 4) | P4 (byte 4) | P4 (byte 4) | 31
167+
168+
Again, due to buffering, data output to the DMG-07 is actually delayed by
169+
several transfers according to the size of the packets. All connected Game
170+
Boys should send their data into the buffer during the first few transfers.
171+
Here, the packet size is 4 bytes, so each Game Boy should submit their data
172+
during the first 4 transfers. The other 12 transfers don't care what the
173+
Game Boys send; it won't enter into the buffer. The next 16 transfers return
174+
the packets each Game Boy previously sent (if no Game Boy exists for player,
175+
that slot is filled with zeroes).
176+
177+
With the buffering system, Game Boys would normally be reading data from
178+
previous packets during transfers 0-15, in addition to sending new packets.
179+
Likewise, during transfers 16-19 each Game Boy is sending new packets. In
180+
effect, while receiving old data, Game Boys are supposed to pump new data into
181+
the network.
182+
183+
When the DMG-07 enters the transmission phase, the buffer is initially filled
184+
with garbage data that is based on output the master Game Boy had sent during
185+
the ping phase. At this time, it is recommended to ignore the earliest packets
186+
received, however, it is safe to start putting new, relevant data into the
187+
buffer.
188+
189+
### Restarting Ping Phase
190+
191+
It's possible to restart the ping phase while operating in the transmission
192+
phase. To do so, the master Game Boy should send 4 or more bytes
193+
(`0xFF 0xFF 0xFF 0xFF`, it's possible fewer 0xFF bytes need to be sent,
194+
but this has not been extensively investigated yet). The bytes alert the DMG-07
195+
that the ping phase should begin again, after which it sends ping packets after
196+
a brief delay. During this delay, the transmission protocol is still working as
197+
intended until the switch happens.

‎src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272

7373
- [Game Boy Printer](./Gameboy_Printer.md)
7474
- [Game Boy Camera](./Gameboy_Camera.md)
75+
- [4-Player Adapter](./Four_Player_Adapter.md)
7576
- [Game Genie/Shark Cheats](./Shark_Cheats.md)
7677

7778
# Other

0 commit comments

Comments
 (0)