USB Device Key not working with mouse buttons

I’m trying to use mouse buttons 4, 5 and 6 as triggers (not at the same time). I selected USB Device Key Trigger, but whenever I click the Press and Release thing with any mouse button (from 1 to 6), it just says Try Again.

I tested my mouse using the mousepad thing in the Karabiner-Elements Event Viewer, and all of the mouse’s buttons are working, and are recognised as normal mouse buttons, 1-6.

Someone else reported that this used to work, but stopped in KM7. They managed to work around the issue by editing the XML file directly, which I’m happy to do, but unlike them, I don’t have examples from before the regression to work from.

Firstly, please look into fixing this. It’s a pretty important feature.

Secondly, could someone please advise me on what I need in my XML file to bind to a mouse button? I only need to know how to make a mouse button a trigger, I can figure the rest out. Thanks.

Keyboard Maestro does not detect mouse buttons, so whether the buttons work as mouse buttons or not is irrelevant.

Keyboard Maestro detects USB Device Keys - specifically any button/key that changes exactly one bit of HID (Human Interface Device) state on and then off again when the button/key is pressed.

The Human Interface Design is a masterpiece of “Design By Committee” - it basically allows absolutely anything at all, and so there is no real standard in what USB devices send and the assumption is that there will be a software driver on the other end that understands whatever messages it sends and turns them in to whatever operating system events are needed.

Keyboard Maestro is not a USB driver, and certainly has no knowledge of any specific USB devices. So it just looks at state/value changes and if it can detect a single bit going on and then off as you press the button, then the button can be used as a USB Device Key trigger.

This is not something that “change in Keyboard Maestro 7”. It is something that could change with any different device, and even for a specific device if the firmware changes or it changes revision.

