From 10b63585ea552d43925836fe010034f2d68d45ee Mon Sep 17 00:00:00 2001 From: AnnsAnn Date: Tue, 12 Nov 2024 10:01:55 +0100 Subject: [PATCH] examples/readme: Improve clarity and adjust categories examples/readme: fix SAUL spelling mistake examples/readme: Link to README.md instead of folder examples/readme: increase title size examples/readme: make networking category name a bit clearer examples/readme: move nimble to own category within BLE examples/readme: move dtls to own category examples/readme: move heart rate sensor to nimble category examples/readme: move arduino sketch to languages examples/timer_periodic: fix file name issue examples/readme: change level wording about nanocoap --- examples/README.md | 177 ++++++++++++----------- examples/timer_periodic_wakeup/README.md | 11 ++ examples/timer_periodic_wakeup/README:md | 44 ------ 3 files changed, 102 insertions(+), 130 deletions(-) create mode 100644 examples/timer_periodic_wakeup/README.md delete mode 100644 examples/timer_periodic_wakeup/README:md diff --git a/examples/README.md b/examples/README.md index 49ced17cc1..f8c6149f97 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,180 +6,185 @@ Each example contains a `README.md` that provides information and instructions h Here is a quick overview of the examples available in the RIOT: -### The Essentials +## The Essentials -- [default](./default) +- [default](./default/README.md) - This application is a showcase for RIOT's hardware support. Using it for your board, you should be able to interactively use any hardware that is supported. -- [hello-world](./hello-world) +- [hello-world](./hello-world/README.md) - A simple "Hello World" that shows the basic structure of a RIOT application. -- [blinky](./blinky) +- [blinky](./blinky/README.md) - The classic "Hello World" example for embedded systems: blinking an LED (or printing "Blink!" via stdio when none are available). -- [leds_shell](./leds_shell) +- [leds_shell](./leds_shell/README.md) - The application `leds_shell` is a basic example, which allows easy, interactive control of internal board LEDs, and basic GPIO for externally connected simple devices (for e.g. additional LEDs, relay, motors - via dedicated drivers, etc.) via the shell. -- [saul](./saul) - - This example demonstrates the usage of the SAUL (Sensor Abstraction Layer User) module. -- [timer_periodic_wakeup](./timer_periodic_wakeup) +- [saul](./saul/README.md) + - This example demonstrates the usage of the SAUL (Sensor Actuator Uber Layer) module. +- [timer_periodic_wakeup](./timer_periodic_wakeup/README.md) - How to set up a periodic wakeup timer using the RIOT operating system. -- [ipc_pingpong](./ipc_pingpong) +- [ipc_pingpong](./ipc_pingpong/README.md) - This example is to illustrate the usage of RIOTs IPC messaging system. -- [filesystem](./filesystem) +- [filesystem](./filesystem/README.md) - This example showcases ways to interact/manage the filesystem in RIOT. -#### RIOT Language Bindings +### RIOT Language Bindings -##### Officially Supported/Targeted +#### Officially Supported/Targeted -###### _Rust_ +##### _Rust_ -- [rust-hello-world](./rust-hello-world) +- [rust-hello-world](./rust-hello-world/README.md) - This example demonstrates how to write a simple RIOT application in Rust. -- [rust-gcoap](./rust-gcoap) +- [rust-gcoap](./rust-gcoap/README.md) - This example demonstrates how to write a coap server application in Rust using the RIOTs gcoap module. -- [rust-async](./rust-async) +- [rust-async](./rust-async/README.md) - This example demonstrates how to use Rusts async/await syntax in a RIOT application. -###### _C++_ +##### _C++_ -- [riot_and_cpp](./riot_and_cpp) +- [riot_and_cpp](./riot_and_cpp/README.md) - Example of using C++ in RIOT applications. -##### Community Supported +#### Community Supported -- [javascript](./javascript) +- [javascript](./javascript/README.md) - How to write IoT applications using javascript using JerryScript. -- [lua_basic](./lua_basic) +- [lua_basic](./lua_basic/README.md) - How to write IoT applications using Lua. -- [lua_REPL](./lua_REPL) +- [lua_REPL](./lua_REPL/README.md) - This example demonstrates how to use the Lua Read-Eval-Print Loop (REPL) in RIOT. -- [micropython](./micropython) +- [micropython](./micropython/README.md) - How to use the MicroPython port for RIOT. -- [wasm](./wasm) +- [wasm](./wasm/README.md) - How to use WebAssembly in RIOT. +- [arduino_hello-world](./arduino_hello-world/README.md) + - This application demonstrates the usage of Arduino sketches in RIOT. -### Networking & BLE Examples +## Networking -#### Constraint Application Protocol (CoAP) +### Constraint Application Protocol (CoAP) -- [gcoap](./gcoap) +- [gcoap](./gcoap/README.md) - This example demonstrates the usage of the `gcoap` module, a high-level API for CoAP (Constrained Application Protocol) messaging. -- [gcoap_block_server](./gcoap_block_server) +- [gcoap_block_server](./gcoap_block_server/README.md) - CoAP server handling for Block requests, build with gcoap using nanocoap block handling functions. -- [gcoap_fileserver](./gcoap_fileserver) +- [gcoap_fileserver](./gcoap_fileserver/README.md) - This example demonstrates the usage of the `gcoap` module to serve files over CoAP. -- [gcoap_dtls](./gcoap_dtls) - - This example demonstrates the usage of the `gcoap` module with DTLS. -- [nanocoap_server](./nanocoap_server) - - This example demonstrates the usage of the `nanocoap` module, a low-level API for CoAP (Constrained Application Protocol) messaging. +- [nanocoap_server](./nanocoap_server/README.md) + - This example demonstrates the usage of the `nanocoap` module, a high-level API for CoAP (Constrained Application Protocol) messaging. -#### Bluetooth Low Energy (BLE) +### Bluetooth Low Energy (BLE) -- [nimble_scanner](./nimble_scanner) +#### NimBLE + +- [nimble_scanner](./nimble_scanner/README.md) - This example showcases the usage of the `NimBLE` BLE stack as a scanner. -- [skald_eddystone](./skald_eddystone) - - This example demonstrates the usage of `Skald` for creating an Google `Eddystone` beacon. -- [skald_ibeacon](./skald_ibeacon) - - This example demonstrates the usage of `Skald` for creating an Apple `iBeacon`. -- [nimble_gatt](./nimble_gatt) +- [nimble_gatt](./nimble_gatt/README.md) - This example application configures and runs the NimBLE BLE stack as simple GATT server. -- [nimble_heart_rate_sensor](./nimble_heart_rate_sensor) +- [nimble_heart_rate_sensor](./nimble_heart_rate_sensor/README.md) + - This example demonstrates how to implement asynchronous data transfer using GATT + notifications by implementing a mock-up BLE heart rate sensor. +- [nimble_heart_rate_sensor](./nimble_heart_rate_sensor/README.md) - This example demonstrates how to implement asynchronous data transfer using GATT notifications by implementing a mock-up BLE heart rate sensor. -#### MQTT +#### Misc BLE Examples -- [asymcute_mqttsn](./asymcute_mqttsn) +- [skald_eddystone](./skald_eddystone/README.md) + - This example demonstrates the usage of `Skald` for creating an Google `Eddystone` beacon. +- [skald_ibeacon](./skald_ibeacon/README.md) + - This example demonstrates the usage of `Skald` for creating an Apple `iBeacon`. + +### MQTT + +- [asymcute_mqttsn](./asymcute_mqttsn/README.md) - This application demonstrates the usage of the Asymcute (MQTT-SN) module in RIOT. -- [emcute_mqttsn](./emcute_mqttsn) +- [emcute_mqttsn](./emcute_mqttsn/README.md) - This application demonstrates the usage of the emCute (MQTT-SN) module in RIOT. -- [paho-mqtt](./paho-mqtt) +- [paho-mqtt](./paho-mqtt/README.md) - This example demonstrates the usage of the Paho MQTT client library in RIOT. -#### CoRE Resource Directory +### CoRE Resource Directory -- [cord_ep](./cord_ep) +- [cord_ep](./cord_ep/README.md) - Example of RIOT's Resource Directory (RD) endpoint module, called `cord_ep` -- [cord_lc](./cord_lc) +- [cord_lc](./cord_lc/README.md) - Example of RIOT's Resource Directory (RD) lookup module, called `cord_lc` -- [cord_epsim](./cord_epsim) +- [cord_epsim](./cord_epsim/README.md) - This example shows how a node can register with a CoRE resource directory -#### GNRC Networking +### GNRC Networking -- [gnrc_minimal](./gnrc_minimal) +- [gnrc_minimal](./gnrc_minimal/README.md) - This is a minimalistic example for RIOT's gnrc network stack. -- [gnrc_networking](./gnrc_networking) +- [gnrc_networking](./gnrc_networking/README.md) - This example demonstrates the usage of the GNRC network stack in RIOT. -- [gnrc_networking_subnets](./gnrc_networking_subnets) +- [gnrc_networking_subnets](./gnrc_networking_subnets/README.md) - This example demonstrates IPv6 subnet auto-configuration for networks on a tree topology. -- [gnrc_border_router](./gnrc_border_router) +- [gnrc_border_router](./gnrc_border_router/README.md) - Example of `gnrc_border_router` using automatic configuration -- [gnrc_lorawan](./gnrc_lorawan) +- [gnrc_lorawan](./gnrc_lorawan/README.md) - Send and receive LoRaWAN packets and perform basic LoRaWAN commands -- [gnrc_networking_mac](./gnrc_networking_mac) +- [gnrc_networking_mac](./gnrc_networking_mac/README.md) - This example shows you how to try out communications between RIOT instances with duty-cycled MAC layer protocols -#### Misc +### DTLS -- [lorawan](./lorawan) +- [dtls-sock](./dtls-sock/README.md) + - This example shows how to use DTLS sock `sock_dtls_t` +- [dtls-echo](./dtls-echo/README.md) + - This example shows how to use TinyDTLS with sock_udp. +- [dtls-wolfssl](./dtls-wolfssl/README.md) + - This example demonstrates the usage of the DTLS module with the wolfSSL library.^ + +### Misc + +- [lorawan](./lorawan/README.md) - This application shows a basic LoRaWAN use-case with RIOT. -- [openthread](./openthread) +- [openthread](./openthread/README.md) - This example demonstrates the usage of the OpenThread stack in RIOT. -- [lwm2m](./lwm2m) +- [lwm2m](./lwm2m/README.md) - Example of a LWM2M client on RIOT -- [ccn-lite-relay](./ccn-lite-relay) +- [ccn-lite-relay](./ccn-lite-relay/README.md) - This application demonstrates how to use the Content-Centric Networking stack from [CCN-Lite](http://www.ccn-lite.net/) on RIOT -- [telnet_server](./telnet_server) +- [telnet_server](./telnet_server/README.md) - Simple telnet server that listens on port 23 over IPv6. -- [posix_sockets](./posix_sockets) +- [posix_sockets](./posix_sockets/README.md) - Showcase for RIOT's POSIX socket support -- [spectrum-scanner](./spectrum-scanner) +- [spectrum-scanner](./spectrum-scanner/README.md) - This example demonstrates how to monitor energy levels on all available wireless channels -- [sniffer](./sniffer) +- [sniffer](./sniffer/README.md) - This application is built to run together with the script `./tools/sniffer.py` as a sniffer for (wireless) data traffic. -- [dtls-sock](./dtls-sock) - - This example shows how to use DTLS sock `sock_dtls_t` -- [dtls-echo](./dtls-echo) - - This example shows how to use TinyDTLS with sock_udp. -- [dtls-wolfssl](./dtls-wolfssl) - - This example demonstrates the usage of the DTLS module with the wolfSSL library. -### Advanced Examples +## Advanced Examples -- [bindist](./bindist) +- [bindist](./bindist/README.md) - RIOT allows for creating a "binary distribution", which can be used to ship proprietary, compiled objects in a way that makes it possible to re-link them against a freshly compiled RIOT. This application serves as a simple example. -- [usbus_minimal](./usbus_minimal) +- [usbus_minimal](./usbus_minimal/README.md) - This is a minimalistic example for RIOT's USB stack. -- [suit_update](./suit_update) +- [suit_update](./suit_update/README.md) - This example shows how to integrate SUIT-compliant firmware updates into a RIOT application. -- [thread_duel](./thread_duel) +- [thread_duel](./thread_duel/README.md) - This is a thread duel application to show RIOTs abilities to run multiple-threads concurrently, even if they are neither cooperative nor dividable into different scheduler priorities, by using the optional round-robin scheduler module. -- [posix_select](./posix_select) +- [posix_select](./posix_select/README.md) - This example is a showcase for RIOT's POSIX select support - [psa_crypto](./psa_crypto) - - - Basic functions of the PSA Crypto API- [nimble_heart_rate_sensor](./nimble_heart_rate_sensor) - - This example demonstrates how to implement asynchronous data transfer using GATT - notifications by implementing a mock-up BLE heart rate sensor. - -- [pio_blink](./pio_blink) + - Basic functions of the PSA Crypto API +- [pio_blink](./pio_blink/README.md) - How to use the PIO peripheral on the RaspberryPi Pico to blink an LED. -- [arduino_hello-world](./arduino_hello-world) - - This application demonstrates the usage of Arduino sketches in RIOT. -- [twr_aloha](./twr_aloha) +- [twr_aloha](./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. diff --git a/examples/timer_periodic_wakeup/README.md b/examples/timer_periodic_wakeup/README.md new file mode 100644 index 0000000000..292773a09c --- /dev/null +++ b/examples/timer_periodic_wakeup/README.md @@ -0,0 +1,11 @@ +# Periodic Wakeup Timer Example + +This example demonstrates how to set up a periodic wakeup timer using the RIOT operating system. + +## Overview + +The application sets up a timer that periodically wakes up the system and performs a specific task. This is useful for applications that need to perform regular actions, such as sensor readings or data transmissions. + +## Usage + +Once the application is running, you should see periodic messages indicating that the timer has triggered and the system has woken up to perform its task. diff --git a/examples/timer_periodic_wakeup/README:md b/examples/timer_periodic_wakeup/README:md deleted file mode 100644 index 0cb0e1d081..0000000000 --- a/examples/timer_periodic_wakeup/README:md +++ /dev/null @@ -1,44 +0,0 @@ -# Periodic Wakeup Timer Example - -This example demonstrates how to set up a periodic wakeup timer using the RIOT operating system. - -## Overview - -The application sets up a timer that periodically wakes up the system and performs a specific task. This is useful for applications that need to perform regular actions, such as sensor readings or data transmissions. - -## Requirements - -- RIOT OS -- A supported hardware platform - -## Setup - -1. Clone the RIOT repository: - ```sh - git clone https://github.com/RIOT-OS/RIOT.git - cd RIOT - ``` - -2. Navigate to the example directory: - ```sh - cd examples/timer_periodic_wakeup - ``` - -3. Build the application for your target hardware: - ```sh - make BOARD= - ``` - -4. Flash the application to your hardware: - ```sh - make flash - ``` - -5. Connect to the board's serial console to observe the output: - ```sh - make term - ``` - -## Usage - -Once the application is running, you should see periodic messages indicating that the timer has triggered and the system has woken up to perform its task.