mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-13 16:43:52 +01:00
277 lines
9.3 KiB
Plaintext
277 lines
9.3 KiB
Plaintext
---
|
|
title: Installing WSL (Windows-only)
|
|
description: Install Ubuntu LTS and Windows Subsystem for Linux (WSL)
|
|
---
|
|
|
|
:::note
|
|
The following guide is for Windows users only.
|
|
|
|
It explains the process of installing Ubuntu LTS via Windows Subsystem for Linux (WSL) on a Windows machine.
|
|
|
|
If you are using a different operating system, please refer to [the general guide on how to use RIOT](/getting-started/installing).
|
|
:::
|
|
|
|
## Install Ubuntu LTS
|
|
|
|
|
|
|
|
1. Open the Windows Store
|
|
2. Type "Ubuntu LTS" in the search bar
|
|
3. Click on the most recent version (highest number) of Ubuntu LTS found.
|
|
As of February 2024, this is version Ubuntu 22.04.3 LTS.
|
|
|
|
|
|
|
|
1. Click on the button labeled "Get"
|
|
|
|
|
|
|
|
|
|
It will take a while for Ubuntu LTS to be installed.
|
|
|
|
|
|
|
|
Eventually, the installation completes.
|
|
|
|
1. Click on the button labeled "Open"
|
|
|
|
:::caution
|
|
If the Windows Subsystem for Linux (WSL) has not yet been enabled, an error
|
|
such as below will show. Not to worry, the next section got you covered.
|
|
:::
|
|
|
|
|
|
|
|
## Enabling WSL
|
|
|
|
:::note
|
|
If an Ubuntu terminal opened just fine, proceed directly to the next section.
|
|
This section will show how to enable WSL for those who hit the error.
|
|
:::
|
|
|
|
|
|
|
|
1. Search for "powershell" in the search field of the task bar
|
|
2. ***Right***-click on the hit "Windows PowerShell"
|
|
3. Click "Run as administrator"
|
|
|
|
|
|
|
|
1. Click "Yes" to confirm running the PowerShell as administrator
|
|
|
|
|
|
|
|
- Type `wsl --install` and confirm with the return-key.
|
|
- After a while, the following message should appear:
|
|
|
|
|
|
|
|
- Now reboot Windows to complete the installation
|
|
|
|
|
|
|
|
The reboot will take longer than usual due to the installation of WSL. You
|
|
may see a screen like above for some time. Once the reboot is completed,
|
|
an Ubuntu terminal should open automatically.
|
|
|
|
## Setup Ubuntu LTS
|
|
|
|
You should now see an Ubuntu terminal such as:
|
|
|
|
|
|
|
|
<details>
|
|
<summary>
|
|
If no Ubuntu terminal has opened, click here to see how to open it
|
|
</summary>
|
|
|
|
|
|
|
|
1. Click on the Start / Windows button in the task bar
|
|
2. Click on the "Ubuntu" entry
|
|
|
|
</details>
|
|
|
|
- Enter a user name of your choice, memorize it, and confirm with the return-key
|
|
- Enter a password of your choice, memorize it, and confirm with the return-key
|
|
- Repeat the password and confirm with the return-key
|
|
|
|
:::caution
|
|
When typing passwords in the Ubuntu terminal, the chars entered will not
|
|
appear on the screen and neither will appear `*`. You will have to type
|
|
"blindly". This is an intentional security feature.
|
|
:::
|
|
|
|
:::note
|
|
If you fail to repeat the password correctly, the setup will just again. So
|
|
no need to worry.
|
|
:::
|
|
|
|
- Once you successfully have entered user name and password, you should see
|
|
something like this:
|
|
|
|
|
|
|
|
- now type (without quotation signs) "sudo apt update" and confirm with the return-key
|
|
- you will be asked for you password. Enter it and confirm with the return key
|
|
|
|
:::caution
|
|
When typing the password, you will no get any visible feedback such as the
|
|
typed password or `*` chars. This is an intentional security feature.
|
|
:::
|
|
|
|
- Once you successfully entered the password, something like this will show up:
|
|
|
|
|
|
|
|
:::note
|
|
The command `sudo apt update` only updates the list of available software
|
|
packages in Ubuntu. Updating the installed software requires to additionally
|
|
run `sudo apt upgrade`
|
|
:::
|
|
|
|
- Now type `sudo apt upgrade` and confirm with the return-key
|
|
|
|
:::note
|
|
This time you likely will not need to confirm with your password again. The
|
|
`sudo` command that allows you to run administrative commands such as
|
|
`apt update` will skip the password entry, when heuristics indicate that
|
|
you have not left your machine since you last confirmed a command with your
|
|
password.
|
|
:::
|
|
|
|
- This command will list which packages are about to be updated. Confirm with
|
|
with the return-key
|
|
- Eventually after all software packages in Ubuntu have been updated, you will
|
|
see something like this:
|
|
|
|
|
|
|
|
|
|
:::note
|
|
It is recommended to regularly update the installed software in Ubuntu
|
|
using `sudo apt update` followed by `sudo apt upgrade`
|
|
:::
|
|
|
|
## Installing VS Code
|
|
|
|
|
|
|
|
1. Click on the Windows Store icon to open the Windows store
|
|
2. Type `vs code` in the search bar
|
|
3. Click on the "Visual Studio Code by Microsoft Corporation" search result
|
|
(not shown in the screenshot above)
|
|
4. In the Windows Store page of VS Code (as shown in the screenshot above),
|
|
click on the button labeled "Install"
|
|
|
|
|
|
|
|
- Downloading and installing VS Code by the Store App may take some time
|
|
- Eventually, it should show something like this:
|
|
|
|
|
|
|
|
- Now, launch VS Code via the start menu
|
|
- On the first launch, VS code will look similar to this:
|
|
|
|
|
|
|
|
- You can select a theme of you liking
|
|
- You might want to dial back the data collection by Microsoft by clicking on "opt out"
|
|
|
|
|
|
|
|
1. Open the extension marketplace by clicking on the extensions icon in the
|
|
left menu bar
|
|
2. Search for `wsl` in the search field
|
|
3. Click on the "Install" button for the "WSL" extension by "Microsoft"
|
|
|
|
:::note
|
|
The installation of the WSL extension will complete the next time you open
|
|
Ubuntu terminal. If the Ubuntu terminal was still open, close it using the
|
|
`exit` comment and launch it again.
|
|
:::
|
|
|
|
## Installing `usbipd-win`
|
|
|
|
|
|
|
|
0. Open the [release page of `usbipd-win`][usbipd-win-releases]
|
|
1. Download the installer (file extension `.msi`) of the most recent release
|
|
|
|
[usbipd-win-releases]: https://github.com/dorssel/usbipd-win/releases
|
|
|
|
|
|
|
|
Once the download is completed:
|
|
|
|
1. Open the downloaded installer
|
|
|
|
|
|
|
|
1. Confirm that you indeed want to execute the installer by clicking "OK".
|
|
|
|
|
|
|
|
The setup of `usbipd-win` opens.
|
|
|
|
1. Click on the "Install" button to proceed with the installation.
|
|
|
|
|
|
|
|
1. Confirm the installation by clicking on "Yes".
|
|
|
|
|
|
|
|
Eventually, the setup will inform you of the completion of the installation.
|
|
|
|
1. Click the "Close" button to acknowledge.
|
|
|
|
## Attach a USB Device to WSL
|
|
|
|
:::note
|
|
Attaching a USB device to WSL needs to be repeated after any of the following
|
|
happens:
|
|
|
|
1. Windows has been restarted (or hibernated)
|
|
2. WSL (the Ubuntu terminal window) has been restarted
|
|
3. The USB device has been lost (e.g. unplugging and plugging back in)
|
|
:::
|
|
|
|
:::note
|
|
You do not need to install the Windows USB drivers, Linux will use its own
|
|
anyway. All supported board run on Linux out of the box without the need of
|
|
drivers to be installed.
|
|
:::
|
|
|
|
|
|
|
|
1. Search for `powershell` in search field in the task bar
|
|
2. ***Right***-click on the search result "Windows PowerShell"
|
|
3. Select "Run as administrator"
|
|
|
|
|
|
|
|
1. Click on "Yes" to confirm running the PowerShell as admin
|
|
|
|
|
|
|
|
1. Type the command `usbipd list` and confirm with the return-key
|
|
2. Identify the USB device to share. In this guide we use an ESP32 development
|
|
board, which almost all use an USB to UART bridge (here the CP2104).
|
|
3. Run `usbipd bin --busid <BUSID>`, but replace `<BUSID>` with the correct
|
|
BUSID. E.g. `2-5` for the CP2104 identified in step 2.
|
|
4. Run `usbipd attach --wsl --busid <BUSID>`
|
|
- If an error (such as above in red) is shown that WSL is not running, just
|
|
start the Ubuntu terminal now and repeat (step 5.). If it worked the first
|
|
time, no need to run it again.
|
|
|
|
:::note
|
|
If you have trouble identifying the USB device to attach, unplug before
|
|
running `usbipd list`. Run it again with the USB device plugged in. The new
|
|
entry in the list is the device you want to attach to WSL.
|
|
:::
|
|
|
|
Now that you have successfully installed Ubuntu LTS and enabled WSL on your Windows
|
|
we can proceed with the [next steps](/getting-started/installing) to setup our development environment.
|