Windows Subsytem for Linux Support!

[rrbutani]

This isn't quite ready yet: I want to do a little more testing and I need to finish/polish the install guide for WSL. So, don't merge this yet!

I'm making this PR now so people can kick the tires a bit and see if it works.

This also is rebased against the build-system branch; it isn't exactly required for WSL support but it should be merged before this PR.

This:

• updates detect-board for Windows (this needs some polish)
• adds scripts to install and configure OpenOCD on windows
• installs an OpenOCD shim for WSL
• adds instructions to install WSL + install ICDI drivers + chmod /run/screen + chmod the ttyS* in detect-board

[P1n3appl3]

Less bash pls!

[dimembermatt]

We'll get there this summer hopefully 😢
Going to go through this and see what I can salvage for WSL2.

[rrbutani]

@dimembermatt As of last November, USB device support for WSL2 was still kinda sketch; I haven't really kept up with it but it doesn't look like things are much better for arbitrary devices.

This is basically the only roadblock left. In the past I got around it by shelling out to the Windows version of openocd from WSL (that's what the shim that's generated here does) but it's a pretty brittle approach that comes with all kinds annoying things like WSL → Windows path translation and getting gdb in WSL to talk to openocd (the pipe way which we use right now gets gross when the actual thing you're calling is a Windows process and the server way is tricky because then you've got to make a wrapper script that brings them up and down at the same time).

I was hoping that WSL2 would let us access arbitrary USB devices (which we need for ICDI — serial actually gets passed through even with WSL1 which is why screen works) but it doesn't seem like it will. The openocd shim approach is definitely still viable but there are definitely lots of edge cases I didn't anticipate or handle; actually getting it to a state where it's usable will take a fair amount of effort, I think.

But really, after having spent a lot of time trying to do platform support by shoving Linux everywhere, I think ultimately it's probably best to either put time into making guides for native Windows installations (all the tools we use have native Windows binaries) or just have people use VMs. All of the things I tried to do ending up being incredibly brittle and I think they'd require a lot more time to actually get right and then, way more maintenance effort than is justifiable.

I'm partial to just using VMs because:

• I still think it's good that we expose people to a unix-y environment even if we don't teach it very well
• The tlt user experience on Linux with VS Code is pretty darn good, I think; it's basically one-click
• It's much less effort and much easier to provide good supporting materials for; I think this'll matter more than usual next semester if in person meetings and events are going to be discouraged
• Modulo some weird VT-d/VT-x settings on some laptops, it's usually pretty straightforward

That said, I'm happy to help however I can with whatever approach you end up choosing.

[dimembermatt]

It looks like that WSL 2 will eventually have USB support, but I'm not optimistic about the timeline for that.

I'm on board with you on the VM approach. A unified UX will make it a lot easier for us to maintain documentation and iron out or identify bugs. I'd even argue that Mac users should also use a VM, but I don't know if it already works well enough as is now. I'll leave that as a possible extension at the moment.

I was having some hiccups along the way getting make flash to work (timed out while waiting for target halted), but it seems to work -I have the demo running- now that I've restarted my laptop. I'll look into this a little more and update the instructions if I see anything. I'll also start going through my parts and update the demos.

It doesn't look like I see the setup instructions for using this with VSCode, is that somewhere else not on the Rasware repo? (also, tlt?)

Adding @RosannaR to the conversation, I wonder what bugs in general were you experiencing when trying to get this work? Were you using WSL or VirtualBox? I remember we were having some issues with ninja.

Finally, was there anything else you were looking at fixing/extending?

I'm thinking the current list of priorities this summer are:

