dreamcast.wiki - User contributions [en]

Maple bus

2026-01-29T13:58:41Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 50 Hz (PAL) or 60 Hz (NTSC) frame (every 20 or 16.7 ms) until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3 to 255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3 to 255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2 to 255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4 or 36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..254
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-35 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2026-01-29T13:58:14Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 50 Hz (PAL) or 60 Hz (NTSC) frame (every 20 or 16.6 ms) until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3 to 255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3 to 255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2 to 255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4 or 36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..254
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-35 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T19:07:16Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3 to 255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3 to 255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2 to 255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4 or 36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..254
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..254
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-35 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T19:05:13Z

Tails86: /* Non-OEM Commands */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..256]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..256]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..256]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4 or 36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-35 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T17:50:51Z

Tails86: /* Game ID Payload Structure (cmd 0x21) */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..256]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..256]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..256]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4..36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-35 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T17:49:35Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..256]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..256]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..256]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4..36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Words 4-36 (optional)
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T17:40:26Z

Tails86: /* Game ID Payload Structure (cmd 0x21) */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4..36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..3 !! Words 4..36
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String (optional)
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T17:31:25Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4..36]] || 0x07
|}

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..3 !! Words 4..36
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T17:28:42Z

Tails86: Added VM2/WMUPro Game ID command

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

===== Non-OEM Commands =====

