Joybus Protocol

The Joybus Protocol is a proprietary, non-standard, serial protocol by which the N64's Serial Interface (as well as the GameCube and Game Boy Advance) communicates with controllers, controller accessories (Controller Pak, Rumble Pak, etc.), keyboards, mice, game cartridges, and other devices plugged into the console.

= Operation = The protocol utilizes four types of bits: Zero, One, the Console Stop Bit, and the Controller Stop Bit. Zero, One, and the Controller Stop Bits are 4μs long, while the Console Stop Bit is 3μs. Communication is always initiated by the console, by sending an 8 bit (one byte) command to the device plugged in (not necessarily always a standard controller). A Console Stop Bit will usually follow after this command byte unless there is more data.

The controller or device will read this command and any extra data, and then respond appropriately. For example, when the console wishes to write to a Controller Pak, it will send 0x03, followed by a 2 byte address, 32 bytes of data, and then the stop bit.

The default state of the data pin is HIGH. If the connected device isn't in the process of sending a signal, it should not default to sending a HIGH signal (either set to LOW for reading, high-impedance, or disconnect). Wrongly setting the pin HIGH may disrupt the console and will prevent intermediate devices from reading any console signals.

= Command List = Because all commands are exactly 8 bits long, there can be a total of 256 commands. However, only about 16 are known for the N64, and a few more for GameCube and Game Boy Advance. Games also have the ability to define custom commands with or without extra data, but official controllers or devices will not understand them.

$(1)$ Real Time Clock

$(1)$ Requires verification, might be offset by one.

= Command Details =

0xFF - Reset / Info
While identical to 0x00 in what data is returned to the console, if a device has an intended reset function, it should be performed when this command is sent. The N64 controller for example will reset the internal position of its analog stick to (0, 0), essentially recalibrating it. Other devices may have similar functionality, or none at all, but either way they should still send back the same data as if the 0x00 command was sent.

0x00 - Info
This command requests information about the device. The N64 a 2-byte identifier and 1 byte of extra data. The N64 Controller is the only confirmed device to use the 3rd byte, where 0x02 is used if no pak is inserted, and 0x01 is there is. Other devices must still be investigated further. $(1)$ Requires verification yet.

0x01 - Controller State
The response for this command is always the same length of 4 bytes (32 bits), but the data it represents will change depending on the type of controller device. A Controller Stop Bit is always included after the response bytes. ''Note that in the following waveform diagrams, any LOW bit should send a Zero Bit as described in the operation section above. Do not hold the line LOW constantly.''

Standard Controller
The most common is the standard N64 controller. In which case, the data is the current state of the inputs from the controller: the 14 buttons, the current position of the analog stick, and the reset (RST) bit. The default state of buttons and RST is Zero. If a button is pressed, it becomes One. If LT, RT, and Start are pressed, RST is One, Start becomes Zero, and the analog stick's position is reset to (0, 0). Each axis of the analog stick is a Two's Complement byte, giving a decimal value ranging from -128 to +127, even though a standard controller may not reach the full range due to physical limitations. The bit order from left to right, of the response data, is as follows:



Mouse
The mouse follows a similar format to the standard controller. However, it only uses the A and B buttons, and the x/y axis bytes represent the relative position of the mouse.



Densha de Go
The game Densha de Go! used an exclusive train controller instead of the standard tri-wing controller. It had five buttons, and two multi-position levers. Refer to the right image for corresponding positions and values for each lever.



( refers to the accelerator lever)

Other Devices
While more devices exist that use this command, specific response information is not known at this time.

0x02 - Read Controller Accessory
Reading data from Paks connected to the bottom of a controller, is performed by the console sending this command plus two bytes. These bytes contain an 11 bit address, and a 5 bit checksum which is explained in the next section. The address used is still 16 bits long, however the lower 5 bits will be zeros, meaning addresses can only point to blocks of 32 bytes.

The controller will attempt to read 32 bytes from the Pak starting at the provided address. Upon returning the data bytes, a CRC byte is also returned (also explained below). It must begin responding with data within about 62.5 microseconds.

0x03 - Write Controller Accessory
Similar to reading from a Pak, the write command is followed by two bytes for the address and checksum. But 32 bytes are also provided for writing to the Pak. The controller is still required to respond with a CRC byte for the received data, and it must begin responding within about 62.5 microseconds.

How the Pak interprets the address and data is up to the Pak in question. The Controller Pak ignores the most significant address bit (the corresponding pin is not physically connected to anything). The Rumble Pak appears to use some kind of flip-flop/toggling logic on certain pins to control it. The Transfer Pak is a gameboy cartridge interface with bank switching. Other homebrew Paks could be utilized in many other ways too.

0x04 - Read EEPROM Block
If EEPROM is available, this command can be used to read 8 bytes of save data at a time. The command (`0x04`) is followed by which block of EEPROM to read from:

In a 512 byte EEPROM, the top two bits of block number are ignored: blocks 64-255 are repeats of the first 64

0x05 - Write EEPROM Block
If EEPROM is available, this command can be used to write 8 bytes of save data at a time. See "Read EEPROM Block" above for block addressing rules. The 8 bytes of data to write are included in the command immediately following the "block" byte. It may take up to 30 milliseconds for the data to be written to EEPROM.

Real EEPROM data storage has inherent unreliability that requires special consideration: EEPROM chips may become corrupted spontaneously due to uncontrollable factors such as power failure during write or memory cell fatigue causing write failures. It is recommended to use a checksum or parity bits in each EEPROM block to check that the data has not been corrupted. EEPROMs used by retail cartridges are rated for up to 100,000 write cycles and may only retain saved data for up to 10 years. Emulators and flashcarts now provide reliable storage for EEPROM commands that do not suffer from these issues.

