doc/guides: Add Getting Started 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
+:::