Better reference documentation on descriptors

[larsgk]

After a week of trying to create a WebUSB compliant device that will auto load on Linux and Windows (both), I see that

1. there are not that many OSS WebUSB (firmware) implementations out there (apart from the arduino one)
2. the arduino one is very specific to one device and is probably relying on udev rules (linux) and winusb drivers (windows) somehow already present
3. the documentation from Microsoft on the MS 2.0 descriptors and how exactly they should be laid down for WebUSB to be picked up in a composite device is... sorta non existant
4. No collected generic "how to create these typical WebUSB devices by example" documentation seem to exist

I plan to publish my findings in a tutorial/blog for others but it would probably be a good idea with some more hands on examples for a few embedded systems (e.g. zephyr, mbed, etc.) - especially what to be careful with for different versions of windows, how to co-exist with other interfaces on the device, etc.

[larsgk]

I did get it working in the end for linux... still struggling to get windows to load the proper winusb setup (devices is listed in device manager - but chrome doesn't list it unless I force the Arduino 101 DFU driver on it). Progress so far: https://twitter.com/denladeside/status/818717316443676672

[sowbug]

Lars: have you seen https://github.com/sowbug/weblight? If any code there isn't sufficiently helpful, let me know what's confusing, and I'll try to improve comments/docs.

…

On Tue, Jan 10, 2017, 11:26 AM Lars Knudsen ***@***.***> wrote: I did get it working in the end for linux... still struggling to get windows to load the proper winusb setup (devices is listed in device manager - but chrome doesn't list it unless I force the Arduino 101 DFU driver on it). Progress so far: https://twitter.com/denladeside/status/818717316443676672 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#75 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAB2VElBDRS5fILeFXRpfKjn-MS8RyPFks5rQ9twgaJpZM4Lfy_P> .

[larsgk]

Hi Mike,

thanks.

What I am currently struggling with is getting Windows 10 to load the correct (version?..setting along with?) winusb.sys for the WebUSB interface. It looks like it's loaded and ready in the device manager - but chrome doesn't find it. Then I de-install and re-install the driver, forcing the Arduino 101 DFU driver on it .. and all of a sudden it just works forever for that VID/PID combo.

I have a feeling that I need to do more MS 2.0 descriptors or tweak something in either the BOS or the MS USB request replies (handshake)... but have not managed to get a device connect to consistently show itself as available in chrome on windows 10 (chrome 55, 56 and 57)

[devanlai]

@larsgk: Can you post what Chrome records under chrome://device-log/ ?
I've been troubleshooting some non-mbed/Arduino composite WebUSB firmware on Windows that fails on the control transfer when it tries retrieve the BOS,

[larsgk]

@devanlai I know you are .... https://developer.mbed.org/users/larsgk/code/USBDevice_WebUSB/ ;)

I think we (you and I) need to use MS 2.0 descriptors - not the 1.0 that you are currently using. It seems that the loading of a proper winusb.sys is flaky at best - not appearing (at worst = mostly).

If I remove the MS descriptor part altogether and force the Arduino 101 DFU driver over my WebUSB interface (in my case, I have a CDC + WebUSB device), it seems to get listed in chrome. If I just select the std WinUSB from MS or put the WINUSB in the MS 1.0 descriptor, it doesn't work for me on win10

[devanlai]

I'm actually working on a different project with WebUSB using MS 2.0 descriptors (which are kind of flakey on USB 3.0 ports, from what I've seen). I think I might have had the MS 1.0 descriptors working for WebUSB on Windows 7 at one point, but I was also only testing non-composite devices at that time.

From my understanding, for composite devices WinUSB needs the DeviceInterfaceGUIDs registry key to be set on the interface, which can be done automatically the very first time the device is plugged in using the MS OS Descriptors or after the fact using an installer or a tool like Zadig.

Try installing the WinUSB driver using Zadig and see if that helps.

However, even with the DeviceInterfaceGUIDs key set, I've found that the BOS transfer fails on Windows 7, which I think is a Chrome implementation bug that I'll write up after I've investigated it a bit further.

[larsgk]

Interesting. Do you have an example that gets the right driver and descriptors working for a CDC+WebUSB combo on win10? I have been fighting this for a week :)

…

On Jan 10, 2017 21:45, "Devan Lai" ***@***.***> wrote: I'm actually working on a different project with WebUSB using MS 2.0 descriptors (which are kind of flakey on USB 3.0 ports, from what I've seen). I think I might have had the MS 1.0 descriptors working for WebUSB on Windows 7 at one point, but I was also only testing non-composite devices at that time. From my understanding, for composite devices WinUSB needs the DeviceInterfaceGUIDs registry key to be set on the interface, which can be done automatically the very first time <https://github.com/pbatard/libwdi/wiki/WCID-Devices#Defining_a_Device_Interface_GUID_or_other_device_specific_properties> the device is plugged in using the MS OS Descriptors or after the fact using an installer or a tool like Zadig <http://zadig.akeo.ie/>. Try installing the WinUSB driver using Zadig and see if that helps. However, even with the DeviceInterfaceGUIDs key set, I've found that the BOS transfer fails on Windows 7, which I think is a Chrome implementation bug that I'll write up after I've investigated it a bit further. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#75 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA97loy2LuQ-Fqya6aRqfOCQake6x1mBks5rQ-4DgaJpZM4Lfy_P> .

[devanlai]

After some coding-by-permutation, I've found that moving my WebUSB/DFU interface up so that it's the first interface instead of the last one helps.

On Windows 7, after installing the WinUSB driver with Zadig, it doesn't show the landing page notification, but I can select it from the device picker if I navigate to corresponding landing page.
On Windows 10, after auto-installing WinUSB using the Microsoft OS 2.0 descriptors, it's the same situation, except Chrome reads all of the USB strings as blanks, so it shows up in the device picker as an Unknown device from .

In both cases, the actual WebUSB control transfers work fine.

[larsgk]

@devanlai is it possible to mix 1.0 and 2.0 descriptors (in the same device?)

I am banging my head against the wall here on windows... do you have some working descriptor snippets that I could take a peek at? I am also trying to figure out how and what to set for DeviceInterfaceGUIDs

[larsgk]

I managed to get a non breaking 2.0 descriptor sent (inspired by @sowbug 's code - thanks) it does seem to miss the DeviceInterfaceGUIDs part (what should that be set to? - and will this force the WinUSB driver on it... why is MS OS 1.0 not good enough?).

It didn't install the WinUSB driver automatically and choosing the one shipped with windows ("update driver -> MS -> WinUSB generic) doesn't work (WINUSB (v10.0.10240.16384)). only after downgrading to the one shipped with Zadig (WinUSB (v6.1.7600.16385)) it seems to do the trick (or maybe it's the WCID ontop that does this?).

/rant: Christ - it took me 1/2 day to get this running on linux .. why does MS have to make things so complicated :)

[larsgk]

I am beginning to suspect there is a bug (or 2) in chrome - related to WebUSB.

1. it seems odd that the official Windows 10 WinUSB driver seems to load correctly when the correct (version 1 or 2) MS OS descriptors are in place - but Chrome only lists it once a much older (probably libusb related) driver is forced on the interface (see above)
2. even with the working driver forced on, unplugging/replugging the device gives unreliable detection on the chrome side (approx every other time.. but no consistent pattern) - indicating there might be some race condition or other related to when Chrome reads the descriptors...

thoughts?

[devanlai]

Are you able to get the landing page notification popup, or is it only showing up in the device picker (and does it fetch the USB strings correctly)?.

I just tested an older CDC+DFU WebUSB project that uses MS OS 1.0 descriptors. Moving the DFU interface around doesn't seem to make a difference. Whether the DFU interface is first or not still results in no landing page notification, working strings on Win7, broken strings on Win10. Downgrading the driver from v10.0 to v6.1 doesn't seem to make any difference.

If you want to take a look for comparison:
https://github.com/devanlai/termlink/blob/winusb/src/USB/winusb.c

[larsgk]

About the landing page notification: I think I heard it may have been temporarily disabled on Windows. Not sure though as I have also only seen it on Linux. On Jan 11, 2017 6:42 PM, "Devan Lai" <notifications@github.com> wrote: Are you able to get the landing page notification popup, or is it only showing up in the device picker (and does it fetch the USB strings correctly)?. I just tested an older CDC+DFU WebUSB project that uses MS OS 1.0 descriptors. Moving the DFU interface around doesn't seem to make a difference. Whether the DFU interface is first or not still results in no landing page notification, working strings on Win7, broken strings on Win10. Downgrading the driver from v10.0 to v6.1 doesn't seem to make any difference. If you want to take a look for comparison: https://github.com/devanlai/termlink/blob/winusb/src/USB/winusb.c — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#75 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA97lg8IiJTMkbyDlUBcD9Ri0qqLW1wCks5rRRR5gaJpZM4Lfy_P> .

[reillyeon]

Yes, landing page detection is disabled on Windows on Chrome startup due to a bug causing Chrome hangs for a small percentage of users. If you call any of the navigator.usb methods it will initialize Chrome's USB subsystem and you should start getting notifications when you connect a new device.

[larsgk]

@reillyeon , for actual buggy behavior in chrome (or differences between platforms), what are the main keywords to add on crbugs to be caught & who to CC? just WebUSB & you?