examples/guides: Introduce tutorial references

AnnsAnns · AnnsAnns · commit a4e67497bf27 · 2025-04-29T18:48:34.000+02:00
diff --git a/examples/README.md b/examples/README.md
@@ -142,3 +142,14 @@ Here is a quick overview of the examples available in the RIOT:
 | [twr_aloha](./advanced/twr_aloha/README.md) | This example allows testing different two-way ranging algorithms between two boards supporting a dw1000 device. This makes use of the uwb-core pkg. |
 | [senml_saul](./advanced/senml_saul/README.md) | This example demonstrates the usage of the SAUL (Sensor Actuator Uber Layer) module with the SenML (Sensor Measurement Lists) format. |
 | [opendsme](./advanced/opendsme/README.md) | This example demonstrates the usage of the OpenDSME module in RIOT. |
+
+## Examples for Guides
+
+| Example | Description |
+|---------|-------------|
+| [creating_project](./guides/creating_project/README.md) | This example is used in the [Create Project](https://guide.riot-os.org/c_tutorials/create_project/) tutorial |
+| [shell](./guides/shell/README.md) | This example is used in the [Echo](https://guide.riot-os.org/c_tutorials/shell/) tutorial |
+| [gpio](./guides/gpio/README.md) | This example is used in the [GPIO](https://guide.riot-os.org/c_tutorials/gpio/) tutorial |
+| [saul](./guides/saul/README.md) | This example is used in the [SAUL](https://guide.riot-os.org/c_tutorials/saul/) tutorial |
+| [threads](./guides/threads/README.md) | This example is used in the [Threads](https://guide.riot-os.org/c_tutorials/threads/) tutorial |
+| [timers](./guides/timers/README.md) | This example is used in the [Timers](https://guide.riot-os.org/c_tutorials/timers/) tutorial |
diff --git a/examples/guides/creating_project/Makefile b/examples/guides/creating_project/Makefile
@@ -0,0 +1,18 @@
+# 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
diff --git a/examples/guides/creating_project/README.md b/examples/guides/creating_project/README.md
@@ -0,0 +1,5 @@
+# RIOT Tutorial Replica
+
+This example is a replica of the output of the RIOT tutorial. The tutorial is available at [RIOT Tutorial](https://guide.riot-os.org).
+
+The tutorial itself is located within [doc/guides/c_tutorials](/doc/guides/c_tutorials/). Please refer to the original tutorial for more information.
diff --git a/examples/guides/creating_project/main.c b/examples/guides/creating_project/main.c
@@ -0,0 +1,8 @@
+#include <stdio.h>
+
+int main(void)
+{
+    puts("Hello World!");
+
+    return 0;
+}
diff --git a/examples/guides/gpio/Makefile b/examples/guides/gpio/Makefile
@@ -0,0 +1,29 @@
+# name of your application
+APPLICATION = hello-world
+
+# Change this to your board if you want to build for a different board
+BOARD ?= feather-nrf52840-sense
+
+# 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
+
+# This board requires a start sleep to actually catch the printed output
+USEMODULE += shell
+
+# Add the gpio module to the build
+USEMODULE += periph_gpio
+USEMODULE += periph_gpio_irq
+
+# Enable the milliseconds timer.
+USEMODULE += ztimer
+USEMODULE += ztimer_msec
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/guides/gpio/README.md b/examples/guides/gpio/README.md
@@ -0,0 +1 @@
+../creating_project/README.md
diff --git a/examples/guides/gpio/main.c b/examples/guides/gpio/main.c
@@ -0,0 +1,45 @@
+#include "periph/gpio.h"
+#include "board.h"
+#include "ztimer.h"
+
+// Define the LED0 pin and mode
+gpio_t led0 = GPIO_PIN(1, 9);
+gpio_mode_t led0_mode = GPIO_OUT;
+
+// Define the LED0 pin and mode
+gpio_t led1 = GPIO_PIN(1, 10);
+gpio_mode_t led1_mode = GPIO_OUT;
+
+// Define the button pin
+gpio_t button = GPIO_PIN(1, 2);
+
+void button_callback (void *arg)
+{
+    (void) arg; /* the argument is not used */
+    if (!gpio_read(button)) {
+        gpio_set(led1);
+    }
+    else {
+        gpio_clear(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);
+
+  while (1) {
+    gpio_toggle(led0);
+    ztimer_sleep(ZTIMER_MSEC, 500);
+  }
+}
diff --git a/examples/guides/saul/Makefile b/examples/guides/saul/Makefile
@@ -0,0 +1,29 @@
+# name of your application
+APPLICATION = hello-world
+
+# Change this to your board if you want to build for a different board
+BOARD ?= feather-nrf52840-sense
+
+# 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
+
+# This board requires a start sleep to actually catch the printed output
+USEMODULE += shell
+
+# Add the SAUL module to the application
+USEMODULE += saul
+USEMODULE += saul_default
+
+# Enable the milliseconds timer.
+USEMODULE += ztimer
+USEMODULE += ztimer_msec
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/guides/saul/README.md b/examples/guides/saul/README.md
@@ -0,0 +1 @@
+../creating_project/README.md
diff --git a/examples/guides/saul/main.c b/examples/guides/saul/main.c
@@ -0,0 +1,45 @@
+#include <stdio.h>
+
+#include "board.h"
+#include "ztimer.h"
+#include "saul_reg.h"
+
+int main(void) {
+  ztimer_sleep(ZTIMER_MSEC, 5000);
+  puts("Welcome to SAUL magic!");
+
+  // Define our temperature sensor
+  saul_reg_t *temperature_sensor = saul_reg_find_type(SAUL_SENSE_TEMP);
+
+  // Exit if we can't find a temperature sensor
+  if (!temperature_sensor) {
+    puts("No temperature sensor found");
+    return 1;
+  } else {
+    // Otherwise print the name of the temperature sensor
+    // and continue the program
+    printf("Temperature sensor found: %s\n", temperature_sensor->name);
+  }
+
+  while (1) {
+    // Define a variable to store the temperature
+    phydat_t temperature;
+
+    // Read the temperature sensor
+    // and store the result in the temperature variable
+    // saul_reg_read returns the dimension of the data read (1 in this case)
+    int dimension = saul_reg_read(temperature_sensor, &temperature);
+
+    // If the read was successful (1 or more dimensions), print the temperature
+    if (dimension <= 0) {
+      puts("Error reading temperature sensor");
+      return 1;
+    }
+
+    // Dump the temperature to the console
+    phydat_dump(&temperature, dimension);
+
+    // Sleep for 1 seconds
+    ztimer_sleep(ZTIMER_MSEC, 1000);
+  }
+}
diff --git a/examples/guides/shell/Makefile b/examples/guides/shell/Makefile
@@ -0,0 +1,21 @@
+# 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
+
+# This board requires a start sleep to actually catch the printed output
+USEMODULE += shell
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/guides/shell/README.md b/examples/guides/shell/README.md
@@ -0,0 +1 @@
+../creating_project/README.md
diff --git a/examples/guides/shell/main.c b/examples/guides/shell/main.c
@@ -0,0 +1,25 @@
+#include <stdio.h>
+#include "shell.h"
+
+int echo_command(int argc, char **argv)
+{
+    for (int i = 1; i < argc; i++) {
+        printf("%s ", argv[i]);
+    }
+    printf("\n");
+
+    return 0;
+}
+
+SHELL_COMMAND(echo,"Echo a message", echo_command);
+
+int main(void)
+{
+    // Buffer to store command line input
+    char buffer[SHELL_DEFAULT_BUFSIZE];
+
+    // Start the shell
+    shell_run(NULL, buffer, SHELL_DEFAULT_BUFSIZE);
+
+    return 0;
+}
diff --git a/examples/guides/threads/Makefile b/examples/guides/threads/Makefile
@@ -0,0 +1,21 @@
+# 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
+
+# This board requires a start sleep to actually catch the printed output
+USEMODULE += shell
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/guides/threads/README.md b/examples/guides/threads/README.md
@@ -0,0 +1 @@
+../creating_project/README.md
diff --git a/examples/guides/threads/main.c b/examples/guides/threads/main.c
@@ -0,0 +1,21 @@
+#include <stdio.h>
+
+#include "thread.h"
+
+char my_thread_stack[THREAD_STACKSIZE_MAIN];
+
+void *my_first_thread(void *arg) {
+  (void)arg;  // Variable not used
+
+  puts("Hello, from the thread!");
+
+  return NULL;
+}
+
+int main(void) {
+    thread_create(my_thread_stack, sizeof(my_thread_stack),
+            THREAD_PRIORITY_MAIN - 1, 0, my_first_thread, NULL,
+            "My first thread"); 
+
+    puts("Hello, from the main thread!");
+}
diff --git a/examples/guides/timers/Makefile b/examples/guides/timers/Makefile
@@ -0,0 +1,21 @@
+# 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
+
+# This board requires a start sleep to actually catch the printed output
+USEMODULE += ztimer_sec
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/guides/timers/Makefile.ci b/examples/guides/timers/Makefile.ci
@@ -0,0 +1,3 @@
+BOARD_INSUFFICIENT_MEMORY := \
+    atmega8 \
+    #
diff --git a/examples/guides/timers/README.md b/examples/guides/timers/README.md
@@ -0,0 +1 @@
+../creating_project/README.md
diff --git a/examples/guides/timers/main.c b/examples/guides/timers/main.c
@@ -0,0 +1,31 @@
+#include <stdio.h>
+#include "ztimer.h"
+
+void timer_callback(void *arg)
+{
+    // Convert the argument to a string
+    char *message = (char *)arg;
+
+    // Print the message
+    puts(message);
+}
+
+
+int main(void)
+{
+    // Create a timer
+    ztimer_t timer = {
+        .callback = timer_callback,
+        .arg = "3 seconds have passed!"
+    };
+
+    // Set the timer to fire in 3 seconds
+    ztimer_set(ZTIMER_SEC, &timer, 3);
+
+    // Sleep for 5 seconds
+    ztimer_sleep(ZTIMER_SEC, 5);
+
+    puts("5 seconds have passed!");
+
+    return 0;
+}
