doc/guides: Getting Started

doc/guides: remove original windows guide

doc/guides/getting-started/building_example.mdx

@@ -0,0 +1,101 @@
+---
+title: Building an Example
+description: Building an example application with RIOT
+---
+
+import Contact from '@components/contact.astro';
+
+<Contact />
+
+:::note
+This guide uses the `samr21-xpro` board as an example.
+You can replace it with the name of any other supported board,
+as learned in the previous section, by replacing `samr21-xpro`
+with the name of your board.
+:::
+
+RIOT provides a number of examples in the `examples/` directory. Every example
+has a README that documents its usage and its purpose. You can build them by
+opening a shell, navigating to an example (e.g. `examples/default`), and
+running:
+
+```bash
+make BOARD=samr21-xpro
+```
+
+or
+
+```bash
+make all BOARD=samr21-xpro
+```
+
+To flash the application to a board just run:
+
+```bash
+make flash BOARD=samr21-xpro
+```
+
+You can then access the board via the serial interface:
+
+```bash
+make term BOARD=samr21-xpro
+```
+
+If you are using multiple boards you can use the `PORT` macro to specify the
+serial interface:
+
+```bash
+make term BOARD=samr21-xpro PORT=/dev/ttyACM1
+```
+
+For flashing and accessing the board via the serial interface, the current user
+needs to have the correct access rights on the serial device.
+The easiest way to ensure this is to add the current user to the group that is
+owning the serial device. For example, this can be achieved on Linux by issuing
+the following line, logging out and logging in again:
+
+```bash
+sudo usermod -aG $(stat --format="%G" /dev/ttyACM0) $USER
+```
+
+Note that the `PORT` macro has a slightly different semantic in `native`. Here
+it is used to provide the name of the TAP interface you want to use for the
+virtualized networking capabilities of RIOT.
+
+We use `pyterm` as the default terminal application. It is shipped with RIOT in
+the `dist/tools/pyterm/` directory. If you choose to use another terminal
+program you can set `TERMPROG` (and if need be the `TERMFLAGS`) macros:
+
+```bash
+make -C examples/gnrc_networking/ term \
+    BOARD=samr21-xpro \
+    TERMPROG=gtkterm \
+    TERMFLAGS="-s 115200 -p /dev/ttyACM0 -e"
+```
+
+You may not see the greeting
+
+```plaintext title="The greeting message from the board"
+main(): This is RIOT!
+```
+
+when you flash the board. In this case, type `reboot` in the command line or reboot manually.
+
+:::tip[Using the native port with networking]
+If you compile RIOT for the native cpu and include the `netdev_tap` module,
+you can specify a network interface like this: `PORT=tap0 make term`
+
+*Setting up a tap network*
+
+There is a shell script in `RIOT/dist/tools/tapsetup` called `tapsetup` which
+you can use to create a network of tap interfaces.
+
+*USAGE*
+
+To create a bridge and two (or `count` at your option) tap interfaces:
+```shell
+    sudo ./dist/tools/tapsetup/tapsetup [-c [<count>]]
+```
+
+A detailed example can be found in `examples/gnrc_networking`.
+:::

doc/guides/getting-started/finding_modules.mdx

