[BUG] Corrupt commands between HID, Serial and Platforms (mainly Windows)

[AriDeve]

Summary

As expressed in JnyJny/busylight#417 (I have left a comment there explaining it)

TLDR: Windows HID driver API requires an additional mandatory byte before the data buffer when writing. This byte is the Report ID, and it can be left as 0x00 for most, if not all HID devices here.
Afaik in Linux, this Report ID also exists as a byte before the data buffer, BUT it may be omitted when devices only have a single supported HID report, unlike Windows, hence why it has been working. So this should probably also be addressed in case where a device has multiple supported reports.

Devices using Serial communication should not be affected by this, and will cause issues if treated the same JnyJny/busylight#439 JnyJny/busylight#437

Hence, currently match self.platform in light.py is incorrect, as:

• Windows 11 is not an exception to this HID behavior (verified by trying to use a Luxafor Flag, it fails because it requires this byte)
• Devices using Serial communication should not have this byte added (haven't tested it yet, but the expected behavior is that devices like BusyTag will fail on Windows 10)

Due to this, the previously attempted fix JnyJny/busylight#450 was also incorrect

@JnyJny Hope this will be of help in understanding when to add this additional byte :)

Platform

Windows 11 x86_64

Version

uvx busylight v0.45.1

Python version

Python 3.12.6

[JnyJny]

I apologize for taking this long to respond and thank you very much for opening the issue. I'm afraid that rather than having a deep understanding of USB, I've hacked quite a bit of the lower level details so that it "worked" with my collection of USB hardware and system hosts (MacOS and Linux for the most part), and this likely the root cause of the Windows disconnect. It appears you have a deeper understanding of USB operations and I am grateful that you have chimed in.

TLDR: Windows HID driver API requires an additional mandatory byte before the data buffer when writing. This byte is the Report ID, and it can be left as 0x00 for most, if not all HID devices here.
Afaik in Linux, this Report ID also exists as a byte before the data buffer, BUT it may be omitted when devices only have a single supported HID report, unlike Windows, hence why it has been working. So this should probably also be addressed in case where a device has multiple supported reports.

So to summarize, Windows requires the report id whereas Linux/Macos do not (unless the number of report ids is greater than 1)?

I'm going to go back to the HID API that I am consuming and see where I started making bad assumptions that fail with Windows.

Any further insight you could provide would be much appreciated!

[AriDeve]

No worries about the response time, I myself am not TOO proficient in these APIs, but I've worked with light devices for long enough and read through our (wink, from work at one of the companies this project supports that starts with L and ends with R) codebase to know some details that apply here.

So to summarize, Windows requires the report id whereas Linux/Macos do not (unless the number of report ids is greater than 1)?

On Windows, the report ID is a required first byte in the output buffer. If the device doesn't specify unique report IDs, this byte should be set to 0x00.

This of course depends on if the library you are using is implicitly doing this or not. As far as I understand, Windows HidD_SetOutputReport and HidD_SetFeature requires a report ID input (0 if no specified report ID), so hidapi needs it here, but strips it out later. For linux/mac, hidraw (hidapi backend) implicitly does not require the byte (hence why it works on those platforms), but will still strip it if it's present, so you could set the leading 0x00 on all platforms.

Any further insight you could provide would be much appreciated!

Feel free to ask about details and such, while I may not recall much about specific details, I can certainly source information from the aforementioned codebase if it's something related to those products.
I am however, here on my personal time, so here's an early apology if it takes a while for me to respond.

[JnyJny]

Thanks for the more timely response :) I spent some time reading the source for hidapi and the aforementioned Cython source that consumes it today. I think what's happened is some of the lights are writing the report id out explicitly and some are not. I need to do a re-read of the busylight-core lights to verify this theory, and then refactor busylight_core.light.Light to include a report_id property and re-write the I/O methods that are aware of the new property.

[AriDeve]

I only tested if the byte missing was the cause, but didn't check if the device I was testing with had specified a report ID.

Then again, afaik, I tested it with 0x00, and it shouldn't work if the explicit report ID report it was different, so I'm still leaning towards the theory of hidapi binding requiring said byte on Windows.

I may run a test or two later, but adding support for these explicitly specified report IDs might be a good idea regardless of what the fault ends up being.