Enhanced HID protocol support for Arduino Leonardo & Pro Micro

[abratchik]

resolves #388
resolves #389
resolves #390
resolves #393

This pull request is to add new features to the USB API and HID API to extend its functionality.

1. Making the USB_SendStringDescriptor method public so that it can be used for creating custom string descriptors. This can be useful for projects where the string information needs to be passed over the USB back to host (in example, OEM Manufacturer name, battery chemistry etc).
2. Adding the method setSerial(const char*) to the HID class so that one can explicitly set the serial number for the board. Current implementation of the HID library allows only the auto-generated value, which creates issues sometimes because the serial is used in the Arduino board port name.
3. Extending the HID library to enable full support of the USB HID control pipe (methods SetFeature/GetFeature). Current implementation supports only the bulk interrupt (SendReport) functionality, which limits the USB HID use cases and leads to "spam" of the unsolicited messages from the device to the host.
   The main idea of the implementation - a public variable is declared in the sketch and then its address is passed to the HID library via SetFeature function. The address is stored in the memory along with the feature ID. The value of the var can be updated in the sketch loop at any time and sent to host whenever the host invokes the GetFeature through the USB HID protocol. The host can also update the variable (R/W features also supported).
4. Extending the HID library to enable string Feature (method SetStringFeature).

Changes are tested in the HID-Compliant UPS with Arduino project.

[CLAassistant]

All committers have signed the CLA.

[abratchik]

@facchinm This PR is ready for merge I believe :) Any issues please let know.

[obra]

Would you consider adding an example sketch that demonstrates these new features? Without documentation, code comments, or an example, it's likely that many folks will never discover or be able to use the new features you've added.

(Also, is there anything that limits this to the Leonardo & Pro Micro? It ought it to work for any 32U4 device.)

[abratchik]

Would you consider adding an example sketch that demonstrates these new features? Without documentation, code comments, or an example, it's likely that many folks will never discover or be able to use the new features you've added.

(Also, is there anything that limits this to the Leonardo & Pro Micro? It ought it to work for any 32U4 device.)

Hi Jesse, thanks for your interest. The usage of these features should be here ideally so I'm happy to extend this article with your kind advice how to do it (how to submit the changes properly). Currently there is only SendReport method, which limits the HID cases significantly. Basically, it only allows to "bombard" the host with HID reports regardless of the host state or intention to consume these messages. The proposed PR adds support of HID Feature, which is an essential part of HID protocol. With this PR, it will be possible to implement any HID compliant device on Arduino. I used it for my HIDPowerDevice project, which enables implementing HID-compliant UPS but this is only one of many possible scenarios. More details about this project are here.
The example of the sketch for the UPS is here. The usage is very simple - basically you can declare a global variable in your sketch and link it to a HID Feature, which is defined in the HID usage page of your project. Then you may change this variable in the Arduino loop as necessary but the host can "read" the value of your variable through the control pipe of the USB HID protocol. Moreover, the host can also write to this variable, and one can use it in the sketch as necessary.
Lastly, there is no limitation to Leonardo and Pro Micro only, of course, any 32U4 device will work. Some folks already tried it with Sparkfun, for example.