diff --git a/doc/guides/advanced_tutorials/creating_application.md b/doc/guides/advanced_tutorials/creating_application.md index 019d42a917..45c58d75f4 100644 --- a/doc/guides/advanced_tutorials/creating_application.md +++ b/doc/guides/advanced_tutorials/creating_application.md @@ -132,7 +132,7 @@ ifneq (,$(filter native native32 native64,$(BOARD))) endif ``` -# Helper Tools +## Helper Tools To help you start writing an application within RIOT, the build system provides the `generate-example` and `generate-test` make targets. These targets are wrappers @@ -143,8 +143,6 @@ on the module implementation. For applications, the `Makefile` is generated with the dependencies (modules, packages, required features) included. -## Usage - To generate an example application, e.g in the `examples` directory, from the RIOT base directory, run: ```sh @@ -181,7 +179,7 @@ target used. **Testrunner:** when using the `make generate-test`, you can also automatically add a testrunner Python script. Just answer 'y' when prompted. -# Creating an Out of Tree Application Structure +## Creating an Out of Tree Application Structure Applications written for RIOT do not have to reside in the RIOT tree. Out of tree applications, modules and boards are supported. @@ -237,7 +235,7 @@ inside a modules os boards directory. The RIOT build system has both `EXTERNAL_MODULE_DIRS` and `EXTERNAL_BOARD_DIRS` variables to specify directories that contain extra modules and extra boards. -## External Boards +### External Boards External boards can be ported in an identical way as porting a regular board to RIOT, see [Porting Boards](/advanced_tutorials/porting_boards/). @@ -250,7 +248,7 @@ configuration (e.g. configuring some of the pins configured as ADC as additional PWM outputs instead) a copy of the upstream board that is then customized to the application needs is the best course of action. -## External Modules +### External Modules Similar to the external boards, external modules can be written in a similar way as regular in-tree modules. @@ -268,7 +266,7 @@ Note that the make variable (here `USEMODULE_INCLUDES_my_module`) must be unique for every module to make this work. Including the module name here is usually sufficient. -## Extra Makefile Scaffolding +### Extra Makefile Scaffolding A bit of extra, but optional, Makefile scaffolding can help to keep the project easy to maintain. An extra `Makefile.include` in the root directory of the diff --git a/doc/guides/advanced_tutorials/creating_modules.md b/doc/guides/advanced_tutorials/creating_modules.md index 82f29be5c9..221f19468f 100644 --- a/doc/guides/advanced_tutorials/creating_modules.md +++ b/doc/guides/advanced_tutorials/creating_modules.md @@ -170,7 +170,7 @@ See `sys/ztimer/Makefile` for an example in code. `SUBMODULES` can also be true-pseudomodules, or become one by conditionally excluding the source files by adding them to `SUBMODULES_NO_SRC`. -# Helper Tools +## Helper Tools To help you start writing a module, the RIOT build system provides the `generate-module` make target. It is a wrapper around the @@ -180,8 +180,6 @@ copyright headers, doxygen groups, etc, so you can concentrate on the module implementation. The module source files are created in the `sys` directory. -## Usage - From the RIOT base directory, run: ```sh make generate-module diff --git a/doc/guides/advanced_tutorials/device_drivers.md b/doc/guides/advanced_tutorials/device_drivers.md index 64b4e96f60..849c8f1984 100644 --- a/doc/guides/advanced_tutorials/device_drivers.md +++ b/doc/guides/advanced_tutorials/device_drivers.md @@ -11,7 +11,7 @@ peripherals itself are in RIOT not considered to be device drivers, but peripheral or low-level drivers. Typical devices are network devices like radios, Ethernet adapters, sensors, and actuators. -# General Design Objectives +## General Design Objectives Device drivers should be as easy to use as possible. This implies an 'initialize->ready' paradigm, meaning, that device drivers should be ready to use @@ -53,9 +53,9 @@ Sixth, device drivers SHOULD be implemented independent of any CPU/board code. To achieve this, the driver implementations should strictly be based on platform independent interfaces as the peripheral drivers, xtimer, etc. -# General +## General -## Documentation +### Documentation Document what your driver does! Most devices come with a very large number of features, while the corresponding device driver only supports a subset of them. @@ -63,7 +63,7 @@ This should be clearly stated in the device driver's documentation so that anyone wanting to use the driver can find out the supported features without having to scan through the code. -## Device Descriptor and Parameter Configuration +### Device Descriptor and Parameter Configuration Each device MUST supply a data structure, holding the devices state and configuration, using the naming scheme of `DEVNAME_t` (e.g. `dht_t`, or @@ -108,7 +108,7 @@ configuration data that is only used once can be read directly from ROM, while often used fields (e.g. used peripherals) are stored directly in the device descriptor and one saves hereby one de-referencing step when accessing them. -## Default Device Configuration +### Default Device Configuration Each device driver in RIOT MUST supply a default configuration file, named `DEVNAME_params.h`. This file should be located in the `RIOT/drivers/...`. The @@ -201,7 +201,7 @@ Third, we can define more than a single device in the board configuration And finally, we can simply override the `tmpabc_params.h` file as described above. -## Compile-time Configuration Documentation +### Compile-time Configuration Documentation The macros that configure the driver during compilation is added to the listing for [Compile time configurations](https://doc.riot-os.org/group__config.html). Refer to the following example @@ -230,7 +230,7 @@ to [sensors group](https://doc.riot-os.org/group__config__drivers__sensors.htmls Sub-groups defined for different types of drivers can be found in [drivers/doc.txt](https://github.com/RIOT-OS/RIOT/blob/master/drivers/doc.txt) -## Initialization +### Initialization In general, the initialization functions should do the following: @@ -250,7 +250,7 @@ For more detailed information on how the signature of the init functions should look like, please refer below to the specific requirements for network devices and sensors. -## Return Values +### Return Values As stated above, we check communication of a device during initialization and handle error return values from the lower layers, where they exist. To prevent @@ -299,7 +299,7 @@ negative return value indicates an error without exceptions. E.g. like this: int foo_humidity(const foo_t *dev); ``` -### Documenting Return Values +#### Documenting Return Values With the exception of functions returning `void`, all return values have to be documented. Use the `return` Doxygen command to describe what is returned. In @@ -309,7 +309,7 @@ argument (no spaces in the value allowed!), and a description (spaces allowed here) as second. It is safe to use both `return` and `retval` commands, or just one of them - whatever makes most sense for a given function. -## General Device Driver Checklist +### General Device Driver Checklist - *MUST*: the supported feature set and any custom behavior is clearly documented @@ -322,9 +322,9 @@ one of them - whatever makes most sense for a given function. - *MUST*: use `const devab_t *dev` when the device descriptor can be access read-only -## Build System Integration +### Build System Integration -### Internal Include Files +#### Internal Include Files If the driver contains internal include files, a `Makefile.include` must be added in the driver implementation directory, with the following content @@ -335,7 +335,7 @@ USEMODULE_INCLUDES_ := $(LAST_MAKEFILEDIR)/include USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_) ``` -### External Dependencies +#### External Dependencies If the driver has other module or CPU features dependencies (like `xtimer` or `periph_i2c`), they must be added in the `$(RIOTBASE)/drivers/Makefile.dep` @@ -351,7 +351,7 @@ endif **Warning:** Please be careful with alphabetical order when modifying this file. -## Helper Tools +### Helper Tools To help you start writing a device driver, the RIOT build system provides the `generate-driver` make target. It is a wrapper around the @@ -360,8 +360,6 @@ when starting to implement a driver: all minimum files are generated with copyright headers, doxygen groups, etc, so you can concentrate on the driver implementation. -**Usage:** - From the RIOT base directory, run: ``` make generate-driver @@ -379,9 +377,9 @@ Then answer a few questions about the driver: Other global information (author name, email, organization) should be retrieved automatically from your git configuration. -# Sensors +## Sensors -## SAUL +### SAUL All sensor drivers SHOULD implement the SAUL interface. It is however recommended, that the drivers are written in a way, that the drivers do not @@ -410,7 +408,7 @@ int saul_read(saul_t *dev, phydat_t *data) This ensures the versatility of the device driver, having in mind that one might want to use the driver without SAUL or maybe in a context without RIOT. -## Initialization +### Initialization Sensor device drivers are expected to implement a single initialization function, `DEVNAME_init`, taking the device descriptor and the device's @@ -422,15 +420,15 @@ int tmpabc_init(tmpabc_t *dev, const tmpabc_params_t *params); After this function is called, the device MUST be running and usable. -## Value Handling +### Value Handling -### Value Semantics +#### Value Semantics All sensors in RIOT MUST return their reading results as real physical values. When working with sensor data, these are the values of interest, and the overhead of the conversion is normally neglectable. -### Typing +#### Typing All values SHOULD be returned using integer types, with `int16_t` being the preferred type where applicable. @@ -441,7 +439,7 @@ directly while using their fraction. The recommended way to solve this is by scaling the result value using decimal fixed point arithmetic, in other words, just return centi-degree instead of degree (e.g. 2372c°C instead of 23.72°C). -## Additional Sensor Driver Checklist +### Additional Sensor Driver Checklist - *MUST*: mandatory device parameters are configurable through this file, e.g. sampling rate, resolution, sensitivity @@ -459,9 +457,9 @@ just return centi-degree instead of degree (e.g. 2372c°C instead of 23.72°C). - *SHOULD*: the driver exports functions for putting it to sleep and waking up the device -# Network Devices +## Network Devices -## Initialization +### Initialization The initialization process MUST be split into 2 steps: first, initialize the device descriptor and if applicable the used peripherals, and secondly do the @@ -478,7 +476,7 @@ void netabc_setup(netabc_t *dev, const netabc_params_t *params); int netabs_init(netabc_t *dev); ``` -## netdev +### netdev Device driver for network device SHOULD implement the `netdev` interface. It is up to the implementer, if the device driver also offers a device specific @@ -486,7 +484,7 @@ interface which is then mapped to the `netdev` interface, or if the device driver can be purely interfaced using `netdev`. While the second option is recommended for efficiency reasons, this is not mandatory. -## Additional Network Device Driver Checklist +### Additional Network Device Driver Checklist - *MUST*: a setup function in the style of `int devab_setup(devab_t *dev, const devab_params_t *params);` exists @@ -494,7 +492,7 @@ recommended for efficiency reasons, this is not mandatory. exists - *SHOULD*: the driver implements 'netdev' [if applicable] -# TODO +## TODO Add some information about how to handle multiple threads, when to use mutexes, and how to deal with interrupts? And especially patterns for being nice from diff --git a/doc/guides/advanced_tutorials/porting_boards.md b/doc/guides/advanced_tutorials/porting_boards.md index 755fd971ab..42090b9fb3 100644 --- a/doc/guides/advanced_tutorials/porting_boards.md +++ b/doc/guides/advanced_tutorials/porting_boards.md @@ -19,10 +19,10 @@ We assume here that your `CPU` and `CPU_MODEL` is already supported in `RIOT` so no peripheral or cpu implementation is needed. ::: -# Porting Flowchart +## Porting Flowchart ![Porting flowchart](img/porting-boards.svg) -# General Structure +## General Structure Like [applications](/advanced_tutorials/creating_applications/) or [modules](/advanced_tutorials/creating_modules), @@ -47,7 +47,7 @@ board-foo └── Makefile.include ``` -## Source Files +### Source Files Header files in `board-foo/include` define physical mappings or configurations. e.g: @@ -86,9 +86,9 @@ void board_init(void) } ``` -## Makefiles +### Makefiles -### Makefile +#### Makefile A board's Makefile just needs to include `Makefile.base` in the RIOT repository and define the `MODULE` as `board` (see @@ -100,7 +100,7 @@ MODULE = board include $(RIOTBASE)/Makefile.base ``` -### Makefile.dep +#### Makefile.dep Dependencies on other `MODULES` or `FEATURES` can be defined here. This might specify `MODULES` or dependencies that need to be pulled under specific @@ -118,7 +118,7 @@ the dependency block for your board *before* its dependencies pull in their own dependencies. ::: -#### Default Configurations +##### Default Configurations There are two pseudomodules that are used to indicate that certain drivers of devices present in the platform should be enabled. Each board (or CPU) has knowledge as to which drivers should be enabled in each case. @@ -142,7 +142,7 @@ ifneq (,$(filter saul_default,$(USEMODULE))) endif ``` -### Makefile.features +#### Makefile.features This file defines all the features provided by the BOARD. These features might also need to be supported by the `CPU`. Here, define the `CPU` and @@ -161,7 +161,7 @@ FEATURES_PROVIDED += periph_spi FEATURES_PROVIDED += periph_uart ``` -### Makefile.include +#### Makefile.include This file contains BSP or toolchain configurations for the `BOARD`. It should at least define the configuration needed for flashing (i.e. specify a @@ -191,7 +191,7 @@ PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.usbserial*))) PROGRAMMER ?= openocd ``` -## Timer Configurations +### Timer Configurations When using the high level timer `ztimer` there is an overhead in calling the [ztimer_sleep](https://doc.riot-os.org/group__sys__ztimer.html#gade98636e198f2d571c8acd861d29d360) @@ -235,7 +235,7 @@ Alternatively, the pseudomodule [ztimer_auto_adjust](https://doc.riot-os.org/gro can be used in an application to enable automatic timer offset compensation at board startup. This however incurs overhead both in the text segment and at bootup time. -## doc.md +### doc.md Although not explicitly needed, if upstreamed and as a general good practice, this file holds all `BOARD` documentation. This can include @@ -251,15 +251,15 @@ any browser. @brief Support for the foo board @author FooName BarName -### User Interface +#### User Interface ... -### Using UART +#### Using UART ... -### Flashing the device +#### Flashing the device ... ``` @@ -277,7 +277,7 @@ the latest version with pip install --upgrade riotgen ``` -# Helper Tools +## Helper Tools To help you start porting a board, the RIOT build system provides the `generate-board` make target. It is a wrapper around the @@ -286,8 +286,6 @@ when starting to port a board: all required files are generated with copyright headers, doxygen groups, etc, so you can concentrate on the port. The board source files are created in the `boards/` directory. -## Usage - From the RIOT base directory, run: ```bash @@ -306,7 +304,7 @@ Then answer a few questions about the driver: Other global information (author name, email, organization) should be retrieved automatically from your git configuration. -# Using Common Code +## Using Common Code To avoid code duplication, common code across boards has been grouped in `boards/common`. e.g. `BOARD`s based on the same cpu (`boards/common/nrf52`) or @@ -338,7 +336,7 @@ static const timer_conf_t timer_config[] = { /** @} */ ``` -# Boards Outside of RIOTBASE +## Boards Outside of RIOTBASE All `BOARD`s in RIOT reside in `RIOTBOARD` (`RIOTBOARD` being a make variable set to `$(RIOTBOARD)/boards`). @@ -402,7 +400,7 @@ DIRS += $(RIOTBOARD)/foo-parent An example can be found in [`tests/build_system/external_board_native`](https://github.com/RIOT-OS/RIOT/tree/master/tests/build_system/external_board_native). -# Board Names and Aliases +## Board Names and Aliases New boards should be named according to [RDM0003](https://github.com/RIOT-OS/RIOT/blob/master/doc/memos/rdm0003.md). @@ -418,7 +416,7 @@ resolves to either [`native32`](https://doc.riot-os.org/group__boards__native32. or [`native64`](https://doc.riot-os.org/group__boards__native64.html) depending on the host architecture. -# Tools +## Tools Some scripts and tools available to ease `BOARD` porting and testing: @@ -430,7 +428,7 @@ Some scripts and tools available to ease `BOARD` porting and testing: - Run `dist/tools/compile_and_test_for_board/compile_and_test_for_board.py . --with-test-only` to run all automated tests on the new board. -# Further Reference +## Further Reference - [In her blog](https://blog.martine-lenders.eu/riot-board-en.html), Martine Lenders documented her approach of porting the [Adafruit Feather nRF52840 Express](https://doc.riot-os.org/group__boards__adafruit-feather-nrf52840-express.html) diff --git a/doc/guides/build-system/flashing.md b/doc/guides/build-system/flashing.md index 9c150ff257..90b1a4cb43 100644 --- a/doc/guides/build-system/flashing.md +++ b/doc/guides/build-system/flashing.md @@ -3,7 +3,7 @@ title: Flashing via RIOT's Build System description: Guide on how to flash boards using RIOT's build system --- -# General Approach +## General Approach In general, flashing a board from RIOT is as straight forward as typing in a shell (with the application directory as current working directory): @@ -22,7 +22,7 @@ make BOARD= PROGRAMMER=stm32flash flash To flash without rebuilding use `flash-only` as target instead of `flash`. -# Supported Tools +## Supported Tools RIOT supports plenty of flashing tools, that are below grouped into general flashing tools that support multiple MCU families, and specialized tools that @@ -36,7 +36,7 @@ the board due to a missing board feature, bootloader, or similar. To ease use the programmers are given by the value to pass via `PROGRAMMER=`, rather than the official spelling of the programmer. -## Compatibility Matrix of Generic Tools +### Compatibility Matrix of Generic Tools */} + ```c #include "board.h" #include "periph/gpio.h" @@ -134,16 +186,17 @@ and afterwards we turn the LED off by clearing the pin. {/**/} ```c -int main(void) { - /* Initialize the LED0 pin */ - gpio_init(led0, led0_mode); - /* Turn off the LED0 pin */ - gpio_clear(led0); +int main(void) +{ + /* Initialize the LED0 pin */ + gpio_init(led0, led0_mode); + /* Turn off the LED0 pin */ + gpio_clear(led0); - /* Loop forever */ - while (1) { + /* Loop forever */ + while (1) { - } + } } ``` @@ -151,15 +204,41 @@ 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); - } + /* 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) +The full code should now look like this: + +{/**/} +```c title="main.c" {16-21} +#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; + +int main(void) +{ + /* Initialize the LED0 pin */ + gpio_init(led0, led0_mode); + /* Turn off the LED0 pin */ + gpio_clear(led0); + + /* Loop forever */ + while (1) { + /* Toggle the LED0 pin every 500 milliseconds */ + gpio_toggle(led0); + ztimer_sleep(ZTIMER_MSEC, 500); + } +} +``` If we now `make flash` and then `make term` we should see the LED blinking. @@ -183,22 +262,32 @@ that will be called when the button is pressed. ```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; +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); - } + /* 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 and led1 pin and mode and initialize it. -```c {1-6, 27-33} +```c title="main.c" {9-14, 38-44} +#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; + /* Define the LED1 pin and mode */ gpio_t led1 = GPIO_PIN(1, 10); gpio_mode_t led1_mode = GPIO_OUT; @@ -207,46 +296,47 @@ gpio_mode_t led1_mode = GPIO_OUT; 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; +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); - } + /* 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); +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 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); + /* 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); - } + /* 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. @@ -278,18 +368,19 @@ Using this define, we can simplify our code to the following: {/**/} ```c title="Using the LED0_TOGGLE define" -int main(void) { - /* Initialize the LED0 pin */ - gpio_init(led0, led0_mode); - /* Turn off the LED0 pin */ - gpio_clear(led0); +int main(void) +{ + /* Initialize the LED0 pin */ + gpio_init(led0, led0_mode); + /* Turn off the LED0 pin */ + gpio_clear(led0); - /* Loop forever */ - while (1) { - /* Toggle the LED0 pin every 500 milliseconds */ - LED0_TOGGLE; - ztimer_sleep(ZTIMER_MSEC, 500); - } + /* Loop forever */ + while (1) { + /* Toggle the LED0 pin every 500 milliseconds */ + LED0_TOGGLE; + ztimer_sleep(ZTIMER_MSEC, 500); + } } ``` diff --git a/doc/guides/c_tutorials/img/gpio/01_define_board.png b/doc/guides/c_tutorials/img/gpio/01_define_board.png deleted file mode 100644 index e576d00eba..0000000000 Binary files a/doc/guides/c_tutorials/img/gpio/01_define_board.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/gpio/03_gpio_modules.png b/doc/guides/c_tutorials/img/gpio/03_gpio_modules.png deleted file mode 100644 index 340517e7a2..0000000000 Binary files a/doc/guides/c_tutorials/img/gpio/03_gpio_modules.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/gpio/04_code.png b/doc/guides/c_tutorials/img/gpio/04_code.png deleted file mode 100644 index 9bfc01864a..0000000000 Binary files a/doc/guides/c_tutorials/img/gpio/04_code.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/gpio/07_full_code.png b/doc/guides/c_tutorials/img/gpio/07_full_code.png deleted file mode 100644 index 6f19ad0726..0000000000 Binary files a/doc/guides/c_tutorials/img/gpio/07_full_code.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/saul/01_makefile.png b/doc/guides/c_tutorials/img/saul/01_makefile.png deleted file mode 100644 index 6bbbd3260d..0000000000 Binary files a/doc/guides/c_tutorials/img/saul/01_makefile.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/saul/02_main_c.png b/doc/guides/c_tutorials/img/saul/02_main_c.png deleted file mode 100644 index c1f13632b2..0000000000 Binary files a/doc/guides/c_tutorials/img/saul/02_main_c.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/saul/03_register.png b/doc/guides/c_tutorials/img/saul/03_register.png deleted file mode 100644 index 9571884319..0000000000 Binary files a/doc/guides/c_tutorials/img/saul/03_register.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/saul/04_read.png b/doc/guides/c_tutorials/img/saul/04_read.png deleted file mode 100644 index ec3679f431..0000000000 Binary files a/doc/guides/c_tutorials/img/saul/04_read.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/threads/01_thread_function.png b/doc/guides/c_tutorials/img/threads/01_thread_function.png deleted file mode 100644 index 8a17790252..0000000000 Binary files a/doc/guides/c_tutorials/img/threads/01_thread_function.png and /dev/null differ diff --git a/doc/guides/c_tutorials/img/threads/02_stack.png b/doc/guides/c_tutorials/img/threads/02_stack.png deleted file mode 100644 index 50daa6da08..0000000000 Binary files a/doc/guides/c_tutorials/img/threads/02_stack.png and /dev/null differ diff --git a/doc/guides/c_tutorials/saul.md b/doc/guides/c_tutorials/saul.md index 7aa5bf38c9..1746719f65 100644 --- a/doc/guides/c_tutorials/saul.md +++ b/doc/guides/c_tutorials/saul.md @@ -22,9 +22,45 @@ add the following line to the `Makefile`: ```makefile USEMODULE += saul USEMODULE += saul_default + +USEMODULE += ztimer +USEMODULE += ztimer_msec ``` -![Makefile in VSCode](img/saul/01_makefile.png) +```makefile title="Makefile" {21-27} +# name of your application +APPLICATION = saul_example + +# Change this to your board if you want to build for a different board +BOARD ?= arduino-feather-nrf52840-sense + +# This has to be the absolute path to the RIOT base directory: +# If you are following the tutorial, your RIOT base directory will +# most likely be something like RIOTBASE ?= $(CURDIR)/RIOT +# instead of this +RIOTBASE ?= $(CURDIR)/../../.. + +# 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 +``` ## Including the Headers @@ -40,13 +76,27 @@ Add the following lines to the top of the file: ``` We need: + - `stdio.h` for the `printf` function, - `board.h` for the board specific configuration, - `ztimer.h` for the ztimer module so we can sleep for a while, - and `saul_reg.h` for the SAUL registry and related functions. +The code should now look like this: -![main.c in VSCode](img/saul/02_main_c.png) + +```c title="main.c" +#include + +#include "board.h" +#include "saul_reg.h" +#include "ztimer.h" + +int main(void) +{ + +} +``` ## Registering a Sensor @@ -57,8 +107,8 @@ In this example we will register a temperature sensor, as such we need to simply search for `SAUL_SENSE_TEMP` devices. ```c - /* Define our temperature sensor */ - saul_reg_t *temperature_sensor = saul_reg_find_type(SAUL_SENSE_TEMP); + /* Define our temperature sensor */ + saul_reg_t *temperature_sensor = saul_reg_find_type(SAUL_SENSE_TEMP); ``` This doesn't actually guarantee that the sensor is available, which is why we also need to @@ -66,20 +116,53 @@ check if the sensor truly exists. To do this we create a simple if statement tha whether the result of the function was `NULL` or not. ```c - /* 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); - } + /* 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); + } ``` -![Code to register sensor in VSCode](img/saul/03_register.png) +The code should now look like this: + + +```c title="main.c" {9-27} +#include + +#include "board.h" +#include "saul_reg.h" +#include "ztimer.h" + +int main(void) +{ + /* We sleep for 5 seconds to allow the system to initialize */ + 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); + } +} +``` Congratulations, by this point your program should be able to find a temperature sensor on your board. @@ -91,17 +174,17 @@ to read the sensor we simply call the `saul_reg_read` function which then stores the result in a `phydat_t` struct we provide. ```c - /* We start an infinite loop to continuously read the temperature */ - while (1) { - /* Define a variable to store the temperature */ - phydat_t temperature; + /* We start an infinite loop to continuously read the temperature */ + 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); + /* + * 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); ``` Once again, since C doesn't have exceptions, @@ -109,11 +192,11 @@ we need to check if the sensor was read correctly. In this case we simply need to check if the dimension is greater than 0. ```c - /* If the read was successful (1+ Dimensions), print the temperature */ - if (dimension <= 0) { - puts("Error reading temperature sensor"); - return 1; - } + /* If the read was successful (1+ Dimensions), print the temperature */ + if (dimension <= 0) { + puts("Error reading temperature sensor"); + return 1; + } ``` Now all that is left is to print the temperature to the console and go to sleep. @@ -122,14 +205,70 @@ RIOT provides a simple function to solve this problem, `phydat_dump` which prints the data in a `phydat_t` struct to the console. ```c - /* Dump the temperature to the console */ - phydat_dump(&temperature, dimension); + /* Dump the temperature to the console */ + phydat_dump(&temperature, dimension); - /* Sleep for 1 seconds */ - ztimer_sleep(ZTIMER_MSEC, 1000); + /* Sleep for 1 seconds */ + ztimer_sleep(ZTIMER_MSEC, 1000); ``` -![Code to read sensor in VSCode](img/saul/04_read.png) +The final code should now look like this: + +```c title="main.c" {29-52} +#include + +#include "board.h" +#include "saul_reg.h" +#include "ztimer.h" + +int main(void) +{ + /* We sleep for 5 seconds to allow the system to initialize */ + 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); + } + + /* We start an infinite loop to continuously read the temperature */ + 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+ 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); + } +} +``` ## Building and Running the Program diff --git a/doc/guides/c_tutorials/shell.md b/doc/guides/c_tutorials/shell.md index 57de59e1d5..3c2c90732c 100644 --- a/doc/guides/c_tutorials/shell.md +++ b/doc/guides/c_tutorials/shell.md @@ -35,15 +35,16 @@ Go into your `main.c` file and include the following code: ``` ```c title="The main function" -int main(void) { - /* Buffer to store command line input */ - char buffer[SHELL_DEFAULT_BUFSIZE]; +int main(void) +{ + /* Buffer to store command line input */ + char buffer[SHELL_DEFAULT_BUFSIZE]; - /* Start the shell */ - shell_run(NULL, buffer, SHELL_DEFAULT_BUFSIZE); + /* Start the shell */ + shell_run(NULL, buffer, SHELL_DEFAULT_BUFSIZE); - /* Return 0 to indicate that the program has finished successfully */ - return 0; + /* Return 0 to indicate that the program has finished successfully */ + return 0; } ``` @@ -83,17 +84,18 @@ Go into your `main.c` file and include the following code: ```c title="The function that implements the echo command" /* Our command we want to register to the shell */ -int echo_command(int argc, char **argv) { - /* We take the arguments passed to the command */ - for (int i = 1; i < argc; i++) { - /* We print each argument followed by a space */ - printf("%s ", argv[i]); - } - /* Finally, we print a newline character to end the line */ - printf("\n"); +int echo_command(int argc, char **argv) +{ + /* We take the arguments passed to the command */ + for (int i = 1; i < argc; i++) { + /* We print each argument followed by a space */ + printf("%s ", argv[i]); + } + /* Finally, we print a newline character to end the line */ + printf("\n"); - /* Return 0 to indicate success */ - return 0; + /* Return 0 to indicate success */ + return 0; } ``` @@ -107,7 +109,6 @@ Go back to your `main.c` file and include the following code _outside_ of the `m ```c title="Register the command with the shell" /* This little macro registers the command so we can use it in the shell */ SHELL_COMMAND(echo, "Echo a message", echo_command); - ``` This macro takes three arguments: the name of the command, diff --git a/doc/guides/c_tutorials/threads.mdx b/doc/guides/c_tutorials/threads.mdx index 6679f8cb3f..058403c201 100644 --- a/doc/guides/c_tutorials/threads.mdx +++ b/doc/guides/c_tutorials/threads.mdx @@ -19,20 +19,19 @@ Let's create a simple thread that prints a message to the console. Go into your `main.c` file and add the following code: ```c -void *my_first_thread(void *arg) { - /* The argument we receive will not be used */ - (void)arg; +void *my_first_thread(void *arg) +{ + /* The argument we receive will not be used */ + (void)arg; - /* We print a simple message from the thread */ - puts("Hello, from the thread!"); + /* We print a simple message from the thread */ + puts("Hello, from the thread!"); - /* We return NULL to indicate that the thread has finished */ - return NULL; + /* We return NULL to indicate that the thread has finished */ + return NULL; } ``` -![The thread function in Visual Studio Code](img/threads/01_thread_function.png) - This function takes a single argument, a pointer to any data, and prints "Hello, from the thread!" to the console. Now all that is left is to start the thread. @@ -56,26 +55,25 @@ The stack size can vary depending on the complexity of your thread. For example, depending of the amount of local variables you use, the stack size might need to be larger. -Lets define the stack as a global variable: +Let's define the stack as a global variable: ```c char my_thread_stack[THREAD_STACKSIZE_MAIN]; ``` -![The thread stack in Visual Studio Code](img/threads/02_stack.png) - Lastly, we need to actually start the thread. Go into your `main` function and include the following code: ```c -int main(void) { - /* Create a thread with the stack we defined above */ - thread_create(my_thread_stack, sizeof(my_thread_stack), - THREAD_PRIORITY_MAIN - 1, 0, my_first_thread, NULL, - "My first thread"); +int main(void) +{ + /* Create a thread with the stack we defined above */ + thread_create(my_thread_stack, sizeof(my_thread_stack), + THREAD_PRIORITY_MAIN - 1, 0, my_first_thread, NULL, + "My first thread"); - /* The main thread can continue doing its work (e.g., printing a message) */ - puts("Hello, from the main thread!"); + /* The main thread can continue doing its work (e.g., printing a message) */ + puts("Hello, from the main thread!"); } ``` @@ -88,6 +86,43 @@ int main(void) { - `NULL`: The argument for the thread function - `"My first thread"`: The name of the thread +The final code should now look like this: + +```c title="main.c" {5-9, 25-31} +#include + +#include "thread.h" + +/* + * Define a stack for the thread. + * The size of the stack is defined by THREAD_STACKSIZE_MAIN. + */ +char my_thread_stack[THREAD_STACKSIZE_MAIN]; + +void *my_first_thread(void *arg) +{ + /* The argument we receive will not be used */ + (void)arg; + + /* We print a simple message from the thread */ + puts("Hello, from the thread!"); + + /* We return NULL to indicate that the thread has finished */ + return NULL; +} + +int main(void) +{ + /* Create a thread with the stack we defined above */ + thread_create(my_thread_stack, sizeof(my_thread_stack), + THREAD_PRIORITY_MAIN - 1, 0, my_first_thread, NULL, + "My first thread"); + + /* The main thread can continue doing its work (e.g., printing a message) */ + puts("Hello, from the main thread!"); +} +``` + ## Step 3: Building and Running the Program Now that we have created our thread, we can build and run our program. diff --git a/doc/guides/c_tutorials/timers.md b/doc/guides/c_tutorials/timers.md index 70081b2a6c..00a9cd9ae4 100644 --- a/doc/guides/c_tutorials/timers.md +++ b/doc/guides/c_tutorials/timers.md @@ -1,6 +1,6 @@ --- title: Timers and Callbacks -description: This tutorial explains how to use timers and callbacs in RIOT. +description: This tutorial explains how to use timers and callbacks in RIOT. code_folder: examples/guides/timers/ --- @@ -50,7 +50,7 @@ also use soon. Using `ztimer_sleep(ZTIMER_SEC, 5);` we simply wait for around But what if we want to do something else while waiting for the timer to expire? Let's take a closer look at how we can use timers in RIOT. -### Step 1.1: Creating a Callback +### Step 1: Creating a Callback Timers are a way to schedule tasks to be executed at a later time. In RIOT, you have to tell the timers two things: @@ -61,12 +61,13 @@ Lets start by creating the callback that the timer will call when it expires. Go into your `main.c` file and add the following code: ```c -void timer_callback(void *arg) { - /* Cast the received pointer "arg" to a C String type */ - char *message = (char *)arg; +void timer_callback(void *arg) +{ + /* Cast the received pointer "arg" to a C String type */ + char *message = (char *)arg; - /* Print the message */ - puts(message); + /* Print the message */ + puts(message); } ``` @@ -75,15 +76,16 @@ and prints the string to the console. Congrats, you have created a callback func now all that is left is to create the timer and schedule it. To do that lets restructure our `main` function to use the timer. -### Step 1.2: Scheduling the Timer +### Step 2: Scheduling the Timer Go into your `main` function and include the following code: ```c -int main(void) { - /* Create a timer */ - ztimer_t timer = {.callback = timer_callback, - .arg = "3 seconds have passed!"}; +int main(void) +{ + /* Create a timer */ + ztimer_t timer = { .callback = timer_callback, + .arg = "3 seconds have passed!" }; ``` This code creates a timer and initializes it with the callback function we @@ -92,15 +94,15 @@ Now all that is left is to actually start the timer. To do that, we need to simply call the `ztimer_set` function with the timer we created as an argument. ```c - /* Set the timer to fire in 3 seconds */ - ztimer_set(ZTIMER_SEC, &timer, 3); + /* Set the timer to fire in 3 seconds */ + ztimer_set(ZTIMER_SEC, &timer, 3); ``` This code tells the timer to fire in 3 seconds. The first argument specifies which type of clock we want to use, the second argument is the timer we created, and the third argument is the time in seconds. -### Step 1.3: Running the Program +### Step 3: Running the Program Now that we have created the timer and scheduled it, we can run the program. Compile the program using `make` and flash it to your board using `make flash`. @@ -108,20 +110,55 @@ If you look into the terminal via `make term` you should see the message "3 seconds have passed!" printed to the console after 3 seconds. That's all there is to it! You have successfully used a timer in RIOT. + +![The output](img/timers/01_output.png) + Now you can do other things while waiting for the timer to expire, instead of constantly checking if the timer has expired. For example, lets use our knowledge from before to let the main thread go to sleep for 5 seconds and then print a message. -![The output](img/timers/01_output.png) - ```c - /* Sleep for 5 seconds */ - ztimer_sleep(ZTIMER_SEC, 5); + /* Sleep for 5 seconds */ + ztimer_sleep(ZTIMER_SEC, 5); - puts("5 seconds have passed!"); + puts("5 seconds have passed!"); - return 0; + return 0; +``` + +The final code should now look like this: + +```c title="main.c" +#include + +#include "ztimer.h" + +void timer_callback(void *arg) +{ + /* Cast the received pointer "arg" to a C String type */ + 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; +} ``` ## Conclusion diff --git a/doc/guides/c_tutorials/using_cpp.md b/doc/guides/c_tutorials/using_cpp.md index 6e6a71d4ec..481c1f450f 100644 --- a/doc/guides/c_tutorials/using_cpp.md +++ b/doc/guides/c_tutorials/using_cpp.md @@ -3,7 +3,7 @@ title: Using C++ in RIOT description: This document explains how to use C++ in RIOT, including levels of support and requirements for C++ code. --- -# Levels of Support +## Levels of Support A CPU in RIOT can have three levels of support for C++ code: @@ -21,7 +21,7 @@ can be one (or more) of the following: (such as constructor guards for the thread safe initialization of statically allocated instances) or hooks in the startup process to perform initialization -# Using C++ +## Using C++ In order for C++ code to compile with RIOT, the following needs to be done: diff --git a/doc/guides/managing-a-release/README.md b/doc/guides/misc/managing-a-release.md similarity index 91% rename from doc/guides/managing-a-release/README.md rename to doc/guides/misc/managing-a-release.md index 3378759257..a4f801e9b2 100644 --- a/doc/guides/managing-a-release/README.md +++ b/doc/guides/misc/managing-a-release.md @@ -3,19 +3,19 @@ title: Managing a Release description: This page describes the process of managing a release. --- -# Contents +## Contents -1. [Checklist](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#1-checklist) -2. [Preparation](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#2-preparation) -3. [Feature Freeze and Testing](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#3-feature-freeze-and-testing) -4. [Drafting Release Notes](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#4-Drafting-Release-Notes) -5. [Actual Release](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#5-actual-release) -6. [Other Repositories](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#6-Other-repositories) -7. [Important Fixes after Release](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#7-important-fixes-after-release) -8. [Resources](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#8-resources) -9. [Forum post templates](https://github.com/RIOT-OS/RIOT/wiki/Managing-a-Release#9-forum-post-templates) +1. [Checklist](#1-checklist) +2. [Preparation](#2-preparation) +3. [Feature Freeze and Testing](#3-feature-freeze-and-testing) +4. [Drafting Release Notes](#4-drafting-release-notes) +5. [Actual Release](#5-actual-release) +6. [Other Repositories](#6-other-repositories) +7. [Important Fixes after Release](#7-important-fixes-after-release) +8. [Resources](#8-resources) +9. [Forum post templates](#9-forum-post-templates) -# 1. Checklist +## 1. Checklist Steps marked with a :scroll: icon can also be automated with the release manager script. @@ -31,7 +31,7 @@ Steps marked with a :scroll: icon can also be automated with the release manager - [ ] Go through list of deprecated features and make sure pending removals are applied - [ ] Familiarise with release specs and tests, incl open issues, deprecations, api changes, and PRs -**Soft feature freeze** +**Soft Feature Freeze** - [ ] Post about soft feature freeze to the forum - [ ] Check that there are no pending Rust changes (`find -name Cargo.toml -exec cargo update --manifest-path "{}" --package riot-wrappers --package riot-sys ";"` should be a no-op), otherwise poke Rust using maintainers - [ ] Familiarise with nearly-merged, high impact PRs, and contact the contributors to ask them to hold @@ -57,7 +57,7 @@ Do the below actions iteratively, generating new release candidates, until all r - [ ] Inform about the release on the forum - [ ] Update the [release statistics](https://github.com/RIOT-OS/RIOT/wiki/release-statistics) -# 2. Preparation +## 2. Preparation A good time to start preparing for the release is two months before the intended release date. Keep track of open pull requests and issues, especially of those marked with the Milestone label for the imminent release. This is a good time to clean up the GitHub repository and get rid of outdated, redundant or already fixed pull requests and issues. @@ -71,7 +71,7 @@ GitHub's [hub](https://github.com/github/hub) command line tool is useful to col Also review PRs tagged for the milestone that have not been updated in a long time. This state arises when a PR was tagged for a particular milestone, but was not merged in time and so the release manager tagged it for the _next_ milestone. As a guideline, if a PR already has been tagged for three milestones, then simply remove the milestone rather than advancing it to the next. After this removal, either the PR gets some attention or the stale bot eventually will close it. -# 3. Feature Freeze and Testing +## 3. Feature Freeze and Testing There are two feature freezes: soft and hard. @@ -82,21 +82,21 @@ Hard feature freeze is the date at which the release branch gets created. When h Any bugfixes should be merged into RIOT master and backported into the release branch by creating an identical PR against it. The backport_pr tool in the RIOT repo can be used to do this automatically. To coordinate testing, you can use the checkboxes and the discussion in the release candidate's issue, and/or the release tracking spreadsheet, at your discretion. Once all bugfixes addressing test failures have been merged and backported, a new release candidate is generated and testing begins again. This happens iteratively until we get a release candidate which passes all the tests without any further bugfixes. As there are "always" known issues, and deadlines need to be satisfied, it is possible to abstain at some point from backporting and re-testing iteratively, and list the issue as known in the release notes. -## Automatic freezing and release candidate generation +### Automatic Freezing and Release Candidate Generation First create a [classic Token](https://github.com/settings/tokens) and supply it to the `riot-release-manager` script with the `-t ` parameter. -**Feature freeze:** +**Feature Freeze:** ```bash riot-release-manager feature-freeze yyyy.mm ``` -**Generating a new release candidate:** +**Generating a new Release Candidate:** ```bash riot-release-manager rc yyyy.mm ``` -## Manual freezing and release candidate generation +### Manual Freezing and Release Candidate Generation Even if you're using the release manager script, it's worth reading this section so you know what's going on. @@ -115,18 +115,18 @@ In the RIOT [Release Specs](https://github.com/RIOT-OS/Release-Specs/issues) rep When generating a new release candidate, the release candidate needs to be tagged, a new issue needs to be created in the [Release Specs repository](https://github.com/RIOT-OS/Release-Specs/issues) and testing starts from the beginning (as described above). -# 4. Drafting Release Notes +## 4. Drafting Release Notes -## Automatic draft release note generation +### Automatic Draft Release Note Generation -**Setting milestones :** +**Setting Milestones :** This allows the release-notes script to understand which PRs were merged for this release. ```bash riot-release-manager set-milestones yyyy.mm --execute ``` -**Draft release notes :** +**Draft Release Notes :** ```bash riot-release-manager release-notes yyyy.mm ``` @@ -135,11 +135,11 @@ Then review the output to sort potential mismatch in categories where different A key part of the notes, however, is the selected highlights, which are not be generated automatically, and which you must draft manually. -## Manually drafting release note +### Manually Drafting Release Note Obviously, you can also choose to do the above by hand. -# 5. Actual Release +## 5. Actual Release Once a release candidate passed all tests you are ready to create the release notes. Open an etherpad and list new features, major improvements and features as well as known issues as done in [previous releases](https://github.com/RIOT-OS/RIOT/blob/master/release-notes.txt). Make sure the line length is about 90 characters. You should share this pad with other maintainers and give them some time for review. Alternatively you can open a pull request with your notes and discuss there. But the former has proven well so far. @@ -158,7 +158,7 @@ We maintain a Release statistic where you should add numbers from the previously After you have released, be sure to inform all RIOTers about the release via mail on all lists and RIOT forum (under Announcements). -## Automatic releasing +### Automatic Releasing Run the command @@ -166,7 +166,7 @@ Run the command riot-release-manager release yyyy.mm ``` -## Manual releasing +### Manual Releasing Again, it's worth reading this section even if you're using the release manager tool. @@ -174,11 +174,11 @@ Tag this release as you did for the release candidate, except that you should si Now that everything is ready, create the release. This can easily be done via GitHubs web interface. In the [RIOT](https://github.com/RIOT-OS/RIOT) repository click on *Releases->Draft a new release*. Assign the tag you previously created and signed, set title `RIOT- and paste the release notes below. Et voilà, that's the release. -# 6. Other repositories +## 6. Other Repositories Don't forget to update the submodule in the [applications repository](https://github.com/RIOT-OS/applications) and [Tutorials repository](https://github.com/RIOT-OS/Tutorials) and test if the applications still work. -# 7. Important Fixes after Release +## 7. Important Fixes after Release After the release, issues may arise that are important enough to warrant an update to the release. As a first step, such issues should be backported to the release branch. If a single issue represents a critical fix, or if a number of lesser backported issues accumulate, then a bugfix or point release should be created. @@ -186,7 +186,7 @@ For example, after the 2019.10 release [#12653](https://github.com/RIOT-OS/RIOT/ A point release for a critical issue is best limited to a small number of changes to the original release to reduce the amount of testing required and also reduce the introduction of new bugs. We do not have a policy on who should manage a point release, but the previous release manager at least should consult on the point release since they are most familiar with the previous release. -# 8. Resources +## 8. Resources | Description | Location | |-------------|----------| @@ -201,11 +201,11 @@ A point release for a critical issue is best limited to a small number of change | Release test tracking spreadsheet | https://drive.google.com/open?id=0B384VtEXbD_HRzJSY1NGdnFpWERxb2JFeGdaS09iUjV0TGhN | -# 9. Forum post templates +## 9. Forum Post Templates These templates are suggestions, if useful. Whatever the phrasing, posts with similar content should be made to the forum at various stages of the release process. -## Date announcement and feature request +### Date Announcement and Feature Request **Subject** Release [YYYY.MM] - dates and feature requests @@ -230,7 +230,7 @@ Best regards, and happy hacking! [Name] ``` -## Soft feature freeze announcement +### Soft Feature Freeze Announcement **Subject** Release [YYYY.MM] - Soft feature freeze now effective @@ -246,7 +246,7 @@ Wishing you a happy code/polish/review/merge sprint, [Name] ``` -## Hard feature freeze announcement +### Hard Feature Freeze Announcement **Subject** Release [YYYY.MM] - Hard feature freeze now effective @@ -277,7 +277,7 @@ Best regards, [2] https://github.com/RIOT-OS/Release-Specs#pytest-runner ``` -### Release announcement +#### Release Announcement **Subject** Release [YYYY.MM] diff --git a/doc/guides/misc/release_cycle.md b/doc/guides/misc/release_cycle.md index d605ee6586..c5b957880e 100644 --- a/doc/guides/misc/release_cycle.md +++ b/doc/guides/misc/release_cycle.md @@ -16,7 +16,7 @@ are backported from `master` to the release branch, and new release candidates m when certain milestones are reached. Once all major bugs are fixed, the new RIOT release is signed off by the appointed release manager, typically within 2 weeks after the feature freeze. For more details and instructions for release managers, see the -[managing a release guide](https://github.com/RIOT-OS/RIOT/tree/master/doc/guides/managing-a-release). +[managing a release guide](https://guide.riot-os.org/misc/managing-a-release/). RIOT follows a rolling release cycle, meaning support and bug fixes are only provided for the most current release. diff --git a/doc/guides/misc/roadmap.md b/doc/guides/misc/roadmap.md index 1707107b1f..ce82a0ac7d 100644 --- a/doc/guides/misc/roadmap.md +++ b/doc/guides/misc/roadmap.md @@ -8,7 +8,7 @@ For each area, some near-future plans and concrete next steps are indicated. The text and items below are tentative, up for discussion, to be updated by regular pull requests. -# Network Stack High Layers +## Network Stack High Layers (contact/steering: [Martine](https://github.com/miri64)) - ICN stack support clean-up @@ -20,19 +20,19 @@ The text and items below are tentative, up for discussion, to be updated by regu - [ ] in legacy networks (eg. by means of tunneling) - [ ] with configurable on-by-default fallbacks -# Network Stack Low Layers +## Network Stack Low Layers (contact/steering: [Peter](https://github.com/PeterKietzmann)) - Point-to-Point Protocol (PPP): finalize and merge `gnrc_ppp` -# Integrations +## Integrations (contact/steering: [Teufelchen](https://github.com/teufelchen1)) - [Home-Assistant](https://www.home-assistant.io/) BTHome integration - [Home-Assistant](https://www.home-assistant.io/) integration via [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt#mqtt-discovery) -# Power Modes +## Power Modes (contact/steering: [benpicco](https://github.com/benpicco)) - concept to fix shell usage issue while LPM activated @@ -42,17 +42,17 @@ The text and items below are tentative, up for discussion, to be updated by regu -# Peripheral Drivers +## Peripheral Drivers (contact/steering: [maribu](https://github.com/maribu)) -## Timers +### Timers (contact/steering: [kaspar030](https://github.com/kaspar030), [benpicco](https://github.com/benpicco), [maribu](https://github.com/maribu)) - cleanup and unification of low-level timer interfaces (`timer`, `rtt`, `rtc`) - implement capture mode -## SPI +### SPI - introduction of `spi_slave` interface - transition to `spi_clk_t` being the frequency in Hz, not an `enum` constant, to allow arbitrary frequencies @@ -60,12 +60,12 @@ The text and items below are tentative, up for discussion, to be updated by regu - allow a way to detect the actual frequency an SPI bus is running at - see https://github.com/RIOT-OS/RIOT/pull/16727 for one proposal -## I2C +### I2C - introduction of `i2c_slave` interface - see https://github.com/RIOT-OS/RIOT/issues/19560 for a discussion -## GPIO +### GPIO (contact/steering: [gschorcht](https://github.com/gschorcht), [maribu](https://github.com/maribu)) @@ -74,7 +74,7 @@ The text and items below are tentative, up for discussion, to be updated by regu - many MCUs still need an implementation - add a high level API that unifies external and internal GPIOs on top -## ADC +### ADC (contact/steering: [benpicco](https://github.com/benpicco), [kfessel](https://github.com/kfessel), [gschorcht](https://github.com/gschorcht), [maribu](https://github.com/maribu)) @@ -87,7 +87,7 @@ The text and items below are tentative, up for discussion, to be updated by regu -# Software Updates +## Software Updates (contact/steering: [Emmanuel](https://github.com/emmanuelsearch)) - Modularize to provide toolbox supporting other image storing (e.g. support external flash), transport (other than CoAP), crypto (e.g. secure element). @@ -95,14 +95,14 @@ The text and items below are tentative, up for discussion, to be updated by regu -# Documentation +## Documentation (contact/steering: [Emmanuel](https://github.com/emmanuelsearch)) - Write and publish more RDMs -# Low-Level Hardware Support +## Low-Level Hardware Support (contact/steering: [Alex](https://github.com/aabadie)) - radio support for TI SensorTag @@ -110,21 +110,21 @@ The text and items below are tentative, up for discussion, to be updated by regu -# Testing +## Testing (contact/steering: [Kaspar](https://github.com/kaspar030)) - automated network functionality tests (e.g. RPL + UDP/PING tests through border router, multi-hop) in IoTLAB dev sites? -# Security +## Security (contact/steering: [Kaspar](https://github.com/kaspar030)) - RNG unified (secure, or basic), seeding - RIOT default configuration = secure configuration (that's our goal/motto) -## 802.15.4 Link Layer Security +### 802.15.4 Link Layer Security (contact/steering: [chrysn](https://github.com/chrysn)) Current status: RIOT supports application provided keys, diff --git a/doc/starlight/astro.config.mjs b/doc/starlight/astro.config.mjs index 2f529af788..c483f46785 100644 --- a/doc/starlight/astro.config.mjs +++ b/doc/starlight/astro.config.mjs @@ -136,6 +136,7 @@ export default defineConfig({ "misc/io_mapping_and_shields", "misc/roadmap", "misc/release_cycle", + "misc/managing-a-release", "misc/emulators", "misc/terminal_config", "misc/how_to_doc",