As of September 16, 2024, the Xbox One controller protocol (known officially as the Gaming Input Protocol, or GIPUSB) has been published as a Microsoft open standard. This document is thus no longer necessary, and certainly not accurate. Refer to the documentation there for guidance on the protocol.
The original document here is preserved as-is, and will not receive any further updates.
The Xbox One controller protocol is quite in-depth. This is a collection of all the information I've gathered over time about it, most of which is sourced from medusalix's xone driver for Linux. There's a little bit of my own research/reverse engineering in there too, but a majority of the information comes from xone.
The info here refers to the USB/wireless side of things, it does not fully apply to the interface the Xbox One controller driver on Windows exposes. That interface is covered here. The wireless receiver protocol is also not documented here, as that's its own beast to handle.
Struct definitions and code examples are not guaranteed to be valid C/C++ code, and are meant mainly for efficiently defining how things are structured or handled. All structs are assumed to be packed with 1-byte alignment.
- Basic Infrastructure
- Protocol Command Details
- TODO Commands
- Where are
0x09and0x20?
Individual sets of information that are sent between the device and host are referred to here as messages. These messages contain a header, which is followed by a data payload. Multiple messages can be sent in a single transfer by appending successive messages to the end of the previous, so individual transfers are not necessarily for a single message.
The header is as follows:
struct GipHeader
{
uint8_t command;
uint8_t client : 4;
bool needsAck : 1;
bool system : 1;
bool chunkStart : 1;
bool chunked : 1;
uint8_t sequence;
leb128_t length;
};commandis a command/report ID that describes what action/request to carry out.clientis used to distinguish between multiple devices on a singular physical connection, such as audio or plug-in modules. Client 0 is typically the main device.needsAckmeans the message must be responded to using a0x01command ID message (detailed later).systemmeans the message is one specified by the protocol and not the device itself.chunkStartmarks the start of a chunk sequence.chunkmarks a message as part of a chunk sequence.sequencekeeps track of which message is which between multiple messages of the same command. This starts out at 1, goes up to 255, and wraps back around to 1.- This needs to be maintained individually for each command ID.
- The sequence count does not increase between messages of the same chunk sequence.
lengthis a little-endian variable-length number specifying the amount of bytes in the payload. In most messages this will be only one byte long; however, if the top-most bit of that byte is set to 1, it means there is another byte used to encode the length. This continues up to a length of 4 bytes.
-> 50-00-01-03 05-03-01
<- 09-00-05-09 00-0F-FF-FF-00-00-FF-00-EB
To work around data transfer limits (such as the 64-byte payload limit of USB full-speed interrupt transfers), the protocol provides a way to split data into multiple messages. These are referred to as "chunk" sequences.
Messages that have the chunk flag set have an additional length/index value added after the main header. The bytes for this value are not included in the length value of the main header.
struct GipChunkHeader : GipHeader
{
leb128_t chunkLength;
};- In the first message of a chunk sequence,
chunkLengthis the size required to hold the data being chunked out. In the following messages, it is the index into that buffer that the message is starting at. - The header of a chunked message has a minimum length requirement of 6 bytes. If either the message length or chunk length/index only take up a single byte, one or the other must be padded by forcing it to be represented as 2 bytes (e.g.
0x05->0x85 0x00). If the message length is 0, then the chunk length is padded; otherwise the message length is padded.
Chunk messages have a bit of special handling to consider.
The first message of a chunk sequence has the chunk, chunk start, and acknowledgement flags set. The acknowledgement flag is set in order to get information about the remaining size of the chunk buffer allocated on the other end from the acknowledgement message.
The messages following this also have the chunk flag set, and have the same sequence count. Occasionally, another acknowledgement will be requested in order to check on the buffer to ensure things are as expected. If they are not, it'll re-send everything from the previous acknowledgement request.
The last message of the chunk sequence will also set the acknowledgement flag to ensure all of the data has been received (once again restarting from the previous ack if not). After this, one last message is sent with no payload, and the chunk index set to the max size of the buffer.
An example sequence, using 0x50 as an example command ID and with additional formatting to clarify:
-> 50-F0-01-3A 80-02 <3A bytes of data>
<- 01-20-01-09 00-50-20-3A-00-00-00-C6-00
-> 50-A0-01-BA-00 3A <3A bytes of data>
-> 50-A0-01-BA-00 74 <3A bytes of data>
-> 50-A0-01-3A AE-01 <3A bytes of data>
-> 50-A0-01-18 E8-01 <3A bytes of data>
-> 50-B0-01-00 80-02
<- 01-20-02-09 00-50-20-18-00-00-00-00-00
Sometimes a chunk message is sent without a preceding chunk start message, specifically during authentication. I'm unsure of why this is.
There are several commands built into the protocol:
0x01: Acknowledge a previous message0x02: Device arrival0x03: Device status0x04: Descriptor0x05: Power mode0x06: Authentication0x07: Virtual keycode0x08: Audio control0x0A: LED control0x0B: HID report0x0C: Firmware data0x1E: Serial number0x60: Audio sample data
This message must be used in response to messages that have the acknowledgement flag set.
struct GipAcknowledge
{
uint8_t unk1;
uint8_t innerCommand;
uint8_t innerClient : 4;
bool innerNeedsAck : 1;
bool innerSystem : 1;
bool innerChunkStart : 1;
bool innerChunked : 1;
uint16_t bytesReceived;
uint16_t unk2;
uint16_t remainingBuffer;
};- The sequence count in the header must match the sequence count of the message that is being acknowledged!
unk1seems to almost always be 0. I've seen it be0x20in some cases though.innerCommandis the command ID of the message being responded to.innerClientand the inner flag values reflect the client number and flags of the message being responded to. However, the host seems to only respect theinnerSystemflag. All of the other flags are always left unset, and only controllers will set those flags when sending responses.bytesReceivedis the number of bytes received for the message being responded to. For chunk sequences, this is the cumulative number of bytes received across all of the chunk packets that have been received.unk2seems to always be0x0000. It may be part ofbytesReceived, but given thatremainingBufferis only a 16-bit value, it wouldn't make sense for more data than that to be sendable in a sequence (unlessremainingBuffercan expand to a 32-bit number?).remainingBufferis used in chunk message responses to indicate the remaining size of the chunk buffer.
Devices send this message to announce their presence. It'll be sent periodically until the host requests its descriptor.
struct GipArrival
{
uint64_t serial;
uint16_t vendorId;
uint16_t productId;
struct {
uint16_t major;
uint16_t minor;
uint16_t build;
uint16_t revision;
} firmwareVersion, hardwareVersion;
};Take caution: the serial number provided here is used as a unique identifier for the device.
Devices send this message periodically to report their status.
struct GipStatus
{
uint8_t batteryLevel : 2;
uint8_t batteryType : 2;
uint8_t unk1 : 4;
uint8_t unk2[3];
};batteryLevelis the current battery level, from 0-3.batteryTypeis the currently-used battery type:- 0: No battery
- 1: Standard AA batteries
- 2: Rechargable battery pack
- Not sure if 3 is used for anything
This message is sent to request and send descriptor information.
This message works in the following ways:
- A message of this type with no length or data should be sent to a device to request its descriptor:
0x04 0x20 <message count> 0x00
- The controller will then respond with a chunk sequence that encodes its descriptor, which when decoded is structured like the following:
struct GipDescriptor
{
struct {
uint16_t headerLength;
uint8_t unk[12];
uint16_t dataLength;
} header;
union {
struct {
uint16_t customCommands;
uint16_t firmwareVersions;
uint16_t audioFormats;
uint16_t outputCommands;
uint16_t inputCommands;
uint16_t classNames;
uint16_t interfaceGuids;
uint16_t hidDescriptor;
} offsets;
uint8_t data[];
};
};The descriptor starts out with its own header:
headerLengthis the length of the header, including the bytes for this length.unk[0]is typically0x01, the rest ofunkis typically 0s.dataLengthis the length of the data buffer following the header.
After the header comes the data block. This contains both a set of offsets, and the data itself. The offsets are relative to the start of the data block (i.e. the start of the offsets).
Each offset points to a different type of data. The first byte at each offset is a count of how many elements are located at this offset. If either the offset or the count byte are 0, the device does not contain any elements for that type of data.
This struct should hopefully illustrate how it's laid out, though it by no means can be used directly. The data pointed to by the offsets needs to be handled manually.
template <typename T>
struct GipDescriptorElement
{
uint8_t count;
T elements[]; // std::size(elements) == count
}This offset specifies custom commands that a device supports which are not part of the core protocol.
struct GipCustomCommand
{
uint16_t length;
uint8_t commandId;
uint16_t maxMessageLength;
uint16_t unk1;
// flags
uint8_t : 2;
bool headerIncludedInMaxLength : 1;
bool outputCommand : 1;
bool inputCommand : 1;
uint8_t : 3;
uint8_t unk2[15];
};
typedef GipDescriptorElement<GipCustomCommand> GipCustomCommands;lengthis the length of the data in the descriptor, including the length bytes.commandIdis the command ID that the custom command uses.- This can be set to the same ID as one of the core commands; the
systemflag in the command header is used to differentiate between the core command and the custom one.
- This can be set to the same ID as one of the core commands; the
maxMessageLengthis the maximum length that the message will use. IfheaderIncludedInMaxLengthis set, subtract 4 (the size of the typical header) to get the true maximum length.outputCommandandinputCommandspecify whether a command is sent to or received from the device (or possibly both, though I haven't seen one with both set yet).unk1andunk2are typically all 0s.
This offset specifies the firmware versions that a device supports.
struct GipFirmwareVersion
{
uint16_t major;
uint16_t minor;
};
typedef GipDescriptorElement<GipFirmwareVersion> GipFirmwareVersions;This offset specifies the audio formats that a device supports. This is not set on the base client of a device, it's only set on the client that provides audio support.
enum GipAudioFormatType
{
GIP_AUDIO_CHAT_24KHz = 0x04,
GIP_AUDIO_CHAT_16KHz = 0x05,
GIP_AUDIO_HEADSET_MONO_24KHz = 0x09,
GIP_AUDIO_HEADSET_STEREO_48KHz = 0x10,
};
struct GipAudioFormat
{
uint8_t input;
uint8_t output;
};
typedef GipDescriptorElement<GipAudioFormat> GipAudioFormats;This offset specifies the built-in commands that it supports receiving, stored as a byte array.
typedef GipDescriptorElement<uint8_t> GipOutputCommands;This offset specifies the built-in commands that it supports sending, stored as a byte array.
typedef GipDescriptorElement<uint8_t> GipInputCommands;This offset specifies class strings for the interfaces the device supports. This one is a bit more involved than the other data elements, as its individual elements are variable-length. The following struct is pseudocode only!
struct GipClassString
{
uint16_t length;
char string[length];
};
typedef GipDescriptorElement<GipClassString> GipClassStrings;This offset specifies GUIDs for the interfaces the device supports.
typedef GipDescriptorElement<GUID> GipInterfaceGuids;This offset specifies an HID descriptor for the device as a simple byte array.
typedef GipDescriptorElement<uint8_t> GipHidDescriptor;This message is sent to configure the controller, including its power mode. It has many sub-commands, which may or may not have additional data (most do not).
struct GipSetConfiguration
{
uint8_t subcommand;
};subcommandis any of the following:-
0x00: Power on -
0x01: Sleep -
0x04: Power off -
0x05: Unknown- This one seems to be followed by or grouped with other configuration commands of different command IDs, such as setting the Xbox LED or turning vibration off on gamepads.
-
0x06: Wireless pairingstruct GipSetWirelessPairing { uint8_t subcommand = 0x06; uint8_t pairingAddress[6]; // For wireless pairing; all 0s if no receiver is connected char countryCode[2]; // "US" and "AU" are known valid codes, unsure what other ones exist uint8_t unknown[6]; // All 0s if no receiver; otherwise 00 0f 00 00 00 1f };
-
0x07: Reset
-
Authentication is a whole ordeal that probably won't be figured out for quite some time lol, not detailing anything here (nor do I plan to, as it's a touchy thing and easy enough to bypass by just passing through from a real controller).
This message is used to report keystroke inputs.
struct GipKeystroke
{
struct
{
bool pressed : 1;
uint8_t : 7;
uint8_t keycode;
} keystrokes[];
};pressedis 1 when pressed, 0 when released.keycodeis the virtual keycode for the keystroke.
Multiple keystrokes can be reported at once within the same message.
Controllers use this to report the guide button, using the virtual keycode of 0x5B (Left Windows key).
This message is used to control the Xbox button LED.
enum GipLedMode
{
GIP_LED_OFF = 0x00,
GIP_LED_ON = 0x01,
GIP_LED_BLINK_FAST = 0x02,
GIP_LED_BLINK_NORMAL = 0x03,
GIP_LED_BLINK_SLOW = 0x04,
GIP_LED_FADE_SLOW = 0x08,
GIP_LED_FADE_FAST = 0x09,
};
struct GipLedControl
{
uint8_t unk = 0x00; // subcommand?
uint8_t mode;
uint8_t brightness;
};These commands are technically device-defined and aren't part of the main protocol. Thus, they aren't covered here.
See the detail info here ---- https://aka.ms/gipdocs