Wiimote

This page is intended to be a technical guide to the Wii Remote. For an excellent high-level overview of the Wii Remote (aka Wiimote), see the Wikipedia entry.

Communication

The Wiimote communicates with the Wii via a Bluetooth wireless link. The Bluetooth controller is a Broadcom 2042 chip, which is designed to be used with devices which follow the Bluetooth Human Interface Device (HID) standard, such as keyboards and mice. The Bluetooth HID is directly based upon the USB HID standard, and much of the same documentation applies.

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

Name	Nintendo RVL-CNT-01
Vendor ID	0x057e
Product ID	0x0306

The Wiimote does not appear to require any of the authentication or encryption features of the Bluetooth standard. In order to interface with it, one must first put the controller into 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 Wiimote can be queried by the Bluetooth HID driver on the host. If the HID driver on the host does not connect to the Wiimote within 20 seconds, the Wiimote will turn itself off. Holding down the 1 and 2 buttons continuously will force the Wiimote to stay in discoverable mode without turning off. This does not work with the sync button, however. When in discoverable mode, all 4 of the Player LEDs will blink.

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 Wiimote reports its HID descriptor block when queried using the SDP protocol. A human-readable version of the block is shown at Wii_bluetooth_specs, and is summarized in the following table:

Output Report ID Payload Size Known Functions 0x11 1 Player LEDs, Force Feedback 0x12 2 Report type / ID 0x13 1 IR Sensor Enable 0x14 1 Enable speaker 0x15 1 Controller status 0x16 21 Write data 0x17 6 Read data 0x18 21 Speaker data 0x19 1 Mute speaker 0x1a 1 IR Sensor Enable 2

Input Report ID Payload Size Known Functions 0x20 6 Expansion Port 0x21 21 Read data 0x22 4 Write data 0x30 2 Buttons only 0x31 5 Buttons | Motion Sensing Report 0x32 16 Buttons | IR?? 0x33 17 Buttons | Motion Sensing Report 0x34 21 Buttons | IR?? 0x35 21 Buttons | Motion Sensing Report 0x36 21 Buttons | IR?? 0x37 21 Buttons | Motion Sensing Report 0x3d 21 Buttons | IR?? 0x3e 21 Buttons | Motion Sensing Report | IR?? 0x3f 21 Buttons | Motion Sensing Report | IR??

Note that "Ouput" refers to packets are sent from the host to the Wiimote, and "Input" refers to packets that are sent from the Wiimote to the host. For clarity, the convention in this document is to show packets including the Bluetooth header (in parentheses), report ID (also called channel ID in some places), 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), on channel 0x30, with the two byte payload 0x00, 0x00.

Force Feedback is accessible through ALL output channels the same way. This is not included above to avoid clutter.

Linux Notes

On Linux hosts, the BlueZ bluetooth drivers, included in recent 2.4 and 2.6 kernels, allow communication with Bluetooth devices. The BlueZ stack includes a kernel module, hidp, which connects to Bluetooth HID-capable devices. To instruct the kernel to connect to the Wiimote, you will need the bluez-utils package, which includes the hidd daemon. First put the Wiimote into discoverable mode, then run

hidd --search

This will scan for all HID-capable devices and connect to them. After receiving the connection, the Player LEDs will continue to blink, but the Wiimote will not power down until the connection is broken. By default, hidd will maintain the connection for 30 minutes beyond the last packet exchange. Received packets can be observed using the hcidump command:

hcidump -X

Sending packets to the Wiimote requires access to the control and interrupt Bluetooth sockets established by hidd. A modified version of hidd is needed to retain these sockets, and a customized version for the Wiimote will be posted soon.

It should be noted that the HIDP driver creates a /dev/input/eventX when the Wiimote connection is established (see dmesg for a message reporting which event device it is). Preliminary tests suggest this interface is unsuitable for accessing the Wiimote because of the unusual HID information it reports. This is why a lower-level userspace daemon is thought to be required to communicate with the Wiimote directly via Bluetooth sockets.

MacOS X Notes

The Wiimote does not yet work on OS X. The Bluetooth Setup Assistant can be used to setup the connection, by selecting the "Any Device" option, and then selecting "Do not use a passkey with this device" in the Passkey options. However, due to the unusual HID descriptor for the Wiimote, OS X does not activate the Bluetooth HID driver, and the Wiimote powers off at the end of the 20 second timeout. An OS X application that connects to the Wiimote and manually reimplements the HID protocol is in progress, as described in this forum topic.