@@ -0,0 +1,72 @@
+---
+title: Finding and Using Modules
+description: This tutorial will explain how to use modules in RIOT.
+---
+
+import Contact from '@components/contact.astro';
+
+A core concept in RIOT is the use of modules.
+Modules are a way to organize code and data in a way that makes it easy to reuse and share.
+In the previous tutorial, we created a simple hello world program and you might have noticed that we included a module called `ztimer`.
+`ztimer` is one of the core modules in RIOT and provides a way to work with timers,l both software and hardware timers are supported.
+
+Lets take a look at how we can use modules in RIOT and where to find them.
+
+## Step 1: Finding modules
+
+RIOT provides a number of modules that you can use in your application, including modules for networking, sensors, and more.
+Depending on the goal of your application, you might need to use different modules and sometimes even create your own. So where can you find these modules?
+
+There are several approaches to this and none of them are wrong.
+
+### Approach 1: The API Documentation
+
+![API Documentation Website](img/finding_modules/01_api_doc.png)
+
+The first approach is to look at the API documentation. The API documentation provides a list of all modules and functions that are available in RIOT and can be found [here](https://doc.riot-os.org/topics.html).
+
+It can be a bit overwhelming to find the right module in the API documentation, but it is a good starting point if you know what you are looking for.
+
+### Approach 2: The Examples
+
+![RIOT Examples](img/finding_modules/02_examples.png)
+
+Another approach is to look at the examples that are provided with RIOT. The examples are a great way to learn how to use a module and see it in action.
+
+You can find the examples in the `examples` directory of the RIOT repository, most of them come with a `Makefile` that you can use to build the example and a ReadMe file that explains what the example does.
+
+### Approach 3: The Source Code
+
+![RIOT Source Code](img/finding_modules/03_source.png)
+
+The last approach is to look at the source code of RIOT. This can be a bit more challenging, but sometimes it does provide the best insight into how a module works.
+
+Let's say I want to use base64 encoding in my application. I can search the RIOT repository for `base64` and see if there is a module that provides this functionality.
+
+### Approach 4: Asking for Help
+
+<Contact/>
+
+## Step 2: Using modules
+
+Using modules in RIOT is quite simple. You just need to list any modules that you want to use in your application in the `Makefile` of your application.
+
+If we look back at our hello world program, we can see that we included the `ztimer` module in the `Makefile` like this:
+
+```make
+USEMODULE += ztimer_sec
+```
+
+After that we were able to simply include the `ztimer` module in our `main.c` file like this:
+
+```c
+#include "ztimer.h"
+```
+
+and then use the `ztimer_sleep` function in our program to sleep for 3 seconds.
+
+```c
+ztimer_sleep(ZTIMER_SEC, 3);
+```
+
+That's it! You have successfully used a module in RIOT with just a few lines of code.

doc/guides/getting-started/flashing.mdx

@@ -0,0 +1,117 @@
+---
+title: Flashing a RIOT Application
+description: Flash a RIOT application to a real hardware device
+---
+
+import Contact from '@components/contact.astro';
+
+<Contact />
+
+After all of the previous sections are completed, we can finally flash some
+real hardware. In this case, we use an `esp32-mh-et-live-minikit` development
+board. The guide should mostly apply to all other boards as well.
+
+:::note
+    Some boards require extra steps to be flashed, such as pressing a button
+    to enter a bootloader or attaching an external programmer. Refer to the
+    documentation of the board to check if extra steps are required.
+:::
+
+:::tip[Flashing under WSL]
+    If you are using Windows, this assumes that the USB UART bridge of the ESP32 development board has
+    been attached to WSL and VS Code has been launched from within WSL by running
+    `code .` inside the RIOT repository from the Ubuntu terminal.
+:::
+
+![VS Code in WSL](img/08-Flash_Real_Hardware-03.png)
+
+1. Open the `examples` folder
+2. Open the `default` folder within `examples`
+3. Open the `main.c` file in the `default` folder
+4. Select the "Terminal" tab at the bottom
+5. Enter `cd ~/RIOT/examples/default` to enter the `default` folder also in the terminal
+6. Run `make BOARD=esp32-mh-et-live-minikit compile-commands`
+    - You can replace `esp32-mh-et-live-minikit` with the name of any other supported board
+
+:::note
+    Did you notice that IntelliSense did not find headers in `main.c` when you
+    opened it? This should be fixed after the command in 6 has completed.
+:::
+
+![Flashing from VS Code](img/08-Flash_Real_Hardware-04.png)
+
+1. Now run `make BOARD=esp32-mh-et-live-minikit BUILD_IN_DOCKER=1 flash term`
+
+:::note
+    Tired of typing `BOARD=<NAME_OF_THE_BOARD>` and `BUILD_IN_DOCKER=1`? You can
+    add those to the `Makefile` of your app or run
+    `export BOARD=BUILD_IN_DOCKER=1` in the shell. The `export` will not persist
+    needs to be repeated for every new terminal window.
+:::
+
+:::tip
+Running `BOARD=<INSERT_TARGET_BOARD_HERE> make info-programmers-supported` in your
+         application folder lists the programmers supported by RIOT for the given board.
+:::
+
+
+![Pulling docker image](img/08-Flash_Real_Hardware-05.png)
+
+When compiling with `BUILD_IN_DOCKER=1`, the toolchains distributed in the
+[`riot/riotbuild`](https://hub.docker.com/r/riot/riotbuild/) docker image will
+be used for compilation. This image contains toolchains for all supported RIOT
+board and is extensively tested in our CI.
+
+The first time you build with `BUILD_IN_DOCKER=1`, the image is pulled
+automatically.
+
+![Still pulling docker image](img/08-Flash_Real_Hardware-06.png)
+
+This may take a while ...
+
+![Building the firmware](img/08-Flash_Real_Hardware-07.png)
+
+... until eventually the docker image is pulled and the build will start.
+Subsequent builds will no longer need to download the toolchain and be a lot
+quicker.
+
+![Interacting with the firmware](img/08-Flash_Real_Hardware-08.png)
+
+After building and flashing the firmware has succeeded, a shell will open.
+
+1. Wait for the boot message to appear.
+    - The board may boot faster than your PC is able to connect to the serial.
+      If you see nothing after "Welcome to pyterm!" for 5 seconds, try hitting
+      the reset button on the board to boot it again.
+2. You are now connected to the RIOT shell running on the board. Try running
+   the `help` command to get a list of commands supported by the board.
+3. You can drop out of the RIOT serial by pressing `Ctrl` + `C` and return
+   to the Linux shell.
+
+:::tip[Flashing under Windows]
+It is also possible to install a native Windows flash application and invoke that from within WSL.
+However, the setup is too board specific to be covered here. Please refer to the documentation of the board you are using.
+:::
+
+:::caution[Known Issues under Windows]
+    The Linux Kernel in WSL currently has
+    [`CONFIG_USB_HIDDEV` disabled][wsl-hid-issue]. Hence, programmers using HID
+    as transport do not work for now and fail to flash. The (non-conclusive) list of affected
+    programmers is:
+
+    - Atmel/Microchip eDBG
+    - Atmel/Microchip ICE
+    - Any ARM CMSIS DAP compatible programmers
+
+    The (non-conclusive) list of programmers that work with WSL out of the box is:
+
+    - ST-Link (any version), including [cheap clones](https://www.aliexpress.com/wholesale?SearchText=ST-Link+V2)
+    - Segger J-Link, including the [J-Link EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)
+    - Any serial based bootloader (e.g. ESP boards, Arduino Bootloaders, ...)
+    - [Black Magic Probe](https://black-magic.org)
+    - [Jeff Probe](https://flirc.com/more/flirc-jeff-probe-bmp-jtag-black-magic-probe)
+    - Any other non HID USB programmer
+
+
+    [wsl-hid-issue]: https://github.com/microsoft/WSL/issues/10581
+:::

doc/guides/getting-started/install-wsl.mdx

@@ -0,0 +1,276 @@
+---
+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
+
+![Searching Ubuntu LTS in the Windows Store](img/00-Install_Ubuntu-00.png)
+
+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.
+
+![The Ubuntu LTS page in the Windows Store](img/00-Install_Ubuntu-01.png)
+
+1. Click on the button labeled "Get"
+
+
+![The Windows Store App is installing Ubuntu LTS](img/00-Install_Ubuntu-02.png)
+
+It will take a while for Ubuntu LTS to be installed.
+
+![The Windows Store App has completed installing Ubuntu LTS](img/00-Install_Ubuntu-03.png)
+
+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.
+:::
+
+![Error message because WSL is not enabled](img/00-Install_Ubuntu-04.png)
+
+## 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.
+:::
+
+![Opening the PowerShell as administrator](img/01-Install_WSL-00.png)
+
+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"
+
+![Prompt asking for confirmation to run PowerShell as admin](img/01-Install_WSL-01.png)
+
+1. Click "Yes" to confirm running the PowerShell as administrator
+
+![PowerShell terminal opened as administrator](img/01-Install_WSL-02.png)
+
+- Type `wsl --install` and confirm with the return-key.
+- After a while, the following message should appear:
+
+![PowerShell after WSL has been enabled](img/01-Install_WSL-03.png)
+
+- Now reboot Windows to complete the installation
+
+![Windows installing WSL during reboot](img/01-Install_WSL-04.png)
+
+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:
+
+![An Ubuntu terminal when first started](img/02-Setup_Ubuntu-00.png)
+
+<details>
+<summary>
+    If no Ubuntu terminal has opened, click here to see how to open it
+</summary>
+
+![Open Ubuntu in the start menu](img/02-Setup_Ubuntu-01.png)
+
+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:
+
+![Ubuntu terminal after username and password are configured](img/02-Setup_Ubuntu-02.png)
+
+- 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:
+
+![Ubuntu terminal after running apt update](img/02-Setup_Ubuntu-03.png)
+
+:::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:
+
+![Ubuntu terminal after updating software](img/02-Setup_Ubuntu-05.png)
+
+
+:::note
+It is recommended to regularly update the installed software in Ubuntu
+using `sudo apt update` followed by `sudo apt upgrade`
+:::
+
+## Installing VS Code
+
+![Windows Store page of VS Code](img/04-Install_VS_Code-00.png)
+
+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"
+
+![Windows Store installing VS Code](img/04-Install_VS_Code-01.png)
+
+- Downloading and installing VS Code by the Store App may take some time
+- Eventually, it should show something like this:
+
+![Windows Store completed installing VS Code](img/04-Install_VS_Code-02.png)
+
+- Now, launch VS Code via the start menu
+- On the first launch, VS code will look similar to this:
+
+![First Launch page of VS Code](img/04-Install_VS_Code-03.png)
+
+- You can select a theme of you liking
+- You might want to dial back the data collection by Microsoft by clicking on "opt out"
+
+![Installation of the WSL extension for VS Code](img/04-Install_VS_Code-04.png)
+
+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`
+
+![Release Page of usbipd-win](img/07-Install_USBIPd-01.png)
+
+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
+
+![Download of usbipd-win completed](img/07-Install_USBIPd-02.png)
+
+Once the download is completed:
+
+1. Open the downloaded installer
+
+![Confirmation to open the installer](img/07-Install_USBIPd-03.png)
+
+1. Confirm that you indeed want to execute the installer by clicking "OK".
+
+![Setup of usbipd-win](img/07-Install_USBIPd-04.png)
+
+The setup of `usbipd-win` opens.
+
+1. Click on the "Install" button to proceed with the installation.
+
+![Confirmation of installation](img/07-Install_USBIPd-05.png)
+
+1. Confirm the installation by clicking on "Yes".
+
+![Completion of the usbipd-win setup](img/07-Install_USBIPd-06.png)
+
+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.
+:::
+
+![Running PowerShell as admin](img/08-Flash_Real_Hardware-00.png)
+
+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"
+
+![Confirmation to run PowerShell as admin](img/08-Flash_Real_Hardware-01.png)
+
+1. Click on "Yes" to confirm running the PowerShell as admin
+
+![PowerShell terminal](img/08-Flash_Real_Hardware-02.png)
+
+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.

doc/guides/getting-started/installing.mdx

@@ -0,0 +1,189 @@
+---
+title: Setup Development Environment
+description: Setting up a development environment for RIOT
+---
+
+import Contact from '@components/contact.astro';
+
+<Contact />
+
+### Choosing the Right Operating System
+
+#### Linux (Recommended)
+Most of the RIOT OS developers are using Linux on their development PCs, so you can expect the
+most streamlined experience here. Generally, most Linux distributions are supported.
+
+If you are new to Linux, we recommend using Ubuntu, as it is the most widely used distribution
+and has the most extensive documentation and community support.
+
+#### Windows
+Windows is supported through Windows Subsystem for Linux (WSL).
+The experience is not as streamlined as on Linux, but it is still possible to develop with RIOT.
+
+:::note
+Please follow the [installation guide for WSL](/getting-started/install-wsl) to set up your development environment.
+
+Afterwards, you can follow the Ubuntu installation guide. The installation of the required software packages is the same for both Ubuntu and WSL.
+:::
+
+#### macOS
+Native development on macOS machines is not officially supported.
+
+What works well is using Linux in a virtual machine, but at much lower performance than running Linux natively.
+
+We also offer Docker images that make it a bit easier to develop on macOS.
+
+## Installing the required software packages
+
+:::note
+It is also possible to run RIOT in a Docker container.
+
+This is especially useful if you want to avoid installing the required software packages on your host system. For more information, see the [Build in Docker](/docs/guides/build-in-docker) guide.
+:::
+
+Depending on the operation distribution you are using, the installation of the required software packages may vary.
+
+##### Ubuntu
+
+```bash title="Ubuntu command to install required packages"
+    sudo apt install make gcc-multilib python3-serial wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang
+```
+
+#### Arch Linux
+
+```bash title="Arch Linux command to install required packages"
+    sudo pacman -S make gcc-multilib python-pyserial wget unzip git openocd gdb esptool podman-docker clang
+```
+
+This will show something like this depending on your distribution:
+
+![Ubuntu terminal waiting for confirmation for installation](img/03-Install_Base_Packages-01.png)
+
+- Confirm the installation by hitting the return-key
+- The installation process will take some time
+- Eventually the output will look like below (except for the `exit`)
+
+![Ubuntu terminal after installation completed](img/03-Install_Base_Packages-02.png)
+
+## Cloning the RIOT Repository and First Steps in the Terminal
+
+:::note
+Even if you subsequently work only via VS Code, do **NOT** skip this step.
+You will still need a "clone" of the RIOT Repository to work with.
+:::
+
+![Cloning of the RIOT Repo in the Ubuntu terminal](img/05-First_Steps-00.png)
+
+- Open the terminal.
+- Type `git clone https://github.com/RIOT-OS/RIOT` and confirm with the return-key
+- This may take some time. Eventually, it will print `done.` when it completed
+- Type `cd RIOT/examples/hello-world` and confirm with the return-key to enter
+  the folder `hello-world` example app in the RIOT repo
+- Type `make` and confirm with the return key to build the app for the board
+  `native`
+
+:::tip
+If you are having issues with missing libraries you can always also
+use the docker container to build the app.
+In this example you can type `BUILD_IN_DOCKER=1 make` to build the app in the docker container.
+:::
+
+:::note
+The `native` board is a virtual board that will run an RIOT application as
+regular Linux process. This can be useful for testing or during development.
+The app should behave the same when run on real hardware.
+:::
+
+![The `hello-world` app running on the virtual `native` board](img/05-First_Steps-01.png)
+
+- Now run the application by executing `make term`
+- The output should look similar to the screenshot above
+- You can close the terminal by:
+    1. Press and hold the `Ctrl`-key
+    2. With the `Ctrl`-key still held, press the `C`-key
+    3. Release both keys
+
+## Using VS Code for Development
+
+![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-00.png)
+
+- If not already open, open the terminal
+- Confirm that the terminal is pointed to the folder `~/RIOT/examples/hello-world`
+    - The blue part left of the prompt (the `$` sign in the terminal) shows
+      the current working directory for the terminal
+    - If the blue string is not `~/RIOT/examples/hello-world`, type
+      `cd ~/RIOT/examples/hello-world` to enter that path
+- Inside `~/RIOT/examples/hello-world` run the command `make compile-commands`
+- The output should look like above
+
+![Launching VS Code from Ubuntu](img/06-Use_VS_Code-01.png)
+
+- Navigate back to `~/RIOT` using the command `cd ~/RIOT`
+- run `code .` to launch VS Code
+    - This will take a bit longer on the first launch
+- Eventually, a VS Code Window should pop up that looks like this:
+
+![VS Code as opened from WSL](img/06-Use_VS_Code-02.png)
+
+1. Click on "Yes, I trust the authors"
+
+- Now, use the tree view in the left and open the `examples` folder
+- Open the `hello-world` folder inside the `examples` folder
+- Open the `main.c` file in the `hello-world` folder within `examples`
+- The file should open and look like this:
+
+![VS Code asking to install C/C++ Extension](img/06-Use_VS_Code-03.png)
+
+1. Click on the "Install" button when prompted to install the C/C++ Extension.
+
+:::note
+You can also install that extension via the extension marketplace if that pop up does not show up.
+:::
+
+:::danger
+![VS Code asking to configure RIOT as CMake project](img/06-Use_VS_Code-04.png)
+
+Do **NOT** configure RIOT as CMake project. VS Code will incorrectly detect
+RIOT as CMake project, because it contains external packages that indeed are
+using CMake.
+
+1. Click on "Not now" to not configure RIOT as CMake project
+2. Click on "Never" to never ask again whether RIOT should be configured as
+   CMake project (not shown in screenshot)
+:::
+
+![IntelliSense showing that `RIOT_BOARD` is `"native"`](img/06-Use_VS_Code-05.png)
+
+- Confirm that when hovering over `RIOT_BOARD` in the source code, IntelliSense
+  shows that it expands to `"native"`.
+
+:::note
+IntelliSense depends on information how to compile the source code to work
+correctly, which is provided in the file `compile_commands.json`. You can
+regenerate this file by running `make compile-commands` in the app you are
+working on.
+:::
+
+:::caution
+Re-run `make compile-commands` when:
+1. You create, delete or rename source files
+2. You change the set of modules or packages used
+3. You have updated the RIOT repository
+4. You are switching the board to compile for
+:::
+
+![Compiling via the Terminal in VS Code](img/06-Use_VS_Code-06.png)
+
+- Extend the message to be printed, e.g. by adding a `puts("...");` statement
+  in the source code
+- Save the modified source code (e.g. `Ctrl`+`S`)
+- Open the integrated terminal by clicking on the terminal tab at the bottom
+- Navigate to `~/RIOT/examples/hello-world` using `cd ~/RIOT/examples/hello-world`
+- Run the `make` command to build the code
+- Run make `make term` to launch the application
+- The result should look like:
+
+![Running the app in VS Code](img/06-Use_VS_Code-07.png)
+
+Congratulations! You just compiled your first RIOT application. To run RIOT
+on real hardware, proceed with the next to sections.

doc/guides/misc/how_to_doc.md

@@ -90,6 +90,16 @@ Now you can add content to the guide using Markdown. Starlight supports all the
 
 You can see a full list of the supported features in the [Starlight documentation](https://starlight.astro.build/guides/authoring-content/).
 
+### MDX
+
+MDX is a superset of Markdown that allows you to use JSX components within your Markdown file. This means that you can do things such as importing reusable components. One component that is/should be used frequently is the `Contact` component, which adds a small little note explaining some ways of getting help from the RIOT community. This component is imported like this:
+
+```markdown title="doc/guides/test/hello_world.mdx"
+import Contact from '@components/contact.astro';
+
+<Contact/>
+```
+
 :::danger[Keep it simple]
 Please always keep in mind that the more non-standard Markdown you write, the more it will worsen the readability of the guide in the repository itself.
 

doc/guides/setup-windows/README.md

@@ -1,501 +0,0 @@
----
-title: Getting Started with RIOT on Windows
-description: This guide will help you to set up RIOT on Windows using WSL
----
-
-# Getting Started on Windows
-
-> [!NOTE]
-> The documentation is quite verbose: The process is documented down to every
-> click. Because of this verbosity the setup may appear complex and long, but
-> in fact is rather straight forward. A novice user should be able to complete
-> all steps in less than 30 minutes.
-
-> [!NOTE]
-> Do not be afraid to ask for help e.g. in [our forum][riot-forum]
-
-[riot-forum]: https://forum.riot-os.org/
-
-## Install Ubuntu LTS
-
-![Searching Ubuntu LTS in the Windows Store](img/00-Install_Ubuntu-00.png)
-
-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.
-
-![The Ubuntu LTS page in the Windows Store](img/00-Install_Ubuntu-01.png)
-
-1. Click on the button labeled "Get"
-
-
-![The Windows Store App is installing Ubuntu LTS](img/00-Install_Ubuntu-02.png)
-
-It will take a while for Ubuntu LTS to be installed.
-
-![The Windows Store App has completed installing Ubuntu LTS](img/00-Install_Ubuntu-03.png)
-
-Eventually, the installation completes.
-
-1. Click on the button labeled "Open"
-
-> [!WARNING]
-> 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.
-
-![Error message because WSL is not enabled](img/00-Install_Ubuntu-04.png)
-
-## 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.
-
-![Opening the PowerShell as administrator](img/01-Install_WSL-00.png)
-
-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"
-
-![Prompt asking for confirmation to run PowerShell as admin](img/01-Install_WSL-01.png)
-
-1. Click "Yes" to confirm running the PowerShell as administrator
-
-![PowerShell terminal opened as administrator](img/01-Install_WSL-02.png)
-
-- Type `wsl --install` and confirm with the return-key.
-- After a while, the following message should appear:
-
-![PowerShell after WSL has been enabled](img/01-Install_WSL-03.png)
-
-- Now reboot Windows to complete the installation
-
-![Windows installing WSL during reboot](img/01-Install_WSL-04.png)
-
-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:
-
-![An Ubuntu terminal when first started](img/02-Setup_Ubuntu-00.png)
-
-<details><summary>If no Ubuntu terminal has opened, click here to see how to open it</summary>
-
-![Open Ubuntu in the start menu](img/02-Setup_Ubuntu-01.png)
-
-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
-
-> [!WARNING]
-> 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:
-
-![Ubuntu terminal after username and password are configured](img/02-Setup_Ubuntu-02.png)
-
-- 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
-
-> [!WARNING]
-> 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:
-
-![Ubuntu terminal after running apt update](img/02-Setup_Ubuntu-03.png)
-
-> [!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:
-
-![Ubuntu terminal after updating software](img/02-Setup_Ubuntu-05.png)
-
-
-> [!NOTE]
-> It is recommended to regularly update the installed software in Ubuntu
-> using `sudo apt update` followed by `sudo apt upgrade`
-
-## Installation of the required software packages in Ubuntu
-
-- Now, install the required software by typing the following and confirming it
-  with a return-key
-
-```
-sudo apt install make gcc-multilib python3-serial wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang
-```
-
-- This will show something like this:
-
-![Ubuntu terminal waiting for confirmation for installation](img/03-Install_Base_Packages-01.png)
-
-- Confirm the installation by hitting the return-key
-- The installation process will take some time
-- Eventually the output will look like below (except for the `exit`)
-
-![Ubuntu terminal after installation completed](img/03-Install_Base_Packages-02.png)
-
-- Type `exit` and confirm with the return-key to close the Ubuntu terminal
-- The window should close
-
-## Installing VS Code
-
-![Windows Store page of VS Code](img/04-Install_VS_Code-00.png)
-
-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"
-
-![Windows Store installing VS Code](img/04-Install_VS_Code-01.png)
-
-- Downloading and installing VS Code by the Store App may take some time
-- Eventually, it should show something like this:
-
-![Windows Store completed installing VS Code](img/04-Install_VS_Code-02.png)
-
-- Now, launch VS Code via the start menu
-- On the first launch, VS code will look similar to this:
-
-![First Launch page of VS Code](img/04-Install_VS_Code-03.png)
-
-- You can select a theme of you liking
-- You might want to dial back the data collection by Microsoft by clicking on "opt out"
-
-![Installation of the WSL extension for VS Code](img/04-Install_VS_Code-04.png)
-
-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.
-
-## Cloning the RIOT Repository and First Steps in the Terminal
-
-> [!NOTE]
-> Even if you subsequently work only via VS Code, do **NOT** skip this step.
-> You will still need a "clone" of the RIOT Repository to work with.
-
-![Cloning of the RIOT Repo in the Ubuntu terminal](img/05-First_Steps-00.png)
-
-- Open the Ubuntu terminal.
-- (It may show some output regarding the VS Code WSL extension being installed.
-  Just wait for this to complete.)
-- Type `git clone https://github.com/RIOT-OS/RIOT` and confirm with the return-key
-- This may take some time. Eventually, it will print `done.` when it completed
-- Type `cd RIOT/examples/basic/hello-world` and confirm with the return-key to enter
-  the folder `hello-world` example app in the RIOT repo
-- Type `make` and confirm with the return key to build the app for the board
-  `native`
-
-> [!NOTE]
-> The `native` board is a virtual board that will run an RIOT application as
-> regular Linux process. This can be useful for testing or during development.
-> The app should behave the same when run on real hardware.
-
-![The `hello-world` app running on the virtual `native` board](img/05-First_Steps-01.png)
-
-- Now run the application by executing `make term`
-- The output should look similar to the screenshot above
-- You can close the terminal by:
-    1. Press and hold the `Ctrl`-key
-    2. With the `Ctrl`-key still held, press the `C`-key
-    3. Release both keys
-
-## Using VS Code for Development
-
-![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-00.png)
-
-- If not already open, open the Ubuntu terminal
-- Confirm that the terminal is pointed to the folder `~/RIOT/examples/basic/hello-world`
-    - The blue part left of the prompt (the `$` sign in the terminal) shows
-      the current working directory for the terminal
-    - If the blue string is not `~/RIOT/examples/basic/hello-world`, type
-      `cd ~/RIOT/examples/basic/hello-world` to enter that path
-- Inside `~/RIOT/examples/basic/hello-world` run the command `make compile-commands`
-- The output should look like above
-
-![Launching VS Code from Ubuntu](img/06-Use_VS_Code-01.png)
-
-- Navigate back to `~/RIOT` using the command `cd ~/RIOT`
-- run `code .` to launch VS Code
-    - This will take a bit longer on the first launch
-- Eventually, a VS Code Window should pop up that looks like this:
-
-![VS Code as opened from WSL](img/06-Use_VS_Code-02.png)
-
-1. Click on "Yes, I trust the authors"
-
-- Now, use the tree view in the left and open the `examples` folder
-- Open the `hello-world` folder inside the `examples` folder
-- Open the `main.c` file in the `hello-world` folder within `examples`
-- The file should open and look like this:
-
-![VS Code asking to install C/C++ Extension](img/06-Use_VS_Code-03.png)
-
-1. Click on the "Install" button when prompted to install the C/C++ Extension.
-
-> [!NOTE]
-> You can also install that extension via the extension marketplace just like
-> the WSL extension was installed, if that pop up does not show up.
-
-![VS Code asking to configure RIOT as CMake project](img/06-Use_VS_Code-04.png)
-
-> [!WARNING]
-> Do **NOT** configure RIOT as CMake project. VS Code will incorrectly detect
-> RIOT as CMake project, because it contains external packages that indeed are
-> using CMake.
-
-1. Click on "Not now" to not configure RIOT as CMake project
-2. Click on "Never" to never ask again whether RIOT should be configured as
-   CMake project (not shown in screenshot)
-
-![IntelliSense showing that `RIOT_BOARD` is `"native"`](img/06-Use_VS_Code-05.png)
-
-- Confirm that when hovering over `RIOT_BOARD` in the source code, IntelliSense
-  shows that it expands to `"native"`.
-
-> [!NOTE]
-> IntelliSense depends on information how to compile the source code to work
-> correctly, which is provided in the file `compile_commands.json`. You can
-> regenerate this file by running `make compile-commands` in the app you are
-> working on.
-
-> [!WARNING]
-> Re-run `make compile-commands` when:
-> 1. You create, delete or rename source files
-> 2. You change the set of modules or packages used
-> 3. You have updated the RIOT repository
-> 4. You are switching the board to compile for
-
-
-![Compiling via the Terminal in VS Code](img/06-Use_VS_Code-06.png)
-
-- Extend the message to be printed, e.g. by adding a `puts("...");` statement
-  in the source code
-- Save the modified source code (e.g. `Ctrl`+`S`)
-- Open the integrated terminal by clicking on the terminal tab at the bottom
-- Navigate to `~/RIOT/examples/basic/hello-world` using `cd ~/RIOT/examples/basic/hello-world`
-- Run the `make` command to build the code
-- Run make `make term` to launch the application
-- The result should look like:
-
-![Running the app in VS Code](img/06-Use_VS_Code-07.png)
-
-Congratulations! You just compiled your first RIOT application. To run RIOT
-on real hardware, proceed with the next to sections.
-
-## Installing `usbipd-win`
-
-![Release Page of usbipd-win](img/07-Install_USBIPd-01.png)
-
-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
-
-![Download of usbipd-win completed](img/07-Install_USBIPd-02.png)
-
-Once the download is completed:
-
-1. Open the downloaded installer
-
-![Confirmation to open the installer](img/07-Install_USBIPd-03.png)
-
-1. Confirm that you indeed want to execute the installer by clicking "OK".
-
-![Setup of usbipd-win](img/07-Install_USBIPd-04.png)
-
-The setup of `usbipd-win` opens.
-
-1. Click on the "Install" button to proceed with the installation.
-
-![Confirmation of installation](img/07-Install_USBIPd-05.png)
-
-1. Confirm the installation by clicking on "Yes".
-
-![Completion of the usbipd-win setup](img/07-Install_USBIPd-06.png)
-
-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.
-
-![Running PowerShell as admin](img/08-Flash_Real_Hardware-00.png)
-
-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"
-
-![Confirmation to run PowerShell as admin](img/08-Flash_Real_Hardware-01.png)
-
-1. Click on "Yes" to confirm running the PowerShell as admin
-
-![PowerShell terminal](img/08-Flash_Real_Hardware-02.png)
-
-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.
-
-## Flash an ESP32 Development Board
-
-After all of the previous sections are completed, we can finally flash some
-real hardware. In this case, we use an `esp32-mh-et-live-minikit` development
-board. The guide should mostly apply to all other boards as well.
-
-> [!NOTE]
-> Some boards require extra steps to be flashed, such as pressing a button
-> to enter a bootloader or attaching an external programmer. Refer to the
-> documentation of the board to check if extra steps are required.
-
-This assumes that the USB UART bridge of the ESP32 development board has
-been attached to WSL and VS Code has been launched from within WSL by running
-`code .` inside the RIOT repository from the Ubuntu terminal.
-
-![VS Code in WSL](img/08-Flash_Real_Hardware-03.png)
-
-1. Open the `examples` folder
-2. Open the `default` folder within `examples`
-3. Open the `main.c` file in the `default` folder
-4. Select the "Terminal" tab at the bottom
-5. Enter `cd ~/RIOT/examples/basic/default` to enter the `default` folder also in the terminal
-6. Run `make BOARD=esp32-mh-et-live-minikit compile-commands`
-    - You can replace `esp32-mh-et-live-minikit` with the name of any other supported board
-
-> [!NOTE]
-> Did you notice that IntelliSense did not find headers in `main.c` when you
-> opened it? This should be fixed after the command in 6 has completed.
-
-![Flashing from VS Code](img/08-Flash_Real_Hardware-04.png)
-
-1. Now run `make BOARD=esp32-mh-et-live-minikit BUILD_IN_DOCKER=1 flash term`
-
-> [!NOTE]
-> Tired of typing `BOARD=<NAME_OF_THE_BOARD>` and `BUILD_IN_DOCKER=1`? You can
-> add those to the `Makefile` of your app or run
-> `export BOARD=BUILD_IN_DOCKER=1` in the shell. The `export` will not persist
-> needs to be repeated for every new terminal window.
-
-![Pulling docker image](img/08-Flash_Real_Hardware-05.png)
-
-When compiling with `BUILD_IN_DOCKER=1`, the toolchains distributed in the
-[`riot/riotbuild`](https://hub.docker.com/r/riot/riotbuild/) docker image will
-be used for compilation. This image contains toolchains for all supported RIOT
-board and is extensively tested in our CI.
-
-The first time you build with `BUILD_IN_DOCKER=1`, the image is pulled
-automatically.
-
-![Still pulling docker image](img/08-Flash_Real_Hardware-06.png)
-
-This may take a while ...
-
-![Building the firmware](img/08-Flash_Real_Hardware-07.png)
-
-... until eventually the docker image is pulled and the build will start.
-Subsequent builds will no longer need to download the toolchain and be a lot
-quicker.
-
-![Interacting with the firmware](img/08-Flash_Real_Hardware-08.png)
-
-After building and flashing the firmware has succeeded, a shell will open.
-
-1. Wait for the boot message to appear.
-    - The board may boot faster than your PC is able to connect to the serial.
-      If you see nothing after "Welcome to pyterm!" for 5 seconds, try hitting
-      the reset button on the board to boot it again.
-2. You are now connected to the RIOT shell running on the board. Try running
-   the `help` command to get a list of commands supported by the board.
-3. You can drop out of the RIOT serial by pressing `Ctrl` + `C` and return
-   to the Linux shell.
-
-## Known Issues
-
-### Flashing Fails with Programmers using HID
-
-The Linux Kernel in WSL currently has
-[`CONFIG_USB_HIDDEV` disabled][wsl-hid-issue]. Hence, programmers using HID
-as transport do not work for now. The (non-conclusive) list of affected
-programmers is:
-
-- Atmel/Microchip eDBG
-- Atmel/Microchip ICE
-- Any ARM CMSIS DAP compatible programmers
-
-> [!NOTE]
-> It is possible to install a native Windows flash application and invoke that
-> from within WSL.
-
-The (non-conclusive) list of programmers that work with WSL out of the box is:
-
-- ST-Link (any version), including [cheap clones](https://www.aliexpress.com/wholesale?SearchText=ST-Link+V2)
-- Segger J-Link, including the [J-Link EDU Mini](https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/)
-- Any serial based bootloader (e.g. ESP boards, Arduino Bootloaders, ...)
-- [Black Magic Probe](https://black-magic.org)
-- [Jeff Probe](https://flirc.com/more/flirc-jeff-probe-bmp-jtag-black-magic-probe)
-- Any other non HID USB programmer
-
-
-[wsl-hid-issue]: https://github.com/microsoft/WSL/issues/10581

doc/starlight/astro.config.mjs

@@ -48,6 +48,21 @@ export default defineConfig({
             "general/structure",
           ],
         },
+        {
+          label: "Tutorials",
+          items: [
+            {
+              label: "Getting Started",
+              items: [
+                "getting-started/install-wsl",
+                "getting-started/installing",
+                "getting-started/flashing",
+                "getting-started/building_example",
+                "getting-started/finding_modules",
+              ],
+            },
+          ],
+        },
         {
           label: "Build System",
           items: [

doc/starlight/src/components/gitsetup.mdx

@@ -38,3 +38,17 @@ git submodule add https://github.com/RIOT-OS/RIOT.git
 ![Adding the submodule](img/gitsetup/02_riot_submodule.png)
 
 When looking into our directory via `ls`, we can see that a new directory called `RIOT` has been created. This directory contains the RIOT source code. If you were to push your project to a git hosting service, the `RIOT` directory would not be included in the repository. Instead, the repository would contain a reference to the commit of the RIOT repository that you have added as a submodule. This way, the repository stays small and only contains the code that you have written and not the entire RIOT source code.
+
+:::note
+Remember that you need to clone your own repository with the `--recursive` option to get the submodule as well.
+
+```bash
+git clone --recursive https://git.example.com/your/repo.git
+```
+
+Alternatively if you have already cloned your own repository, you can run the following command to initialize and update the submodule:
+
+```bash
+git submodule update --init --recursive
+```
+:::