The following lists non-OEM commands supported by third party devices such as VM2 and VMUPro.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x21 || Game ID || Host->Device || [[Maple_bus#Game_ID_Payload_Structure_.28cmd_0x21.29|4..36]] || 0x07
|}

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Game ID Payload Structure (cmd 0x21) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..3 !! Words 4..36
|-
| [[Maple_bus#Function_Codes|Function code]] || Game ID bytes || Game Name String
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-12-06T01:43:29Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 0: Region code <br> Byte 1: Connection direction code <br> Bytes 2 and 3: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-02-15T06:48:10Z

Tails86: /* Commands */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|3..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2025-02-15T06:47:52Z

Tails86: /* Data Transfer Payload Structure (cmd 0x08) */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

VMU peripheral

2025-02-03T00:31:07Z

Tails86:

The VMU peripheral on the [[Maple_bus|Maple Bus]] contains 3 functions: screen, storage, and timer.

'''NOTE:''' Some information here is misleading and/or incomplete

== Storage ==

The "block read" and "block write" commands (0x0B and 0x0C) with storage function code are used to read and write blocks of memory in the storage peripheral.

Normally, there are 256 blocks of memory that make up the entire storage space, and normally each block consists of 512 bytes. That makes a total of 128 KB of memory. These values are configurable according to the Maple Bus spec, but anything other than these values is not practically usable by most games due to many high-level APIs and libraries within the SDKs not adhering properly to the Maple spec and making hardcoded assumptions about the volume information.<ref>''[https://www.dreamcast-talk.com/forum/viewtopic.php?f=5&t=15562&p=171565] TapamN | 400 block VMU on emulator''</ref>

=== Function Definition ===
The function definition may be found in the peripheral's [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|device info packet]]. It is necessary to read this word to know how to access blocks of memory on the storage.
{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| bit 7: removable (1: true)<br>bit 6: CRC (1: needed)<br>bits 0-5: unused (0) || bits 4-7: number of write accesses per block<br>bits 0-3: number of read accesses per block || number of bytes per block<br>(x + 1)*32 bytes || number of partitions (x + 1)
|}

=== Get Media Info ===
Execute a [[Maple_bus#Commands|get memory information]] command to get information about the size and locations of some information within the media. On successful execution, a [[Maple_bus#Commands|data transfer]] packet with the following payload will be returned.

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Word 2 !! Word 3 !! Word 4 !! Word 5 !! Word 6
|-
| [[Maple_bus#Function_Codes|Function code]] <br> 0x00000002 || 2 most sig bytes: total size <br> 2 least sig bytes: the partition number of this media || 2 most sig bytes: block number of system area <br> 2 least sig bytes: block number of start of FAT area || 2 most sig bytes: number of FAT blocks <br> 2 least sig bytes: block number of file information || 2 most sig bytes: number of file info blocks <br> 2 least sig bytes: icon number || 2 most sig bytes: block number of save area <br> 2 least sig bytes: number of blocks in save area || execution file info
|}

=== Block Read ===
Execute a sequence of [[Maple_bus#Commands|block reads]] to read data from storage. The number of sequences is dependent on the number of read accesses per block defined in the function definition above. On successful execution, a [[Maple_bus#Commands|data transfer]] packet will be returned.

=== Block Write ===
Execute a sequence of [[Maple_bus#Commands|block writes]] to write data to storage. The number of sequences is dependent on the number of write accesses per block defined in the function definition above. On successful execution, a [[Maple_bus#Commands|acknowledge]] packet will be returned. After the final write sequence, execute a [[Maple_bus#Commands|get last error]] command with an incremented phase value to commit the block from RAM to storage.
* A VMU cannot handle successive block write packets faster than about 10 ms per write
** After such error, the storage functionality acts as if it never received this sequence and never returns a response packet - it may be possible to successfully resend this sequence, but writing a "get last error" command would be necessary before starting over at the first sequence
** The Dreamcast does each read/write sequence on the same cadence as controller polling (about every 16 ms)

== Screen ==

The "block write" command (0x0C) with screen function code and 48 data words is used to write monochrome images to the screen. The payload of this command should look like the following.
{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..49
|-
| [[Maple_bus#Function_Codes|Function code]] <br> 0x0000000C || [[Maple_bus#Location_Word|Location word]] <br> 0x00000000 || Screen data
|}

A screen is 48 bits wide and 32 bits tall. For each bit in the 48 data words, a value of 1 means the pixel is on (black) and 0 means the pixel is off (white). Data is written from left to right and top to bottom (when holding the VMU in the upright orientation i.e. controller flipped upside down). The most significant bit of the first word sets the pixel on the top, left of the screen. The two most significant bytes write to the 33rd through 48th bit of the first row. The next two bytes write to the 1st through 16th bits of the second row. This is repeated for the rest of the 48 words like pictured below.

[[File:Dreamcast Screen Words.png|Dreamcast Screen Words]]

== Timer ==

The timer function allows the host to activate the buzzer on the VMU and get button conditions.

== References ==
<references />

Maple bus

2024-03-10T22:56:20Z

Tails86: /* Light Gun CRT Beam Detection Sequence */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 milliseconds for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-03-10T19:47:51Z

Tails86: /* Light Gun CRT Beam Detection Sequence */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan either only odd lines or the entire screen, depending on how the specific game is coded. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 16.68 for half or 33.37 milliseconds for full. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-02-10T02:11:12Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines and horizontal retrace takes 10 microseconds per line, the time window for each pixel on a 60 Hz screen is about 83.6 nanoseconds. If beam detection only occurs in the last 16.68 milliseconds, the shot won't count, and the Dreamcast may also flag the light gun as faulty. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-02-04T02:42:32Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 99 nanoseconds. If beam detection only occurs in the last 16.68 milliseconds, the shot won't count, and the Dreamcast may also flag the light gun as faulty. If no beam is detected, meaning SDCKB remains HIGH throughout the entire period, then the game normally treats this as a gun reload event.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-02-04T02:38:52Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 99 nanoseconds. A beam detection must occur within the first 16.68 milliseconds or the shot won't count, and the Dreamcast may also flag the light gun as faulty.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-02-04T02:34:38Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements both Controller and either Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 99 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-02-04T02:33:30Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

This mode is only activated when the main peripheral implements Gun or AR Gun [[Maple_bus#Function_Codes|function code]]. Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 99 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-01-27T22:05:53Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Data Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-01-27T15:25:38Z

Tails86: /* Peripheral Implementation */

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

* [[Controller peripheral]]
* [[VMU peripheral]]
* [[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-01-27T15:25:05Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== Peripheral Implementation ==

Refer to the following pages for a specific peripheral implementation.

[[Controller peripheral]]
[[VMU peripheral]]
[[Jump pack peripheral]]

== References ==
<references />

Maple bus

2024-01-27T14:55:25Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the [[Maple_bus#Word_Format|word format]] section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-27T14:51:55Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref> For the communication direction, Host implies the Dreamcast and Device implies a peripheral.

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-27T14:43:58Z

Tails86: Light gun does not hold down SDCKB - it only stays low for the period that the beam is in view of the lens

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. Once the Dreamcast brings SDCKA back HIGH, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-23T02:15:25Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== Data Packet End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection Sequence ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Talk:VMU peripheral

2024-01-23T02:04:32Z

Tails86: I typed the wrong frequency

I played around with the VMU buzzer control through the maple bus and came to the conclusion that it is probably referencing a clock frequency that is too high in this mode (seems like 1 MHz). All I can play are high pitched tones. I also can't remember off the top of my head any games which used this feature.

Talk:VMU peripheral

2024-01-22T03:40:04Z

Tails86: Created page with "I played around with the VMU buzzer control through the maple bus and came to the conclusion that it is probably referencing a clock frequency that is too high in this mode (seems like 2732 Hz). All I can play are high pitched tones. I also can't remember off the top of my head any games which used this feature."

I played around with the VMU buzzer control through the maple bus and came to the conclusion that it is probably referencing a clock frequency that is too high in this mode (seems like 2732 Hz). All I can play are high pitched tones. I also can't remember off the top of my head any games which used this feature.

User talk:Tails86

2024-01-21T22:36:25Z

Tails86: Blanked the page

User talk:Tails86

2024-01-21T22:35:52Z

Tails86: Created page with "This image is incorrect - there should be no end sequence"

This image is incorrect - there should be no end sequence

Maple bus

2024-01-21T22:33:43Z

Tails86: I was mistaken - no end sequence is sent on Light Gun CRT Beam Detection

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. No end sequence is sent after this is completed.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

File:Light Gun CRT Beam Detect.png

2024-01-21T22:32:23Z

Tails86: Tails86 uploaded a new version of File:Light Gun CRT Beam Detect.png

Shows the bit sequence for light gun positioning on a CRT screen

Maple bus

2024-01-21T21:16:46Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. A normal end sequence is then sent by the Dreamcast.

The duration of time given for beam detection is the time it takes to scan the entire screen. For a 60 Hz screen (59.94 Hz actual) displaying 480i, this is about 33.36 milliseconds. Assuming a composite signal actually scans 525 lines, the time window for each pixel on a 60 Hz screen is about 97 nanoseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T19:18:55Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. A normal end sequence is then sent by the Dreamcast.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For a 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T19:11:02Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the period of time marked blue in the image below once it detects that the electron beam of a CRT is in view of the light gun's lens. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. A normal end sequence is then sent by the Dreamcast.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T19:09:25Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun. A normal end sequence is then sent by the Dreamcast.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

File:Light Gun CRT Beam Detect.png

2024-01-21T19:08:19Z

Tails86: Tails86 uploaded a new version of File:Light Gun CRT Beam Detect.png

Shows the bit sequence for light gun positioning on a CRT screen

Maple bus

2024-01-21T18:51:34Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB LOW within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held LOW by the light gun until after Dreamcast brings SDCKA back HIGH. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T18:31:51Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low by the light gun until after Dreamcast brings SDCKA back high. At that point, SDCKB must be brought back HIGH, and the control of SDCKB must be let go by the light gun.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T18:28:04Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for position detection of the electron beam for a specific pixel on a CRT monitor which the light gun is currently aiming at.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low by the light gun until after Dreamcast brings SDCKA back high. At that point, SDCKB must be brought back HIGH and the control of SDCKB must be let go by the light gun.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T18:25:03Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for light gun triggering.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low by the light gun until after Dreamcast brings SDCKA back high. At that point, SDCKB must be brought back HIGH and the control of SDCKB must be let go by the light gun.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|Light Gun CRT Beam Detect]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T18:24:31Z

Tails86: Better describe light gun timing

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== Light Gun CRT Beam Detection ===

The start sequence for light gun CRT beam detection looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for light gun triggering.

Dreamcast initiates this sequence to a light gun once the Dreamcast detects that the trigger (A button) has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the within the period of time marked blue in the below image once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low by the light gun until after Dreamcast brings SDCKA back high. At that point, SDCKB must be brought back HIGH and the control of SDCKB must be let go by the light gun.

The duration of time given for beam detection lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Light Gun CRT Beam Detect.png|thumb]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

File:Light Gun CRT Beam Detect.png

2024-01-21T18:16:01Z

Tails86:

Shows the bit sequence for light gun positioning on a CRT screen

Maple bus

2024-01-21T03:17:04Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== SDCKB Occupancy ===

The SDCKB occupancy start sequence looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for light gun triggering. Dreamcast initiates this sequence to a light gun once Dreamcast detects that the trigger has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the SDCKB Occupancy once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low until after Dreamcast brings SDCKA back high.

The SDCKB occupancy lasts for a little longer than the time it takes to scan the entire screen. For 60 Hz screen displaying 480i, this is a little longer than 33.3 milliseconds.

[[File:Maple Bus SDCKB Occupancy.png|Maple Bus SDCKB Occupancy]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />

Maple bus

2024-01-21T03:11:04Z

Tails86:

The Maple bus is the communications bus the Dreamcast uses to connect controllers and other related peripherals. It is a symmetrical serial protocol.

== Hardware Overview ==

[[File:Dreamcast Port.png|thumb|Dreamcast Port]]

Four separate Maple Buses exist on a Dreamcast system - one for each player. Each Maple Bus consists of 2 signal/clock lines that are labeled SDCKA and SDCKB. Hardware on the Maple Bus consists of one host, zero or one main peripheral, and zero to five sub-peripherals. The only difference between a main peripheral and a sub-peripheral is that a main peripheral communicates to the host what sub-peripherals are attached during normal communication. The main peripheral is something like a Dreamcast controller, and the sub-peripherals are things like a VMU, jump pack, and microphone. The host and all connected peripheral devices communicate on the same 2-line Maple Bus.<ref name="MBNutshell">''[https://tech-en.netlify.app/articles/en540236/index.html] Geek Tech Report | Maple BUS in a nutshell or SEGA Dreamcast Peripherals how to make''</ref> Devices are powered with 5V from the host, and signals on the Maple Bus operate at 3.3V TTL.<ref name="raphnet">''[https://www.raphnet.net/programmation/dreamcast_usb/index_en.php] Raphaël Assenat | Dreamcast controller to USB build log''</ref>

[[File:Maple Bus Electronics Block Diagram.png|frameless|500px|Maple Bus Electronics Block Diagram]]

* Both lines on the Bus are pulled HIGH through weak pullup resistors
* Only one connected component on the bus may communicate at a time
* During communication, a device should not drive both lines HIGH for very long to prevent a downstream device from thinking the bus is free
* Before a component starts communicating, it must verify the bus is neutral for a sufficient amount of time
* A peripheral device will only communicate 1 packet of data in response to a request from the host<ref name="MBNutshell" />

[[File:Maple Bus Hardware Communication.png|frameless|600px|Maple Bus Hardware Communication]]

=== Sense ===

The Dreamcast does not rely on any sense line as some projects implement.<ref name="raphnet" /><ref>''[http://mc.pp.se/dc/controller.html] Dreamcast Programming - Controllers''</ref><ref>''[https://hackaday.com/2021/03/16/dreamcast-controller-adapter-even-works-with-mice/] Lewin Day | DREAMCAST CONTROLLER ADAPTER EVEN WORKS WITH MICE''</ref> Both ground wires from the controller are tied to ground at the controller port module on the Dreamcast. To detect the presence of a device, Dreamcast instead sends a device info request every 16 ms until a main peripheral responds on the bus.

== Maple Bus Signals ==

There is no handshaking done to determine how fast each component may transmit on the Maple Bus. Transmission speeds are internally pre-determined by each hardware component. Generally speaking, for all signals, the minimum amount of time between an edge (transition between logic levels) of one line and an edge of the other is about 125 nanoseconds. The minimum amount of time between edges on the same line is about 225 nanoseconds.<ref name="MBMeasurements">''[https://github.com/OrangeFox86/DreamcastControllerUsbPico/tree/main/measurements] Tails86 | DreamcastControllerUsbPico Maple Bus Measurements''</ref> There is no maximum time limit as long as both lines aren't held HIGH during active transmission for any extended amount of time. These guidelines may be applied for any sequence below.

=== Data Packet Start Sequence ===

[[File:Maple Bus Start Sequence.png|thumb|Maple Bus Start Sequence]]

Every data packet begins with a start sequence.

# SDCKA is brought LOW
# SDCKB is toggled 4 times
# SDCKA is then brought back HIGH to complete the sequence<ref name="MBWireProtocol">''[http://mc.pp.se/dc/maplewire.html] Marcus Comstedt | Dreamcast Programming - Maple Bus Wire Protocol''</ref>
<br>

=== End Sequence ===

[[File:Maple Bus End Sequence.png|thumb|Maple Bus End Sequence]]

Every packet is completed with an end sequence to commit the data to the target component.

# SDCKA is brought HIGH
# SDCKB is toggled HIGH then LOW
# SDCKA is toggled 2 times
# SDCKB is brought back HIGH to complete the sequence<ref name="MBWireProtocol"/>
<br><br><br><br><br><br>

=== Data Bit Sequences ===

[[File:Maple Bus Clocking Phases.png|thumb|Maple Bus Clocking Phases]]

For each bit, one line of the maple bus acts as a clock while the other is the data to be sampled. A data bit is clocked when the designated clock line transitions from HIGH to LOW. The two lines trade their function after each bit. Line '''A''' acts as clock and '''B''' acts as data for the first bit. Line '''B''' acts as clock and '''A''' acts as data for the next bit. Line '''A''' acts as clock again for the bit after that. The pattern repeats until all data is transmitted.

Each bit transmission sequence can be broken down into 3 phases<ref>''[https://archive.org/details/MaplePatent/mode/1up]Maple Bus Patent''</ref>:
* Phase 1 - Clock Conditioning: Bring clock HIGH and keep data at the state it was previously
* Phase 2 - Data Conditioning: Transition the data bit to the target value
* Phase 3 - Clocking: Bring clock LOW in order to have the data bit sampled

There are a total of 6 types of state transitions, depending on what the previous phase was and the target bit value. A depiction of state transitions can be seen in the image below.

[[File:Maple Bus Data.png|Maple Bus Data]]

Notice that each line, A & B transitions states in a staggard pattern i.e., only one line may change its logic level within each phase. Because of the staggard pattern, the minimum time between an edge of one line and an edge of the other is 1 phase length, and the minimum time between edges on the same line is the sum of the time of 2 phases. The total bit transmission time is of course the sum of the time of all 3 phases.

* The Dreamcast host transmits each phase at about 160 nanoseconds<ref name="MBMeasurements" />
** This works out to be about 2 mbps raw data transfer speed
* Dreamcast controllers and other peripheral devices usually transmit a little slower at about 250 nanoseconds per phase and sometimes with about 110 to 130 microsecond delays between each 4-word chunk after the first frame word<ref name="MBMeasurements" />
** This works out to between about 0.5 and 1.3 mbps raw data transfer speed

=== SDCKB Occupancy ===

The SDCKB occupancy start sequence looks similar to a data packet start sequence, but 8 pulses on the SDCKB line signify the start of this mode. This mode is used to gain precise timing for light gun triggering. Dreamcast initiates this sequence to a light gun once Dreamcast detects that the trigger has been pressed through normal data packet sequences. The light gun is expected to bring SDCKB low within the SDCKB Occupancy once it detects that the electron beam of a CRT is in view of the lens of the light gun. SDCKB is then held low until after Dreamcast brings SDCKA back high.

[[File:Maple Bus SDCKB Occupancy.png|Maple Bus SDCKB Occupancy]]

=== Reset Sequence ===

A reset sequence may be sent from the host in order to attempt to reset all devices on the bus. It is similar to a start sequence, but there are 14 pulses on SDCKB.

[[File:Maple Bus Reset Sequence.png|Maple Bus Reset Sequence]]

== Maple Bus Packet ==

This section contains information about the packet structure inherent to the Maple Bus. Any data transmission follows this packet structure.

=== Word Format ===

Each word is 32 bits in length, transmitted in little-endian byte order. The most significant bit of each byte transmits first. This means that the most significant bit of the least significant byte of each word transmits first. All tables in this wiki list bytes in transmission order with the least significant bit (LSB) as the first byte.

When ASCII text or a byte stream is transmitted, the most significant byte is the first character of the 4 character sequence in each word. This means that the byte order of each word needs to be flipped before parsing the payload as a character or byte array. The size of an ASCII payload section is pre-determined based on the command. No NULL termination byte is supplied at the end of the string, and spaces (0x20) are used to pad out remaining characters at the end of the string.

=== Packet Data Format ===

A packet consists of the following data.

* '''[[Maple_bus#Frame_Word|Frame]]:''' 1 32-Bit Word
* '''[[Maple_bus#Payload|Payload]]:''' 0 to 255 32-Bit Words
* '''[[Maple_bus#CRC|CRC]]:''' 1 Byte
==== Frame Word ====

The following is how a frame word is broken down into its 4 parts<ref name="DPMapleBus">''[http://mc.pp.se/dc/maplebus.html] Marcus Comstedt | Dreamcast Programming - Maple Bus''</ref>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| <div style="text-align: center;">Number of Words<br>in Payload</div> || <div style="text-align: center;">Sender<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">Recipient<br>[[Maple_bus#Addressing|Address]]</div> || <div style="text-align: center;">[[Maple_bus#Commands|Command]]</div>
|}

example:

[[File:Frame Word.png|Frame Word Example]]

===== Addressing =====

The following addresses are used for all components on the bus.

{| class="wikitable"
|-
! Player Number !! Host !! Main Peripheral !! Sub-Peripheral 1 !! Sub-Peripheral 2 !! Sub-Peripheral 3 !! Sub-Peripheral 4 !! Sub-Peripheral 5
|-
| 1 || 0x00 || 0x20* || 0x01 || 0x02 || 0x04 || 0x08 || 0x10
|-
| 2 || 0x40 || 0x60* || 0x41 || 0x42 || 0x44 || 0x48 || 0x50
|-
| 3 || 0x80 || 0xA0* || 0x81 || 0x82 || 0x84 || 0x88 || 0x90
|-
| 4 || 0xC0 || 0xE0* || 0xC1 || 0xC2 || 0xC4 || 0xC8 || 0xD0
|}

<nowiki>*</nowiki>When the main peripheral responds with its sender address, it also sets the bits corresponding to which sub-peripherals are attached. For example, if sub-peripherals 1 and 2 are attached to player 1's main peripheral, the main peripheral will set its sender address to 0x23. This informs the host what else is attached. The host should still set the recipient address to 0x20 when sending data to this peripheral though.

In testing, there have been cases where a peripheral will respond with a sender address as if it is player 1. As such, the host should ignore whatever the upper 2 bits that the device uses as its sender address.

===== Commands =====

Below shows command values and their meanings.<ref name="DPMapleBus"/><ref name="DCDocs">''[https://github.com/Kochise/dreamcast-docs/tree/master/CONTROLR/DOCS] Dreamcast Documents''</ref>

{| class="wikitable"
|-
! Command Value !! Description !! Communication Direction !! Number of Payload Words !! Expected Response**
|-
| 0x01 || Device Info Request* || Host->Device || 0 || 0x05
|-
| 0x02 || Extended Device Info Request || Host->Device || 0 || 0x06
|-
| 0x03 || Reset || Host->Device || 0 || 0x07
|-
| 0x04 || Shutdown || Host->Device || 0 || 0x07
|-
| 0x05 || Device Info || Device->Host || [[Maple_bus#Device_Info_Payload_Structure_.28cmd_0x05.29|28]] || -
|-
| 0x06 || Extended Device Info || Device->Host || [[Maple_bus#Extended_Device_Info_Payload_Structure_.28cmd_0x06.29|48]] || -
|-
| 0x07 || Acknowledge || Device->Host || 0 || -
|-
| 0x08 || Data Transfer || Device->Host || [[Maple_bus#Data_Transfer_Payload_Structure_.28cmd_0x08.29|2..255]] || -
|-
| 0x09 || Get Condition || Host->Device || [[Maple_bus#Get_Condition_Payload_Structure_.28cmd_0x09.29|1]] || 0x08
|-
| 0x0A || Get Memory Information || Host->Device || [[Maple_bus#Get_Memory_Information_Payload_Structure_.28cmd_0x0A.29|2]] || 0x08
|-
| 0x0B || Block Read || Host->Device || [[Maple_bus#Block_Read_Payload_Structure_.28cmd_0x0B.29|2]] || 0x08
|-
| 0x0C || Block Write || Host->Device || [[Maple_bus#Block_Write_Payload_Structure_.28cmd_0x0C.29|3..255]] || 0x07
|-
| 0x0D || Get Last Error || Host->Device || [[Maple_bus#Get_Last_Error_Payload_Structure_.28cmd_0x0D.29|2]] || 0x07
|-
| 0x0E || Set Condition || Host->Device || [[Maple_bus#Set_Condition_Payload_Structure_.28cmd_0x0E.29|2..255]] || 0x07
|-
| 0xF9 || AR Error || Device->Host || 0 || -
|-
| 0xFA || LCD Error || Device->Host || 0 || -
|-
| 0xFB || File Error || Device->Host || 0 || -
|-
| 0xFC || Request Resend || ANY || 0 || Last Sent Command
|-
| 0xFD || Unknown Command || Device->Host || 0 || -
|-
| 0xFE || [[Maple_bus#Function_Codes|Function code]] Not Supported || Device->Host || 0 || -
|}

<nowiki>*</nowiki>Most peripheral devices won't respond to any other command until device info is requested for the device.

<nowiki>**</nowiki>This is the expected response when device didn't experience an error

==== Payload ====

The structure of a payload is dependent on the command used in the frame word.

===== Device Info Payload Structure (cmd 0x05) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption****
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Extended Device Info Payload Structure (cmd 0x06) =====

{| class="wikitable"
|-
! Word 0 !! Words 1-3 !! Word 4 !! Words 5-11 !! Words 12-26 !! Word 27 !! Words 28-47
|-
| Supported [[Maple_bus#Function_Codes|function codes]] mask* || Function definitions for up to 3 devices** || Byte 3 (MSB): Region code <br> Byte 2: Connection direction code <br> Bytes 1 and 0: first two characters of description ASCII string*** || The rest of the description ASCII string*** || Producer information ASCII string*** || 2 most significant bytes: standby current consumption <br> 2 least significant bytes: maximum current consumption**** || Version information and/or capabilities ASCII string***
|}

<nowiki>*</nowiki>The supported function codes mask in device info responses will contain the bitmask for 1 or more devices ex: a VMU will have a mask of 0x0000000E for Timer, Screen, and Storage.

<nowiki>**</nowiki>The first word in this set is meant for the most significant bit that is set to 1 in the function codes word

<nowiki>***</nowiki>Refer to the word format section about how to parse ASCII strings.

<nowiki>****</nowiki>Current values in (x / 10) mA, each two byte value is transmitted as big-endian

===== Data Transfer Payload Structure (cmd 0x08) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Data - device dependent structure
|}

===== Get Condition Payload Structure (cmd 0x09) =====

{| class="wikitable"
|-
! Word 0
|-
| [[Maple_bus#Function_Codes|Function code]]
|}

===== Get Memory Information Payload Structure (cmd 0x0A) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]*
|}

<nowiki>*</nowiki>Only the partition number should be set in the location word. Set all other bytes in the location word to 0.

===== Block Read Payload Structure (cmd 0x0B) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Block Write Payload Structure (cmd 0x0C) =====

{| class="wikitable"
|-
! Word 0 !! Word 1 !! Words 2..255
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]] || Data - device dependent structure
|}

===== Get Last Error Payload Structure (cmd 0x0D) =====

{| class="wikitable"
|-
! Word 0 !! Word 1
|-
| [[Maple_bus#Function_Codes|Function code]] || [[Maple_bus#Location_Word|Location word]]
|}

===== Set Condition Payload Structure (cmd 0x0E) =====

{| class="wikitable"
|-
! Word 0 !! Words 1..255
|-
| [[Maple_bus#Function_Codes|Function code]] || Condition - device dependent structure
|}

===== Common Payload Word Types =====

The following word types are used in some of the above payload structures.

====== Function Codes ======

The below are function codes which are used to address functionality in some payloads<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Code / Mask !! Description
|-
| 0x00000001 || Controller
|-
| 0x00000002 || Storage
|-
| 0x00000004 || Screen
|-
| 0x00000008 || Timer
|-
| 0x00000010 || Audio Input
|-
| 0x00000020 || AR Gun
|-
| 0x00000040 || Keyboard
|-
| 0x00000080 || Gun
|-
| 0x00000100 || Vibration
|-
| 0x00000200 || Mouse
|}

====== Location Word ======

Below defines a location word which is used to address blocks of memory in some peripherals<ref name="DPMapleBus"/>.

{| class="wikitable"
|-
! Byte 0 (LSB) !! Byte 1 !! Byte 2 !! Byte 3 (MSB)
|-
| Block LSB || Block MSB || Phase || Partition
|}

* '''Block''': Memory block number index
* '''Phase''': Sequence number (starts at 0 and counts up)
* '''Partition''': Partition number (normally 0)

==== CRC ====

CRC byte transmits last, just before the end sequence is transmitted. It is the value after starting with 0 and applying XOR against each byte in the packet.

== References ==
<references />