Announcement: Windows Gui Tool

[andrewleech]

Hello, I just wanted to say a huge thanks for all your work here @dorssel, this is a fantastic piece of work that's making my day to day life as an embedded design engineer much easier.
In the past I have used virtualhere to achieve similar goals, but it was always difficult to install and keep running reliably. I did however really like having a gui tool to manage the connected state of devices, and provide auto-attach based on USB port used and/or device unique ID. So I built one, which I thought I'd share here in case others find it useful too!

https://gitlab.com/alelec/wsl-usb-gui#wsl-usb-gui
https://gitlab.com/alelec/wsl-usb-gui/-/releases

This is simply an orchestration tool for usbipd-win, a copy of which is bundled in the installer (I hope you don't mind me including it?).
The installer also makes a best-effort at updating & converting WSL if needed, as well as install the other tools required (assuming the user has ubuntu installed). So this should be a one-click installer for new users to get WSL USB devices up and running.

While the app is running it monitors for USB connect/disconnect events in windows to auto refresh and manage the auto-attach feature. The auto-attach can be configured to monitor:

• a particular device (based on the windows unique device ID)
• the specific USB port used (so you can tag a port as WSL use and anything plugged in gets forwarded)
• or both (so a particular device only gets forwarded when plugged into specific port)

The priv elevation required for first connect of new devices is handed automatically as needed.

You can also rename a device, to add your own label for it within the manager app. This is particulary helpful if you've got a bunch of devices that all show as "USB Serial Port". This rename applies a new lable within the app only, it doesn't affect windows / device manager / linux in any way.

[andrewleech]

I've only just caught-up on #56 and acknowledge there's a number of limitations in my app here, mainly that it only work for the current windows users default WSL instance.
That being said, once a USB device has been attached it does so at a kernel level, so the device is also available to WSL docker containers etc (if you bind mount /dev) so I've found it quite flexible in that regard.
I don't have any support for remote clients / hyper-v etc as I wanted to keep the UI simple for now.

My main motivation for writing this app windows side was to make it easy for less-technical / non-linux users to get up and running with a gui tool that did not need linux/wsl gui set up and running (many people do not have this yet) and to deal with the admin escalation needed for first connect - linux tools can only see usb devices that have been connected manually previously from windows side.

[dorssel]

@andrewleech
Awesome!

This is exactly what I meant in #56 (comment).
And I actually appreciate it being a separate project, as the tooling/skills/issues will be quite distinct.
This is even more so since this has the auto-detect functionality mentioned in #371 (comment) and #56 (comment).

I see that it is now very WSL-centric. If you add 'bind' and 'unbind', it would be useful for Hyper-V/remote users as well...

[dorssel]

@andrewleech
Next note: I will leave this issue open for others to find. Maybe you can change the title to "Available: xxxx" or "Announcement: xxxx", so it does not look like a request.

I will at some point change the README and wiki to refer to your project, after which the issue will be migrated to a "show-and-tell" discussion, if you're OK with that.

[dorssel]

@andrewleech
Final note (sorry for the legalese):
usbipd-win is a derivative work, based on GPL 2 VBox drivers. That means usbipd-win must be GPL 2 too. Not by my choice (I prefer MIT licenses), but by the license terms of the VBox drivers. See: https://github.com/dorssel/usbipd-win/blob/master/Drivers/README.md.

I'm not a lawyer, but...
I don't know if your work qualifies as a derivative work. If it does, then it too must be GPL 2 licensed.

I'm perfectly fine that you incorporate the installer (it's free, and open source after all). But that certainly constitutes binary distribution. And that has certain implications, such as the requirement to make available the source code. I'm fine with the way it is, but there are more authors (including Microsoft), and then there is Oracle...

[andrewleech]

I see that it is now very WSL-centric. If you add 'bind' and 'unbind', it would be useful for Hyper-V/remote users as well...

