Better Readme

This commit is contained in:
Nico 2015-01-02 18:28:14 +01:00
parent bf249280a6
commit 8efa9e116d
4 changed files with 490 additions and 21 deletions

294
Readme.md
View file

@ -1,14 +1,141 @@
Arduino HID Project 2.1
=======================
![Header Picture](header.jpg)
This project went through a lot of phases and has now reached a new Arduino USB-Core
with a lot of new functions like extended HID. It also supports HoodLoader1+2.
The idea is to enable enhanced USB functions to almost all 'standard' Arduino boards.
This is done with slightly different methods for different boards.
**Supported Arduinos (IDE 1.5.8 or higher!):**
* Uno (with HoodLoader1 or 2)
* Mega (with HoodLoader1 or 2)
* Leonardo
* (Pro)Micro
* Any other 8u2/16u/at90usb162/32u2/32u4 compatible board
**Main features of the new USB-Core:**
* New HID devices(list below)
* HID reports are easier to modify now
* USB Wakeup
* Smaller flash/ram usage
* More Serial functions
* u2 Series support (HL2)
* HoodLoader1 compatible legacy example
**There are many more additions and fixes in this USB Core. See change log for more details.**
**Supported HID devices:**
* Keyboard with Leds out (modifiers + 6 keys pressed at the same time)
* Mouse (5 buttons, move, wheel) + Absolute Mouse
* Media Keys (4 keys for music player, webbrowser and more)
* System Key (for PC standby/shutdown)
* Gamepad (32 buttons, 4 16bit axis, 2 8bit axis, 2 D-Pads)
The HID project contains HID APIs to generate HID reports and functions to send them to the USB Host.
The API (syntax/usage) of the HID Project is always the same for each solution, **you can port code from one device to another very easy**.
* On a Leonardo this function is extended and improved to get more HID devices + some improvements.
* [HoodLoader2](https://github.com/NicoHood/HoodLoader2) is a BootLoader for the 16u2 that let's you use it as standalone MCU with the same USB-Core.
* [HoodLoader1](https://github.com/NicoHood/HoodLoader) is a 16u2 firmware that filters special HW Serial signals from the main MCU and sends HID signals to the USB Host.
To make things more clear the HID Software is in a separate repository than the HoodLoader (1 & 2) sources and installing instructions.
**HoodLoader 1&2 is only used for an Uno/Mega to actually enable USB functions.** The 16u2 is normally used for USB-Serial programming of the main MCU but can do way more than that.
To use HoodLoader1&2 you also need the HID Project. For more information and installation instructions see the specific repository.
HoodLoader1 was the first solution to enable HID functions to the Uno/Mega but HoodLoader2 opens way more options because you can reprogram the whole MCU standalone.
See the repository for more infos about this great new opportunity. HoodLoader1 API is still usable in a specific example. HoodLoader1&2 are not needed/compatible with a Leonardo/Micro.
Installation
============
put these files into *sketchbook/hardware/HID/*
Put all files from *avr/* into *sketchbook/hardware/HID/avr*.
Make sure you use Arduino IDE 1.5.8 or newer.
at the moment you have to move
the cores/hid folder into your Arduino installation because of a bug in the ide.
This Core is ment to use with 1.5.8 or newer Arduino IDE
At the moment you have to move the cores/hid folder into your Arduino installation
*arduino-1.6.0/hardware/arduino/avr/cores/hid* because of a bug in the IDE.
If you like to, you can add the keywords to your Arduino IDE so that words like 'Gamepad' are highlighted.
(TODO)
How to use
==========
### Micro/Leonardo + HoodLoader2
**You can compile all HID APIs but this doesnt mean that you can use them if no hid descriptor is set correctly.**
Edit the *sketchbook/hardware/HID/avr/variants/hid_descriptors/hid_descriptors.h* to use the extended HID core.
At the moment you have 3 options: Default, Gamepad or Extended. Extended should work for anything expect Gamepads.
See the bug section below to find out more about working hid reports. Not all of them are playing well together.
Have a closer look at these lines:
``` cpp
// use this to enable the Keyboard Led functions
#define HID_KEYBOARD_LEDS_ENABLED
// add your custom HID Report Descriptor here.
// you can use the pre defined reports as well
//#define EXTERN_HID_REPORT DEFAULT_HID_REPORT
#define EXTERN_HID_REPORT EXTENDED_HID_REPORT
//#define EXTERN_HID_REPORT GAMEPAD_HID_REPORT
```
You can also add your own descriptor with your own APIs.
Use the void HID_SendReport(uint8_t id, const void* data, int len); function to send hid reports.
See *Project/USB-Serial* for a fully usable USB-Serial bridge and how to use the new Serial functions.
In the CDC.h you can also see the new Control Line functions for advanced users.
**Try the Basic HID examples for each HID device. They are pretty much self explaining.
You can also see the *Projects/HID_Test* for an all in one example.**
### HoodLoader1
**Try the HoodLoader1 example. It provides the basic Serial protocol API to send HID reports. You have to copy this to every sketch again.**
With HoodLoader1 you can **only use baud 115200 for HID** due to speed/programming reasons.
Use Serial.begin(115200) in every HoodLoader1 sketch.
Its not bad anyway because its the fastest baud and you want fast HID recognition.
You still can **fully use any other baud** for normal sketches but HID wont work.
If you try nevertheless it will output Serial crap to the monitor.
Keep in mind that HoodLoader1 has **no flush function**. If the PC is reading HID too slow it can miss data, like on a Raspberry Pi.
Add a delay to the sending function or just use the newer HoodLoader2.
Do not use HID in interrupts because it uses Serial. Your Arduino can crash!
Always release buttons to not cause any erros. Replug USB cable to reset the values if anything went wrong.
Keep in mind that **with HoodLoader1 the 16u2 is always on**. The 16u2 and its HID reports are not reset if the main MCU is reset.
So you need to reset the HID reports on every startup with a begin() of each used API.
On Windows every USB report will reset when you open the lock screen.
See [deactivate HID function (Hoodloader only)](https://github.com/NicoHood/Hoodloader) how to temporary disable HID again.
For **16u2 as ISP usage** (optional, Hoodloader only, has nothing to do with HID function)
see [Hoodloader repository](https://github.com/NicoHood/Hoodloader).
The sending API is no longer integrated directly in the HID Project since it is now more an extended USB-Core and this has nothing to do with it.
Its more a legacy version to still use HoodLoader1 or to reimplement something similar with HoodLoader2 if you still want full report access for the main MCU.
**The older, full integrated HID Core can be found here.** Keep in mind to remove all newer stuff since it may conflict (a clean arduino core would do it).
It is not better than this solution, maybe easier to use since its just more integrated.
[Outdated HID Project for 1.5.7](https://github.com/NicoHood/HID/tree/3d8a9b40752a143141b8be4b8f744e203c80b000)
How it works
============
For the Leonardo/Micro + HoodLoader2 its a modified version of the HID descriptors and USB-Core.
This changes were made to improve the functions, add more devices and add u2 series compatibility.
HoodLoader1 only:
For the Uno/Mega you need a special Bootloader. Why? See [Hoodloader repository](https://github.com/NicoHood/Hoodloader).
To sum it up: Serial information is grabbed by the "man in the middle, 16u2" and you dont have to worry to get any wrong Serial stuff via USB.
Thatswhy you need a special baud (115200) that both sides can communicate with each other.
Every USB command is send via a special [NicoHood Protocol](https://github.com/NicoHood/NicoHoodProtocol)
that's filtered out by the 16u2. If you use Serial0 for extern devices it cannot filter the signal of course.
You can still use the NHP, just dont use the reserved Address 1.
You can compile all HID APIs
but this doesnt mean that you can use them if no hid descriptor is set correctly.
TODO
====
@ -20,29 +147,43 @@ Keyboard Layout for different Languages
Clean up USB Core code from fixed values. Use better understandable definitions
Magic key fix for 32u4?
Add Keywords.txt definitions
Add/update Keywords.txt definitions
keycode/raw for keyboard
Check Keyboard keycode function again?
Generalize HID key definitions via HIDTables for example?
Add custom HID reports example
add keyboard led example
update Burning via ISP (advanced)
Test with Android phone
update no usb workaround notice (no longer needed for hoodloader2, but for leonardo)
```
Bugs
Mouse Abs only works with system report under special circumstances.
Gamepad + Mouse Abs doesnt work (fix Gamepad)
Fix HID_SendReport() prototype workaround in HID-APIs
Core selection in boards.txt is not working
Do not name the Arduino Sketch 'Mouse.ino' or 'Keyboard.ino' etc.
Known Bugs
==========
* See Hoodloader1+2 repositories for HoodLoader1+2 related Bugs/Issues.
* Mouse Abs only works with system report under special circumstances.
* Gamepad + Mouse Abs doesnt work together
* Fix HID_SendReport() prototype workaround in HID-APIs
* Core selection in boards.txt is not working
* Do not name the Arduino Sketch 'Mouse.ino' or 'Keyboard.ino' etc.
Your Arduino IDE will output errors then if you double click the file and try to compile.
```
* RawHID is not working properly, test it at your own risk.
* Feel free to open an Issue on Github if you find a bug. Or message me via my [blog](http://nicohood.wordpress.com/)!
* All OS have some problems with Gamepads. Dont use more than one device for Linux and be careful when you change the descriptor.
* XBMC 13.1 (a Media Center) 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.
* The Serial may disconnect if you have too much throughput. This is a general bug of the Arduino Core,
which might be fixed. For example Adalight dosnt work well for me,
so you better use an Arduino Uno with Hoodloader1 (yes the older one!) for Mediacenter control and Ambilight.
Version History
===============
```
2.1 Release (xx.01.2015)
* Reworked the whole USB-Core from scratch
* Uses less flash if HID or Serial is not used
* Extended and compacter(flash) HID Report Descriptors
* Fixed USB Device Descriptor
@ -67,8 +208,131 @@ Your Arduino IDE will output errors then if you double click the file and try to
* Separated USB-Core in its own folder
* Added HID Tables
* USB-Serial now fully reprogrammable
2.0 Release (29.11.2014)
* Added HoodLoader2
* Separated HoodLoader1&2 more
* Added u2 series for USB-Core
* Extended USB core and fixed minor things for the u2 series
* Added Led Out report.
* Added CDC Line state
* Reworked the whole library structure again
1.8 Beta Release (26.08.2014)
* Changes in the Hoodloader:
* **Huge improvements**, see [Hoodloader repository](https://github.com/NicoHood/Hoodloader)
* Reworked the whole library, easy installation now
* HID fixes for Media Keys/Ubuntu
* Removed Joystick, added 4 Gamepads
1.7.3 Beta Release (10.08.2014)
* Changes in the Hoodloader:
* Fixed HID flush bug (1.6 - 1.7.2)
1.7.2 Beta Release (10.08.2014)
* Changes in the Hoodloader:
* Added Lite version for 8u2
* Added Versions that show up as Uno/Mega (not recommended)
* Makefile and structure changes
1.7.1 Beta Release (10.08.2014)
* Changes in the Hoodloader:
* Fixed HID deactivation bug
1.7 Beta Release (10.08.2014)
* Changes in the Hoodloader:
* Works as ISP now. See the [Hoodloader Repository](https://github.com/NicoHood/Hoodloader) for more information.
* Exceeded 8kb limit. For flashing a 8u2 use v1.6 please!
* Changed Readme text
1.6 Beta Release (09.08.2014)
* Bugfixes in the Hoodloader:
* Changed HID management (not blocking that much, faster)
* added RawHID in/out (HID to Serial)
* Added RawHID Class and example
1.5 Beta Release (21.07.2014)
* Moved Hoodloader source to a [separate Github page](https://github.com/NicoHood/Hoodloader)
* Bugfixes in the Hoodloader:
* Firmware is still available here
* Overall a lot of ram improvements, now with a big global union of ram
* Removed USBtoUSART buffer (not needed, saved 128/500 bytes)
* Removed Lite version because of better ram usage not needed
* Separated different modes better to not cause any errors in default mode
* Improved the deactivate option
* Integrated NHP directly
* Replaced LightweightRingbuffer with native Lufa Ringbuffer
* Improved writing to CDC Host
* Fixed a bug in checkNHPProtocol: & needs to be a ==
* General structure changes
* Improved stability
* Fixed Arduino as ISP bug
1.4.1 Beta Release (10.07.2014)
* #define Bugfix in USBAPI.h
1.4 Beta Release (10.07.2014)
* Bugfixes in the Hoodloader:
* Added Lite Version with less ram usage
* Changed PIDs, edited driver file
* merged v1.0.x and v1.5.x together (both are compatible!)
* added IDE v1.5.7 support
* added Tutorials
1.3 Beta Release (01.07.2014)
* Bugfixes in the Hoodloader:
* Improved ram usage (you can get even better but that messes up code and increases flash)
* **Important NHP fix inside the HID Class for Uno/Mega**
1.2 Beta Release (22.06.2014)
* Added 1.0.x/1.5.x support
* Bugfixes in the Hoodloader:
* Sometimes HID Devices weren't updating when using more than 1 Device (set forcewrite to true)
* Fast updates crashed the bootloader (too much ram usage, set CDC buffer from 128b to 100b each)
* Minor file structure changes
1.1 Beta Release (05.06.2014)
* Added Leonardo/Micro support
* Included NicoHoodProtocol
* Minor fixes
1.0 Beta Release (03.06.2014)
```
Useful Links/Credits
====================
* [LUFA from Dean Camera](http://www.fourwalledcubicle.com/LUFA.php)
* [Darran's HID Projects] (https://github.com/harlequin-tech/arduino-usb)
* [Connor's Joystick for the Leonardo](http://www.imaginaryindustries.com/blog/?p=80)
* [Stefan Jones Multimedia Keys Example](http://stefanjones.ca/blog/arduino-leonardo-remote-multimedia-keys/)
* [Athanasios Douitsis Multimedia Keys Example](https://github.com/aduitsis/ardumultimedia)
* [The Original Arduino Sources](https://github.com/arduino/Arduino/tree/master/hardware/arduino/firmwares/atmegaxxu2/arduino-usbserial)
* [USBlyzer](http://www.usblyzer.com/)
* [Mattairtechs 16u2 Lufa USB Core](https://www.mattairtech.com/index.php/development-boards/mt-db-u1.html)
* [Paul Brook's Minimus 32u2 Arduino USB Core](https://github.com/pbrook/minimus-arduino)
* [Paul Stoffregen's Teensy Core](https://github.com/PaulStoffregen/cores)
* [Keyboard Led Out report by hartmut_holgraefe](http://forum.arduino.cc/index.php?topic=173583.0)
* [Github Pull Request with a lot of new functions](https://github.com/arduino/Arduino/pull/1803)
* A lot of searching through the web
* The awesome official Arduino IRC chat!
* [The NicoHood Protocol ^.^](https://github.com/NicoHood/NicoHoodProtocol)
* See HoodLoader1&2 repository for more credits/links
* [Hackaday post about HoodLoader2](hackaday.com/2014/11/30/using-the-second-microcontroller-on-an-arduino)
* [Gamecube to PC adapter](https://github.com/NicoHood/Nintendo)
* See http://nicohood.wordpress.com/ for more tutorials, projects and contact.
* For donations please contact me on my blog :)
For Developers
==============
If you deactivate some reports it can occur that windows will cause problems and recognize it as different device.
While developing I had that much trouble that I had to change the PID. No way to repair the broken windows driver settings.
So be careful if you change the source on your own with important PIDs.
Therefore reinstall the divers for any device or just dont touch the HID reports.
See this how to uninstall the drivers:
https://support.microsoft.com/kb/315539
```
Include schematic
- Arduino.h

View file

@ -21,12 +21,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
// add your custom HID Report Descriptor here.
// you can use the pre defined reports as well
//#define EXTERN_HID_REPORT DEFAULT_HID_REPORT
#define EXTERN_HID_REPORT EXTENDED_HID_REPORT
//#define EXTERN_HID_REPORT GAMEPAD_HID_REPORT
#define EXTENDED_HID_REPORT \
HID_REPORT_KEYBOARD_LEDS(HID_REPORTID_KEYBOARD), \
HID_REPORT_MOUSE(HID_REPORTID_MOUSE), \
@ -39,9 +33,19 @@ HID_REPORT_KEYBOARD_LEDS(HID_REPORTID_KEYBOARD), \
HID_REPORT_MOUSE(HID_REPORTID_MOUSE), \
HID_REPORT_GAMEPAD(HID_REPORTID_GAMEPAD)
//================================================================================
// Settings
//================================================================================
// use this to enable the Keyboard Led functions
#define HID_KEYBOARD_LEDS_ENABLED
// add your custom HID Report Descriptor here.
// you can use the pre defined reports as well
//#define EXTERN_HID_REPORT DEFAULT_HID_REPORT
#define EXTERN_HID_REPORT EXTENDED_HID_REPORT
//#define EXTERN_HID_REPORT GAMEPAD_HID_REPORT
// Keep in mind that changing the ids or reports might confuse your OS
// Then you might need to reinstall all drivers or change the USB PID

BIN
header.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 147 KiB

201
keywords.txt Normal file
View file

@ -0,0 +1,201 @@
#######################################
# Syntax Coloring Map For HID
#######################################
#######################################
# Datatypes (KEYWORD1)
#######################################
#######################################
# Methods and Functions (KEYWORD2)
#######################################
begin KEYWORD2
end KEYWORD2
click KEYWORD2
move KEYWORD2
write KEYWORD2
press KEYWORD2
isPressed KEYWORD2
releaseAll KEYWORD2
buttons KEYWORD2
xAxis KEYWORD2
yAxis KEYWORD2
zAxis KEYWORD2
rxAxis KEYWORD2
ryAxis KEYWORD2
rzAxis KEYWORD2
dPad1 KEYWORD2
dPad2 KEYWORD2
HID_SendReport KEYWORD2
#######################################
# Classes (KEYWORD3)
#######################################
Mouse KEYWORD3
Keyboard KEYWORD3
RawHID KEYWORD3
Media KEYWORD3
System KEYWORD3
Gamepad KEYWORD3
#######################################
# Instances (KEYWORD2)
#######################################
#######################################
# Constants (LITERAL1)
#######################################
#CDC
CDC_CONTROL_LINE_OUT_DTR LITERAL1
CDC_CONTROL_LINE_OUT_TRS LITERAL1
#Mouse
MOUSE_LEFT LITERAL1
MOUSE_RIGHT LITERAL1
MOUSE_MIDDLE LITERAL1
MOUSE_PREV LITERAL1
MOUSE_NEXT LITERAL1
#Keyboard
LED_NUM_LOCK LITERAL1
LED_CAPS_LOCK LITERAL1
LED_SCROLL_LOCK LITERAL1
KEY_LEFT_CTRL LITERAL1
KEY_LEFT_SHIFT LITERAL1
KEY_LEFT_ALT LITERAL1
KEY_LEFT_GUI LITERAL1
KEY_LEFT_WINDOWS LITERAL1
KEY_RIGHT_CTRL LITERAL1
KEY_RIGHT_SHIFT LITERAL1
KEY_RIGHT_ALT LITERAL1
KEY_RIGHT_GUI LITERAL1
KEY_RIGHT_WINDOWS LITERAL1
KEY_UP_ARROW LITERAL1
KEY_DOWN_ARROW LITERAL1
KEY_LEFT_ARROW LITERAL1
KEY_RIGHT_ARROW LITERAL1
KEY_BACKSPACE LITERAL1
KEY_TAB LITERAL1
KEY_RETURN LITERAL1
KEY_ENTER LITERAL1
KEY_ESC LITERAL1
KEY_INSERT LITERAL1
KEY_DELETE LITERAL1
KEY_PAGE_UP LITERAL1
KEY_PAGE_DOWN LITERAL1
KEY_HOME LITERAL1
KEY_END LITERAL1
KEY_CAPS_LOCK LITERAL1
KEY_F1 LITERAL1
KEY_F2 LITERAL1
KEY_F3 LITERAL1
KEY_F4 LITERAL1
KEY_F5 LITERAL1
KEY_F6 LITERAL1
KEY_F7 LITERAL1
KEY_F8 LITERAL1
KEY_F9 LITERAL1
KEY_F10 LITERAL1
KEY_F11 LITERAL1
KEY_F12 LITERAL1
KEY_PRINT LITERAL1
KEY_NUM_LOCK LITERAL1
KEY_SCROLL_LOCK LITERAL1
KEY_PAUSE LITERAL1
#Raw Keyboard definitions
RAW_KEYBOARD_LEFT_CTRL LITERAL1
RAW_KEYBOARD_LEFT_SHIFT LITERAL1
RAW_KEYBOARD_LEFT_ALT LITERAL1
RAW_KEYBOARD_LEFT_GUI LITERAL1
RAW_KEYBOARD_RIGHT_CTRL LITERAL1
RAW_KEYBOARD_RIGHT_SHIFT LITERAL1
RAW_KEYBOARD_RIGHT_ALT LITERAL1
RAW_KEYBOARD_RIGHT_GUI LITERAL1
RAW_KEYBOARD_KEY LITERAL1
RAW_KEYBOARD_UP_ARROW LITERAL1
RAW_KEYBOARD_DOWN_ARROW LITERAL1
RAW_KEYBOARD_LEFT_ARROW LITERAL1
RAW_KEYBOARD_RIGHT_ARROW LITERAL1
RAW_KEYBOARD_SPACEBAR LITERAL1
RAW_KEYBOARD_BACKSPACE LITERAL1
RAW_KEYBOARD_TAB LITERAL1
RAW_KEYBOARD_RETURN LITERAL1
RAW_KEYBOARD_ESC LITERAL1
RAW_KEYBOARD_INSERT LITERAL1
RAW_KEYBOARD_DELETE LITERAL1
RAW_KEYBOARD_PAGE_UP LITERAL1
RAW_KEYBOARD_PAGE_DOWN LITERAL1
RAW_KEYBOARD_HOME LITERAL1
RAW_KEYBOARD_END LITERAL1
RAW_KEYBOARD_CAPS_LOCK LITERAL1
RAW_KEYBOARD_F1 LITERAL1
RAW_KEYBOARD_F2 LITERAL1
RAW_KEYBOARD_F3 LITERAL1
RAW_KEYBOARD_F4 LITERAL1
RAW_KEYBOARD_F5 LITERAL1
RAW_KEYBOARD_F6 LITERAL1
RAW_KEYBOARD_F7 LITERAL1
RAW_KEYBOARD_F8 LITERAL1
RAW_KEYBOARD_F9 LITERAL1
RAW_KEYBOARD_F10 LITERAL1
RAW_KEYBOARD_F11 LITERAL1
RAW_KEYBOARD_F12 LITERAL1
RAW_KEYBOARD_PRINT LITERAL1
RAW_KEYBOARD_SCROLL_LOCK LITERAL1
RAW_KEYBOARD_PAUSE LITERAL1
#RawHID
RAWHID_RX_SIZE LITERAL1
RAWHID_TX_SIZE LITERAL1
#Media
MEDIA_FAST_FORWARD LITERAL1
MEDIA_REWIND LITERAL1
MEDIA_NEXT LITERAL1
MEDIA_PREVIOUS LITERAL1
MEDIA_STOP LITERAL1
MEDIA_PLAY_PAUSE LITERAL1
MEDIA_VOLUME_MUTE LITERAL1
MEDIA_VOLUME_UP LITERAL1
MEDIA_VOLUME_DOWN LITERAL1
MEDIA_EMAIL_READER LITERAL1
MEDIA_CALCULATOR LITERAL1
MEDIA_EXPLORER LITERAL1
MEDIA_BROWSER_HOME LITERAL1
MEDIA_BROWSER_BACK LITERAL1
MEDIA_BROWSER_FORWARD LITERAL1
MEDIA_BROWSER_REFRESH LITERAL1
MEDIA_BROWSER_BOOKMARKS LITERAL1
#System
SYSTEM_POWER_DOWN LITERAL1
SYSTEM_SLEEP LITERAL1
SYSTEM_WAKE_UP LITERAL1
#Gamepad
GAMEPAD_DPAD_CENTERED LITERAL1
GAMEPAD_DPAD_UP LITERAL1
GAMEPAD_DPAD_UP_RIGHT LITERAL1
GAMEPAD_DPAD_RIGHT LITERAL1
GAMEPAD_DPAD_DOWN_RIGHT LITERAL1
GAMEPAD_DPAD_DOWN LITERAL1
GAMEPAD_DPAD_DOWN_LEFT LITERAL1
GAMEPAD_DPAD_LEFT LITERAL1
GAMEPAD_DPAD_UP_LEFT LITERAL1