doc/guides: Riot Tutorial

examples/guides: Introduce tutorial references

doc/guides/tutorial: Introduce code_folder for all tutorials

Author: AnnsAnns

doc/guides/c_tutorials/create_project.mdx

@@ -0,0 +1,141 @@
+---
+title: Creating a Project
+description: This tutorial will guide you through creating a new project with a simple hello world program.
+code_folder: examples/guides/creating_project/
+---
+import Contact from '@components/contact.astro';
+import GitSetup from '@components/gitsetup.mdx';
+
+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.
+
+Lets start with the basic git setup, if you already have a git repository set up, you can skip to the next section.
+
+## Step 1: The Basics of Git and Submodules
+
+<GitSetup />
+
+## Step 2: Creating our hello world program
+
+Now that we have added RIOT as a submodule to our project, we can start writing our hello world program. To do this, we create a new file called `main.c` in the `hello_world` directory. You can use any text editor to create this file. We will use Visual Studio Code in this example. To open Visual Studio Code in the directory, you can use the following command:
+
+```bash
+code .
+```
+
+Now that Visual Studio Code is open, we create a new file called `main.c` and add the following code:
+
+```c title="hello_world/main.c"
+/*
+ * For many printing related things, such as the puts function here
+ * we import stdio, depending on your board, platform or form of output
+ * it then includes the right definitions without the need to
+ * worry about the specific details.
+ */
+#include <stdio.h>
+
+/*
+ * This is the main function of the program.
+ * It serves as the entry point for the program and gets called once your CPU is
+ * initialized.
+ *
+ * The function returns an integer value, which is the exit status
+ * of the program. A return value of 0 indicates that the program has finished
+ * successfully.
+ */
+int main(void) {
+  puts("Hello World!");
+
+  return 0;
+}
+```
+
+![The hello world program in Visual Studio Code](img/create_project/03_main_c.png)
+
+This program will print "Hello World!" to the console when it is run. The `#include <stdio.h>` line includes the standard input/output library, which allows us to use the `puts` function to print to the console.
+
+## Step 3: Creating the Makefile
+
+Now that we have created our hello world program, we need to create a Makefile to build our program. The Makefile is a build automation tool that allows us to define how our program should be built. We create a new file called `Makefile` in the `hello_world` directory and add the following code:
+
+```makefile  title="hello_world/Makefile"
+# name of your application
+APPLICATION = hello-world
+
+# Change this to your board if you want to build for a different board
+BOARD ?= native
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/RIOT
+
+# Comment this out to disable code in RIOT that does safety checking
+# which is not needed in a production environment but helps in the
+# development process:
+DEVELHELP ?= 1
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
+```
+
+![The Makefile in Visual Studio Code](img/create_project/04_makefile.png)
+
+Congratulations! You have now created a new project with a simple hello world program. In the next step, we will build and run our program just like we did in the "Getting Started" guide.
+
+## Step 4: Building and running the program
+
+<Contact />
+
+To build our program, we use the following command:
+
+```bash
+BUILD_IN_DOCKER=1 make all
+```
+
+:::note
+The `BUILD_IN_DOCKER=1` flag tells the build system to use the docker image provided by RIOT to build our program. This ensures that we have all the necessary dependencies to build our program. If you have already built RIOT on your system, you can omit this flag and the build system will use the toolchain installed on your system.
+:::
+
+![Building the program](img/create_project/05_make.png)
+
+After building the program, we can run it using the following command to start the RIOT shell:
+
+```bash
+make term
+```
+
+If everything went well, you should see our hello world program printing "Hello World!" to the console after a few seconds.
+
+![The hello world program running in the RIOT shell](img/create_project/06_output.png)
+
+Hooraay! You have successfully created a new project with a simple hello world program.
+
+:::tip
+Before you push your project to a git hosting service such as Github, make sure to add a `.gitignore` file to your project to exclude unnecessary files from being tracked by git.
+
+For this project, a `.gitignore` file could look like this:
+
+```bash title=".gitignore"
+# Ignore build artifacts
+bin/
+*.bin
+*.elf
+*.hex
+*.map
+*.lst
+*.o
+*.d
+*.a
+*.out
+```
+:::
+
+## Conclusion
+
+In this tutorial, we have created a new project with a simple hello world program. We have added RIOT as a submodule to our project, created a hello world program, and built and run the program using the RIOT build system. You can now start building your own applications using RIOT and explore the vast possibilities that RIOT has to offer.
+
+:::note
+The source code for this tutorial can be found [HERE](https://github.com/RIOT-OS/RIOT/tree/master/examples/guides/creating_project).
+
+If your project is not working as expected, you can compare your code with the code in this repository to see if you missed anything.
+:::

doc/guides/c_tutorials/gpio.mdx

@@ -0,0 +1,251 @@
+---
+title: GPIO & Real Boards
+description: This tutorial explains how to use GPIO in RIOT to control LEDs or read button presses.
+code_folder: examples/guides/gpio/
+---
+
+import Contact from '@components/contact.astro';
+import WorkingVideo from './img/gpio/05_working_video.mp4';
+import ButtonVideo from './img/gpio/08_buttons.mp4';
+
+So far we have been running all our code using the `arduino-feather-nrf52840-sense` board.
+
+In this tutorial, we will learn how to use the GPIO pins on a real board to control LEDs or read button presses.
+
+For this tutorial I will be using a the `arduino-feather-nrf52840-sense` board with the [Teamagochi PCB](https://github.com/smartuni/teamagochi), but you can use any board that has GPIO pins.
+
+## Step 1: Configuring our Board
+
+<Contact />
+
+First, we need to inform RIOT about the board we are using.
+
+To do this we adapt the `BOARD` variable in our `Makefile` to the board we are using.
+
+```make
+BOARD ?= arduino-feather-nrf52840-sense
+```
+
+![The board variable in Visual Studio Code](img/gpio/01_define_board.png)
+
+First we want to make sure that we can build the code for the board.
+To do this we can simply run `make all` in the terminal,
+this will build the code for the board and check if everything is set up correctly.
+
+If everything is set up correctly, we should now be able to move on to flashing the board.
+
+:::tip
+It might return something like:
+
+```
+/bin/sh: line 1: arm-none-eabi-gcc: command not found
+Compiler arm-none-eabi-gcc is required but not found in PATH.  Aborting.
+```
+
+This means that you need to install the ARM toolchain,
+you can do this by running `sudo apt install gcc-arm-none-eabi` on Ubuntu
+or `sudo pacman -S arm-none-eabi-gcc` on Arch Linux.
+
+If it still doesn't work, consider running it via the Docker container using `BUILD_IN_DOCKER=1 make flash`.
+
+Please refer to the [Flashing a RIOT Application](/getting-started/flashing) guide for more information.
+:::
+
+Try flashing the board with `make flash` and see if it works,
+it should still execute the same code as before when running RIOT natively on your
+own hardware but now using the actual board.
+
+![Flash output in Visual Studio Code](img/gpio/02_flash_output.png)
+
+Now if we type `make term` we should see the output of the board in the terminal.
+Make sure that you have the board connected to your computer via USB and
+that your user has the necessary permissions to access the serial port.
+
+:::tip
+On Arch Linux, you might need to add your user to the `uucp` group to access the serial port.
+
+```bash
+sudo usermod -a -G uucp $USER
+```
+:::
+
+## Step 2: Controlling LEDs
+
+Now that we have the board working, let's try to control the LEDs on the board.
+
+The exact pins that control the LEDs might vary depending on the board you are using,
+but in the case of the `arduino-feather-nrf52840-sense` board, the LED would be connected
+on Port 1 Pin 9.
+
+First we need to include the necessary modules in our projects `Makefile`.
+
+```make
+# Add the gpio module to the build
+USEMODULE += periph_gpio
+USEMODULE += periph_gpio_irq
+
+# Enable the milliseconds timer.
+USEMODULE += ztimer
+USEMODULE += ztimer_msec
+```
+
+![The Makefile with the GPIO modules](img/gpio/03_gpio_modules.png)
+
+This allows us to both control the GPIO pins and timers.
+
+Now we need to actually define the pin that we want to control in our code.
+To do this include the following lines **before** the `main` function.
+{/*<!--skip ci-->*/}
+```c
+#include "board.h"
+#include "periph/gpio.h"
+#include "ztimer.h"
+
+/* Define the LED0 pin and mode */
+gpio_t led0 = GPIO_PIN(1, 9);
+gpio_mode_t led0_mode = GPIO_OUT;
+```
+
+Now we can control the LED. First we initialize the pin and afterwards we turn the LED off by clearing the pin
+
+{/*<!--skip ci-->*/}
+```c
+int main(void) {
+  /* Initialize the LED0 pin */
+  gpio_init(led0, led0_mode);
+  /* Turn off the LED0 pin */
+  gpio_clear(led0);
+
+  /* Loop forever */
+  while (1) {
+
+  }
+}
+```
+
+Turning the LED off when the board starts is quite boring,
+so let's make it blink by adding a delay and toggling the LED.
+
+```c
+  /* Loop forever */
+  while (1) {
+    /* Toggle the LED0 pin every 500 milliseconds */
+    gpio_toggle(led0);
+    ztimer_sleep(ZTIMER_MSEC, 500);
+  }
+```
+
+![The Code in Visual Studio Code](img/gpio/04_code.png)
+
+If we now `make flash` and then `make term` we should see the LED blinking.
+
+<video controls>
+  <source src={WorkingVideo} type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+## Step 3: Reading Button Presses
+
+If you remember what we did in the timers tutorial,
+we can use quite similar code to read button presses.
+
+On a constrained device you usually don't want to poll the button state,
+which is why we will use an interrupt to detect the button press,
+that way we can drastically reduce the power consumption of the device.
+
+
+First we need to define the callback function that will be called when the button is pressed.
+
+```c title="Define the LED1 pin and mode"
+/* Define the LED1 pin and mode */
+gpio_t led1 = GPIO_PIN(1, 10);
+gpio_mode_t led1_mode = GPIO_OUT;
+```
+
+```c title="Define the button callback function"
+/* This callback function will be called when the button state changes */
+void button_callback(void *arg) {
+  /* the argument is not used */
+  (void)arg;
+
+  /* Toggle the LED1 pin based on the button state */
+  if (gpio_read(button)) {
+    gpio_clear(led1);
+  } else {
+    gpio_set(led1);
+  }
+}
+```
+
+Now we need to define the button pin and mode and initialize it.
+
+```c {1-2, 26-27}
+/* Define the button pin */
+gpio_t button = GPIO_PIN(1, 2);
+
+/* This callback function will be called when the button state changes */
+void button_callback(void *arg) {
+  /* the argument is not used */
+  (void)arg;
+
+  /* Toggle the LED1 pin based on the button state */
+  if (gpio_read(button)) {
+    gpio_clear(led1);
+  } else {
+    gpio_set(led1);
+  }
+}
+
+int main(void) {
+  /* Initialize the LED0 pin */
+  gpio_init(led0, led0_mode);
+  /* Turn off the LED0 pin */
+  gpio_clear(led0);
+
+  /* Initialize the LED1 pin */
+  gpio_init(led1, led1_mode);
+  /* Turn off the LED1 pin */
+  gpio_clear(led1);
+
+  /* Initialize the button pin */
+  gpio_init_int(button, GPIO_IN_PU, GPIO_BOTH, button_callback, NULL);
+
+  /* Loop forever */
+  while (1) {
+    /* Toggle the LED0 pin every 500 milliseconds */
+    gpio_toggle(led0);
+    ztimer_sleep(ZTIMER_MSEC, 500);
+  }
+}
+```
+
+This code will initialize the button pin and call the `button_callback` function whenever the button is pressed.
+
+![Full Code in Visual Studio Code](img/gpio/07_full_code.png)
+
+If we now `make flash` and then `make term` we should see the LED turn on when the button is pressed.
+
+:::tip
+If you are using the `arduino-feather-nrf52840-sense` board, the button is on the back of the board.
+
+Be careful to not press the reset button by mistake 😉
+:::
+
+<video controls>
+  <source src={ButtonVideo} type="video/mp4" />
+  Your browser does not support the video tag.
+</video>
+
+## Conclusion
+
+In this tutorial we learned how to use the GPIO pins on a real board to control LEDs or read button presses.
+
+This is a very basic example, but it should give you a good starting point to build more complex applications.
+
+<Contact />
+
+:::note
+The source code for this tutorial can be found [HERE](https://github.com/RIOT-OS/RIOT/tree/master/examples/guides/gpio).
+
+If your project is not working as expected, you can compare your code with the code in this repository to see if you missed anything.
+:::