• establish a minimum viable build that'll work on Linux and Windows Linux VM (VirtualBox or VMware?)
  • simplify the build process (ideally for me it's a script that'll do everything in the Rasware linux instructions up until running RASDemo)
  • bug testing (looking at last year's comp. somehow a lot of people had issues and even though the instructions were pretty simple for me to set up...)
• one click building with vscode (my code editor of choice 🦜)
• add RGB color sensor api and demo to the existing codebase (not sure if the I2C code will work now as is)
• look at cleaning the code base if needed (i.e. standardizing function signatures, adding more user documentation, etc)

It's a pretty big project considering my other priorities this summer, so hopefully Burak frees up some time later on to help throw more bodies at this.

[rrbutani]

I'd even argue that Mac users should also use a VM, but I don't know if it already works well enough as is now. I'll leave that as a possible extension at the moment.

So actually, I think things worked pretty okay for macOS last year but I might be misremembering. If y'all end up using tlt again I can make sure things work natively; in theory things should Just Work, save for the docker container stuff in VS Code (you have to install things yourself but I made a script that helps you through it).

But yeah, VMs for macOS wouldn't be so bad.

I was having some hiccups along the way getting make flash to work (timed out while waiting for target halted), but it seems to work -I have the demo running- now that I've restarted my laptop. I'll look into this a little more and update the instructions if I see anything. I'll also start going through my parts and update the demos.

So, are you using Rasware with it's make based build system or the tlt based thing that we used last year?

I kind of botched things last year and I can't actually find where we ended up putting install docs; I think they were in a thread in the slack that's since disappeared. 😕

It doesn't look like I see the setup instructions for using this with VSCode, is that somewhere else not on the Rasware repo? (also, tlt?)

So tlt is this thing that we used for robotathon last year. It tries to do a few things but the main point was that it's supposed to be easy to use and set up. It kind of achieves this (at least on Linux) but it has a couple of quirks.

I'm not sure where the setup instructions went but for Linux with VS Code it's just:

• install docker
• install VS Code
  • can't be the community edition, unfortunately
• install the Remote Development extension pack
  • ctrl+p → ext install ms-vscode-remote.vscode-remote-extensionpack
  • we only use the containers extension, details here
• clone the rasware-template repo inside VS Code
  • ctrl+p → git clone → https://github.com/ut-ras/rasware-template → open
• press the "Reopen in Container" button in the popup on the bottom right

And it should build the container, install all the plugins it needs, make the files it needs for clangd to work and then relaunch VS Code. From there if you hit F5 it should flash your board and open up the debugger. IIRC it grabs the Cortex-Debug plugin too and gives it the right SVD file so you should be able to see the peripherals and stuff too.

There are a bunch of things tlt can do for you (like, you get a CI setup that matches your laptop for free since the entire toolchain runs in a container anyways; the template actually uses this GitHub Action by default), but those don't matter as much for Robotathon/Rasware.

Not sure whether it makes more sense to use tlt or go back the Makefiles but I'm happy to maintain tlt if y'all end up using it.

Finally, was there anything else you were looking at fixing/extending?

Most of my qualms with Rasware have been tooling/build system related. Outside of build system things, I've wanted to update Rasware to actually use hardware PWM now (since we don't really hand out LM4Fs anymore) but this is super unimportant.

The other thing I've wanted to do was more in the way of automated testing but I never really got to making very concrete plans for how to do this and it'd be a pretty bad use of time at this point.

I'm thinking the current list of priorities this summer are:

* establish a minimum viable build that'll work on Linux and Windows Linux VM (VirtualBox or VMware?)
  
  * simplify the build process (ideally for me it's a script that'll do everything in the Rasware linux instructions up until running RASDemo)

This has definitely been brought up before but: it's actually super viable to just give people a VM image, as a backup.

Hopefully you have better luck than I've had, but I've tried to do install scripts many times before and I've found good install instructions to be more resilient/less likely to need to be updated.

* look at cleaning the code base if needed (i.e. standardizing function signatures, adding more user documentation, etc)

I actually think Rasware is pretty good about this as is, but it'd could be good to maybe put the docs up somewhere a little more accessible than the GitHub wiki for this repo. The examples are good too but documenting them more never hurts.

[dimembermatt]

I was using the make build system, but tlt iirc looked very promising last year when I saw some of the teams using it. I'll try that out as well.

Thanks for reminding me that we were looking at VM images with the thing already set up; I think that this would probably be the easiest way to get things running, especially with the steering-committee's bandwidth.

For more devious purposes, this would be very beneficial for hooking a new generation of students on [OS]/[code editor]/[shell]... any preferences for this? @benbelov would probably vouch for Manjaro and zsh. Of course, I'll leave the manual instructions for the Arch inclined to get setup on. I'm thinking of Ubuntu 20.04 for this prebuilt image, but it might be useful to have a 32 bit version since I don't know if some students will have very old laptops.

Hopefully I can get an image set up and OS specific instructions for getting it working on VirtualBox by the end of this week. Will send it out to Wendy and co to get some feedback.

[rrbutani]

I was using the make build system, but tlt iirc looked very promising last year when I saw some of the teams using it. I'll try that out as well.

I just wanted to clarify: tlt is something I wrote so you should probably take anything I say about it with some skepticism :-P.

Thanks for reminding me that we were looking at VM images with the thing already set up; I think that this would probably be the easiest way to get things running, especially with the steering-committee's bandwidth.

For more devious purposes, this would be very beneficial for hooking a new generation of students on [OS]/[code editor]/[shell]... any preferences for this? @benbelov would probably vouch for Manjaro and zsh. Of course, I'll leave the manual instructions for the Arch inclined to get setup on.

This was actually before my time but RAS used to have RASBox, which was VM images with Arch and vim, I think.

Realistically though, I think Ubuntu + are your best bet.

I'm thinking of Ubuntu 20.04 for this prebuilt image, but it might be useful to have a 32 bit version since I don't know if some students will have very old laptops.

I'd be very surprised if anyone showed up with a 32-bit laptop.