Skip to content

doc: Add guide for dev setup on Windows#20426

Merged
dylad merged 1 commit intoRIOT-OS:masterfrom
maribu:doc/getting-started/windows
Feb 28, 2024
Merged

doc: Add guide for dev setup on Windows#20426
dylad merged 1 commit intoRIOT-OS:masterfrom
maribu:doc/getting-started/windows

Conversation

@maribu
Copy link
Copy Markdown
Member

@maribu maribu commented Feb 23, 2024 •
edited
Loading

Contribution description

This adds a detailed instruction on how to get a working development setup on Windows.

State

  • Installation of WSL/Ubuntu
  • Cloning RIOT + first steps
  • Installation of VS Code
  • Integration of VS Code to WSL + IntelliSense
  • Working and compiling from VS Code
  • Working on real hardware via USB IP

Testing procedure

Check here for a rendering of the added README.md

Issues/PRs references

#20388

@github-actions github-actions bot added the Area: doc Area: Documentation label Feb 23, 2024
@dylad
Copy link
Copy Markdown
Member

dylad commented Feb 23, 2024

@maribu Note that you can also use .exe directly from WSL so one can install JLinkExe.exe (for example) into windows, symlink the .exe binary to JLinkExe within WSL then use good old make flash from WSL console to flash a board. This could be an interesting alternative to USBIP.
Of course, it will only work if the tool has a Windows version of it.

@dylad dylad self-assigned this Feb 23, 2024
@maribu
Copy link
Copy Markdown
Member Author

maribu commented Feb 23, 2024

With USB-IP also make term works and it is actually quite straight forward. I just need to prepare the screen shots

@dylad
Copy link
Copy Markdown
Member

dylad commented Feb 24, 2024

Let me know when the full tutorial is ready. I'll give it a try on my W10 laptop.

@maribu maribu changed the title [WIP]doc: Add guide for dev setup on Windows doc: Add guide for dev setup on Windows Feb 26, 2024
@maribu
Copy link
Copy Markdown
Member Author

maribu commented Feb 26, 2024

Should be good now :)

@Teufelchen1
Copy link
Copy Markdown
Contributor

Teufelchen1 commented Feb 27, 2024

Awesome! Please be patient for a couple of days, maybe one or two weeks. I'm drowning in work rn.

@dylad
Copy link
Copy Markdown
Member

dylad commented Feb 27, 2024

Followed the whole tutorial. I was able to successfully flash p-nucleo-wb55 and nrf5340dk-app on W10 with WSL2.

The only issue is with DAP programmer which rely on USB HID. This is not supported by the default WSL Linux Kernel.
For now, I suggest to add a note in the tutorial to warn users.
We can add a specific workaround (using edbg windows binary) in a followup PR. Maybe this will be fix in a future WSL release.

For now, I think this PR is already in good shape !

@maribu maribu force-pushed the doc/getting-started/windows branch from 91d2b15 to 9044471 Compare February 28, 2024 08:23
@maribu
Copy link
Copy Markdown
Member Author

maribu commented Feb 28, 2024

Thanks. I added the info about USB HID programmers.

I do get why Microsoft disabled CONFIG_USB_HIDDEV, as users are not expected to forward their Mouse and Keyboard directly to WSL.

The thing is that HID devices are the only USB device class that works on Windows without any driver being installed. (Which also makes sense: Installing your Mouse and Keyboard driver without using a Mouse and Keyboard on Windows will be a challenge.)

Abusing HID as transport for debuggers only became popular because of the desire to have the smooth driver-less experience Linux users are familiar with also on Windows. It's quite ironic that this decision resulted in the experience now being less smooth for Windows users wanting to use RIOT.

@maribu maribu force-pushed the doc/getting-started/windows branch from 9044471 to 5f1beb1 Compare February 28, 2024 08:29
@maribu maribu added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Feb 28, 2024
@riot-ci
Copy link
Copy Markdown

riot-ci commented Feb 28, 2024 •
edited
Loading

Murdock results

✔️ PASSED

8b088c8 doc: Add guide for dev setup on Windows

Success Failures Total Runtime
1 0 1 19s

Artifacts

dylad
dylad requested changes Feb 28, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@dylad dylad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spotted a typo in the newly added text.
You can squash directly.

@maribu @dylad
doc: Add guide for dev setup on Windows
8b088c8 
This adds a step-by-step guide to install a dev setup based on
WSL2 / Ubuntu and native VS Code with the WSL extension. The guide
uses screenshots and adds annotations on top using Inkscape, so that
every click is documented.

The Inkscape sources are also added to allow adjusting / fixing the
annotations later on without having to record a new set of screenshots.

Co-authored-by: Dylan Laduranty <[email protected]>
@maribu maribu force-pushed the doc/getting-started/windows branch from 046ce5f to 8b088c8 Compare February 28, 2024 09:21
dylad
dylad approved these changes Feb 28, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@dylad dylad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good !

@dylad dylad added this pull request to the merge queue Feb 28, 2024
Merged via the queue into RIOT-OS:master with commit 5b2beea Feb 28, 2024
@maribu maribu deleted the doc/getting-started/windows branch February 28, 2024 12:46
@maribu
Copy link
Copy Markdown
Member Author

maribu commented Feb 28, 2024

Thx :)

@jkarinkl jkarinkl mentioned this pull request Mar 6, 2024
Open
13 tasks
@MrKevinWeiss MrKevinWeiss added this to the Release 2024.04 milestone Apr 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dylad dylad dylad approved these changes

@aabadie aabadie Awaiting requested review from aabadie aabadie is a code owner

@jia200x jia200x Awaiting requested review from jia200x jia200x is a code owner

Assignees

@dylad dylad

Labels

Area: doc Area: Documentation CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR

Projects

None yet

Milestone

Release 2024.04

Development

Successfully merging this pull request may close these issues.

5 participants

@maribu @dylad @Teufelchen1 @riot-ci @MrKevinWeiss