HID reports issue migrating from IOKit.hid to CoreHID

More troubleshooting: running the following line:

let report = try await deviceClient!.dispatchGetReportRequest(type: .input, id: HIDReportID(rawValue: 0x80))

gives me an error of type CoreHID.HIDDeviceError.unknown with error code of 0xE0005000. I cannot find at all what that specific code corresponds to, and the error description is the generic unknown error text.

OK, broke it down with two simple examples. Note that on first run you need to enable Input Monitoring for the application under Privacy settings. For CoreHID, i tried two different ways, both error with the same result. For IOKit, it works just fine. Also attached is the full Device report descriptors for the mouse.

And I can confirm that input reports are being received just fine through a Windows app using the code attached. So there is something in CoreHID that is giving an error when trying to get this report. (using dispatchGetReportRequest in CoreHID just doesn't get any reports).

gives me an error of type CoreHID.HIDDeviceError.unknown with error code of 0xE0005000.

For future reference, the kernel uses a structured error code system which makes it easier to divide the error code range between components, but harder to lookup specific error code. The error code "space" is defined by a whole series of nested macro's, so you won't actually fine "0xE0005000" or even "0x5000".

In case, the key points to note:

• The start of "0xE000" means it's from IOKit. Technically, I believe it's defined as "iokit_common_err" in IOReturn.h, however, I don't remember ever seeing an one of the other IOKit ranges.

• The last three digits ("0x000") are the specific code, for example, "kIOReturnExclusiveAccess" is 0xE00002BC:

#define kIOReturnExclusiveAccess iokit_common_err(0x2c5) // exclusive access and

• The fourth digit is used for the subsystem ("0x5"-> IOUSBHost), but the crucial point is that a non-zero value there means that the error came from a specific family, not the common pool.

Pulling all of that together, in this case, the error is "kUSBHostReturnPipeStalled" defined "IOUSBHostFamilyDefinitions.h" from IOKit.framework.

#define kUSBHostReturnPipeStalled                   iokit_usbhost_err(0x0)  // 0xe0005000  Pipe has issued a STALL handshake.  Use clearStall to clear this condition.
 

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Ah, the 4th digit information is what I was missing. Thank you for that information; that at least gives me something more to look into. I'm trying to solve that 0xE0005000 issues, as I'm trying to clean up the code and switch it to CoreHID. But as I have code that works using IOKit.hid and windows, and as the configuration for CoreHID looks pretty straight forward with minimal options or lower level access, I really don't have an Idea of a direction to go. I can get standard mouse events (movement and standard mouse buttons) just fine with the HIDDeviceClient.monitorNotifications() method. When asking for this usage, it doesn't get any events at all (no errors that i can see, just no events).

Ah, the 4th digit information is what I was missing. Thank you for that information; that at least gives me something more to look into. But as I have code that works using IOKit.hid

Looking at your IOKit code, you're not actually retrieving the descriptor. Have you tried just registering notifications against the elements the device returned? I think that's what your IOHIDManager code is doing.

One the to understand here is that CoreHID and IOHIDManager are both interacting with exactly the same underlying USB object, so when you're seeing different behavior you're either not doing the "same" thing or your doing it when the device is a fundamentally different state.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

My line for notifications is:

for try await notification in await deviceClient!.monitorNotifications(reportIDsToMonitor: [] , elementsToMonitor: [] ) { ...

which sound like it should grab both reports and elements. I get NO reports from that usage. My windows test code looks to be getting an input report, making me think that i SHOULD be getting a report from CoreHID as well. And in my CoreHID test code, i also have a second attempt using HIDDeviceClient.RequestElementUpdate requesting that Element, and that also returns the kUSBHostReturnPipeStalled error.

And i can confirm, IOKit version also works with the HID reports. Attached code works without issue, output also attached.

I cannot see anything that is saying this shouldn't work. My guess is this is bug in CoreHID, most likely because the UsagePage in question is two bytes long instead of the usual one byte:

0x06, 0x80, 0xFF,  // Usage Page (Vendor Defined 0xFF80)

If you or anyone else has other ideas to try, I would definitely appreciate them.

So, I was able to spend some time on test with this morning and, while I'm not sure of exactly what went wrong, I was able to get your CoreHID to return valid data and I think I can give you the path forward. First off, in terms of replicating the problem:

• I don't have a G600, but I do happen to have a G502. After modifying your code to match my hardware and tweaking some of your element code, I replicated the "kUSBHostReturnPipeStalled" error.

• That error is in fact "real". Here are the errors coming from the USB stack:

2025-03-07 11:52:54.835554-0800  (IOUSBHostFamily) AppleUSBIORequest: AppleUSBIORequest::complete: device 8 (G502 HERO Gaming Mouse@02113000) endpoint 0x00: status 0xe0005000 (pipe stalled): 0 bytes transferred
2025-03-07 11:52:54.839564-0800  (IOUSBHostFamily) AppleUSBIORequest: AppleUSBIORequest::complete: device 8 (G502 HERO Gaming Mouse@02113000) endpoint 0x00: status 0xe0005000 (pipe stalled): 0 bytes transferred

• The nature of working with hardware means that this moves the immediate issue out of our software stack (CoreHID or the USB stack). Basically, if you send a particular command to a device and the device chokes, the only choices are "fix the hardware" or "don't do that". Assuming you don't work for Logictech, that means going with "don't do that".

• Similarly, the reason the IOKit code DID have the same failure... is that it didn't do what your CoreHID code did.

As an aside here, one thing to keep in mind if you're new to working with HID accessories is that the gap between a devices physical design and the HID interface it presents can be very... large. Case in point, the G502 is a lovely and complicated device, but it doesn't have the 956 buttons it's HIDElement list would imply. I didn't investigate further, but it's very likely that one or some combination of those elements are what caused the bus stall and your only option is "no do that".

Shifting to the path forward, the first thing to do is look* at the output of this code snippet:

let allElements = await deviceClient?.elements
print ("Report \(String(describing: allElements))")

*It's actually more helpful to stop in the debugger and print the description by right clicking, as the debugger provides some helpful indenting which "print" completely mangles.

Each element entry contains the data about the relevant report. So, for example, my hardware returned:

    ▿ 1 : CoreHID.HIDElement(client: CoreHID.HIDDeviceClient:(deviceID: 0x1007b952d,
    	primaryUsage: CoreHID.HIDUsage(page: 1, usage: 6), vendorID: 1133, productID: 49291), 
     type: CoreHID.HIDReportType.input, 
     usage: CoreHID.HIDUsage(page: 7, usage: 225), reportID: CoreHID.HIDReportID(1))

When I fed those values back into your (modified) code, everthing worked fine. Here's my output:

DeviceName: G502 HERO Gaming Mouse
dispatchGetReportRequest succeeded: 9 bytes
Report: <Optional([CoreHID.HIDElement.Value(element:...>

And my code:

As a quick side note, using NSLog (instead of print) can be EXTREMELY helpful in this sort of code because it includes a timestamp (never a bad thing) and, more importantly, it also prints to the system console. That lets you use your app's own logging to find the broader activity it's generating like, for example, the USB errors I showed above.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

I'll look deeper when I get home, but i do see one key difference; the buttons i'm trying to capture on the G600 is a 3x4 grid of 'macro' buttons use many times in MMORPGs, labels G9 to G20. I'm specifically un-mapping them from any standard inputs. As a result, the reports are not coming from the standard page/usage as in your code: HIDUsage(page: 0x01, usage: 0x06) I can get HID reports from the mouse and keyboard Input reports without issue with my mouse.

So where there are no standard mouse and keyboard reports coming from these buttons now, the mouse still does send a HID report under the 'Vendor Defined' Usage Page of 0xFF80(note, that unlike your standard keyboard and mouse usage pages, this is a TWO byte value), and the usage of 0x80 (still one byte). Looking at your mouse, you might want to see if you have a similar entry in your HID report descriptor, as it does have extra buttons on the side 'G4' and 'G5'. My latest post above is a modified IOKit code that looks to use the standard input reports, showing they are in fact being generated

Now that I"m at the computer with the mouse, the primary HIDUsage from my last comment isn't the issue, that needs to be 0x01, 0x06 because the second usage page is under that primary usage. The issue is when I change your code fromdispatchGetReportRequest(type: .input, id: HIDReportID(rawValue: 1) to a rawValue: 0x80, then i get the following error:

dispatchGetReportRequest failed: unknown(-536850432)

And if you look at the last IOKit code, i did update that to use

IOHIDManagerRegisterInputReportWithTimeStampCallback

and it gets the report just fine.

And forgot to attach the full output:

OK, I don't know what all changed, but I went back from monitoring for the report event to the element update and it's working now. I'm still wondering why the report isn't picking up, but i can read the element and get the information I need now.

Thanks again for your help, Kevin! You definitely helped fill a couple holes in knowledge for me in this.

First off, as some clarifying background context, there has always been a pretty large "gap" between how the HID specification was "intended" to work and what actually ships as hardware. In theory, HID devices should be largely "self documenting". The accessory describes it's physical configuration, the system maps that configuration into the system user interface, and everything "just works".

Unfortunately, in practice that's not how most hardware actually ships. More specifically:

1. HID has been fairly widely used as software control/configuration API, not just for actual control accessories. For example, MANY microphones have one or more secondary interfaces which are used to configure the microphone. HID actually works VERY well for this sort of thing, though it does mean that an app needs to be careful about how it interacts with whatever it finds.

2. A very large percentage of HID accessories present HID configuration which are WILDLY out of line with their physical configuration. It's entirely possible that hardware vendors have excellent and well considered reason for doing this, but I've never really heard one.

That leads to here:

OK, I don't know what all changed, but I went back from monitoring for the report event to the element update and it's working now. I'm still wondering why the report isn't picking up, but i can read the element and get

The big issue that #2 creates is a feedback circle of:

1. Creating a truly "generic" HID controller is difficult because the logic presentation is so disconnected from the physical accessory.

2. Because of #1, HID controller software is designed/special cased for specific hardware so that the software can properly present "reality".

3. Because of #2, it's easy to avoid/ignore issues with the HID implementation. The software is already special cased for <insert device name> so it can just avoid doing <insert thing that should work but doesn't>.

4. ...which then makes it harder to make generic HID control software, looping us back to #1.

Core functionality like "the mouse working when plugged in" works because the default system driver isn't special cased and, more importantly, there are few things more frustrating than trying to install a mouse driver so your mouse will work... without a working mouse.

The good news here is that the HID protocol is well enough designed that you can figure these issues out with testing and experimentation, you just have to keep in mind that the hardware can't be blindly tested.

Thanks again for your help, Kevin! You definitely helped fill a couple holes in knowledge for me in this.

You're very welcome and good luck!

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware