WebUSB compatibility and example

[riggs]

Added support for BOS descriptors and created WebUSB low-level example (needed because WebUSB devices are required to respond to custom device requests).

Perhaps WebUSBDevice.h could live somewhere deeper in the library because it has no need to be in user-land code, but I'm not sure where would be most appropriate, or how to hook it into the build system.

[jpliew]

Hey @riggs , just wondering if you have implemented the MS_OS_20_DESCRIPTOR ?

Also for BOS_DESCRIPTOR

const USB_Descriptor_BOS_t PROGMEM BOSDescriptor = BOS_DESCRIPTOR(
		(WEBUSB_DESCRIPTOR(WEBUSB_VENDOR_CODE, WEBUSB_LANDING_PAGE_INDEX))
);

and

		#define WEBUSB_DESCRIPTOR(VendorCode, LandingPageIndex) \
			WEBUSB_PLATFORM_DESCRIPTOR_SIZE, DTYPE_DeviceCapability,\
			DCTYPE_Platform, \
			/* Reserved */ 0, \
			WEBUSB_PLATFORM_UUID, \
			(uint8_t)(WEBUSB_VERSION % 256), (uint8_t)(WEBUSB_VERSION / 256), \
			VendorCode, \
			LandingPageIndex

seems to be a lot more shorter than the WebUSB Arduino 's BOS

const uint8_t BOS_DESCRIPTOR_PREFIX[] PROGMEM = {
0x05,  // Length
0x0F,  // Binary Object Store descriptor
0x39, 0x00,  // Total length
0x02,  // Number of device capabilities

// WebUSB Platform Capability descriptor (bVendorCode == 0x01).
0x18,  // Length
0x10,  // Device Capability descriptor
0x05,  // Platform Capability descriptor
0x00,  // Reserved
0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47,
0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65,  // WebUSB GUID
0x00, 0x01,  // Version 1.0
0x01,  // Vendor request code
};

// Landing page (1 byte) sent in the middle.

const uint8_t BOS_DESCRIPTOR_SUFFIX[] PROGMEM {
// Microsoft OS 2.0 Platform Capability Descriptor (MS_VendorCode == 0x02)
0x1C,  // Length
0x10,  // Device Capability descriptor
0x05,  // Platform Capability descriptor
0x00,  // Reserved
0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C,
0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F,  // MS OS 2.0 GUID
0x00, 0x00, 0x03, 0x06,  // Windows version
MS_OS_20_DESCRIPTOR_LENGTH, 0x00,  // Descriptor set length
0x02,  // Vendor request code
0x00   // Alternate enumeration code
};

Is this pull request the full implementation ?

Thanks mate, keep up the good work.

Cheers

[riggs]

@jpliew
My code only looks shorter because I've hidden the complexity in some macro voodoo: dbd4afe#diff-5e900a9e6badabaeb6eb2e6c9a904b9eR517 It does have the added benefit of being very easy to add additional BOS descriptors, however.

I've been researching the MS documentation about the MS OS platform descriptor and it's a complicated mess, it turns out. If your device is simple, with a single endpoint, just treating it as a magic number should work. However, I haven't had a chance to integrate & test it, yet.

Adding the MS OS descriptor will be simple:

const USB_Descriptor_BOS_t PROGMEM BOSDescriptor = BOS_DESCRIPTOR(
		(MS_OS_DESCRIPTOR_MAGIC_NUMBER)
		(WEBUSB_DESCRIPTOR(WEBUSB_VENDOR_CODE, WEBUSB_LANDING_PAGE_INDEX))
);

[riggs]

Finally working on Windows.

@jpliew This is what you were looking for.

[jpliew]

@riggs just tested with ATmega32U2, make successful

AVR Memory Usage
----------------
Device: atmega32u2

Program:    2480 bytes (7.6% Full)
(.text + .data + .bootloader)

Data:         13 bytes (1.3% Full)
(.data + .bss + .noinit)


 [INFO]    : Finished building project "WebUSB".

$ dfu-programmer atmega32u2 erase
Checking memory from 0x0 to 0x6FFF...  Not blank at 0x1.
Erasing flash...  Success

$ dfu-programmer atmega32u2 flash WebUSB.hex
Checking memory from 0x0 to 0x9FF...  Empty.
0%                            100%  Programming 0xA00 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
0%                            100%  Reading 0x7000 bytes...
[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
Validating...  Success
0xA00 bytes written into 0x7000 bytes memory (8.93%).

However, Windows 8.1 device manager showed the following error message

Windows has stopped this device because it has reported problems. (Code 43)

A request for the Microsoft OS 2.0 descriptor set failed.

USBDeview showed the following

A good working WebUSB will show the following properties

[riggs]

I have a product in the wild that has this working and I extracted this example from it, but I clearly missed a part. I should have time this week to take a look at this example and get it fixed up.

[riggs]

While very long overdue, this is now updated and working. I've even included some JS to demonstrate functionality. It's tested on both Windows & OS X.

[riggs]

Rebased onto master to accommodate copyright changes.

[abcminiuser]

Whoops - missed this once again. Happy to merge this in once the documentation issues are fixed - ignore the bootloader build failures in the Drone checks as that's something on my end to fix.

[riggs]

I'm not super familiar with doxygen, so I'm struggling to see why my \refs aren't working correctly:

/.../lufa/Demos/Device/LowLevel/WebUSB/MS_OS_20_Device.h:49: warning: unable to resolve reference to `BOS_DESCRIPTOR' for \ref command
/.../lufa/Demos/Device/LowLevel/WebUSB/WebUSBDevice.h:63: warning: unable to resolve reference to `WebUSB_URL_Descriptor_t' for \ref command
/.../lufa/Demos/Device/LowLevel/WebUSB/WebUSBDevice.h:44: warning: unable to resolve reference to `BOS_DESCRIPTOR' for \ref command
/.../lufa/Demos/Device/LowLevel/WebUSB/WebUSBDevice.h:63: warning: unable to resolve reference to `WebUSB_URL_Descriptor_t' for \ref command

BOS_DESCRIPTOR is defined in StdDescriptors.h, but I thought doxygen should figure that out on its own.

WebSUB_URL_Descriptor_t is defined in the same file as the \ref, so I really have no idea why that's an error (twice).

[riggs]

Also, both WebUSBDevice.h and MS_OS_20_Device.h are essentially library files rather than user-land, so perhaps they should live deeper in the library. I'm not sure where, however.

[RuRo]

Hi, sorry to bother you, but is this still getting worked on? If my understanding is correct, the downstream qmk#8 PR is blocked in favour of waiting for this PR, which also effectively blocks qmk/qmk_firmware#7778.

[riggs]

@RuRo I have not actively looked at this since the previous issues (the related project was shelved). I remember trying to figure out how to appease Doxygen, but never being able to get it to successfully build.

[RuRo]

@riggs I've fixed the problems with Doxygen for you and submitted them as a PR to EntropicEngineering:WebUSB: EntropicEngineering#1. Would you be willing to spend a little of your time to finally get this PR through?

[riggs]

Thanks to @RuRo for figuring out the Doxygen issues and bringing the PR forward.

I don't have a device (or Windows box) currently available to verify Windows' view of the demo device, but the example has been tested working previously.

[RuRo]

It's that time of the week, where I go around all the PRs I am participating in and ping everyone!

@abcminiuser what do you think about this PR? As I've mentioned previously, this PR is currently effectively blocking some PRs for WebUSB support in qmk/lufa and qmk/qmk_firmware.