The Joybus Protocol - ZadenRB/OpenGCC_Firmware GitHub Wiki

Overview

Joybus is the protocol used by the N64, Game Boy Advance, and GameCube to communicate with controllers. This page focuses on Joybus as it relates to GameCube controllers, but be sure to check out Additional Reading below for more info on N64 and Game Boy Advance implementations.

Hardware

Joybus operates over a single 3.3V bi-directional open-collector data line. This means the data line is at 3.3V normally, and the console or controller pulls it down to 0V, then releases it to 3.3V as needed to transmit data. The circuit diagram below demonstrates the simple hardware involved, with the horizontal wire representing the data line between controller and console.

Joybus Schematic

Each bit begins with the data line pulled low. How long the line is held low determines if the bit is a 0 or a 1. For a 0, the line is held low for 75% of the bit, and let high for the final 25%. For a 1, the line is held low for 25% of the bit, and let high for the final 75%. Additionally, the "stop bit" sent by the controller to indicate the end of a transfer is low for 50%, and high for the final 50% of the bit. The controller stop bit is low for 33%, and high for 66%.

You'll notice these high and low states are described in terms of percentages. This is because bit lengths vary - 0 and 1 bits sent by the console last 5us (5 millionths of a second), while the console stop bit is only 3us. All bits sent by the controller are 4us in length. Additionaly, while modern controller adapters will send bits that are precisely 5us in length, real consoles (and to a lesser extent, OEM controllers) aren't as accurate with their timing (my Wii's bits are more like 4.3us each). In practice, it's best to leave some buffer, and consider a bit high or low based on the data line's value halfway through the theoretical bit length. For reference, below is the ideal shape of each bit, where each major grid line is 1us.

Joybus Bits

Protocol

Basics

Because Joybus operates over a single data line, the console and controller cannot both transmit simultaneously. Instead, the controller sends a command, and the controller processes it and responds with the appropriate data. A generic transaction is outlined below. Future diagrams will not include stop bits and will follow the same color key.

Joybus Generic Transaction

Commands

There are 5 distinct commands the console will send to a GameCube controller. Each command consists of the command byte, and some commands send additional bytes (Command Length > 1). The table below provides a quick reference of the commands.

Command Command Code Command Length Response Length
Identify 0x00 1 3
Short Poll 0x40 3 8
Read Origin 0x41 1 10
Calibrate 0x42 3 10
Long Poll 0x43 3 10
Reset 0xFF 1 3

Command Descriptions

This flowchart provides a brief overview of each command's content and function. Keep in mind that the controller response (in blue) will always occur after the full command is sent, and the flowchart is simply ordered by when each command byte is sent. The following sections give a more thorough explanation of each command.

Commands Overview

Identify (0x00)

Identify is sent by the console to poll for a connected controller. When a controller receives this command, it responds with its 2-byte device identifier, allowing the console to distinguish between a GameCube controller and DK Bongos or other controller types, then a 1-byte status. A GameCube controller is identified by 0x9000, and OEM controllers send 0x03 for their status byte.

Short Poll (0x40)

Poll is sent by the console to read the controller state. This command also sends two additional bytes after the command itself.

The second byte determines the format of the controller state that the controller should respond with. There are 5 modes, requested by 0x00, 0x01, 0x02, 0x03, and 0x04. If the second byte is a value greater than 0x04, the controller will respond as if it was 0x00 (unconfirmed).

The third byte controls the controller's rumble motor. It ranges from 0x00 to 0x03, where bit 0 determines whether the controller should enable rumble, and bit 1 tells the controller whether rumble is already active. So, 0x00 means rumble is off and should remain off, 0x01 means rumble is off and should be turned on, 0x02 means rumble is on and should turn off, and 0x03 means rumble is on and should remain on.

Read Origin (0x41)

Read Origin is sent by the console after it identifies a connected controller. When a controller receives this command, it sets its origin bit to 0 (explained in Controller State and responds with its state in Mode 5. It is used to determine the zero-state of a controller, which the controller provides using Mode 5. Future reads of the controller are processed with analog values offset from the state of the controller provided in response to the Read Origin command. This functionality is what allows trigger-tricking and causes your stick to drift if you are holding it in a particular direction when plugging in your controller.

Calibrate (0x42)

Calibrate is sent by the console to tell the controller to calibrate itself. When a controller receives this command, it recalibrates itself (if applicable) and responds with its state in Mode 5.

Long Poll (0x43)

Long Poll is sent by the console to request the full state of a connected controller. When a controller receives this command, it responds with its state in Mode 5.

Reset (0xFF)

Reset is sent by the console to tell the controller to reset its internal state. When a controller receives this command, it should reset its state (if applicable) and then provide the same response as it would to the Identify command.

Controller State

A GameCube controller's state represents the users current inputs, as well as whether the controller has provided its origin to the console. In order to support other controller types, all GameCube input devices present a 1-byte analog A & B state, but for GameCube controllers these values are always zero. The specific format of the data sent varies by data mode, but generally consists of two bytes giving button states and origin state, followed by one byte for each analog value in the order: left stick X, left stick Y, right stick X, right stick Y, left trigger, right trigger, analog A, analog B. Each data mode below has a graphical representation of its state, which may be easier to understand.

Data Modes

In response to polling commands, the controller may send its state in a variety of formats (data modes) based on the console's request. There are 5 total modes. Modes 0-4 are used in response to the Short Poll (0x40) command based on the value of its second byte, and Mode 5 is used in response to Read Origin (0x41), Calibrate (0x42), and Long Poll (0x43). The diagrams in each data mode show how it formats controller state. Each row in the diagrams is one byte, and state is sent from top to bottom. The key below identifies each symbol in the diagrams. In some cases, these symbols are combined with bit shift operations to indicate that only the top nibble of a piece of state is sent.

State Symbol
Origin Bit O
Start Button S
Y Button Y
X Button X
B Button B
Left Trigger Button LB
Right Trigger Button RB
Left Stick X LX
Left Stick Y LY
Right Stick X RX
Right Stick Y RY
Left Trigger Analog LT
Right Trigger Analog RT
A Analog AA
B Analog AB
Mode 0

Used in response to a Short Poll (0x40) with 0x00 as the second byte.

Mode 0

Mode 1

Used in response to a Short Poll (0x40) with 0x01 as the second byte.

Mode 1

Mode 2

Used in response to a Short Poll (0x40) with 0x02 as the second byte.

Mode 2

Mode 3

Used in response to a Short Poll (0x40) with 0x03 as the second byte. This is the most commonly used data mode.

Mode 3

Mode 4

Used in response to a Short Poll (0x40) with 0x04 as the second byte.

Mode 4

Mode 5

Used in response to Read Origin (0x41), Calibrate (0x42), and Long Poll (0x43).

Mode 5

Communication Flowchart

A typical communication between the console and controller consists of an Identify command, followed by a Read Origin and any number of polling commands. This is visualized below.

Communication Flowchart

Additional Reading

⚠️ **GitHub.com Fallback** ⚠️