article in Personal
projects-and-research
Horners HIDHelve
Horner's HIDHelve - handle your human interface device.
davehorner/HIDHelve · GitHub - the code, just for you.
What the Helve?
helve /helv/
noun - The handle of a weapon or tool.
What is HIDHelve?
HIDHelve listens to your USB HID devices for state changes and publishes that data in a variety of ways.
It's useful in automating some work to be done when smashing buttons.
Every tool or weapon you write shouldn't have to interface directly with the low level HID libraries.
HIDHelve decouples you from direct HID manipulation.
HIDHelve is a collection of scripts/executables, consisting of:
- HIDHelve - written in C++ using HIDAPI for HID interactions. HIDHelve creates a mailslot for publishing HID events and another mailslot for controlling the single instance of HIDHelve. HIDHelve's standard output is easily parsed, if IPC like mailslots is unneeded.
- AHKHIDMapper - simple AHK HIDHelve example. The AHK script launches HIDHelve, processes the HID data sent through the HIDHelve publishing mailslot, and signals HIDHelve to exit before termination of the script.
Why am I spending my personal time on such things?
Like most software, HIDHelve was born out of frustration. I couldn't get AHKHID or any other AHK script which used the HID RawInput apis to work with my device.
Mapping gamepads/footpedals should be simple kid stuff. But it isn't easy, you apparently need to be a software developer, capable of installing compilers, SDKs, and deciphering HID report data.
In windows XP, MS gave us a Start>"Control Panel">"Game Controllers" which was a fairly easy way to map gamepads/etc to your computer. This has been removed, with no replacement in current versions of windows. That cool gravis gamepad from back in the day won't work on windows without custom software..
I found that my usb gravis gamepad pro worked like a charm in win8 - no additional software required, shows up as a USB Input Device/HID-compliant game controller with a model of "GamePad Pro USB".
The Gravis GamePad Pro device is not recognized when you install it on a Windows XP-based computer - running joy.cpl works in win8.
Test the controller using joy.cpl; pressing buttons and moving the directional pad will show changes in the button and axis controls. However, it doesn't provide a way to automate tasks from a users perspective (do something when I press this and do that).
I think a modern OS should provide a simple mapper for hardware ppl have laying around their house. I can't really point to an OS/application today that does simple generic HID interfacing(mapping key presses/sliders to OS actions like mouse clicks, keyboard presses, etc) right for an everyday user out of the box.
Where's the OS that asks me if I'd like to configure the generic 3/4/5/6/7/8 button HID device as an assistive device? Without the installation of expensive specialized screen readers and custom hardware driver shims.
People talk about ARIA (Accessible Rich Internet Applications), give me an AOS. Accessible Operating System.
It'd be nice to have a general joystick/gamepad/hid mapper which was cross platform. Working with DDE/WDK/DirectInput code to interface with custom hardware is tedious and easy to do wrong.
HIDHelve Devices
These are some of the devices that I've used personally with HIDHelve. Let me know if you use HIDHelve with some other device...
VEC/Infinity pedal
How do I use HIDHelve and AHKHIDMapper?
At this time there is no installer or separate download provided. Pre-compiled windows unicode x86 64bit & 32bit binaries are stored directly within github, you can also build HIDHelve from source. Install AutoHotkey. Clone the repository and run AHKHIDMapper.ahk within examples/windows.
Above is a screen capture showing ahkhidmapper.ahk, which by default sets HIDHelve's command line parameters to "-pFoot". You can change the default by editing ahkhidmapper.ahk DEFAULT_ARGUMENTS variable.
Current HidHelve Help Output
Horner's HIDHelve - handle your human interface device.
your app listens to the PublishSlot for events or reads from my STDOUT.
if ControlSlot recieves a message, I exit nicely.
General:
-l [ --listmode ] list devices on system and exit
-h [ --help ] produce this help message
-v [ --verbose ] arg (=1) verbosity level
-e [ --exitvalue ] arg (=-1) termination value indicates when to exit (-1=none)
-r [ --response-file ] arg set settings from rsp file, @pathto.rsp also valid syntax.
HID Specification:
-P [ --Path ] arg the full HID device path
-p [ --product ] arg regex to match against product
Mailslot IPC:
-d [ --domain ] arg (=.) mailslot IPC domain
-s [ --slotname ] arg mailslot IPC terminal subslot name (useful for multi-instance)
Example usage of HIDHelve
So, first run "HIDHelve -l" to get a listing of usb devices. Try and locate the device you'd like to interface within the list.
For example, when I run a listing on my computer with the "VEC USB Footpedal" attached. I see the following within my HIDHelve -l output:
path: \\?\hid#vid_05f3&pid_00ff#8&28b28e39&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
serial_number: Manufacturer: VEC
Product: VEC USB Footpedal
Type: 05f3 00ff
Release: 100
Interface: -1
Currently, HIDHelve provides two methods of specifying a device. -P(--Path) and -p(--product). The -pFoot default, works with my "VEC USB Footpedal" because the product field contains "Foot". RegEx will be added in the future for more complex selection, but currently -p is a substr search. It will select the first device that contains the specified product string.
Using the -P or --Path parameter is as easy as selecting the path as listed.
-P"\\?\hid#vid_05f3&pid_00ff#8&28b28e39&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}"
would be the example cmd line, when trying to use the path specification for my "VEC USB Footpedal". The path will change when the device is placed on another usb port.
HIDHelve is written to listen to one device at a time. Once you specify either a path or product, HIDHelve will connect and listen to the device. My foot pedal device sends a single byte. HIDHelve displays the current hexadecimal value of that byte, along with binary representation of that same byte in the next column. HIDHelve stores off the prior byte sent and Bitwise XOR's that byte with the current byte being sent. This XOR'd data is printed out within the next columns, again in hexadecimal and binary representations.
Currently HIDHelve requires that another application be listening to the publish mailslot. Otherwise it'll complain at you, as it attempts to resend the data over the mailslot twice for each byte received.
[info] OPENING \\?\hid#vid_05f3&pid_00ff#7&25f926ce&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
current(hex),current(binary),current^prior(hex),current^prior(bin)
02,00000010,02,00000010
[info] attempting to open PublishSlot: \\.\mailslot\hornersHidHelvePublishSlot
[error] open failed, perhaps there aren't any listeners?
[info] attempting to open PublishSlot: \\.\mailslot\hornersHidHelvePublishSlot
[error] open failed, perhaps there aren't any listeners?
You can write your own application to connect to the mailslot and process the data. Or, run the provided example ahkhidmapper.ahk, which connects to the mailslot if an instance of HIDHelve is already running, or will create a new instance of HIDHelve for you.
ahkhidmapper.ahk receives data from HIDHelve through the PublishSlot(\\.\mailslot\hornersHidHelvePublishSlot). ahkhidmapper.ahk StringSplit's the data received into columns and uses the current and prior hexadecimal value to determine which autohotkey actions to take.
ahkhidmapper.ahk signals HIDHelve to exit through ControlSlot(\\.\mailslot\hornersHidHelveControlSlot). Currently HIDHelve exits cleanly when any data is received through the ControlSlot.
Is that all HIDHelve does?
What were you expecting? It is just a helve.
The requirement on mailslots will go away, as mailslots are a MS specific technology. AMQP replace/supplement mailslot communication?
In the future, maybe HIDHelve will allow you to perform actions itself.... but I sorta like that HIDHelve is small and just listens and broadcasts the data to interested apps.
put the action on the end of the handle.
Websites used in the making...
hidapi: hidapi API
nasfarley88/pedal2bash · GitHub - A simple program to link up transcription pedal to keyboard presses. (using hidapi, centered around .sh files)
Interprocess communication using Mailslots - Scripts - AutoHotkey Community
AHKHID - An AHK implementation of the HID functions - Scripts - AutoHotkey Community
Uniquely Identifying RawInput Devices in AutoHotKey — Visual Basic Feng Shui
musings from the underground: The dream, AutoHotkey-powered foot pedal for programmers and ergonomanics
Using Mailslots (Windows)
Do you have Mailslots on your Windows PC? « Didier Stevens - a did ya know, process explorer can see mailslots, \Device\Mailslot. or C# string file in Directory.GetFiles(@".mailslot", "*.*", SearchOption.AllDirectories)
Inkscape. Draw Freely. - Axe_kirves.svg USB_Icon.svg
AHK CodeQuickTester GIST
WindowPad - window-moving tool - Scripts - AutoHotkey Community - latest download on first post.
hoppfrosch/WindowPadX · GitHub - enhanced WindowPad.
vJoy Forum :: Topic: UJR - Universal Joystick Remapper (AHK GUI script) (1/2)
vjoystick Home - vJoy is a device driver that bridges the gap between any device that is not a joystick and an application that requires a joystick.
HID Profiler - Wheel, Joystik, HOTAS - Scripts - AutoHotkey Community
Building a custom game controller for the physically disabled - YouTube
The Controller Project | Building Custom gaming controllers
Able Gamer
strings for your spider.
Unrecognized VEC USB pedals
The foot pedal (Infinity IN-USB-1, VEC USB)
VEC USB foot pedal
infinity foot pedal c++
The VideoLAN Forums • View topic - Transcription using USB VEC Infinity foot pedal
How to capture footpedal input - Support - AutoHotkey Community - last message "I didn't realize foot pedals were so popular.", thread is archived, otherwise, I'd post.
Created: 2012-12-31 18:17:24
Modified: 2014-07-05 05:24:43
