diff --git a/doc/guides/getting-started/building_example.mdx b/doc/guides/getting-started/building_example.mdx new file mode 100644 index 000000000000..eecdcead43cc --- /dev/null +++ b/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'; + + + +:::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 []] +``` + +A detailed example can be found in `examples/gnrc_networking`. +::: diff --git a/doc/guides/getting-started/finding_modules.mdx b/doc/guides/getting-started/finding_modules.mdx new file mode 100644 index 000000000000..3c346b0eef04 --- /dev/null +++ b/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 + + + +## 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. diff --git a/doc/guides/getting-started/flashing.mdx b/doc/guides/getting-started/flashing.mdx new file mode 100644 index 000000000000..095e6c321e2a --- /dev/null +++ b/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'; + + + +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=` 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= 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 +::: diff --git a/doc/guides/setup-windows/img/00-Install_Ubuntu-00.png b/doc/guides/getting-started/img/00-Install_Ubuntu-00.png similarity index 100% rename from doc/guides/setup-windows/img/00-Install_Ubuntu-00.png rename to doc/guides/getting-started/img/00-Install_Ubuntu-00.png diff --git a/doc/guides/setup-windows/img/00-Install_Ubuntu-01.png b/doc/guides/getting-started/img/00-Install_Ubuntu-01.png similarity index 100% rename from doc/guides/setup-windows/img/00-Install_Ubuntu-01.png rename to doc/guides/getting-started/img/00-Install_Ubuntu-01.png diff --git a/doc/guides/setup-windows/img/00-Install_Ubuntu-02.png b/doc/guides/getting-started/img/00-Install_Ubuntu-02.png similarity index 100% rename from doc/guides/setup-windows/img/00-Install_Ubuntu-02.png rename to doc/guides/getting-started/img/00-Install_Ubuntu-02.png diff --git a/doc/guides/setup-windows/img/00-Install_Ubuntu-03.png b/doc/guides/getting-started/img/00-Install_Ubuntu-03.png similarity index 100% rename from doc/guides/setup-windows/img/00-Install_Ubuntu-03.png rename to doc/guides/getting-started/img/00-Install_Ubuntu-03.png diff --git a/doc/guides/setup-windows/img/00-Install_Ubuntu-04.png b/doc/guides/getting-started/img/00-Install_Ubuntu-04.png similarity index 100% rename from doc/guides/setup-windows/img/00-Install_Ubuntu-04.png rename to doc/guides/getting-started/img/00-Install_Ubuntu-04.png diff --git a/doc/guides/setup-windows/img/01-Install_WSL-00.png b/doc/guides/getting-started/img/01-Install_WSL-00.png similarity index 100% rename from doc/guides/setup-windows/img/01-Install_WSL-00.png rename to doc/guides/getting-started/img/01-Install_WSL-00.png diff --git a/doc/guides/setup-windows/img/01-Install_WSL-01.png b/doc/guides/getting-started/img/01-Install_WSL-01.png similarity index 100% rename from doc/guides/setup-windows/img/01-Install_WSL-01.png rename to doc/guides/getting-started/img/01-Install_WSL-01.png diff --git a/doc/guides/setup-windows/img/01-Install_WSL-02.png b/doc/guides/getting-started/img/01-Install_WSL-02.png similarity index 100% rename from doc/guides/setup-windows/img/01-Install_WSL-02.png rename to doc/guides/getting-started/img/01-Install_WSL-02.png diff --git a/doc/guides/setup-windows/img/01-Install_WSL-03.png b/doc/guides/getting-started/img/01-Install_WSL-03.png similarity index 100% rename from doc/guides/setup-windows/img/01-Install_WSL-03.png rename to doc/guides/getting-started/img/01-Install_WSL-03.png diff --git a/doc/guides/setup-windows/img/01-Install_WSL-04.png b/doc/guides/getting-started/img/01-Install_WSL-04.png similarity index 100% rename from doc/guides/setup-windows/img/01-Install_WSL-04.png rename to doc/guides/getting-started/img/01-Install_WSL-04.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-00.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-00.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-00.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-00.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-01.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-01.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-01.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-01.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-02.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-02.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-02.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-02.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-03.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-03.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-03.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-03.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-04.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-04.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-04.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-04.png diff --git a/doc/guides/setup-windows/img/02-Setup_Ubuntu-05.png b/doc/guides/getting-started/img/02-Setup_Ubuntu-05.png similarity index 100% rename from doc/guides/setup-windows/img/02-Setup_Ubuntu-05.png rename to doc/guides/getting-started/img/02-Setup_Ubuntu-05.png diff --git a/doc/guides/setup-windows/img/03-Install_Base_Packages-00.png b/doc/guides/getting-started/img/03-Install_Base_Packages-00.png similarity index 100% rename from doc/guides/setup-windows/img/03-Install_Base_Packages-00.png rename to doc/guides/getting-started/img/03-Install_Base_Packages-00.png diff --git a/doc/guides/setup-windows/img/03-Install_Base_Packages-01.png b/doc/guides/getting-started/img/03-Install_Base_Packages-01.png similarity index 100% rename from doc/guides/setup-windows/img/03-Install_Base_Packages-01.png rename to doc/guides/getting-started/img/03-Install_Base_Packages-01.png diff --git a/doc/guides/setup-windows/img/03-Install_Base_Packages-02.png b/doc/guides/getting-started/img/03-Install_Base_Packages-02.png similarity index 100% rename from doc/guides/setup-windows/img/03-Install_Base_Packages-02.png rename to doc/guides/getting-started/img/03-Install_Base_Packages-02.png diff --git a/doc/guides/setup-windows/img/04-Install_VS_Code-00.png b/doc/guides/getting-started/img/04-Install_VS_Code-00.png similarity index 100% rename from doc/guides/setup-windows/img/04-Install_VS_Code-00.png rename to doc/guides/getting-started/img/04-Install_VS_Code-00.png diff --git a/doc/guides/setup-windows/img/04-Install_VS_Code-01.png b/doc/guides/getting-started/img/04-Install_VS_Code-01.png similarity index 100% rename from doc/guides/setup-windows/img/04-Install_VS_Code-01.png rename to doc/guides/getting-started/img/04-Install_VS_Code-01.png diff --git a/doc/guides/setup-windows/img/04-Install_VS_Code-02.png b/doc/guides/getting-started/img/04-Install_VS_Code-02.png similarity index 100% rename from doc/guides/setup-windows/img/04-Install_VS_Code-02.png rename to doc/guides/getting-started/img/04-Install_VS_Code-02.png diff --git a/doc/guides/setup-windows/img/04-Install_VS_Code-03.png b/doc/guides/getting-started/img/04-Install_VS_Code-03.png similarity index 100% rename from doc/guides/setup-windows/img/04-Install_VS_Code-03.png rename to doc/guides/getting-started/img/04-Install_VS_Code-03.png diff --git a/doc/guides/setup-windows/img/04-Install_VS_Code-04.png b/doc/guides/getting-started/img/04-Install_VS_Code-04.png similarity index 100% rename from doc/guides/setup-windows/img/04-Install_VS_Code-04.png rename to doc/guides/getting-started/img/04-Install_VS_Code-04.png diff --git a/doc/guides/setup-windows/img/05-First_Steps-00.png b/doc/guides/getting-started/img/05-First_Steps-00.png similarity index 100% rename from doc/guides/setup-windows/img/05-First_Steps-00.png rename to doc/guides/getting-started/img/05-First_Steps-00.png diff --git a/doc/guides/setup-windows/img/05-First_Steps-01.png b/doc/guides/getting-started/img/05-First_Steps-01.png similarity index 100% rename from doc/guides/setup-windows/img/05-First_Steps-01.png rename to doc/guides/getting-started/img/05-First_Steps-01.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-00.png b/doc/guides/getting-started/img/06-Use_VS_Code-00.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-00.png rename to doc/guides/getting-started/img/06-Use_VS_Code-00.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-01.png b/doc/guides/getting-started/img/06-Use_VS_Code-01.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-01.png rename to doc/guides/getting-started/img/06-Use_VS_Code-01.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-02.png b/doc/guides/getting-started/img/06-Use_VS_Code-02.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-02.png rename to doc/guides/getting-started/img/06-Use_VS_Code-02.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-03.png b/doc/guides/getting-started/img/06-Use_VS_Code-03.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-03.png rename to doc/guides/getting-started/img/06-Use_VS_Code-03.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-04.png b/doc/guides/getting-started/img/06-Use_VS_Code-04.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-04.png rename to doc/guides/getting-started/img/06-Use_VS_Code-04.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-05.png b/doc/guides/getting-started/img/06-Use_VS_Code-05.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-05.png rename to doc/guides/getting-started/img/06-Use_VS_Code-05.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-06.png b/doc/guides/getting-started/img/06-Use_VS_Code-06.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-06.png rename to doc/guides/getting-started/img/06-Use_VS_Code-06.png diff --git a/doc/guides/setup-windows/img/06-Use_VS_Code-07.png b/doc/guides/getting-started/img/06-Use_VS_Code-07.png similarity index 100% rename from doc/guides/setup-windows/img/06-Use_VS_Code-07.png rename to doc/guides/getting-started/img/06-Use_VS_Code-07.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-00.png b/doc/guides/getting-started/img/07-Install_USBIPd-00.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-00.png rename to doc/guides/getting-started/img/07-Install_USBIPd-00.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-01.png b/doc/guides/getting-started/img/07-Install_USBIPd-01.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-01.png rename to doc/guides/getting-started/img/07-Install_USBIPd-01.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-02.png b/doc/guides/getting-started/img/07-Install_USBIPd-02.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-02.png rename to doc/guides/getting-started/img/07-Install_USBIPd-02.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-03.png b/doc/guides/getting-started/img/07-Install_USBIPd-03.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-03.png rename to doc/guides/getting-started/img/07-Install_USBIPd-03.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-04.png b/doc/guides/getting-started/img/07-Install_USBIPd-04.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-04.png rename to doc/guides/getting-started/img/07-Install_USBIPd-04.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-05.png b/doc/guides/getting-started/img/07-Install_USBIPd-05.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-05.png rename to doc/guides/getting-started/img/07-Install_USBIPd-05.png diff --git a/doc/guides/setup-windows/img/07-Install_USBIPd-06.png b/doc/guides/getting-started/img/07-Install_USBIPd-06.png similarity index 100% rename from doc/guides/setup-windows/img/07-Install_USBIPd-06.png rename to doc/guides/getting-started/img/07-Install_USBIPd-06.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-00.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-00.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-00.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-00.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-01.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-01.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-01.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-01.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-02.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-02.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-02.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-02.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-03.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-03.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-03.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-03.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-04.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-04.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-04.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-04.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-05.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-05.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-05.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-05.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-06.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-06.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-06.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-06.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-07.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-07.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-07.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-07.png diff --git a/doc/guides/setup-windows/img/08-Flash_Real_Hardware-08.png b/doc/guides/getting-started/img/08-Flash_Real_Hardware-08.png similarity index 100% rename from doc/guides/setup-windows/img/08-Flash_Real_Hardware-08.png rename to doc/guides/getting-started/img/08-Flash_Real_Hardware-08.png diff --git a/doc/guides/getting-started/img/finding_modules/01_api_doc.png b/doc/guides/getting-started/img/finding_modules/01_api_doc.png new file mode 100644 index 000000000000..7cf2a57bc9c9 Binary files /dev/null and b/doc/guides/getting-started/img/finding_modules/01_api_doc.png differ diff --git a/doc/guides/getting-started/img/finding_modules/02_examples.png b/doc/guides/getting-started/img/finding_modules/02_examples.png new file mode 100644 index 000000000000..ebd866ba2322 Binary files /dev/null and b/doc/guides/getting-started/img/finding_modules/02_examples.png differ diff --git a/doc/guides/getting-started/img/finding_modules/03_source.png b/doc/guides/getting-started/img/finding_modules/03_source.png new file mode 100644 index 000000000000..02a6884b8d67 Binary files /dev/null and b/doc/guides/getting-started/img/finding_modules/03_source.png differ diff --git a/doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-00.svg b/doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-00.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-00.svg rename to doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-00.svg diff --git a/doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-01.svg b/doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-01.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-01.svg rename to doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-01.svg diff --git a/doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-03.svg b/doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-03.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/00-Install_Ubuntu-03.svg rename to doc/guides/getting-started/img/inkscape/00-Install_Ubuntu-03.svg diff --git a/doc/guides/setup-windows/img/inkscape/01-Install_WSL-00.svg b/doc/guides/getting-started/img/inkscape/01-Install_WSL-00.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/01-Install_WSL-00.svg rename to doc/guides/getting-started/img/inkscape/01-Install_WSL-00.svg diff --git a/doc/guides/setup-windows/img/inkscape/01-Install_WSL-01.svg b/doc/guides/getting-started/img/inkscape/01-Install_WSL-01.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/01-Install_WSL-01.svg rename to doc/guides/getting-started/img/inkscape/01-Install_WSL-01.svg diff --git a/doc/guides/setup-windows/img/inkscape/02-Setup_Ubuntu-01.svg b/doc/guides/getting-started/img/inkscape/02-Setup_Ubuntu-01.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/02-Setup_Ubuntu-01.svg rename to doc/guides/getting-started/img/inkscape/02-Setup_Ubuntu-01.svg diff --git a/doc/guides/setup-windows/img/inkscape/04-Install_VS_Code-00.svg b/doc/guides/getting-started/img/inkscape/04-Install_VS_Code-00.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/04-Install_VS_Code-00.svg rename to doc/guides/getting-started/img/inkscape/04-Install_VS_Code-00.svg diff --git a/doc/guides/setup-windows/img/inkscape/04-Install_VS_Code-05.svg b/doc/guides/getting-started/img/inkscape/04-Install_VS_Code-05.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/04-Install_VS_Code-05.svg rename to doc/guides/getting-started/img/inkscape/04-Install_VS_Code-05.svg diff --git a/doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-02.svg b/doc/guides/getting-started/img/inkscape/06-Use_VS_Code-02.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-02.svg rename to doc/guides/getting-started/img/inkscape/06-Use_VS_Code-02.svg diff --git a/doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-03.svg b/doc/guides/getting-started/img/inkscape/06-Use_VS_Code-03.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-03.svg rename to doc/guides/getting-started/img/inkscape/06-Use_VS_Code-03.svg diff --git a/doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-04.svg b/doc/guides/getting-started/img/inkscape/06-Use_VS_Code-04.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/06-Use_VS_Code-04.svg rename to doc/guides/getting-started/img/inkscape/06-Use_VS_Code-04.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-00.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-00.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-00.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-00.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-01.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-01.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-01.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-01.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-02.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-02.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-02.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-02.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-03.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-03.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-03.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-03.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-04.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-04.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-04.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-04.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-05.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-05.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-05.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-05.svg diff --git a/doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-06.svg b/doc/guides/getting-started/img/inkscape/07-Install_USBIPd-06.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/07-Install_USBIPd-06.svg rename to doc/guides/getting-started/img/inkscape/07-Install_USBIPd-06.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-00.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-00.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-00.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-00.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-01.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-01.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-01.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-01.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-02.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-02.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-02.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-02.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-03.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-03.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-03.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-03.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-04.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-04.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-04.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-04.svg diff --git a/doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-08.svg b/doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-08.svg similarity index 100% rename from doc/guides/setup-windows/img/inkscape/08-Flash_Real_Hardware-08.svg rename to doc/guides/getting-started/img/inkscape/08-Flash_Real_Hardware-08.svg diff --git a/doc/guides/getting-started/install-wsl.mdx b/doc/guides/getting-started/install-wsl.mdx new file mode 100644 index 000000000000..b2eb85550ef6 --- /dev/null +++ b/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) + +
+ + If no Ubuntu terminal has opened, click here to see how to open it + + +![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 + +
+ +- 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 `, but replace `` with the correct + BUSID. E.g. `2-5` for the CP2104 identified in step 2. +4. Run `usbipd attach --wsl --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. diff --git a/doc/guides/getting-started/installing.mdx b/doc/guides/getting-started/installing.mdx new file mode 100644 index 000000000000..10d98dce0878 --- /dev/null +++ b/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'; + + + +### 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. diff --git a/doc/guides/misc/how_to_doc.md b/doc/guides/misc/how_to_doc.md index db6e3afdc41a..4ca4fa260695 100644 --- a/doc/guides/misc/how_to_doc.md +++ b/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'; + + +``` + :::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. diff --git a/doc/guides/setup-windows/README.md b/doc/guides/setup-windows/README.md deleted file mode 100644 index e395df417fe4..000000000000 --- a/doc/guides/setup-windows/README.md +++ /dev/null @@ -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) - -
If no Ubuntu terminal has opened, click here to see how to open it - -![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 - -
- -- 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 `, but replace `` with the correct - BUSID. E.g. `2-5` for the CP2104 identified in step 2. -4. Run `usbipd attach --wsl --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=` 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 diff --git a/doc/starlight/astro.config.mjs b/doc/starlight/astro.config.mjs index f5eb11287aad..ffb80294e4a6 100644 --- a/doc/starlight/astro.config.mjs +++ b/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: [ diff --git a/doc/starlight/src/components/contact.astro b/doc/starlight/src/components/contact.astro new file mode 100644 index 000000000000..a4371716480f --- /dev/null +++ b/doc/starlight/src/components/contact.astro @@ -0,0 +1,15 @@ +--- +import { Aside } from "@astrojs/starlight/components"; +--- + + diff --git a/doc/starlight/src/components/gitsetup.mdx b/doc/starlight/src/components/gitsetup.mdx new file mode 100644 index 000000000000..f1d94fa462e7 --- /dev/null +++ b/doc/starlight/src/components/gitsetup.mdx @@ -0,0 +1,54 @@ +:::note +This tutorial assumes that you have already set up your development environment +as described in the [Getting Started](/getting-started/installing/) guide. +::: + +Now that we have played around with the examples and have a basic understanding of how to use RIOT, let's create a new project from scratch. We will create a simple hello world program that will print "Hello World!" to the console. + +#### Step 1: Create a new git repository + +We start by creating a new git repository for our project. If you have never worked with git before, you can find a good introduction [here](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) or [here](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git). + +Let's create a new directory for our project in which we will store our code. We will call this directory `hello_world`. + +```bash +mkdir hello_world && cd hello_world +``` + +Next, we initialize a new git repository in this directory. This will allow us to track changes to our code and collaborate with others and also allows us to easily get RIOT as a submodule. + +```bash +git init +``` + +![The output of the git init command](img/gitsetup/01_empty_git.png) + +Congratulations! You have now created a new empty git repository. In the next step, we will add RIOT as a submodule to our project. + +#### Step 2: Add RIOT as a submodule + +We want to import RIOT as a submodule to our project. This will allow us to easily update to newer versions of RIOT and also allows us to easily share our project with others on GitHub, Gitlab, or any other git hosting service. + +To add RIOT as a submodule, we use the following command: + +```bash +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 +``` +::: diff --git a/doc/starlight/src/components/img/gitsetup/01_empty_git.png b/doc/starlight/src/components/img/gitsetup/01_empty_git.png new file mode 100644 index 000000000000..4de56b785439 Binary files /dev/null and b/doc/starlight/src/components/img/gitsetup/01_empty_git.png differ diff --git a/doc/starlight/src/components/img/gitsetup/02_riot_submodule.png b/doc/starlight/src/components/img/gitsetup/02_riot_submodule.png new file mode 100644 index 000000000000..63798d7cc83a Binary files /dev/null and b/doc/starlight/src/components/img/gitsetup/02_riot_submodule.png differ diff --git a/doc/starlight/tsconfig.json b/doc/starlight/tsconfig.json index 8bf91d3bb997..e707d6c17807 100644 --- a/doc/starlight/tsconfig.json +++ b/doc/starlight/tsconfig.json @@ -1,5 +1,12 @@ { "extends": "astro/tsconfigs/strict", "include": [".astro/types.d.ts", "**/*"], - "exclude": ["dist"] + "exclude": ["dist"], + "compilerOptions": { + "baseUrl": ".", + "paths": { + "@components/*": ["src/components/*"], + }, + "types": ["astro/client", "astro/astro-jsx"] + } }