It is possible to access the Wiimote from Linux running directly on Mac hardware, or a Linux virtual machine running inside a virtualizer like Parallels. See this post for more information about how to use Bluetooth devices from a Linux VM.

Windows XP Notes

There is a Windows "driver" called GlovePIE[1]. It can read the buttons and accelerations, and it can set the leds and the rumble.

The wiimote is accessible exacly like a USB HID device: using Delphi and the TJvHidDeviceController component. You can access all the info with the demo program (ReadWriteDemo\SimpleHIDWrite.dpr). I am using W2K.

The wiimote can be paired with Windows XP and a generic driver is installed. It appears in the game controller's panel but cannot be configured in any way.

Some people have had trouble sending reports to the Wiimote. Some people have got around this by using a different bluetooth stack. Being unable to send reports to the wiimote makes it impossible to read the acceleration data. The Bluesoleil bluetooth stack is most recommended to fix these problems. The problem of sending reports occurs with the TJvHidDeviceController component.

Inputs

Buttons

There are 12 buttons on the Wiimote. Four of them are arranged into a directional pad, and the rest are spread over the controller.

By default, whenever a button is pressed or released, a packet is sent to the host via HID input report 30H, with a payload containing a 2-byte bitmask with the current state of all the buttons.

The button state also seems to be included in the first two bytes of all other input reports.

Some of the bits in the first two bytes don't seem to be directly related to button presses, and are somewhat unknown. Their activity seems to point towards them being the LSBs of the motion bytes, but it is impossible to determine which since their data is too random.

When the A button is pressed, this HID DATA input packet is received:

(a1) 30 00 08

and when it is released, this is packet received:

(a1) 30 00 00

The bit assignments (in big endian order) for the buttons are:

Button	Number (dec)	Value (hex)
Two	1	0x0001
One	2	0x0002
B	3	0x0004
A	4	0x0008
Minus	5	0x0010
? motion ?	6	0x0020
? motion ?	7	0x0040
Home	8	0x0080
Left	9	0x0100
Right	10	0x0200
Down	11	0x0400
Up	12	0x0800
Plus	13	0x1000
? motion ?	14	0x2000
? motion ?	15	0x4000
? Reading Mii ?	16	0x8000

The power button is unusual in that it sends a disconnect request when held down instead of emitting a normal button code.

Motion Sensor

File:Wiimote axes.png Coordinate system used by Wiimote

The motion of the remote is sensed by a 3-axis linear accelerometer located 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.

Inside the chip is a small micromechanical structure which is supported by springs built out of silicon. Differential capacitance measurements allow the net displacement of the tiny mass to be converted to a voltage, which is then digitized. It is important to note that the sensor does not measure the acceleration of the Wiimote, but rather the force exerted by the test mass on its supporting springs. Due to the sign convention used, this quantity is proportional to the net force exerted by the player's hand on the Wiimote when holding it. Thus, at rest on a flat table, the accelerometer reports vertical force of +g (the mass can be normalized away into the aribitrary units), and when dropped reports a force of nearly zero.

The sensor uses a right-handed coordinate system with the positive X-axis to the left, and the positive Z-axis pointing upward, when the remote is held horizontally, as shown in the diagram at the right. Forces on each axis are digitized to 8 bit unsigned integers, with the zero scale set to 0x80. Manufacturing and calibration defects of course cause some intrinsic zero offsets. However, the Earth's gravitational field and a flat, level surface upon which to rest the remote, in principle, allow any offsets or chip skew to be measured and calibrated away in software. Decomposing the force measured by the sensor into rotation and linear components is tricky, and discussed further on the [Motion analysis] page.

The Wiimote does not normally report motion sensor readings to the host, but can be requested by sending SET_REPORT request to channel 0x12:

(52) 12 00 31

