Skip to content

API Documentation

Jump to bottom
Nico edited this page Oct 11, 2015 · 15 revisions

####Single and multi report HID devices HID Project introduced a lot of new features. To use them the previously used multi report does not support all features (without side effects/bugs e.g. more than 1 Gamepad glitches). Because of that I added single reports as well. But what does this mean?

You can declare HID devices in two ways: Each device gets it own report or you smash them all together. Last open we used till 2.3. With 2.4 both options are supported and they have their pro and cons. All basic features should be possible with a multireport. You can have a look at the specific API documentation which report type is supported with what name (example: Keyboard vs BootKeyboard).

The difference you should care about is the endpoint limitation of the microcontrollers. The 32u4 has 6 USB endpoints and the 8/16/32u2 series only 4 (with less USB_EP_SIZE on top of that: 64 vs 16 bytes). This means that you can only add a limited number of devices. The CDC Serial uses 3 endpoints. This means you can add up to 3 devices for the 32u4 and 1 for the 8/16/32u2. If you add more, some will be ignored.

This means especially for the 8/16/32u2 you want to use the multi reports (which only use 1 endpoint even with multiple devices) but may have less features (such a leds or boot keyboard support). Or you decide on using only a BootKeyboard and nothing else. With the 32u4 you have more room to play with. Deactivating the CDC Serial is currently not possible, maybe soon (part of the Arduino IDE, not my "fault").

Multi reports use the pluggable HID of the Arduino IDE. This adds a little overhead to the HID API. If you can avoid this, use single report devices. It is also recommended to use only multi reports or only single reports. You can mix them, but it adds even more overhead. Each API is available as single and multi report.

Supported Arduinos (IDE 1.6.6 or higher!):

  • Uno (with HoodLoader2)
  • Mega (with HoodLoader2)
  • Leonardo
  • (Pro)Micro
  • Any other 8u2/16u2/at90usb8/162/32u2/32u4 compatible board

Supported HID devices:

  • Keyboard with Leds out (modifiers + 6 keys pressed at the same time)
  • NKRO Keyboard with Leds out (press up to 113 keys at the same time)
  • Mouse (5 buttons, move, wheel)
  • Absolute Mouse
  • Consumer/Media Keys (4 keys for music player, web browser and more)
  • System Key (for PC standby/shutdown)
  • Gamepad (32 buttons, 4 16bit axis, 2 8bit axis, 2 D-Pads)

####Some experiments showed that (regarding multi reports only):

  • Make sure to not use too many HID devices at once. This can cause trouble with some OS.
  • Changing the devices causes driver problems under Windows
  • Mouse + Keyboard + System + Consumer works fine
  • Mouse and Absolute Mouse together dont work fine
  • Mouse Abs only works with system report under special circumstances.
  • Mouse and Gamepad together causes problems
  • Using Gamepad with any other HID device causes trouble
  • All OS have some problems with Gamepads. Dont use more than one device for Linux and be careful when you change the descriptor.
  • RawHID is not working properly, test it at your own risk.
  • XBMC 13.1 (a Media Center, now Kodi) uses Gamepad input. Its seems to not work and may cause weird errors. Even with a standard Gamepad I have these errors. Just want to mention it here.

####More specific key definitions for the HID devices can be found here:

Copyright (c) 2014-2015 NicoHood

Documentation (Home)

Clone this wiki locally