= Nintendo Wii Remote Protocol = The wiimote communicates via standard bluetooth technology with the host. This document is divided into two parts. The first part described the low-level bluetooth connection that is established between the host and the wiimote with pairing support. The second part is about the protocol that is used to communicate with the wiimote. == Bluetooth Connection == The wiimote can be in the following states: off: The wiimote power is turned off and no interactions are possible. discoverable: The wiimote is not connected to any host but put into bluetooth discoverable mode. Furthermore, it is possible to establish a new bluetooth baseband connection to the wiimote. connecting: The wiimote is currently establishing a connection with a host or vice versa. connected: The wiimote is currently connected to a host. === Discoverable State === The wiimote is built around a Broadcom bluetooth chip that can be placed into discoverable mode in two ways: 1: Pressing the red sync-button behind the battery-cover on the back of the wiimote. This will place the wiimote directly into discoverable mode for exactly 20 seconds and then turn the wiimote off again. 2: Holding down the 1 and 2 buttons on the front of the wiimote will put the wiimote into discoverable mode. First, the wiimote performs auto-reconnect and if that fails it goes into discoverable mode. If the buttons are held down continuously, the wiimote will stay in discoverable mode, otherwise it turns off after 20 seconds. When in discoverable mode, the wiimote is seen as: "Nintendo RVL-CNT-01" For all later references in this document, we assume the wiimote has the following bluetooth address: "00:1E:35:3B:7E:6D" The binary representation of BD-addresses is in reversed order so this would be the six byte array: 0x6d 0x7e 0x3b 0x35 0x1e 0x00 When in discoverable mode, a host may establish a new bluetooth baseband connection to the wiimote. Every host is allowed to do that. No encryption nor pairing is required. When in discoverable mode, all four LEDs on the wiimote will blink when the battery is full. With lower battery status, less LEDs will blink. If the battery is nearly empty, only the left most LED blinks. === Connecting State === There are two ways to establish a connection with a wiimote: 1: Initiate a baseband connection to the wiimote while the wiimote is in discoverable state. 2: Let the wiimote auto-reconnect to your host. ==== Initiating a Connection ==== When the wiimote is in discoverable state, any bluetooth host can create a new baseband BR/EDR bluetooth connection to the wiimote. There are no special considerations or non-standard procedures. However, optionally, you may initiate pairing with the wiimote. This is not required and may be skipped, though, auto-reconnection can only be used when the host is paired with the wiimote. Pairing can be initiated by sending an HCI authentication request. The bluetooth stack will require a PIN for legacy pairing. This PIN depends on the method used to put the wiimote into discoverable mode. If method (1) was used (that means, the red sync button was pressed) then the PIN is the bluetooth address of the host in binary form (that is reversed order). If the buttons 1+2 were used (that is method (2)), then the PIN is the address of the wiimote in binary form. In our case this would be the 6-byte array: 0x6d 0x7e 0x3b 0x35 0x1e 0x00 When pairing is done, all further connections may use the new link-key instead of PIN-requests, but this should be handled by the bluetooth stack automatically. When the wiimote is paired with a host with method (1) (And only with this method! That is, red sync button!) then the wiimote will save the bluetooth address of the host for further reference so it can automatically reconnect to the host on disconnection. ==== Auto-Reconnection ==== The wiimote maintains a list of bluetooth addresses of hosts that it was connected to and paired with. If any single button on the wiimote is pressed while it is turned off, the wiimote turns on and tries to connect to one of the hosts in this list. It tries only once so you may need to press a single button multiple times to get connected to a host. It is currently impossible to control which host is tried first. Moreover, it is unknown how many addresses the wiimote can save so it may take many times (5 times, 10 times or even more) until the wiimote connects to an available host. If more than one host is available, it is not possible to predict what host the wiimote connects to. However, it seems that the wiimote maintains an internal sorted list of hosts and if it successfully connects to a host, this host is put on top of this list and hence tried first next time. When using auto-reconnection, no pairing is required and pairing does not provide any more functionality here. ==== SDP Information ==== When a low-level connection is established, you may query the SDP server of the xwiimote which returns a great deal of information: * Name: "Nintendo RVL-CNT-01" * PnP: VendorID: 0x057e ProductID: 0x0306 And a lot more PnP, SDP and HID related information. When the low-level baseband connection is established, the l2cap channels can be opened. On auto-reconnection, the wiimote will connect to the host (that is, the host must listen on the l2cap channels). If the connection is initiated by the host, then the wiimote listens for incoming connections on the l2cap channels. Two l2cap channels are used for communication: * Channel PSM 0x11 for sending data to the Wiimote * Channel PXM 0x13 for receiving data from the Wiimote Both must be opened for communication with the wiimote. No further steps are required to setup the connection with the wiimote. The wiimote is considered to be in "connected" state now. === Connected State === When in connected state, the host can communicate with the wiimote. The protocol used for communication is described below in "Fake-HID Protocol". To shutdown the connection, simply shut down the l2cap connections to the wiimote. The wiimote will shut down the connection when the "power"-button is pressed for 3 seconds. == Fake-HID Protocol == Communication is done via HID input/output reports. The wiimote's HID descriptor table does not contain any information about the reports except the data length. Many bits in the commands are still unknown and shall be initialized to 0 to avoid unwanted behaviour. === Reports === Following a list of all input and output reports. Many reports include the same information. These common structures are listed separately and each report that uses them just refers to them. Every report is built as a byte array of a fixed length. The array shall be initialized to 0 if not noted otherwise. If a report has a variable length parameter with a fixed maximum, then always the trailing bytes shall be padded with 0 if not used. Multibyte integers are always in big-endian format. A single report is constructred the following way: report[0] = 0xa1 (for input reports) report[0] = 0x52 (for output reports) report[1] = report[2-X] = The first byte is the HID command which is the same for all input and output reports. They are often omitted or automatically set by your HID layer. See your kernel/library documentation. The second byte is the report identifier. Byte 3 up to X is the report payload. Each report has a fixed length that specifies how long this payload is (without the report byte). A report with length 8 would need 10 bytes to be constructed: 8 payload bytes + 1 HID byte + 1 report byte = 10 bytes The "Data" decription of each report below gives a short overview of how the report is assembled. Each integer is given as hexadecimal number without the 0x prefix. Two characters form a single byte. ==== Common (Output) ==== Length: 1 Data: CC This is no real output report but rather a common structure that is used in almost all other output reports. Byte 1 (CC) contains the following flags: 0x01: This enables the rumble motor. This flag must be set on every output to keep the rumble motor running. If this flag is not set then the rumble is disabled. 0x02: This requests a report acknowledgement. The wiimote will send a 0x22 input report in response to this report. 0x04: Enable flag. This has different meanings depending on the output report but is generally used to enable/disable the requested feature. 0x08: unknown 0xf0: The upper bits are used by different output reports for special features. ==== Rumble Report (Output) ==== Report: 0x10 Length: 1 Data: 52 10 CC Payload information contains only the common output report. This report is no special rumble report, because rumble is enabled and disabled with every output report that includes the common output report. However, this report has no side effects so it may be used to affect the rumble motor without changing any other peripheral. ==== LED Report (Output) ==== Report: 0x11 Length: 1 Data: 52 11 CC Payload includes only the common output report. The upper 4 bits of the common output report set the different leds: 0x10: LED 1 0x20: LED 2 0x40: LED 3 0x80: LED 4 Turning all four LEDs off for too long is discouraged since it may lead the user to believe the wiimote is turned off while it is still turned on. Brightness modulation can be achieved by turning the leds off and on very fast. ==== DRM Set Report (Output) ==== Report: 0x12 Length: 2 Data: 52 12 CC MM The first byte is the common output report. The Enable Flag in the common output report (0x04) is used to enabled or disable continuous input reporting. If enabled, the wiimote continously sends input reports to the host. If disabled, the wiimote sends input reports only when data has changed. The second byte is used to request a specific data reporting mode (DRM). You should set it to the report identifier of the request input report. The wiimote will send data input reports always with the requested DRM. Upon powerup, the DRM defaults to 0x30. After an extension is (un)plugged, data reporting is disabled and needs to be reset with this report. A specific DRM does not explicitely enable or disable the peripherals of the wiimote. The wiimote simply pulls the data from its peripherals, puts it into the output report and sends it to the host. If the requested DRM needs data from a disabled peripheral, then the data is set to 0 in the input report. You have to enabled/disable the specific peripherals of the wiimote independently. Also the requested DRM should match the current data mode of each peripheral. For example if the IR is in extended state, then it reports IR data only if the requested DRM has 12 IR bytes. It must have exactly 12 bytes, not 10 and not 36! However, each peripheral will give hints what DRM to use below. ==== IR Set1 Report (Output) ==== Report: 0x13 Length: 1 Data: 52 13 CC This request is used to enable the IR camera. The payload is the common output report. The Enable Flag (0x04) of the common output report is used to enable or disable the IR camera. This is only one part of the initialization procedure of the IR camera. See below for full instructions how to initialize IR. ==== Speaker Set Report (Output) ==== Report: 0x14 Length: 1 Data: 52 14 CC This request is used to enable the speaker. The payload is the common output report. The Enable Flag (0x04) of the common output report is used to enable or disable the speaker. This is only one part of the initialization procedure of the speaker. See below for full instructions how to initialize the speaker. ==== Status Request Report (Output) ==== Report: 0x15 Length: 1 Data: 52 15 CC The payload is the common output report with no special flags. This report requests a status report from the wiimote. The wiimote will answer with input report 0x20. ==== Write Memory Report (Output) ==== Report: 0x16 Length: 21 Data: 52 16 CC OO OO OO SS DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD This writes data into the wiimote's EEPROM or registers. The first byte is the common output report. Its Enable Flag (0x04) specifies the namespace. If set, then the wiimote's registers are written, otherwise the EEPROM is written. The following 3 bytes OO OO OO specify the offset where to start the write followed by one byte SS specifying the size of the data that is written. SS can be a maximum of 16. The rest of the report is the data (DD). Trailing bytes are padded with 0. Acknowledgement is always received via input report 0x22. ==== Read Memory Report (Output) ==== Report: 0x17 Length: 6 Data: 52 17 CC OO OO OO SS SS This request a memory read of the wiimote's EEPROM or registers. The first byte (CC) is the common output report. Its Enable Flag (0x04) specifies whether EEPROM or registers shall be read. If set, the registers are read, otherwise internal EEPROM is read. The following three bytes OO OO OO specify the data offset where to start the memory read. The last two bytes SS SS specify the amount of data that is read starting at the offset. ==== Speaker Data Report (Output) ==== Report: 0x18 Length: 21 Data: 52 18 CC DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD This sends speaker data to the wiimote. The exact format of the data is described below in the speaker peripheral details. The first byte is the common output report. The upper 5 bits of the common output report specify the size of the data payload (they shall be shifted right for 3 bits). All following bytes (DD) contain the sound data that is sent to the speaker. ==== Speaker Mute Report (Output) ==== Report: 0x19 Length: 1 Data: 52 19 CC This mutes or unmutes the speaker. The payload is the common output report and the Enable Flag (0x04) specifies whether to mute (if enabled) or to unmute (if disabled) the speaker. ==== IR Set2 Report (Output) ==== Report: 0x1a Length: 1 Data: 52 1a CC This has the same syntax as "IR Set1 Report" and is also used to initialize the IR camera. ==== Common (Input) ==== Length: 2 Data: BB BB This is no real input report but rather a common structure that is used in almost all other input reports. The two BB BB bytes include the current state of the buttons on the wiimote. If the following flags are set, then the related button is currently pressed: Byte 1: Byte 2: 0x01: Left Two 0x02: Right One 0x04: Down B 0x08: Up A 0x10: Plus Minus 0x20: - - 0x40: - - 0x80: Home The power-button is never included in input reports. The 0x80 flag of byte one is never used. The bits 0x20 and 0x40 of both bytes are not used for button information but often include important LSB/MSBs or other flags of the surrounding input report. They are referred to as "Special Flags" of the common input report. The sync button on the back of the wiimote is also never included in the button input report. ==== Status Report (Input) ==== Report: 0x20 Length: 6 Data: a1 20 BB BB LF UU UU VV This is sent in request to Status Request Report (0x15) and also when an extension is plugged or unplugged. In the latter case you need to reset the DRM mode (see DRM Set Report), otherwise not further input reports will be sent. The first two bytes of this report include the common input report. The last byte VV is the current battery level from 0-255 where 0 is empty and 255 is full. The four upper bits of LF (L) are the leds: 0x10: LED 1 0x20: LED 2 0x40: LED 3 0x80: LED 4 These flags are set if the related LED is enabled. The lower 4 bits of LF (F) specfiy different things: 0x01: Set if battery is nearly empty 0x02: Set if an extension is plugged 0x04: Set if speaker is enabled 0x08: Set if IR is enabled The two bytes in between (UU UU) are always zero and its unknown why they exist. ==== Memory Report (Input) ==== Report: 0x21 Length: 21 Data: a1 21 BB BB SE OO OO DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD This is sent when data is read via read-memory request. The first two bytes include the common input information. The upper bits in SE are the size of the data that is read minus one (0xff => 16 byte, 0x00 => 1 byte) and the lower bits of SE are the error flag which is 0 when everything is ok, 7 when reading write-only memory and 8 when reading from unexisting memory. Other error flags are unknown. The two OO bytes are the lower 2 bytes of the offset. The upper two bytes are not reported back and must be known by the caller. The 16 DD bytes are the actual data and padded with zeros at the end if less data than 16 bytes were read. If the read-memory request has read more than 16 bytes, multiple responses are sent with the offset increased by 16 each time. Input reporting is disabled during those reads and continues after the read is done. ==== Result Report (Input) ==== Report: 0x22 Length: 4 Data: a1 22 BB BB RR EE This report is sent when a output report failed or explicit acknowledgement was requested by the caller via 0x02 bit in the common output request. The two BB bytes include the common input information, the RR byte is the number of the related report that this report is the result of. The EE byte is the error identifier: 0 if everything was ok, and >0 on error. The meaning of each error number is unknown. ==== DRM reports (Input) ==== All following reports are used to report input information to the host. The DRM-set output report is used to select the DRM report that is used for input reports. ==== DRM B ==== Report: 0x30 Length: 2 Data: a1 30 BB BB ==== DRM BA ==== Report: 0x31 Length: 5 Data: a1 31 BB BB AA AA AA ==== DRM BE ==== Report: 0x32 Length: 10 Data: a1 32 BB BB EE EE EE EE EE EE EE EE ==== DRM BAI ==== Report: 0x33 Length: 17 Data: a1 33 BB BB AA AA AA II II II II II II II II II II II II ==== DRM BEE ==== Report: 0x34 Length: 21 Data: a1 34 BB BB EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE ==== DRM BAE ==== Report: 0x35 Length: 21 Data: a1 35 BB BB AA AA AA EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE ==== DRM BIE ==== Report: 0x36 Length: 21 Data: a1 36 BB BB II II II II II II II II II II EE EE EE EE EE EE EE EE EE ==== DRM BAIE ==== Report: 0x37 Length: 21 Data: a1 37 BB BB AA AA AA II II II II II II II II II II EE EE EE EE EE EE ==== DRM E ==== Report: 0x3d Length: 21 Data: a1 3d EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE ==== DRM SBAI1 ==== Report: 0x3e Length: 21 Data: a1 3e BB BB AA II II II II II II II II II II II II II II II II II II ==== DRM SBAI2 ==== Report: 0x3f Length: 21 Data: a1 3f BB BB AA II II II II II II II II II II II II II II II II II II == Authors == This document is written by: * David Herrmann - dh.herrmann@googlemail.com The following people contributed to this document: * WiiBrew Project: http://www.wiibrew.org/ http://www.wiibrew.org/wiki/Wiimote * BlueZ Mailing List: http://www.bluez.org/ * Wiimote Project: http://www.wiimoteproject.com/ * Wiiuse: http://sourceforge.net/projects/wiiuse * WiiYourself: http://wiiyourself.gl.tter.org/ == Links == * Gyro hardware: http://invensense.com/mems/gyro/idg650.html == Unknown == The following list contains protocol details which where not investigated and are still unknown: * What happens if two hosts try to connect to the wiimote? * Does the Wiimote implement the BT HID profile or just use HID commands via an l2cap channel? * How many host can be saved for auto-reconnection on the wiimote? * How to manage the list of auto-reconnection hosts? * How to reset the wiimote? * Is pairing possible when using auto-reconnection? Which key to use?