From 953fbee2dda43226662dd2ba2c55e627b56cd7ac Mon Sep 17 00:00:00 2001 From: crasbe Date: Mon, 13 Apr 2026 17:27:40 +0200 Subject: [PATCH 1/3] doc/guides: add cross-references betw. app guides --- .../advanced_tutorials/creating_application.mdx | 6 ++++++ doc/guides/c_tutorials/create_project.mdx | 11 ++++++++--- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/guides/advanced_tutorials/creating_application.mdx b/doc/guides/advanced_tutorials/creating_application.mdx index c78bd72c874c..10446fa0af96 100644 --- a/doc/guides/advanced_tutorials/creating_application.mdx +++ b/doc/guides/advanced_tutorials/creating_application.mdx @@ -5,6 +5,12 @@ description: How to create your own application for RIOT import FileTree from '@components/FileTree.astro'; +:::note +This is an advanced tutorial, if you are looking for a beginner introduction +about RIOT applications, take a look at +[Creating a Project](/c_tutorials/create_project). +::: + To create your own application you need to create a directory containing one or multiple C file(s) with your source code and a Makefile. A template Makefile is available in the `dist` folder of the diff --git a/doc/guides/c_tutorials/create_project.mdx b/doc/guides/c_tutorials/create_project.mdx index 964650d4eae1..c4c91d5b8c52 100644 --- a/doc/guides/c_tutorials/create_project.mdx +++ b/doc/guides/c_tutorials/create_project.mdx @@ -11,9 +11,14 @@ Now that we have played around with the examples and have a basic understanding 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. +:::note +This is a beginner tutorial, if you are looking for more advanced information +about RIOT applications, take a look at +[Creating an Application](/advanced_tutorials/creating_application). +::: + +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 From 0bf4c83cfd09dc5d1cc714b8fad632ca3736dafe Mon Sep 17 00:00:00 2001 From: crasbe Date: Fri, 10 Apr 2026 15:47:37 +0200 Subject: [PATCH 2/3] drivers/periph/spi: add doc about multiple SPI buses and default configs --- drivers/include/periph/spi.h | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/drivers/include/periph/spi.h b/drivers/include/periph/spi.h index 9ce9bebf8a99..19cd80a8120e 100644 --- a/drivers/include/periph/spi.h +++ b/drivers/include/periph/spi.h @@ -23,7 +23,7 @@ * `spi_release()` functions. * * This interface supports both software and hardware chip select lines. This is - * reflected by the cpi_cs_t type, which overloads the gpio_t type with platform + * reflected by the spi_cs_t type, which overloads the gpio_t type with platform * specific values for defining platform dependent hardware chip select lines. * * Some devices have however very uncommon requirements on the usage and the @@ -46,6 +46,31 @@ * configures the bus with specific parameters (clock, mode) for the duration * of that transaction. * + * # Default Configuration and Dealing with Multiple SPI Buses + * + * Many advanced microcontrollers feature multiple SPI buses and some devices, + * such as the Nordic Semiconductor nRF52 family, even allow arbitrary pin + * assignments for the SPI peripherals. + * + * RIOT boards provide sane defaults for bus and pin assignments on Development + * Boards. The first SPI controller `SPI_DEV(0)` is assigned to + * the SPI pins marked on the board. Often that corresponds to the + * Arduino headers or other manufacturer standardized pinouts. + * + * If there are additional devices such as a display, flash memory, sensor, + * etc. present on the board, a higher number SPI controller will be selected, + * e.g. `SPI_DEV(1)` or `SPI_DEV(2)`. + * The exact assignment depends on the number of SPI controllers and + * organization of peripherals as well as the capabilities of the individual + * controller. Some controllers support faster transfer rate or special + * operating modes. More details are documented in the + * `periph_conf.h` file of the specific board. + * + * If you wish to modify the default configuration for your application, + * take a look at the + * [guides page](https://doc.riot-os.org/advanced_tutorials/creating_application/#modifying-board-defaults-of-peripherals) + * about creating applications. + * * # (Low-) Power Implications * * As SPI buses are shared peripherals and the interfaces implements a From be59d09dac7fbf9f92507c33ee7474a813523a73 Mon Sep 17 00:00:00 2001 From: crasbe Date: Tue, 14 Apr 2026 12:53:54 +0200 Subject: [PATCH 3/3] doc/guides/creating_app: add info about custom periph_conf.h --- .../creating_application.mdx | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/guides/advanced_tutorials/creating_application.mdx b/doc/guides/advanced_tutorials/creating_application.mdx index 10446fa0af96..4ddd995400a0 100644 --- a/doc/guides/advanced_tutorials/creating_application.mdx +++ b/doc/guides/advanced_tutorials/creating_application.mdx @@ -194,6 +194,37 @@ ifneq (,$(filter native native32 native64,$(BOARD))) endif ``` +## Modifying Board-Defaults of Peripherals + +Sometimes the default configuration of CPU peripherals from the board's +`periph_conf.h` file does not fit the need of the application. This can be due +to custom pin mapping or collosions, additional or different controllers +required, or other reasons. + +Usually it is not desirable to modify the default board configuration in the +RIOT folder, but rather to keep the custom configuration close to the +application itself. +Therefore, a custom `periph_conf.h` file can be created in the base directory +of the application, as shown in the file tree below. + + +- apps + - my_app + - Makefile + - main.c + - periph_conf.h +- RIOT/ + - boards + - specific_board + - include + - periph_conf.h + + +It is usually a good idea to copy the `periph_conf.h` file from the board you +are working with as a starting point and then applying the modifications. This +ensures that all the other peripherals are still working as intended and gives +you a reliable starting point. + ## Helper Tools To help you start writing an application within RIOT, the build system provides