Four Player Adapter improvements #608
Conversation
- Corrections and more detail about packet timing and RATE setting - Clarify meaning and timing of "reply" (a value loaded into SB for tx during the next transfer) - Add start transmission and ping restart indicators - Clarification about which consoles can trigger phase switches - Adapter power info
src/Four_Player_Adapter.md
Outdated
| where the Game Boys exchange data across the network. | ||
| connection status. Afterwards, the DMG-07 is switched to the transmission | ||
| phase where the Game Boys exchange data across the link cable network. | ||
| Later, connected Game Boys may restart the ping phase by sending specific |
There was a problem hiding this comment.
"specific commands" maybe can be more precise here? or link to afterwards?
There was a problem hiding this comment.
Good idea, I can rephrase it to mention the "ping restart sequence" and link to "Restarting Ping Phase".
src/Four_Player_Adapter.md
Outdated
| Later, connected Game Boys may restart the ping phase by sending specific | ||
| commands. | ||
|
|
||
| An important thing to note is that all Game Boys transfer data across |
There was a problem hiding this comment.
Maybe this should go in a "info box"?
There was a problem hiding this comment.
I'd carried that forward (with some edits) from the previous version, but thinking about it more, I don't think it needs so much urgency. Where the clock is sourced is more like basic spec material.
I'm going to try simplifying it and splitting it to a short "Clock Control" section after "Power". That and some changes might also reduce the redundancy noted in your comment on the "Ping Phase" intro.
|
|
||
| When the DMG-07 is powered up it will begin operation by automatically | ||
| sending out ping packets periodically on every port. In order to start | ||
| receiving these ping packets a connected Game Boy should use external |
There was a problem hiding this comment.
This seems like a repetition of the previous clock observation
There was a problem hiding this comment.
Per my reply to your info box comment, I'll try and reduce that repetition.
Co-authored-by: Rangi <[email protected]>
Co-authored-by: Antonio Vivace <[email protected]>
src/Four_Player_Adapter.md
Outdated
| After the DMG-07 finishes sending the indicator packet of \$FF bytes it will | ||
| immediately begin transmitting ping phase packets. | ||
|
|
||
| The following chart is an example of switching from transmission back to ping phase. |
There was a problem hiding this comment.
It feels like an introduction to the list is missing here?
The following chart [...] then a list is presented
There was a problem hiding this comment.
The list is setting up context that's needed to interpret the chart correctly, the kind of things that might normally be in a legend. Is there a preferred way of implementing that in pandocs? (and, in particular when the items are more general and less like singular item footnotes)
Here's a couple of ideas.
Collapsing some of the bullet points into the introductory sentence:
"The following chart is an example of switching from ping to transmission phase, here the packet size is 4 bytes and only the Player 1 Game Boy is connected." (and then converting the last item to a note style below the chart)
A try at additional lead-in:
"The chart below is an example of switching from transmission back to ping phase. When reading the chart use these conditions to interpret it."
Or, moving the bullet points to below the chart with a note:
"Use the following to interpret the chart above:"
src/Four_Player_Adapter.md
Outdated
|
|
||
| For example, say the packet size is 2 bytes; the flow of data for two consecutive | ||
| packets would look like this. | ||
| - The format shown for a player byte is P\[player num\].\[packet num\], so P3.1 is player 3, packet 1. |
There was a problem hiding this comment.
Same as the next comment, list here feels a bit confusing
There was a problem hiding this comment.
Made some changes as an attempt to address this the other charts. The lists are gone and replaced with a sentence or two, and a note at the bottom of the chart about how to interpret the Received and Reply columns.
This is a substantial overhaul of the DMG-07 Four Player Adapter content based on writing a working implementation for a game and doing logic analyzer captures of the hardware.
The main focus of the improvements are:
This is a first pass and in particular guidance on the following would be appreciated:
For feedback on how and where "reply" is defined: In the current documentation it's somewhat ambiguous and for me that made it harder to understand the docs and interface with the hardware until I figured it out.
The crux of the issue is the difference between these two ways of interpreting "reply" in this context:
To avoid that ambiguity I attached the following note to several of the diagrams/tables. I think this is a sub-optimal solution because it's repetitive and wordy.
column should be loaded into the [SB] register as a reply that will be transmitted
during the next serial transfer.
However repeating that note for diagrams/tables avoids the issue that someone might skip or not notice a terminology note at the top when looking at diagrams/tables much farther down in the document.