Difference between revisions of "Wiimote"

From WiiBrew
Jump to navigation Jump to search
(Correct link for DJ Hero controler)
Line 1,181: Line 1,181:
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" | 0300 A420 0103*
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" | 0300 A420 0103*
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" |  
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" |  
| style="border: 1px solid #ccc; padding: 0.2em; background-color: #eef;" | [[Wiimote/Extension Controllers#DJ_Hero|DJ Hero Turntable]]
+
| style="border: 1px solid #ccc; padding: 0.2em; background-color: #eef;" | [[Wiimote/Extension Controllers#DJ_Hero_Wii|DJ Hero Turntable]]
 
|-
 
|-
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" | 0000 A420 0402*
 
| style="border: 1px solid #ccc; padding: 0.2em; text-align: center; background-color: #efe;" | 0000 A420 0402*

Revision as of 19:45, 1 December 2009

Wii remote circuit board, top surface
Wii remote circuit board, bottom surface
This article is a technical guide to the Wii Remote. For a high-level overview of the Wii Remote, see the Wikipedia entry.
Broadcom BCM2042 in a Wii remote

The Wii Remote (informally known as the Wiimote) is the Wii's main input device. It is a wireless device, using standard Bluetooth technology to communicate with the Wii. It is built around a Broadcom BCM2042 bluetooth System-on-a-chip, and contains multiple peripherals that provide data to it, as well as an expansion port for external add-ons. The Wii Remote uses (and, at times, abuses) the standard Bluetooth HID protocol to communicate with the host, which is directly based upon the USB HID standard. As such, it will appear as a standard input device to any Bluetooth host. However, the Wii Remote does not make use of the standard data types and HID descriptor, and only describes its report format length, leaving the actual contents undefined, which makes it useless with standard HID drivers (but some Wiimote Drivers exist). The Wii Remote actually uses a fairly complex set of operations, transmitted through HID Output reports, and returns a number of different data packets through its Input reports, which contain the data from its peripherals.

Contents

Summary

Reverse engineering and documenting all of the Wii Remote's features is a work in progress. Here are the known features and their status:

Bluetooth Communication ButtonGreen.png Connection to the Wii Remote using the 1+2 sync sequence works sometimes, and single-press reconnection is understood.
Core Buttons ButtonGreen.png All working.
Accelerometer ButtonGreen.png All working.
IR Camera ButtonGreen.png All working.
Power Button ButtonYellow.png Pressing Power disconnects and turns off the Wii Remote. Power-on currently unknown.
Speaker ButtonGreen.png All working.
Player LEDs ButtonGreen.png Can be controlled by software arbitrarily. Even brightness modulation works.
Status Information ButtonGreen.png Battery and extension info in Status Report
Extension Controllers ButtonYellow.png Wireless Nunchuks don't work at all. Motion Plus support is limited.
Legend ButtonGreen.png Perfect or near-perfect ButtonYellow.png Usable but not complete ButtonRed.png Unusable

Bluetooth Communication

When queried with the Bluetooth Service Discovery Protocol (SDP), the Wii Remote reports back a great deal of information. In particular, it reports:

Name Nintendo RVL-CNT-01
Vendor ID 0x057e
Product ID 0x0306
Major Device Class 1280
Minor Device Class 4
Service Class 0
(Summary of all Class Values) 0x002504

The Wii Remote does not appear to require any of the authentication or encryption features of the Bluetooth standard. In order to interface with it, it must first be placed in discoverable mode by either pressing the 1 and 2 buttons at the same time, or by pressing the red sync button under the battery cover. Once in this mode, the Wii Remote can be queried by the Bluetooth HID driver on the host. If the HID driver on the host does not connect to the Wii Remote within 20 seconds, the Wii Remote will turn itself off. Holding down the 1 and 2 buttons continuously will force the Wii Remote to stay in discoverable mode without turning off. This does not work with the sync button, however. When in discoverable mode, a number of the player LEDs based on the battery level will blink.

The "syncing" of a Wii Remote involves standard Bluetooth pairing. When the Sync button is pressed on the remote, it will accept pairing requests. The required PIN is the hosts's Bluetooth address, backwards (last byte first), in binary (6 bytes). Most current Bluetooth implementations don't deal with this correctly, as they usually consider the PIN to be a regular ASCII string (no 00 bytes, etc). Any further steps that need to be taken after the Wii Remote is paired have not been reverse engineered yet.

Once the Wii Remote is synced, when a button is pressed, it will actively seek out its paired host and try to connect to it, instead of the other way around. Establishing a connection can be done on PSM 0x11 for writing and PSM 0x13 for reading using the Bluetooth L2CAP protocol.

HID Interface

The HID standard allows devices to be self-describing, using a HID descriptor block. This block includes an enumeration of reports that the device understands. A report can be thought of similar to a network port assigned to a particular service. Reports are unidirectional however, and the HID descriptor lists for each port the direction (Input or Output) and the payload size for each port. Like all Bluetooth HID devices, the Wii Remote reports its HID descriptor block when queried using the SDP protocol. However, no information regarding the actual data units within each report is returned, only the length in bytes.

Note: An "Input" report is sent by the Wii Remote to the host. An "Output" report is sent by the host to the Wii Remote.

These are the reports the Wii Remote uses, and their use:

I/O ID(s) Size Function
O 0x10 1 Unknown
O 0x11 1 Player LEDs
O 0x12 2 Data Reporting mode
O 0x13 1 IR Camera Enable
O 0x14 1 Speaker Enable
O 0x15 1 Status Information Request
O 0x16 21 Write Memory and Registers
O 0x17 6 Read Memory and Registers
O 0x18 21 Speaker Data
O 0x19 1 Speaker Mute
O 0x1a 1 IR Camera Enable 2
I 0x20 6 Status Information
I 0x21 21 Read Memory and Registers Data
I 0x22 4 Acknowledge output report, return function result
I 0x30-0x3f 2-21 Data reports

For clarity, the convention in this document is to show packets including the Bluetooth-HID command (in parentheses), report ID, and payload, as described in sections 7.3 and 7.4 of the Bluetooth HID specification. Each byte is written out in hexadecimal, without the 0x prefix, separated by spaces. For example,

(a1) 30 00 00

is a DATA input packet (0xa1)(0x00 on European Wii remotes), on channel 0x30, with the two byte payload 0x00, 0x00. When using higher level HID functions rather than Bluetooth functions, the bytes in parentheses will never be present.

Force Feedback is accessible through the first byte of ALL output reports in the same way. This is not included above to avoid clutter.

Output Report common information

The first byte in many Output reports has a similar meaning. In every single Output Report, bit 0 (0x01) of the first byte controls the Rumble feature. Additionally, bit 2 (0x04) is used in several Output Reports as the ON/OFF flag for the specific feature controlled by it. For example, sending 0x04 to Report 0x19 (Speaker Mute) will mute the speaker:

(52) 19 04

Sending 0x00 will unmute it:

(52) 19 00

These Output Reports share the above behavior: Data Reporting Mode (0x12), IR Camera Enable (0x13), Speaker Enable (0x14), Speaker Mute (0x19), IR Enable 2 (0x1a).

Input Report common information

The first two bytes of ALL input reports, except 0x3d, contain the Core Buttons (BB BB). This includes all the 0x2~ status reports, not just the 0x3~ data reports. 0x3d is an exception, since it only returns expansion information.

Status Reporting

0x20: Status

To request the status report, send anything to Output Report 0x15. The Status Report will also be automatically sent when an Extension Controller is connected or disconnected.

This will request the status report (and turn off rumble):

(52) 15 00

This report is sent either on request (in response to report 0x15), or in response to an expansion being plugged in or unplugged (or synced if wireless). If this report is received when not requested, the application 'MUST' send report 0x12 to change the data reporting mode, otherwise no further data reports will be received.

(a1) 20 BB BB LF 00 00 VV

BBBB is the core Buttons data. VV is the current battery level, L is the LED state, and F is a bitmask of flags indicating, whether the battery is flat, whether an expansion is currently connected, etc.

The Wii Remote can report its status, which includes the state of a few basic settings, the status of the Extension Controller (connected or disconnected), and the battery level.

BB is the current battery level, and FF is a bitmask of flags:

Bit Mask Meaning
0 0x01 Battery is nearly empty
1 0x02 An Extension Controller is connected
2 0x04 Speaker enabled
3 0x08 IR camera enabled
4 0x10 LED 1
5 0x20 LED 2
6 0x40 LED 3
7 0x80 LED 4

0x21: Read Memory Data

This report is sent when a read memory request is made. It returns 1 to 16 bytes of data at a time.

(a1) 21 BB BB SE AA AA DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD

BBBB is the core Buttons data.

AA AA are the 2 least significant bytes of the absolute memory address of the first byte of data returned (the high byte of the offset is not returned, and neither is whether it is a register or memory that is being used. Thus, this must be known from the read request).

E (low nybble of SE) is the error flag. Known error values are 0 for no error, 7 when attempting to read from a write-only register or an expansion that is not connected, and 8 when attempting to read from nonexistant memory addresses.

S (high nybble of SE) is the size in bytes, minus one, for the current data packet. This is 0xf (16 bytes) for all but the last packet, where it might be less if the requested number of bytes is not a multiple of 16. The DD bytes are the data, padded with zeroes to 16 bytes. If more than 16 bytes are requested, multiple packets will be received, with AA AA addresses increasing by 16 each time.

0x22: Acknowledge output report, return function result

This input report is sent to the host to report an error related to an output report, or the function result from that output report. It is only sent under certain conditions.

Attempting to send an output report using the WriteFile method on the Microsoft Bluetooth Stack causes one such error for all output reports except report 16H (write to memory). Report 16H reports success when using the WriteFile method. That may be because report 16H is 22 bytes long unlike other reports (I haven't tested Report 18H), or may be a special behaviour of report 16H.

(a1) 22 BB BB RR EE

BBBB is the core Buttons data.

RR is the output report number that the Wii remote is acknowledging it received.

EE is the error code or function result. 00 = success. 03 = error, such as using WriteFile on the Microsoft stack. 04 = unknown. (possibly returned by report 16H, 17H or 18H) 05 = unknown (possibly returned by report 12H). 08 = unknown (possibly returned bt report 16H).

Data Reporting

The Wii Remote has a number of different data reporting modes. Each of these modes combines certain Core data features with data from external peripherals, and sends it to the host through one of the report IDs, determined by the mode. The data format from the peripherals is determined by the peripherals themselves, all the Wii Remote controller does is pull bytes from them and send them out to the host. Due to this, certain feature combinations are not available, as there are not enough bytes for them in any of the output modes.

The Data Reporting Mode is set by sending a two-byte command to Report 0x12:

(52) 12 TT MM

Bit 2 of TT specifies whether continuous reporting is desired. If bit 2 (0x04) is set, the Wii Remote will send reports whether there has been any change to the data or not. Otherwise, the Wii Remote will only send an output report when the data has changed.

MM specifies the Reporting Mode. Each Mode is specified by the Output Report ID that the data will be sent to. For example, this will set mode to 0x33:

(52) 12 00 33

Data will then arrive through Input Report 0x33.

Upon powerup, the Data Reporting Mode defaults to 0x30. Following a connection or disconnection event on the Extension Port, data reporting is disabled and the Data Reporting Mode must be reset before new data can arrive.

Modes which include Accelerometer data also embed part of it in the unused Buttons bits. In all modes except for 0x3e/0x3f, the Buttons data includes the LSBs of the Accelerometer data. In mode 0x3e/0x3f, the interleaved Buttons data includes the Z-axis Accelerometer data.

0x30: Core Buttons

This mode returns data from the buttons in the Wii Remote:

(a1) 30 BB BB

BBBB is the core Buttons data.

0x31: Core Buttons and Accelerometer

This mode returns data from the buttons and the accelerometer in the Wii Remote:

(a1) 31 BB BB AA AA AA

BBBB is the core Buttons data. AA AA AA is the Accelerometer data.

0x32: Core Buttons with 8 Extension bytes

This mode returns data from the buttons in the Wii Remote, and data from an extension controller connected to it:

(a1) 32 BB BB EE EE EE EE EE EE EE EE

BBBB is the core Buttons data. The 8 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x33: Core Buttons and Accelerometer with 12 IR bytes

This mode returns data from the buttons, accelerometer, and IR Camera in the Wii Remote:

(a1) 33 BB BB AA AA AA II II II II II II II II II II II II 

BBBB is the core Buttons data. AA AA AA is the Accelerometer data. The 12 II bytes are from the built-in IR Camera.

0x34: Core Buttons with 19 Extension bytes

This mode returns data from the buttons in the Wii Remote, and data from an extension controller connected to it:

(a1) 34 BB BB EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE 

BBBB is the core Buttons data. The 19 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x35: Core Buttons and Accelerometer with 16 Extension Bytes

This mode returns data from the buttons and accelerometer in the Wii Remote, and data from an extension controller connected to it:

(a1) 35 BB BB AA AA AA EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE

BBBB is the core Buttons data. AA AA AA is the Accelerometer data. The 16 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x36: Core Buttons with 10 IR bytes and 9 Extension Bytes

This mode returns data from the buttons and IR camera in the Wii Remote, and data from an extension controller connected to it:

(a1) 36 BB BB II II II II II II II II II II EE EE EE EE EE EE EE EE EE

BBBB is the core Buttons data. The 10 II bytes are from the built-in IR Camera, and the 9 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x37: Core Buttons and Accelerometer with 10 IR bytes and 6 Extension Bytes

This mode returns data from the buttons, accelerometer, and IR camera in the Wii Remote, and data from an extension controller connected to it:

(a1) 37 BB BB AA AA AA II II II II II II II II II II EE EE EE EE EE EE

BBBB is the core Buttons data. AA AA AA is the Accelerometer data. The 10 II bytes are from the built-in IR Camera, and the 6 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x3d: 21 Extension Bytes

This mode returns data from an extension controller connected to the Wii Remote. It is the only input report that does not include core buttons.

(a1) 3d EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE EE

The 21 EE bytes are from the Extension Controller currently connected to the Wii Remote.

0x3e / 0x3f: Interleaved Core Buttons and Accelerometer with 36 IR bytes

Both 0x3e and 0x3f are equivalent, and return data alternately through report IDs 0x3e and 0x3f. The data is interleaved, and is returned at half the speed of other modes (as two reports are needed for a single data unit). This mode returns data from the buttons, accelerometer, and IR camera in the Wii Remote:

(a1) 3e BB BB AA II II II II II II II II II II II II II II II II II II
(a1) 3f BB BB AA II II II II II II II II II II II II II II II II II II

BBBB is the core button data, as specified in the Buttons section. AA AA is the Accelerometer data, in a format specific to this mode described in the Interleaved Accelerometer Reporting section. The 36 II bytes are from the built-in IR Camera.

Memory and Registers

The Wii Remote includes a built-in EEPROM memory, part of which is accessible to the user to store that. This user part is used to store calibration constants, as well as the Mii Data. Additionally, many peripherals on the Wii Remote have registers which are accessible through a portion of the address space.

Both built-in memory and peripheral registers are accessed using the same reports, where a flag is used to select between the two.

Reading and Writing

To read data, commands are sent to Output Report 0x17:

(52) 17 MM FF FF FF SS SS

FF FF FF is the offset, and SS SS is the size to read in bytes (both in big-endian format). Bit 2 (0x04) of MM selects the address space. Clearing this bit results in reading from EEPROM Memory, while setting it results in reading from the control registers. Setting bit 3 (0x08) also works to access registers, but setting both results in errors. As with all other reports, it also includes the Rumble flag, which must be set to the current rumble state to avoid affecting it.

Data read is returned through Input Report 0x21:

(a1) 21 BB BB SE FF FF DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD

BB BB is the state of the buttons on the Wii Remote. During data reads, regular input reporting is temporarily suspended. Button data is available through the data input reports, but no other input data can be collected while the transfer lasts. FF FF is the offset expressed in absolute memory address of the Wii remote memory for the first byte of data returned (the high byte of the offset is not returned, and neither is which data memory is being used. Thus, this must be known from the read request). E (low nybble of SE) is the error flag. Known error values are 0 for no error, 7 when attempting to read from a write-only register, and 8 when attempting to read from nonexistant memory. S (high nybble of SE) is the size in bytes, minus one, for the current data packet. This is 0xf (16 bytes) for all but the last packet, where it might be less if the requested number of bytes is not a multiple of 16. The DD bytes are the data, padded with zeroes to 16 bytes. If more than 16 bytes are requested, multiple packets will be received, with FF FF offsets increasing by 16 each time.

To write data, commands are sent to Output Report 0x16:

(52) 16 MM FF FF FF SS DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD

The meaning of the bytes is the same as during reads, except that size can be a maximum of 16 bytes (as there is only space for that much data), and the actual data to write follows (the DD bytes), padded out to 16 bytes.

Some kind of acknowledgement is received on Input Report 0x22. This has not been investigated yet.

EEPROM Memory

Wii Remote Flash.jpg

There is a 128kbit (= 16kB) EEPROM chip (Data Sheet / Full EEPROM dump from a sample Wii Remote) in the Wii Remote. Part of its contents include code for the built-in microcontroller, and a generic section which can be freely read and written by the host. This section is 0x1700 bytes long, and part of this memory is used to store the Mii Data. It can be accessed by reading from/writing to addresses 0x0000-0x16FF in the Wii Remote's virtual memory space; in the actual EEPROM chip, the data is located at 0x0070-0x176F.

The firmware stored in the Wiimote has been disassembled.

The BCM2042 microcontroller built into the Wii Remote includes a large 108kb on-chip ROM section for storing firmware. If the EEPROM chip really contains code for the BCM2042 then this was probably done to make firmware updates possible, so there might be a way of accessing the other parts of the EEPROM via Bluetooth as well. From the BCM2042 Product Brief: "ROM-based design eliminates external flash memories; Flash option offered to support feature development".

On a virgin Wii Remote, acquired separately (not bundled with a Wii), that has never communicated with any device (except the PC used to dump the memory contents), most of the memory is blank (0x00). However, the first few bytes contain some information:

0000:  A1 AA 8B 99 AE 9E 78 30 A7 74 D3 A1 AA 8B 99 AE
0010:  9E 78 30 A7 74 D3 82 82 82 15 9C 9C 9E 38 40 3E
0020:  82 82 82 15 9C 9C 9E 38 40 3E 00 00 00 00 00 00
0030:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

This can be better visualized as two sequences, each one repeated twice:

0000:  A1 AA 8B 99 AE 9E 78 30 A7 74 D3
000B:  A1 AA 8B 99 AE 9E 78 30 A7 74 D3
0016:  82 82 82 15 9C 9C 9E 38 40 3E
0020:  82 82 82 15 9C 9C 9E 38 40 3E

It is not yet clear why these sentences are repeated; but since at least the second one is known to be calibration data, maybe one version contains the calibration data that is actually being used, while the other version is meant for backup purposes (for example a "Return to factory settings" option) in case there will be a way of recalibrating the Wii Remote with future Wii firmware updates.

The four bytes starting at 0x0016 and 0x0020 store the calibrated zero offsets for the accelerometer (high 8 bits of X,Y,Z in the first three bytes, low 2 bits packed in the fourth byte as --XXYYZZ). Apparently, the four bytes at 0x001A and 0x24 store the force of gravity on those axes. The function of other data bytes is not known, and most of them differ between Wii Remotes. Some or all of these bytes might not be used by the Wii. However, there has been a case of a Wii Remote where Extension functionality was lost following a battery change, and restoring these bytes (which had been previously overwritten) fixed the problem. The Extension controllers did not work with a PC either (which did not explicitly use these bytes), suggesting some of these might be used by the Wii Remote itself. This is unconfirmed, but it is advised that these never be overwritten, and recommended that they be backed up, just in case.

At 0x16D0, there is some more unknown data:

16D0:  00 00 00 FF 11 EE 00 00 33 CC 44 BB 00 00 66 99
16E0:  77 88 00 00 2B 01 E8 13 00 00 00 00 00 00 00 00
16F0:  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

In contrast to the data at 0x0000, this data seems to differ in only a few bytes between different Wii Remotes.

Known memory ranges are listed below. Note that the "user data" area is 0x0FA0 = 4000 bytes long, which seems to confirm the 4kB figure that has been mentioned (meaning 4000 bytes, that is, using the SI prefix meaning instead of the binary meaning).

Start End Length Initial Value Use
0x0000 0x0029 0x002A See above Calibration values / pre-set data
0x002A 0x0FC9 0x0FA0 Zeroed User data / Unknown uses
0x0FCA 0x12B9 0x02f0 Zeroed Mii Data block 1
0x12BA 0x15A9 0x02f0 Zeroed Mii Data block 2
0x15AA 0x16CF 0x0126 Zeroed Unknown / Unused
0x16D0 0x16FF 0x0030 See above Unknown data

The top byte of the address is unused, which means memory is mirrored every 0x10000 bytes. Reading from unused addresses where the low 16 bits are >= 0x1700 will result in error returns.

Control Registers

The Wii Remote has several memory mapped register spaces corresponding to different peripherals in it. These include the Speaker, Extension Controllers, and the IR Camera.

Reminder
Remember to set bit 2 (0x04) on the first byte of the Output Report, otherwise you'll overwrite EEPROM memory!

The peripheral to access is selected by the first byte of the address, and the lower 16 bits specify the register to access within that peripheral. The lowest bit of the high byte is ignored, which means every peripheral is mirrored at its address + 0x10000. Known peripherals are listed below:

Start End Use
0xA20000 0xA20009 Speaker settings
0xA40000 0xA400FF Extension Controller settings and data
0xA60000 0xA600FF Wii Motion Plus settings and data
0xB00000 0xB00033 IR Camera settings

Most of these are also mirrored across the high bits of the individual peripheral. For example, the second byte of the address is ignored in the Extension controller address, which means any address of the form 0xA4xx00 will work (as will 0xA5xx00).

Input Features

The Wii Remote has two input features that are controlled directly by the Broadcom chip: a Three-Axis Accelerometer and 11 Buttons. Additionally, it has an IR Camera with an object tracking processor, and an expansion port that allows for external input features such as those contained in the Nunchuk and the Classic Controller (see Extension Controllers).

Buttons

The Wii Remote has 11 buttons on its front face, and one trigger-style button on the back. Of these, the Power button is special and is treated differently by the Wii Remote. All the other buttons are independantly accessible through a two-byte bitmask which is transmitted first in most Input Reports. A button will report a 1-bit if pressed, or a 0-bit otherwise. By default, these are sent only when the state of any button changes, in Data Reporting Mode 0x30. However, the Wii Remote may be configured to report the state of the buttons continuously; see Data Reporting.

Core Buttons

The Wii Remote has 11 buttons that are used as regular input devices: A, B (trigger), a 4-directional D-Pad, +, -, Home, 1, and 2. These are reported as bits in a two-byte bitmask. These are the assignments, in big-endian order:

Bit Mask First Byte Second Byte
0 0x01 D-Pad Left Two
1 0x02 D-Pad Right One
2 0x04 D-Pad Down B
3 0x08 D-Pad Up A
4 0x10 Plus Minus
5 0x20 Other uses Other uses
6 0x40 Other uses Other uses
7 0x80 Unknown Home

Power Button

When the Wii Remote is turned off, pressing the Power button will attempt to wake up the Wii that is synchronized to it. The mechanism for this is unknown, and it is handled entirely within the Wii's bluetooth module. When the Wii Remote is turned on and connected to a host, pressing and holding the Power button for a few seconds will turn the Wii Remote off and request disconnection from the host. The disconnection reason included with the Baseband (ACL) disconnection request indicates that the power button was pressed: REMOTE DEVICE TERMINATED CONNECTION DUE TO POWER OFF (0x15). Another possible value is REMOTE DEVICE TERMINATED CONNECTION DUE TO LOW RESOURCES (0x14), which indicates that the Wii Remote performed a controlled shut down due to a low battery condition.

Sync Button

The sync button is hidden under the battery cover. When the Sync button is pressed, the Wii remote will disconnect from whatever it is currently connected to, make itself discoverable, and accept pairing or connection requests for exactly 20 seconds (regardless of how long the button is held down for).

The "syncing" of a Wii Remote involves standard Bluetooth pairing. When the Sync button is pressed on the remote, it will accept pairing requests. The required PIN is the hosts's Bluetooth address, backwards (last byte first), in binary (6 bytes). Most current Bluetooth implementations don't deal with this correctly, as they usually consider the PIN to be a regular null-terminated ASCII string (no 00 bytes, etc) and most Bluetooth addresses will contain null bytes. Any further steps that need to be taken after the Wii Remote is paired have not been reverse engineered yet.

Once the Wii Remote is synced, when a button is pressed, it will actively seek out its paired host and try to connect to it, instead of the other way around. Establishing a connection can be done on PSM 0x11 for writing and PSM 0x13 for reading using the Bluetooth L2CAP protocol.

Button Hardware

The physical hardware of the buttons varies: there are membrane switches and microswitch click buttons. There has been some success soldering wires to the membrane switch contacts and actuating the switch through an external switch. The following table describes the physical hardware for each input.

Function Switch type Circuit board surface
A membrane top, SW9
B membrane bottom, SW8
- microswitch top, SW10
Home microswitch top, SW11
+ microswitch top, SW5
1 membrane top, SW7
2 membrane top, SW6
Up membrane top, SW4
Down membrane top, SW3
Left membrane top, SW1
Right membrane top, SW2
Sync bottom, SW12
Power top, SW13

Accelerometer

ADXL330 in a Wii remote
Coordinate system used by Wii Remote

The Wii Remote includes a three-axis linear accelerometer located on the top suface of the circuit board, slightly left of the large A button. The integrated circuit is the ADXL330 (data sheet), manufactured by Analog Devices. This device is physically rated to measure accelerations over a range of at least +/- 3g with 10% sensitivity.

Since the accelerometer actually measures the force exerted by a set of small proof masses inside of it with respect to its enclosure, the accelerometer measures linear acceleration in a free fall frame of reference. If the Wii Remote is in free fall, it will report zero acceleration. At rest, it will report an upward acceleration (+Z, when horizontal) equal to the acceleration due to gravity, g (approximately 9.8 m/s²) but in the opposite direction. This fact can be used to derive tilt from the acceleration outputs when the Wii Remote is reasonably still.

Normal Accelerometer Reporting

In all Data Reporting Modes which include Accelerometer data except for mode 0x3e/0x3f, the accelerometer data is reported as three consecutive bytes:

(a1) RR BB BB XX YY ZZ [...]

XX, YY, and ZZ are unsigned bytes representing the acceleration in each of the three axis, where zero acceleration is approximately 0x80. The coordinate system is shown in the diagram above (note that this is different from the coordinate system used by GlovePIE). Additionally, the BB BB Buttons bytes also include the LSBs of the acceleration values in the unused bits, according to the following table:

  Bit
Byte 7 6 5 4 3 2 1 0
0   X<1:0>  
1   Z<1> Y<1>  

Note that X has 10 bits of precision, while Y and Z only have 9. For consistency, they are assumed all to have a 10-bit range and the LSB is always set to zero for Y and Z.

Interleaved Accelerometer Reporting

In Data Reporting Mode 0x3e/0x3f, the accelerometer data is spread over two reports:

(a1) 3e BB BB XX [...]
(a1) 3f BB BB YY [...]

In this mode, the LSBs are not available. Instead, X and Y acceleration is reported as a single byte, and the Z value is encoded in the unused bits of the BB BB Buttons data as follows:

  Bit
Report ID Byte 7 6 5 4 3 2 1 0
0x3e 0   Z<5:4>  
0x3e 1   Z<7:6>  
0x3f 0   Z<1:0>  
0x3f 1   Z<3:2>  

IR Camera

Wii remote camera

The Wii Remote includes a 128x96 monochrome camera with built-in image processing. The camera looks through an infrared pass filter in the remote's plastic casing. The camera's built-in image processing is capable of tracking up to 4 moving objects, and these data are the only data available to the host. Raw pixel data is not available to the host, so the camera cannot be used to take a conventional picture. The built-in processor uses 8x subpixel analysis to provide 1024x768 resolution for the tracked points. The Sensor Bar that comes with the Wii includes two IR LED clusters at each end, which are tracked by the Wii Remote to provide pointing information. The distance between the centers of the LED clusters is 20 cm (as measured on one unit).

The IR Camera is enabled by setting bit 2 on output reports 0x13 and 0x1a:

(52) 13 04
(52) 1a 04

The first enables a 24MHz pixel clock on pin 7 of the camera. The second pulls pin 4 low - probably an active-low enable.

Mechanical Characteristics

The camera component is mounted on the bottom surface of the circuit board.

Optical Characteristics

The IR camera has an effective field of view is about 33 degrees horizontally and 23 degrees vertically (as measured on one unit). With the IR-pass filter intact, 940nm sources are detected with approximately twice the intensity of equivalent 850nm sources, but are not resolved as well at close distances. If the filter is removed, it can track any bright object.

Initialization

Reminder
Remember to set bit 2 (0x04) on the first byte of the Output Reports to write to registers!

The following procedure should be followed to turn on the IR Camera:

  1. Enable IR Camera (Send 0x04 to Output Report 0x13)
  2. Enable IR Camera 2 (Send 0x04 to Output Report 0x1a)
  3. Write 0x08 to register 0xb00030
  4. Write Sensitivity Block 1 to registers at 0xb00000
  5. Write Sensitivity Block 2 to registers at 0xb0001a
  6. Write Mode Number to register 0xb00033
  7. Write 0x08 to register 0xb00030 (again)

After these steps, the Wii Remote will be in one of 3 states: IR camera on but not taking data, IR camera on and taking data and half sensitivity, IR camera on and taking data at full sensitivity. Which state you end up in appears to be pretty much random. Repeat the steps until you're in the desired state. To avoid the random state put a delay of at least 50ms between every single byte transmission.

The Wii preforms these steps slightly different, differences in bold:

  1. Enable IR Pixel Clock (send 0x06 to Output Report 0x13)
  2. Enable IR Logic (send 0x06 to Output Report 0x1A)
  3. Write 0x01 to register 0xb00030
  4. Write Sensitivity Block 1 to registers at 0xb00000
  5. Write Sensitivity Block 2 to registers at 0xb0001a
  6. Write Mode Number to register 0xb00033
  7. Write 0x08 to register 0xb00030 (again)

Sensitivity Settings

Sensitivity is controlled by two configuration blocks, 9 bytes and 2 bytes long. The following settings are known to work:

Block 1 Block 2 Notes
00 00 00 00 00 00 90 00 C0 40 00 Suggested by Marcan
02 00 00 71 01 00 aa 00 64 63 03 Suggested by Cliff
00 00 00 00 00 00 90 00 41 40 00 Suggested by inio (max sensitivity)
02 00 00 71 01 00 64 00 fe fd 05 Wii level 1
02 00 00 71 01 00 96 00 b4 b3 04 Wii level 2
02 00 00 71 01 00 aa 00 64 63 03 Wii level 3 (also Cliff's suggestion)
02 00 00 71 01 00 c8 00 36 35 03 Wii level 4
07 00 00 71 01 00 72 00 20 1f 03 Wii level 5

The last byte of both blocks determines the intensity sensitivity, with increasing values reducing the sensitivity. The Wii Remote will return data for the dimmest objects possible when the last byte of block 1 is 0x41, and second byte of block 2 is 0x00. Setting the sensitivity as high as possible, without unwanted light being tracked, is recommended to achieve the highest subpixel resolution. As the sensitivity is reduced, the subpixel resolution also reduces, approaching the true sensor resolution of 128x96.

Data Formats

The IR Camera can return different sets of data describing the objects it is tracking. When the IR camera identifies an object, it assigns it to the first available object slot. If an object moves out of view, its slot is marked as empty (returns 0xFF data), but other objects retain their slots. For example, if the camera is tracking two objects and the first moves out of view, the data returned will be [empty, second object, empty, empty]. With more than four objects visible, the camera is prone to rapidly switching between some of them. This could allow perception of more than four objects, at a reduced response speed and reliability.

Mode Mode Number
Basic 1
Extended 3
Full 5

The data format MUST match the number of bytes available in the Reporting Mode selected. Even choosing a mode with space for more bytes than necessary will not work, it has to be an exact match.

Basic Mode

In Basic Mode, the IR Camera returns 10 bytes of data corresponding to the X and Y locations of each of the four dots. Each location is encoded in 10 bits and has a range of 0-1023 for the X dimension, and 0-767 for the Y dimension. Each pair of dots is packed into 5 bytes, and two of these are transmitted for a total of 4 dots and 10 bytes.

This is the data format for a pair of objects:

  Bit
Byte 7 6 5 4 3 2 1 0
0 X1<7:0>
1 Y1<7:0>
2 Y1<9:8> X1<9:8> Y2<9:8> X2<9:8>
3 X2<7:0>
4 Y2<7:0>

Extended Mode

In Extended Mode, the IR Camera returns the same data as it does in Basic Mode, plus a rough size value for each object. The data is returned as 12 bytes, three bytes per object. Size has a range of 0-15.

This is the data format for each object:

  Bit
Byte 7 6 5 4 3 2 1 0
0 X<7:0>
1 Y<7:0>
2 Y<9:8> X<9:8> S<3:0>

Full Mode

In Full Mode, the IR Camera returns even more data, 9 bytes per object for a total of 36 bytes for all four. The data is split up between two input reports of 18 bytes each (see Data Reporting Mode 0x3e/0x3f). The first three bytes of each object are the same as the extended mode, and are followed by the bounding box of the pixels included in the blob along with a deeper intensity value. The data format of each object is:

  Bit
Byte 7 6 5 4 3 2 1 0
0 X<7:0>
1 Y<7:0>
2 Y<9:8> X<9:8> S<3:0>
3 0 X min<6:0>
4 0 Y min<6:0>
5 0 X max<6:0>
6 0 Y max<6:0>
7 0
8 Intensity<7:0>

Feedback Features

The Wii Remote sports three feedback features: Player LEDs, Rumble, and the Speaker.

Player LEDs

Wii remote player LEDs

There are four blue LEDs on the front face of the Wii Remote. During discovery and before initialization, these LEDs blink at a fixed rate. The number of blinking LEDs is proportional to the battery voltage, indicating battery charge (all four are lit for newly charged batteries, and only the first is lit if the batteries are low and should be replaced).

During gameplay with the Wii, one LED is lit to indicate the player number assigned to the Wii Remote. However, the LEDs are independently controllable by the host, and can be set to display any pattern. They can also be modulated at a moderately high speed, enabling some brightness control at the cost of a lot of Bluetooth bandwidth. Sigma-delta modulation works reasonably well for this.

The LEDs can be controlled by sending a report with ID 0x11:

(52) 11 LL

The high nybble of LL controls the four LEDs. Bit 4 of LL controls the first LED, and bit 7 controls the last:

Bit Mask LEDs
4 0x10
·
··
···
····
5 0x20
·
··
···
····
6 0x40
·
··
···
····
7 0x80
·
··
···
····

Turning off all LEDs for an extended period of time is discouraged, as it might lead the user to believe the Wii Remote is turned off and disconnected, when in fact it is active.

The LEDs are surface mount parts, driven at 2.66 VDC.

Rumble

Wii remote rumble motor

The Wii Remote includes a rumble feature, which is implemented as a small motor attached to an off-center weight. It will cause the controller to vibrate when activated.

The rumble motor can be turned on or off through any of the Output Reports. Setting the LSB (bit 0) of the first byte of any output report will activate the rumble motor, and unsetting it will deactivate it. For example, the following report will turn the rumble motor on:

(52) 11 01

However, this will also have the side-effect of turning off all LEDs. Since there is no output report that only affects the rumble motor, and all of them do affect it, an implementation might need to store both the rumble and LED values locally (for example), and use the same Output Report for both. Another possibility would be using the status request report (0x15). The rumble bit needs to be set properly with every single report sent, to avoid inadvertently turning the rumble motor off.

Different photos of the rumble motor hardware show different markings. One example is SEM 8728DA. The Wii Remote drives it at 3.3 VDC and it draws 35 mA. It would be reasonable to think that the rumble motor could be removed and the motor replaced with another device with equal voltage and equal or less current draw.

Speaker

The Wii Remote has a small low-quality 21mm piezo-electric speaker, used for short sound effects during gameplay. The sound is streamed directly from the host, and the speaker has some adjustable parameters.

The speaker is controlled by using three output reports, together with a section of the register address space of the Wii Remote.

Report 0x14 is used to enable or disable the speaker. Setting bit 2 will enable the speaker, and clearing it will disable it. For example, to enable the speaker, send:

(52) 14 04

Report 0x19 is used to mute or unmute the speaker, and works identically to report 0x14. 0x04 will mute the speaker, and 0x00 will unmute it.

Report 0x18 is used to send speaker data. 1-20 bytes may be sent at once:

(52) 18 LL DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD

LL specifies the data length, shifted left by three bits. The DD bytes are the speaker data. To fullfill the report length requirements, the data must be padded if it is less than 20 bytes long. Sound data must be sent at the proper rate.

Initialization Sequence

Reminder
Remember to set bit 2 (0x04) on the first byte of the Output Reports to write to registers!

The following sequence will initialize the speaker:

  1. Enable speaker (Send 0x04 to Output Report 0x14)
  2. Mute speaker (Send 0x04 to Output Report 0x19)
  3. Write 0x01 to register 0xa20009
  4. Write 0x08 to register 0xa20001
  5. Write 7-byte configuration to registers 0xa20001-0xa20008
  6. Write 0x01 to register 0xa20008
  7. Unmute speaker (Send 0x00 to Output Report 0x19)

Speaker Configuration

7 bytes control the speaker settings, including volume. The full purpose of these bytes is not known, but the following values seem to produce some sound:

00 FF RR RR VV 00 00

RR RR specify the sample rate (little-endian format), using the following formulae:

pcm_sample_rate = 12000000 / rate_value adpcm_sample_rate = 6000000 / rate_value

The standard value is 0x7d0, for 3000Hz 4-bit PCM

FF configures the data format. Setting it to 0x40 configures the speaker to use signed 8-bit PCM, while setting it to 0x00 configures it to use 4-bit Yamaha ADPCM. VV specifies the volume, which has a range of 0x00-0xFF for 8-bit mode, and 0x00-0x40 for 4-bit mode.

This configuration can be used to play 4-bit ADPCM sound at 3000Hz:

00 00 D0 07 40 00 00

This configuration can be used to play 8-bit PCM sound at 1500Hz sample rate:

00 40 40 1f 40 00 00

Sound Data Format

The Wii Remote can use multiple sound formats at multiple sampling rates. PC drivers currently seem unable to keep up with the higher rates.

The 4-bit ADPCM is Yamaha ADPCM (for example, as implemented in ffmpeg).

8-bit signed PCM mode works, but when in 8-bit mode the sampling frequency must be made so low that the audio quality is pretty bad.

Extension Controllers

The Wii Remote includes a 6-pin proprietary expansion connector, which carries synchronous serial data to and from external add-ons, using a two-wire interface. These include the Nunchuk and the Classic Controller, the Guitar Hero guitars, the Guitar Hero World Tour drum kit, and Wii Motion Plus. These addons map onto a portion of the Wii Remote's register space, and can also stream data out through Output Reports (see Data Reporting for a list of modes which include Extension Controller data).

Registers / Initialization

Reminder
Remember to set bit 2 (0x04) on the first byte of the Output Reports to write to registers!

Wii Motion Plus is mapped at register 0xa60000.

Other extension Controllers are mapped at register address 0xa40000. The data is 0x100 bytes long, and it is mirrored across the entire 16-bit address space up to 0xa4FFFF. These registers are readable and writable. Communications are optionally encrypted, and explicit initialization is required to disable encryption (see below).

In encrypted mode, bytes can be decrypted using the following transformation:

decrypted_byte = (encrypted_byte XOR table1[address%8]) + table2[address%8]

Where table1 and table2 are 8-byte tables calculated based on the 16-byte key sent by the host, and address is the address of the byte being read (only the bottom 3 bits matter). If the host key is 16 zero bytes, table1[x] and table2[x] are all 0x97. The value 0x17 was used previously, which is equivalent. Proof of why any two pairs of table entries a,b and x,y are equivalent if (a^b^x^y)&0x80 == 0 is left as an exercise to the reader.

The calculations should be performed mod 256, that is, truncated to 8 bits (in languages such as C and Python, use &0xFF or work directly with 8-bit datatypes).

If the Wii Remote is initialized using the new method listed below, then the encryption of the extension bytes is disabled and they need not be decrypted using the transform listed above.

The Wii Remote will stream data bytes from the Extension Controller starting at offset 0x08, and continuing for however many bytes the current Data Reporting Mode requires. Data streamed through the Input Reports must also be decrypted using the above transformation if encryption is enabled.

Identification

Once initialized, the last six bytes of the register block identify the connected Extension Controller. A six-byte read of register 0xa400fa will return these bytes. The Extension Controller must have been initialized prior to this. There are two ways of initializing the extension.

The Old Way

The old way to initialize the extension was by writing the single encryption byte 0x00 to 0x(4)A40040, but that only works on Nintendo's own brand extensions and the GH3 Guitar, and will fail on 3rd party wireless nunchuks and GHWT extensions. If it fails, the 6 bytes will be FFFF FFFF FFFF. With this method you must decrypt the extension bytes to read them.

The New Way

The new way to initialize the extension is by writing 0x55 to 0x(4)A400F0, then writing 0x00 to 0x(4)A400FB. It works on all extensions, and makes the extension type bytes unencrypted. This means that you no longer have to decrypt the extension bytes using the transform listed above.


Encrypted Decrypted Meaning
0000 0000 0000* 0x2E2E BladeFX adapter that has been initialised old way, unplugged then replugged
FFFF FFFF FFFF* 0xFFFF GHWT Guitar or Drums or synced BladeFX or other wireless nunchuk initialised the old way
0xFEFE 0000 A420 0000 Nunchuk
0xFDFD 0000 A420 0101 Classic Controller
0xFDFB 0000 A420 0103 GH3 or GHWT Guitar
0xFDFB 0100 A420 0103 Guitar Hero World Tour Drums
0300 A420 0103* DJ Hero Turntable
0000 A420 0402* 0x2A2C Wii Balance Board
0000 A420 0405* Activated Wii Motion Plus
0000 A420 0505* Activated Wii Motion Plus in Nunchuck passthrought mode
0000 A420 0705* Activated Wii Motion Plus in Classic Controller passthrought mode

(4)A60000:

Encrypted Decrypted Meaning
0000 A620 0005* Inactive Wii Motion Plus
0000 A620 0405* No-longer active Wii Motion Plus
0000 A620 0505* No-longer nunchuk-passthrough Wii Motion Plus
0000 A620 0705* No-longer classic-passthrough Wii Motion Plus


The values marked with a * are actually already unencrypted, and should not be decrypted. They are given here along with unencrypted version for those wanting to use simplified detection code. You can easily tell whether a value should be decrypted or not by looking at the other values in the 0xa400fa to 0xa400fd region.

The "Partially inserted" condition allegedly occurs when the connector is loose or has a bad connection. Usually, this will correct itself upon full insertion. However, it has been known to "stick" in the partially inserted state rarely. This is a hardware glitch, the fix is to simply disconnect and reconnect the Extension Controller. Third party controllers such as wireless nunchuks also return this value if initialized with the old method, in which case the whole last 16 bytes will be FF.

Contrary to previous documentation, the 0000 0000 0000 value does NOT occur when nothing is inserted. Instead you get error 7 when you try to read the expansion type. A successful 0000 0000 0000 only occurs when a BladeFX wireless nunchuk is synced, initialized with the old method, then the adapter is unplugged, then the adapter is replugged.

A Wii Balance Board extension is only found in a Wii Balance Board. Although it exposes functionality as an Extension Controller, they are not separable and this controller is documented separately.

Encryption setup

After the identification is read, the encryption can be set up if required. This is done by enabling encryption by writing 0xAA to extension register 0xF0, and then writing the 16-byte key to register 0x40. The key is written in 3 blocks of 6, 6, and 4 bytes. (Writing a single encryption byte to register 0x40 will work on genuine Nintendo controllers, but not on others). After this the extension can be operated in full encryption mode.

Extension Controller Documentation

Individual Extension Controllers are described on the Extension Controllers page.

Acknowledgements

Some of the information here is based on the documentation at Wiili