Example Program on how to use the Windows HID API for Wii Remotes.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
HIDAPI-Test
.gitattributes
.gitignore
LICENSE.md
README.md

README.md

Wiimote-HIDAPI

This started as a simple program to test the current state of the Windows HIDAPI in regards of Nintendo Wii Remotes. But it grew into an example program to show off an implementation for the communication with Wiimotes, that works on Windows 7 and higher, support "-TR" Wiimotes, the Toshiba Bluetooth Stack, as well as the DolphinBar.

Current State

The program shows, that on Windows 8 and higher "-TR" Wiimotes are working completly fine with the Microsoft Bluetooth Stack and the Toshiba Bluetooth Stack is not required anymore, especially as the common "hack". However a bug in the default Microsoft HID Class Driver on Windows 7 renders the "WriteFile"-Method unusable on Windows 7, therefore it is not possible to use the HIDAPI to send data to "-TR" Wiimotes.

HIDAPI

Sending & Recieving

Sending HID Reports:

Recieving HID Reports:

The MSDN Design Guides Sending HID Reports and Obtaining HID Reports are stating, that WriteFile and ReadFile are the preferred methods to send and recieve data from the device. Additionally sending data to a "-TR" Wiimote via WriteFile is working fine, whereas using HidD_SetOutputReport will result in the Wiimote turning off.

Issues with WriteFile

As the MSDN Desgin Guide Sending HID Reports by Kernel-Mode Drivers (WriteFile will send out an IRP_MJ_WRITE request to the driver interface) suggests, the output report buffers shall have the size of the largest output report supported by the device. In case of the Wiimote this is 22 Byte.

This seems to be currently enforced by the Microsoft HID Class Driver on Windows 7 and the Toshiba Bluetooth Stack, as they will fail WriteFileattempts with the error ERROR_INVALID_USER_BUFFER, when the buffer size is less.

On Windows 7 however more bytes than the acutal report are sent to the device, which produces an error on the Wiimote. It is unknown whether this is a bug or intented behaviour. The Toshiba Bluetooth Stack in contrast only sends the appropiate amount of bytes according to the used report to the device.

On Windows 8 and higher, the output report buffer can be arbitrary in size, as the given amount of byte are submitted to the device.

This results in the following table of compability.

Table of compability

x Toshiba Stack Win 7 Win 8.1 Win 10
WriteFile Largest Report Size + - - -
WriteFile Acutal Report Size - - + +
SetOutputReport - +* +* +*

* does not support "-TR" when connected via Bluetooth

Method Priority Order

This leads us to the following order of prioritized methods:

  1. Detect whether the Microsoft Stack or the Toshiba Stack is used for the Wii Remote.
  2. In case of Toshiba Stack, use WriteFile with the largest report size for the buffer
  3. In case of Microsoft Stack, try WriteFile with the actual report size
  4. If WriteFile fails, fall back to HidD_SetOutputReport

Detecting Stack

To detect the used stack for the Wiimote, the provider property of the used HID Class Driver is evaluated. As the enumerated Wiimote Devices are just raw PDO's, that are acting as interfaces for the HID Class Driver and don't have a driver directly associated with, it is neccessary to move one node up in the device tree to get to the device node that is associated with the HID Class Driver. To do so the PnP Configuration Manager API is used.

Why WriteFile supports "-TR"

It is believed, that the usage of HidD_SetOutputReport will result in sending the output report via the Control Channel. This is not supported by "-TR" Wiimotes, as they will immediately shut down. In contrast WriteFile seems to send the data to device via the Interrput/Data Channel.

DolphinBar

The Mayflash DolphinBar enumerates Wiimotes as USB Devices, resulting in using the Microsoft HID Class Driver. Therefore WriteFile won't work on Windows 7 for Wiimotes connected through the DolphinBar either. However as the DolphinBar takes care of the Bluetooth communication and the outgoing data is send via USB to the DolphinBar, HidD_SetOutputReport does support "-TR" Wiimotes as long as they are connected through a DolphinBar.

License

This project is licensed under the terms of the MIT license.