0x06 - Real-Time Clock Info
In order to permit using both an EEPROM and the RTC at the same time, the RTC does not respond to command 0, and has its own identify command.

If RTC (Real-Time Clock) is available, this command will return a 2 byte identifier (0x0010) and a status byte. If RTC is not available, this command will respond with three bytes containing zero.

0x07 - Read Real-Time Clock Block
The RTC read command sends 2 bytes (1 for the command, 1 for block selection) and responds with 8 bytes of block data plus a status byte that has the same meaning as the "RTC Info" command's status byte.

The RTC has three blocks each containing 8 bytes of data:

The top six bits of the block number are ignored: reading from or writing to blocks above the first 4 will wrap within the first four.

All RTC reads also include a status byte with the same meaning as the "RTC Info" command's status byte.

RTC Block 0 (Control Registers)
Byte 0:

Byte 1:

Bytes 2, 3, 6, and 7 always read back as 0.

Bytes 4 and 5 contain 7- and 6- bit numbers respectively that can be updated but have no visible function.

RTC Block 1 (SRAM)
RTC block 1 is not used by Animal Forest, and is not implemented by emulators or flashcarts.

RTC Block 2 (Date/Time)
RTC block 2 updates once per second with 8 bytes of data representing the current date and time. The fields are encoded using packed binary-coded decimals:

RTC Block 3 (Empty)
RTC block 3 always reads back all zeroes.

0x08 - Write Real-Time Clock Block
The RTC write command sends 10 bytes (1 for the command, 1 for block selection, and 8 for the block data) and responds with a status byte that has the same meaning as the "RTC Info" command's status byte. The block data to write matches the same format as the block read responses in "Read RTC Block" above.

The most-compatible routine for setting the time with the Joybus Real-Time Clock is:
 * 1) Send "Write RTC Block" command to Control Registers (Block 0) with write protect disabled and clock stopped (0x0004...).
 * 2) Wait 20 milliseconds for RTC block to write.
 * 3) Send "Read RTC Status" command, check for "Stopped" (0x80) status: if stopped, proceed; otherwise abort.
 * 4) Send "Write RTC Block" command to Date/Time Fields (Block 2) with new time to set.
 * 5) Wait 20 milliseconds for RTC block to write.
 * 6) Send "Write RTC Block" command to Control Registers (Block 0) with write protect enabled and clock running (0x0300...).
 * 7) Poll "RTC Read Status" command until "Running" (0x00) status.
 * 8) Wait 500 milliseconds before sending "RTC Read Block" command to Date/Time Fields (Block 2)

Emulator and flashcart support for writing to the Real-Time Clock is not guaranteed:
 * Most emulators will ignore RTC write commands and always use the host system's local time.
 * EverDrive 64 3.0 and EverDrive64 X7 will ignore Joybus RTC write commands; date/time must be set through the Everdrive OS.
 * 64drive hw2 supports Joybus RTC writes, but requires a 500 millisecond delay after setting the time in order to read it back correctly.

For homebrew, it is recommended to test whether the RTC implementation supports the write command to set the proper expectation with players. To do this:
 * 1) Read the current RTC time.
 * 2) Write a different time to the RTC.
 * 3) Read the new RTC time.
 * 4) If the new time is within a second of what was written: write back the original time, success; otherwise failure.

= Checksums = There are two different checksums used in some of the official commands. The first is an 8 bit CRC, and the other uses eleven different XOR values based on the position of each set bit. While the former is used for large chunks of data, the latter is used to check the 11 bit address for where that data is written to or read from. These checksums are used to ensure data integrity. The address checksum, which is 5 bits long, is always a part of the communication sent from the console to the device, just after the 11 bit address.

Data CRC
The 8 bit CRC known to be used in the controller accessory read/write commands, and the GBA read/write commands. It uses a standard CRC8 function, with a seed (initial value) of 0x00, and 0x85 for the polynomial. A CRC polynomial is a mathematical way to say that a particular number is used as a mask, or to be applied to the working CRC byte using an XOR operation. The mathematical form can be expressed as $$x^7 + x^2 + x^0$$.

In every known case, the connected device is always the side which generates this CRC. For read commands, it reads 32 bytes of data from a particular address, calculates the CRC, and sends all 32 bytes plus the CRC byte back to the console. For write commands, it calculates the CRC from the 32 bytes sent by the console, sends the CRC byte back, and performs the write operation. The order in which it does this may differ for different devices. For write commands, the device has a window of approx 62.5 microseconds after the console stop bit, to begin sending the CRC byte.

Address Checksum
When the console wishes to read data from, or write data to, a particular address on the connected device, it will send the top 11 bits of a 16 bit address, plus a 5 bit checksum. This means these operations must be done in 32 byte chunks, as the lower 5 bits of the address are assumed to be 0, to make room for the checksum. By definition, this checksum is not a CRC, because it doesn't use a cyclic code (as in, there is no bit shifting used), and the XOR value is not constant.

The 5 bit checksum is calculated using the following table. The working checksum is initially set to zero. For each bit of the 11 address bits, starting at the upper-most bit, if the bit is set (is 1), then XOR the corresponding byte to the working checksum. If the bit is clear (is 0), do nothing and move onto the next bit. If the resulting checksum matches the one provided by the console, the address is valid.

The process as pseudocode: for bits 15 -> 5 if the bit is set xor the checksum with the corresponding value in the above table