Some devices send more than one bit change. Sometimes this is actually a physical effect (eg a physical button that is on top of two switches which can happen for large keys (eg the Enter or Return key or Space Bar), though it does not normally happen on regular keyboards. In those cases, Keyboard Maestro still cannot detect the change because it does not know which bit to pay attention to and it does not know that both bits will always change in sync. However in those cases, if you edit the XML directly, you could make it work by providing Keyboard Maestro with the bit to pay attention to and as far as Keyboard Maestro was concerned it would be as if you were pressing two keys every time but it only cared about one.

Doing this is non-trivial and not supported, it involves turning on debugging for the HID system and figuring out the exact details of what is changing and how that goes in to the XML. It’s a complicated process that would likely take me an hour or more to do.

Much easier might be to get a different mouse.

Thank you for taking the time to explain, and sorry if the title was inaccurate. I thought it was a bug, as it was reported that it worked until Keyboard Maestro 7, then stopped. You were part of that conversation, and it ended with the user working around the issue by editing the XML directly, so you can see why I thought what I did. Again, sorry. It was a simple misunderstanding.

I changed the title, from still not working to just not working, just so the title doesn’t give anyone who doesn’t read the thread the impression that Keyboard Maestro has a longstanding issue with mouses.

Getting another mouse isn’t an option for me personally. It’s a $50 mouse that matches a $200 keyboard, and frankly, I’m pretty broke, so I’m committed to getting it working somehow. The mouse doesn’t really need to work with Keyboard Maestro, as I only want the mouse to do simple things that macOS can do out the box, and Keyboard Maestro has always worked perfectly with the keyboard.

When Apple deprecated IOHID with Sierra, they broke a lot of input drivers. Karabiner, SmoothMouse and SteelSeries Engine 3 (which drives all modern SteelSeries peripherals) were among the victims, and SmoothMouse is gone forever. Having full support for mapping mouse buttons to Keyboard Maestro macros would be an awesome feature at any point, but now would be especially helpful, though of course, it’s not so simple from a developer’s perspective.

As I mentioned, Karabiner Elements sees the buttons, and I only need simple functionality bound to them, so I’m confident I’ll figure it out. Thanks again for taking the time to explain, and also for Keyboard Maestro generally.

You can enable HID debugging with

defaults write com.stairways.keyboardmaestro.engine Debug HID

Relaunch the Keyboard Maestro Engine and the Engine.log file will have lots of debug info about the HID system when you try to set a button.

It might be enough for you to guess at that change is required from a working button (1, 2, 3?) to a non-working button (4,5,6?).

Buttons 1, 2 and 3 work the same as 4, 5, and 6, so can’t be used as a starting point.

The odd thing I discovered today is that it does actually work, but rarely, like in one in a hundred attempts. I can’t figure out what makes it work though. I’ve gotten all six of the buttons working at least once.

When it works, it’s perfect.

Adding HID to the logs was helpful. Thanks.

Ok, so I figured out something. Just hitting a button repeatedly never works, while mashing on a few buttons together, just randomly, takes about five or ten ‘mashes’, before one of the mashed buttons will register.

If the registered button is not the one you want, you have to delete the trigger, then add a USB Device Key Trigger again, and just keep trying till you get the button you want.

By doing that, I’ve got my three buttons all set up perfectly, and know how to redefine them, so I’m happy, but it’s obviously one of the least elegant workarounds ever.

This does seem to boil down to a bug in Keyboard Maestro, and has the hallmarks of a race condition.

I’m not sure how, but if I can possibly be of any help in fixing this, please just let me know.

I’d be surprised if it is a bug in Keyboard Maestro per se.

What is probably happening is the device is changing more than one bit of state, and that some behaviour when mashing the keys is resulting in the second bit having already been changed and staying changed long enough to detect the other one going on and off.

As mentioned, the HID “specification” allows the device to send pretty much anything, so it is a miracle it works for as many keys as it does.

Fair enough - makes sense. Keyboard Maestro has always been very dependable on my system, and you seem to understand what’s likely going on here, so there’s nothing to be fixed, without getting into new features.

Thanks for taking the time to help me out with this, and your patience explaining there is no bug :smile:

I use SteerMouse to define a mouse button to then trigger a KM macro - has been very stable, can also use the scroll wheel on a kensington and use modifier keys in conjunction with the mouse buttons (1-5) or scroll wheel as well. Chording is also supported.

Thanks, troy. I did see that. It’s $20 for SteerMouse, but it looks good. You can also buy ControllerMate for the same price, and it seems a bit more powerful, based on what little I know. It’s the main software used with X-Keys hardware too.

I don’t think there are any open source options now. There was SmoothMouse, but the API it used (IOHID) was removed from Sierra. The SmoothMouse homepage now states “macOS Sierra will not be supported”.

My mouse is working with Keyboard Maestro now, but it’s good to offer anyone else who reads this one day a few options for hacking mouses.

1 Like

Keyboard Maestro uses IOHID framework, so if it goes away, so will the USB Device Key triggers.

However I can’t actually find anything that indicates it is deprecated in Sierra. It’s not in the release notes, and I can’t find any IOHID functions listed as deprecated.

Another option might be Control Plane, see if it can detect the mouse buttons.

Oh :confused: That’s what the author of SmoothMouse wrote. On the homepage, they talk about being killed by Sierra, and there’s a link to the Full statement and discussion, which mentions IOHID in the first bullet point:

Long story short.

  • In Sierra, Apple has deprecated “IOHID”, the API SmoothMouse uses to move the mouse pointer.

When Sierra was released, Karabiner stopped working, and is now being rewritten almost from scratch. SteelSeries Engine 3 (that acts a a driver for all their keyboards, mouses, headsets etc) got took out too. When I saw SmoothMouse has also stopped working, then read their blog, I just assumed deprecating IOHID must be what broke Karabiner and SSE3 as well.

Still, if you’re using IOHID, then it’s hard to understand what’s happened. You obviously know what APIs you’re using, and Keyboard Maestro is working on Sierra, so I’m just confused now.

1 Like

Just an update…

TLDR: Updates to Karabiner have improved mouse support in Keyboard Maestro.

Karabiner Elements now recognises my Steel Series mouse, and adding it to my Karabiner devices list makes it appear to Keyboard Maestro as a Karabiner virtual device. For example, I can now set This device key as the trigger type, highlight the input field and press Button 5 on my mouse, and it will show up as Karabiner VirtualHIDPointing Button 5. From there, it works like any other trigger (no more bugginess).