diff --git a/Readme.md b/Readme.md index ca00482..07a023b 100644 --- a/Readme.md +++ b/Readme.md @@ -1,247 +1,17 @@ Arduino HID Project 2.1 ======================= -![Header Picture](pictures/header.jpg) +![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. -##### Content -* [Features](https://github.com/NicoHood/HID/tree/Official-Integration#features) -* [Installation](https://github.com/NicoHood/HID/tree/Official-Integration#installation) -* [How to use](https://github.com/NicoHood/HID/tree/Official-Integration#how-to-use) -* [Troubleshoot](https://github.com/NicoHood/HID/tree/Official-Integration#troubleshoot) -* [How it works](https://github.com/NicoHood/HID/tree/Official-Integration#how-it-works) -* [Known bugs](https://github.com/NicoHood/HID/tree/Official-Integration#known-bugs) -* [Version history](https://github.com/NicoHood/HID/tree/Official-Integration#version-history) -* [Useful links and credits](https://github.com/NicoHood/HID/tree/Official-Integration#useful-linkscredits) -* [Developer information](https://github.com/NicoHood/HID/tree/Official-Integration#for-developers) -* [License and copyright](https://github.com/NicoHood/HID/tree/Official-Integration#licence-and-copyright) +Wiki +==== -Features -======== - -**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 -* HID APIs are external usable now -* USB Wakeup -* Smaller flash/ram usage -* More Serial functions -* u2 Series support (with [HoodLoader2](https://github.com/NicoHood/HoodLoader2)) -* [HoodLoader1](https://github.com/NicoHood/HoodLoader) compatible legacy example -* See change log for more additions and fixes - -**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) - -Installation -============ - -##### 1. Grab the newest Arduino release -HID-Project only works with the new Arduino IDE 1.5.8 or newer. -I recommend you to use the new [IDE 1.6 rc1](https://groups.google.com/a/arduino.cc/d/msg/developers/2_GD40Sl6FA/OLWZMwaLJ3IJ). - -##### 2. Install HoodLoader2 (Arduino Uno/Mega only) -For Arduino Uno/Mega first install [HoodLoader2 dev](https://github.com/NicoHood/HoodLoader2/tree/dev) on your 16u2 + the needed software files. -Make sure your HoodLoader2 software is up to date when you also update the HID-Project files. -[HoodLoader1](https://github.com/NicoHood/HoodLoader) is only supported for legacy but will get a new use soon! -For Arduino Micro/Leonardo ignore this step. - -##### 3. Install the HID core files -Installation has changed over the time. You don't have to modify the original core any more. -Put all files into *sketchbook/hardware/HID/*. **You have to rename the folder HID-master to HID.** - -Ensure that under 'File->Preferences' the correct sketchbook folder is selected. **Restart the IDE.** - -**Your sketchbook folder should look like this:** - -![Installation Picture](pictures/installation.png) - -##### 4. Add the keyword.txt for highlights (optional) -If you like to, you can add the keywords.txt to your Arduino IDE so that words like 'Gamepad' are highlighted. -Replace the file in *arduino-1.6.0/lib/keywords.txt* with the *keywords.txt* provided in this project. - -How to use -========== - -### Micro/Leonardo & HoodLoader2 - -##### 1. Select the new board via *Tools->Board->Arduino Leonardo HID-Project* for example. -For HoodLoader2 select the 16u2 MCU, for Leonardo/Micro the specific entry. -Ensure HoodLoader2 board definition files are up to date and installed. -The Uno and Mega entry is just for advanced users who want to use the HID-APIs but normally you'd -need the new HoodLoader2 (16u2) board definition files. - -![Board Selection Picture](pictures/board.png) - -##### 2. Select the USB-Core you want to use. You have 5 options here: -* Extended (Keyboard+Leds, Mouse+Absolute, Consumer, System) -* Gamepad (Keyboard+Leds, Mouse, Gamepad) -* Custom (Your custom configuration, see below) -* Default Core (Standard Arduino Core) -* No USB Core (No USB functions available, saves ram + flash) - -![USB-Core Selection Picture](pictures/usb-core.png) - -To create a **custom HID report descriptor** you can edit the file in *avr/variants/leonardo_custom/pins_arduino.h*. -Same for Micro and HoodLoader2. Not all HID reports are playing well together on all OS so I made these pre selections. -With the custom report you can try it out yourself. Everything you need should be in the pins_arduino.h file. - -##### 3. Try the Basic HID examples for each HID device. - -![example Picture](pictures/example.png) - -You may want to start with the HelloWorld and HID_Basic examples. They are pretty much self explaining. -Ensure that always the correct HID-Core is selected. - -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. -Keep in mind that the USB_ENDPOINTs for the u2 Series are set to 16 bytes, so the Serial buffer is also smaller (normally 64b). - -##### 4. Deactivate USB-Core to save flash and ram (optional) -If you don't want to use the USB-Core you can also choose under *Tools/USB Core* "No USB functions" to get rid of the USB stuff -and save the ram for other stuff if you don't need it. You also don't need the HID Project essentially if you don't want to use the USB functions. - -Due to a bad Leonardo/Micro bootloader you need to add an add an ISR into every sketch as workaround. -**This is not needed for HoodLoader2 devices**, since the bootloader does a true watchdog reset on reprogramming and not a simple application jump -(the usb clock is then still on and breaks any delay functions). -Checkout the 'Leonardo_Micro_NoUSB_Blink' example. - -```cpp -// workaround for undefined USBCON has to be placed in every sketch -// otherwise the timings wont work correctly -ISR(USB_GEN_vect) -{ - UDINT = 0; -} -``` - -### HoodLoader1 (legacy, new stuff coming soon) - -**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) - -### Arduino as ISP -You want to use your Leonardo/Micro as ISP as well? Here is a simple fix (not working with HoodLoader2 currently): -Select the Leonardo board and upload the Arduino as ISP sketch from this project to your Leonardo. -Select the board you want to flash and under *Tools->Programmer->Arduino as ISP (Leonardo)*. -Ensure the correct Serial port is selected, wires are also correct and hit burn bootloader. - -A fix for the u2 Series is in work. Optional you could use HoodLoader1 firmware as ISP. -The only thing I changed was the reset pin to pin 10 instead of SS -and the upload protocol from stk500v1 to arduino to avoid any CDC Serial dtr state problems. - -Troubleshoot/FAQ -================ - -##### Error: Selected board depends on 'HID' core (not installed) -See [issue #9](https://github.com/NicoHood/HID/issues/9). - -##### Midi support? -Some people have asked me about Midi support. It is not planned to integrate Midi into the HID-Project USB-Core since it is very complicated to do so. -But I will work on a new Midi firmware for the 16u2 that supports of course Midi (HoodLoader2 only). A firmware is something like a pre-compiled sketch. With the difference -that I wont use the Arduino IDE to create this firmware. I will use Lufa and a makefile to compile this firmware. This is more efficient. - -When the firmware is done you may upload it via avr-dude as described on the HoodLoader2 github page. Then you are able to start the midi with a simple reset -or start the bootloader (HoodLoader2) again with a double reset like you are used to. Then you can reprogram your 328 again. - -So be patient, I have a lot of new stuff planned and Midi will come. But you are able to flash other firmwares like HIDuino. Maybe thats all you need. -Install HoodLoader2 and flash the hex file. If it works please leave me some info. - -* https://github.com/ddiakopoulos/hiduino -* http://hunt.net.nz/users/darran/weblog/5b7f8/Arduino_UNO_USB_MIDI_firmware.html -* Also see [issue #2](https://github.com/NicoHood/HID/issues/2) - -##### Any random weird problem -is mostly solved by a pc reboot or a port switching. Try another (USB2.0) port if you have any problems with your device. -You might also try it on another pc to see if your OS mixes up drivers. Once I had a problem with my USB-Hub, so ensure to connect it directly. -You could also try a different/shorter USB cable. - -##### Switching the HID-Core -might confuse the OS since the USB device changes completely from one second to the other. -Therefore go to Printers and Devices on Windows and select remove. Reconnect your Arduino and maybe remove it again if its not working properly. -Alternatively you can also restart your PC or use another USB PID (in the boards.txt) to see if its a Windows problem or not. -If you change the USB PID the CDC Driver wont be loaded but you can always reupload a sketch in bootloader mode. - -![remove usb device](pictures/remove-device.png) - -##### Gamepads -had several problems over the time. The first thing I'd like to mention is that the calibration windows only updates if you focus it. -Windows only supports gamepads with up to 7 axis and 32 buttons and has problems with more than one Gamepad in a multireport. -Linux has problems when gamepads are in multi reports with a system device for example. It may occur that it display immense axis/buttons or none at all. -The current gamepad setting was tested under windows and ubuntu and seems to work. Feel free to extend the gamepad report at your own risk. - -![gamepad](pictures/gamepad.png) - -**If you have any other problem, open an issue on github or contact me on my blog.** - -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. - -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. - - -HoodLoader1 only: -For the Uno/Mega you need a special Bootloader(actually firmware in this case). 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 don't use the reserved Address 1. +All documentation moved to the [wiki page](https://github.com/NicoHood/HID/wiki). +An offline version will be available soon. TODO ==== @@ -281,6 +51,30 @@ 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. * Feel free to open an Issue on Github if you find a bug. Or message me via my [blog](http://nicohood.wordpress.com/)! +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) +* [Arduino ISP fix](https://petervanhoyweghen.wordpress.com/2012/09/16/arduinoisp-on-the-leonardo/) +* 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 :) Version History =============== @@ -408,63 +202,12 @@ Version History 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) -* [Arduino ISP fix](https://petervanhoyweghen.wordpress.com/2012/09/16/arduinoisp-on-the-leonardo/) -* 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 - - USBAPI.h -> Arduino.h, USBDESC.h, USBCore.h - - CDC.h -> Arduino.h, USBDESC.h, USBCore.h - - HID.h -> Arduino.h, USBDESC.h, USBCore.h, HID-APIs(Keyboard.h, Mouse.h, etc) - - Keyboard.h -> Arduino.h - - Mouse.h -> Arduino.h - - [Other APIs].h -> Arduino.h - - HIDTables.h - -HID.h contains all HID configuration. -Each HID-API (like Mouse) includes Arduino.h and gets these settings as well. -The pins_Arduino.h can overwrite each HID descriptor or define complete new one. -``` - Licence and Copyright ===================== If you use this library for any cool project let me know! ``` -Copyright (c) 2014 NicoHood +Copyright (c) 2014-2015 NicoHood See the readme for credit to other people. Permission is hereby granted, free of charge, to any person obtaining a copy diff --git a/pictures/header.jpg b/header.jpg similarity index 100% rename from pictures/header.jpg rename to header.jpg diff --git a/pictures/board.png b/pictures/board.png deleted file mode 100644 index a3dd47c..0000000 Binary files a/pictures/board.png and /dev/null differ diff --git a/pictures/example.png b/pictures/example.png deleted file mode 100644 index 949047f..0000000 Binary files a/pictures/example.png and /dev/null differ diff --git a/pictures/gamepad.png b/pictures/gamepad.png deleted file mode 100644 index 3dbef39..0000000 Binary files a/pictures/gamepad.png and /dev/null differ diff --git a/pictures/installation.png b/pictures/installation.png deleted file mode 100644 index 13dd833..0000000 Binary files a/pictures/installation.png and /dev/null differ diff --git a/pictures/preferences.png b/pictures/preferences.png deleted file mode 100644 index 44247e1..0000000 Binary files a/pictures/preferences.png and /dev/null differ diff --git a/pictures/remove-device.png b/pictures/remove-device.png deleted file mode 100644 index 3ad5407..0000000 Binary files a/pictures/remove-device.png and /dev/null differ diff --git a/pictures/usb-core.png b/pictures/usb-core.png deleted file mode 100644 index 6cf0c59..0000000 Binary files a/pictures/usb-core.png and /dev/null differ