I'm assuming this just binds the USB device to the usbipd service, such that remote clients can see / attach them as needed?
Certainly this would be easy to do in code... I'll just have to think about how to represent it on the gui, ig two more buttons won't fit where the existing ones are without reorganising something, and I'd want to show bound devices differently to attached. The difference between the two would be confusing to some people too. I'm certainly not saying no to this feature (it's well worth it), this is more of a train of thought of what I'll want to solve.

I don't know if your work qualifies as a derivative work. If it does, then it too must be GPL 2 licensed.

I also am not a lawyer, though I've spent a lot of time in the past working with / in / around these licences. I'm pretty sure it's technically not a derivative work as it's interacting with your binaries on a command line level - it does not include any code directly, nor link in any code (statically or dynamically). That being said, as you mention, I'm distributing the msi - the source of which I won't have properly declared currently. Regardless of all of this - it would certainly simplify any of these discussions if I simply match the GPL2 licence here, I'm certainly not opposed to doing that, that would also make it easier to reference this projects licence/s directly as well :-)

[dorssel]

I'll suggest and describe the bind/unbind use case on your project. Seems only logical.

And about the license. I also believe yours is not a derivative work. And of course you should release your code under whatever license you whish. I don't think it is an issue at all distributing a GPL work alongside a MIT work (as long as they are not derived). Just take care of the source requirement. A README similar to mine (referring to the releases page of usbipd-win, where source tarballs are offered right next to the msi) should be sufficient.

[andrewleech]

And about the license. I also believe yours is not a derivative work. And of course you should release your code under whatever license you whish. I don't think it is an issue at all distributing a GPL work alongside a MIT work (as long as they are not derived). Just take care of the source requirement. A README similar to mine (referring to the releases page of usbipd-win, where source tarballs are offered right next to the msi) should be sufficient.

I think GPL will fit my gui project just fine, it's mainly libraries / embedded things I like to keep MIT etc so I can also use them at work easily. Standalone apps / tools are good as GPL with the extra protections that entails. I've updated my project LICENCE file as such and added references / links to the readme which should tick this off. These files are now also included in the installed app folder. Thanks for bringing this up too, while I make efforts to give credit where due, I do often forget to include LICENCE files in installers etc.

[dorssel]

Added reference to https://github.com/dorssel/usbipd-win/blob/master/README.md, converting to "Show-and-tell" discussion.

[andrewleech]

@dorssel thanks for raising the feature request issues too, that detail helps. I'll have to think about the UI for it a bit but the suggestions certainly make sense

[rgbigel]

@dorssel thanks, I was lucky to find WSL USB Manager.
As a beginner to WSL, I have the following comments / daft questions:

1. the startup is slow, which is ok, but while waiting for the window to open,
   -- how about showing an hour glass?
   (I wound up launching it 4 times befor seeing anything, being somewhat impatient)

2. the documentation of the gui?
   -- what does "bound" or "forced" actually mean? what are profiles used for?

3. as it uses only the default wsl, how about showing the -distro used?

4. I did not find a way to actually access a usb mass storage device,
   -- please supply information about how to mount one, to e.g. /mnt/u for attached device
   -- I have a bus id 1-8 referring to a "USB Mass Storage device Norelsys " (a SD Card)

Thank you, Rolf

[dorssel]

I think you have a better chance asking the author of the tool. It has its own project page.

[andrewleech]

I'm surprised to hear about a slow startup, I haven't seen that myself. It does so the initial USB scan before showing the GUI I think, that might be the issue, I could possibly reorder startup a bit there. I've added a ticket here: https://gitlab.com/alelec/wsl-usb-gui/-/issues/20

It's true I don't have any documentation. I originally made this tool for myself and then just thought it was worth sharing... I haven't had a lot of time to think about how to support its use by others though.
Bind and force are basically just exposing usbipd features, some tooltips or something in the app to also expose the help would be useful, as would proper usage docs.
Auto-attach profiles are to make devices always connect to wsl automatically when unplugging / replugging.

Others have mentioned distro settings too, there's discussion about that here: https://gitlab.com/alelec/wsl-usb-gui/-/issues/8
Generally it doesn't matter which distro is used, the same kernel is used for all distros so the USB device is available to all. It only possibly matters during the actual connect (attach) because the usbip tools need to be installed in the distro being used for the connection.

WSL2 does not support mass storage, the kernel driver for it isn't included by Microsoft. That's something that usbipd can't help with unfortunately.

[andrewleech]

Hi @rgbigel I've recently made some updates that should cover most of the issues you raised! GUI startup time should now be pretty much instant, this is down to better use of asyncio internally for the app management along with improvements in usbipd that are in the upcoming v4.0.0 release.

I've also added a Usage section to the readme, hopefully this goes a long way towards describing usage and demystifying some of the terminology and features provided.

Also included in the usbipd release are changes that reduce the dependence on any particular WSL distro, which should remove any real need for the gui to show / provide options to select one.
One discrepancy from this is the udev permissions stuff I've added in the gui tool, that only interacts with the default WSL distro and probably wont work properly on all distro types. I haven't thought of a clean / intuitive way to change this, it also meets my personal needs perfectly as is.

Note these changes are in my tool repo, but aren't released yet. Once usbipd v4 is released I'll get an update to the gui tool rolled out that includes it.

[znmeb]

This looks cool. Does it include logging to help users troubleshoot issues with connection drops?

[dorssel]

Logging for usbipd is documented here: https://github.com/dorssel/usbipd-win/wiki/Troubleshooting. If it is about the tool: it has its own project page. Better ask there.

[andrewleech]

My GUI app does have some logging though it's not overly advertised, mostly to help with issues during the automated installation process.