The 3rd byte is a bitmask. 0x01 turns on the rumble, and 0x04 turns on continuous output. If 0x04 is not set, packets are only output when the values change (almost always when the motion sensor is enabled). If 0x04 is set, values are output continuously (it's obvious when channel/mode 0x30 is chosen, which disables motion readback. With byte3=0x04, the button values are output multiple times a second. With byte3=0x00, they are output only when you press or release a button). The 4th byte specifies which HID channel to which log sensor output should be sent. After receiving this command once, the Wiimote will send back stream of DATA INPUT packets on the requested channel/mode (0x31 in the above example), where the 5th, 6th and 7th bytes contain the X, Y, and Z readings of the accelerometer. A sample packet when the Wiimote is at rest, face up, on a table is:

(a1) 31 40 20 86 8a a5

where 0x86 is the X-axis measurement, 0x8a is the Y-axis measurement, and 0xa5 is the Z-axis measurement. The first two bytes of the payload, 0x40 and 0x20, are the button values and some unknown bits. It is not known what these bits are, as they change apparently randomly with no obvious pattern. One possible explanation is that they are the LSBs of the motion sensor values. The button values are still in the same place and have the same meanings as in the Buttons section.

Other channels can be selected for motion sensor reports, including 0x31, 0x33, 0x35, 0x37, 0x3e and 0x3f. If either 0x3e or 0x3f are selected then sensor readings will alternate between the two channels. The length of the report payload will depend upon the channel, as show in the table in HID Interface section. Channels which have payloads longer than needed for the motion sensor are used to report information from other peripherals, such as the IR camera. If these are disabled, 0xff data is returned in the extra space:

(a1) 33 40 00 86 8a a5 ff ff ff ff ff ff ff ff ff ff ff ff ff

Motion sensor reports can be stopped by setting the output channel to 0x30:

(52) 12 00 30

It the channel mode is actually a mode selection. Button output is always enabled. Mode 0x30 is just buttons, 0x31 is motion sensor, and 0x33 is both IR camera and motion sensor. The two sets of data are tacked onto each other, first the button values, then the three motion sensor bytes, then the camera bytes. Other modes seem to include motion data and / or IR data in different ways.

IR Sensor

During R&D, Nintendo discovered the motion sensors were not accurate enough to use the remote to control an on-screen cursor. To correct this, they augmented the remote with an infrared image sensor on the front designed to locate two IR beacons within the controller's field of view. The beacons are housed within a device misleadingly called the sensor bar. The sensor bar is powered by the Wii base unit, and contains 2 groups of IR LEDs, spaced 7.5 inches apart. Each group is composed of 5 LEDs, but homemade sensor bars have been effective with fewer LEDs, so long as the intensity is sufficient. The cable from the Wii to the sensor bar only carries power. No information is passed either to or from the sensor bar, and the intensity is not modulated in any way.

These two sources of IR light are tracked by a PixArt sensor in the front of the Wiimote housing. By tracking the locations of these two points in the sensors 2D field of view, the system can derive more accurate pointing information. Not much is known about this feature yet, but circumstantial evidence from the Nintendo/PixArt press release suggests that Nintendo is using a PixArt System-on-a-Chip to process the images on-board the Wiimote and sends the minimum information needed for tracking back to the base unit. Transmitting full 2D images constantly would require a prohibitive amount of bandwidth, especially when multiple remotes are in use.

The Wiimote detects and transfers up to four IR hotspots back to the host. Various amounts of data can be requested, from position values only, position and size, to position, size and pixel value. The amount of different configurations are quite numerous, and also ties in with the connected peripheral device.

Work is being done on how to enable and use the IR sensor. Currently, we can enable it and set the correct sensitivity, and receive position and brightness data successfully.

marcan's info

Here are the reports you need to send to activate IR transmission:

(52) 12 00 33
(52) 13 04
(52) 1A 04
(52) 16 04 B0 00 30 01 08 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
(52) 16 04 B0 00 06 01 90 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
(52) 16 04 B0 00 08 01 C0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
(52) 16 04 B0 00 1A 01 40 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
(52) 16 04 B0 00 33 01 33 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Python / pseudocode follows.

FEATURE_DISABLE = 0x00
FEATURE_ENABLE = 0x04

IR_MODE_OFF = 0
IR_MODE_STD = 1
IR_MODE_EXP = 3
IR_MODE_FULL = 5

CMD_SET_REPORT = 0x52

RID_LEDS = 0x11
RID_MODE = 0x12
RID_IR_EN = 0x13
RID_SPK_EN = 0x14
RID_STATUS = 0x15
RID_WMEM = 0x16
RID_RMEM = 0x17
RID_SPK = 0x18
RID_SPK_MUTE = 0x19
RID_IR_EN2 = 0x1A

MODE_BASIC = 0x30
MODE_ACC = 0x31
MODE_ACC_IR = 0x33
MODE_FULL = 0x3e

def send(cmd,report,data):
    Send cmd, report, data to Wiimote. If cmd is CMD_SET_REPORT, this amounts to sending data to the specified report.
    Interface code to Wiimote goes here.

def setmode(mode,cont):
        aux = 0
        if rmbl:
                aux |= 0x01
        if cont:
                aux |= 0x04
        send(CMD_SET_REPORT,RID_MODE,[aux,mode])

# size here is redundant, since we can just use len(data) if we want.
def senddata(data,offset,size): # see writing to data under On-board memory.
        of1 = offset >>; 24 & 0xFF #extract offset bytes
        of2 = offset >> 16 & 0xFF
        of3 = offset >> 8 & 0xFF
        of4 = offset & 0xFF
        data2 = data + [0]*(16-len(data)) # append zeros to pad data if less than 16 bytes
        if len(data2) > 16:
                data2 = data2[:16] # crop data if we have too much
        # format is [OFFSET (BIGENDIAN),SIZE,DATA (16bytes)]
        send(CMD_SET_REPORT,RID_WMEM,[of1,of2,of3,of4,size]+data2)

# this seems to be the minimal code to get it to work
setmode(MODE_ACC_IR,0)
send(CMD_SET_REPORT,RID_IR_EN,[FEATURE_ENABLE])
send(CMD_SET_REPORT,RID_IR_EN2,[FEATURE_ENABLE])
senddata([8],0x04B00030,1) # enable IR data out
senddata([0x90],0x04B00006,1) # sensitivity constants (guessed, Cliff seems to have more data, but this works for me)
senddata([0xC0],0x04B00008,1)
senddata([0x40],0x04B0001A,1)
senddata([IR_MODE_EXP],0x04B00033,1) # enable IR output with specified data format

# this is Cliff's version pythonified, probably more accurate as far as sensitivity. Works pretty much the same for me.
setmode(MODE_ACC_IR,0)
send(CMD_SET_REPORT,RID_IR_EN,[FEATURE_ENABLE])
send(CMD_SET_REPORT,RID_IR_EN2,[FEATURE_ENABLE])
senddata([1],0x04B00030,1) # seems to enable the IR peripheral
senddata([0x02, 0x00, 0x00, 0x71, 0x01, 0x00, 0xaa, 0x00, 0x64],0x04B00000,9)
senddata([0x63, 0x03],0x04B0001A,2)
# this seems incorrect - for FULL IR mode, we must use FULL wiimote mode (0x3e).
# otherwise the data is probably garbled.
senddata([IR_MODE_FULL],0x04B00033,1) 
senddata([8],0x04B00030,1) # Enable data output. Can be specified first it seems, we don't really need to be in mode 1.

Output format EXP is three bytes per dot recognized. Bytes 0 and 1 are X and Y, byte 2 is the LSBs of X and Y and a size value. In binary:

xxxxxxxx yyyyyyyy yyxxssss

No dot is indicated by 0xff data. This means you will not see any change in the output data even if you did do all the initialization correctly, unless you actually point the Wiimote at a (powered) sensor bar!

Output format for FULL is unknown, but we know the data is interleaved. Data sent to report 0x3e contains the data for the first two dots recognized, data sent to 0x3f contains the data for the next two dots recognized, if any.

Note that the original hidd patch has trouble with 0x00 bytes in commands. Make sure you're sending the right data.

Cliff's info

Set the report 0x12 to a report number such as 0x33.

You need to start by setting reports 0x13 and 0x1a to 0x04 to enable transmission.

Then to activate the IR Sensor you need to write to the wiimote's memory. Set 0x04b00030 to 1, then set the sensitivity, then set 0x04b00033 to 5, then set 0x04b00030 to 8.

The sensitivity data is 9 bytes at 0x04b00000 and 2 bytes at 0x04b0001a. For midrange sensitivity, it's {0x02, 0x00, 0x00, 0x71, 0x01, 0x00, 0xaa, 0x00, 0x64}, and {0x63, 0x03}.

Outputs

Player LEDs

The bottom edge of the remote body contains 4 blue LEDs. These LEDs are used during normal play to indicate that the remote is in Bluetooth discoverable mode (all blinking), or to indicate the player number of the controller (one light illuminated). The LEDs are independently controllable, however, using SET_REPORT ouput packet to channel 11, which has a payload size of 1. The most-significant 4 bits control each LED, with bit 4 corresponding to the player 1 LED. Channel 11 also can control the rumble feature, so it is best to keep the 4 least-significant bits zero in order to avoid vibrating the controller. For example, this packet turns on the player 1 LED only:

(52) 11 10

Since each LED has its own bit, any combination of LEDs can be illuminated.

Force Feedback

Force feedback is provided via a "rumble pack" style device inside the Wiimote body. It is roughly an off-center weight connected to a motor which can be activated to cause the controller to vibrate. The motor can be activated by sending a SET_REPORT output packet to channels 0x11, 0x13, 0x14, 0x15, 0x19 or 0x1a with the least significant bit set:

(52) 13 01

And the vibration can be turned off by clearing the bit:

(52) 13 00

So far, it appears all channels are equivalent, though using channel 0x11 is not advised because it also controls the player LEDs.

Speaker

A small speaker is embedded in the top face of the controller to provide audio feedback. The control method of this speaker is still somewhat unknown.

On-board Memory

The remote carries 4 KB of on-board memory, used by the Wii to store the Mii character users can construct when playing games like Wii Sports.

We can now read data. Here's the command:

(52) 17 0r 00 FF FF SS SS

FF FF is the offset (big-endian format). SS SS is the size in bytes. The low bit of r is the usual rumble flag. Others unknown.

The responses look like this:

        btns? S  FF FF data
        vvvvv v  vv vv v------>
(a1) 21 80 00 f0 11 f0 80 6c 8c c7 c2 5d 2e bd 40 00 4e 00 99 80 08 b1                              

S is the size in bytes, minus one, for the current packet. FF is the offset of the current packet (big-endian). Everything else is the data (16 bytes max, if there is an incomplete trailer S is set to something other than 0xF and the data is padded out.)

Writing data is as follows:

        FF FF FF FF SS data
        vv vv vv vv vv v------>
(52) 16 00 00 00 00 10 57 69 69 57 69 6c 6c 52 6f 63 6b 59 6f 75 21 21

FF,SS same meaning as reading (you can only write 16 bytes at a time here, so SS is only one byte). 16 bytes of data follow. It seems we get some kind of acknowledge on Input 0x22.

The offset is 32 bits at least on the Write Data command. Offsets with the "rumble bit" set will trigger rumble. The high byte of the offset seems to specify a different memory type other than internal Flash. Offsets beginning with 0x04B00000 are used to configure the IR sensor.

Expansion Port

The expansion port on the bottom of the unit is used to connect the remote to auxiliary controllers which augment the input options of the Wiimote. Auxiliary controllers use the Bluetooth interface of the remote to communicate with the Wii base unit, allowing them to be much simpler and cheaper to build. Currently available controllers are the Nunchuk and the Classic controller.

The expansion port itself is a ???-style connector with 6 contacts. Two of the contacts are slightly longer, which allows them to make contact first when a plug is inserted. Presumably these contacts carry Vcc and ground, much like standard USB connectors. The remaining 4 contacts most likely carry data, and the small number suggests that a serial interface of some sort is used. The connector is not suitable for charging the remote. More information is needed on the electrical specifications of this connector.

The status of the expansion port is indicated with report 20H. This report is sent whenever the status of the expansion port changes, or when the computer sends output report 15H to request the status.

After an attachment is plugged in or unplugged, no other reports are sent except 20H. The computer needs to send an output request (report 12H) to retrieve new input reports.

The format of input report 20H consists of the report number, then two bytes which are presumably the button state like in other reports, then a status flags byte, then two unknown 00 bytes, then a device byte.

Status byte flags

bit	Value (hex)	Flag
0	0x01	? 0 ?
1	0x02	any attachment plugged in
2	0x04	? 0 ?
3	0x08	continuous output mode
4	0x10	LED 1
5	0x20	LED 2
6	0x40	LED 3
7	0x80	LED 4

Device byte values

Value	Device
0x00	Nothing, just the remote
0x63	Nunchuk
0x84	Classic Controller
0x85	Classic Controller
0x86	Classic Controller

For example, when the classic controller is plugged in, input report 20H is sent:

(a1) 20 00 00 02 00 00 86

The 02H indicates the classic controller has been plugged in. The 86H varies between 84H, 85H and 86H, with no apparent pattern.

When the classic controller is unplugged, input report 20H is sent again, but with 00 instead of the 02:

(a1) 20 00 00 00 00 00 84

Note that the 84H could be 84 85 or 86. It seems irrelevant which one it is. It is the 00 in the middle which is important.

The 84, 85, 86 seems to indicate the attachment. A nunchuk attachment behaves identically, except that the last byte is 63H always:

(a1) 20 00 00 02 00 00 63

Unknown behavior / Random findings

Sending a byte to ID 0x15 returns the Extension status report (at 0x20, see above), besides setting rumble. Seems everything sets rumble if bit 0 of the first byte is set.

The third byte in the extension status report (00/02 above) can take other values. It seems only that bit is the status, other bits can take on other values depending on the bytes sent to 0x13 and 0x14. For example, sending 0x04 to ID 0x13 makes the values in byte 3 be 08/0a instead of 00/02.