add initial example applications

Author: leandrolanzieri

.gitignore

@@ -0,0 +1,95 @@
+# Object files
+*.o
+# Target files
+*.elf
+# Documentation artifacts
+doc/doxygen/html
+doc/doxygen/latex
+doc/doxygen/man
+doc/doxygen/*.log
+doc/doxygen/*.db
+doc/doxygen/*.tmp
+# bin (e.g.:build directory) and .bin files
+bin
+*.bin
+# Build directory
+/build
+# AFL findings
+fuzzing/**/findings/
+# Backup files
+*~
+*.orig
+.*.swn
+.*.swo
+.*.swp
+*.save
+*.rej
+\#*\#
+cachegrind.out*
+# Eclipse workspace files
+.project
+.cproject
+.settings
+.idea
+# KDevelop4 project files
+.kdev4
+*.kdev4
+# Codelite (among others) project files
+*.project
+# Visual Studio Code user settings
+.vscode/
+# ctags index files
+tags
+# GDB initialization scripts
+.gdbinit
+
+# Eclipse symbol file (output from make eclipsesym)
+eclipsesym.xml
+/toolchain
+# Ignore created Arduino sketch files
+_sketches.cpp
+
+# local override files
+Makefile.local
+
+# Vagrant
+.vagrant
+
+# clang-complete command line argument lists (Vim: clang-complete, Atom: linter-clang, autocomplete-clang addons)
+.clang_complete
+# YouCompleteMe (https://github.com/Valloric/YouCompleteMe)
+.ycm_extra_conf.py
+
+# Python compiled files
+*.pyc
+
+# Ignore download cache
+.dlcache
+
+# scan-build artifacts
+scan-build/
+
+# compile_and_test_for_boards default "results" directory
+results/
+
+# mypy artifacts
+.mypy_cache/
+
+# Clangd compile flags (language server)
+compile_commands.json
+compile_flags.txt
+
+# cache files of clangd (and probably other tools)
+.cache/
+
+# generated by clang-check for C++ code
+*.plist
+
+# suit manifest keys
+keys/
+
+# clangd language server
+.clangd/
+
+# custom clang-tidy flags, also used when using clangd language server
+.clang-tidy

01-hello-world/Makefile

@@ -0,0 +1,18 @@
+# name of your application
+APPLICATION = hello-world
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= nrf52840dk
+
+# 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

01-hello-world/README.md

@@ -0,0 +1,19 @@
+# Hello World!
+
+This is a basic example how to use RIOT in your embedded application.
+It prints out the famous text `Hello World!`.
+
+This example should foremost give you an overview how to use the Makefile system:
+
+* First you must give your application a name, which is commonly the same as the name of the directory it resides in.
+  Then you can define a default BOARD for which the application was written.
+  By using e.g. `make BOARD=nrf52840dk` you can override the default board.
+
+* The variable `RIOTBASE` contains an absolute or relative path to the directory where you have checked out RIOT.
+  If your code resides in a subdirectory of RIOT, then you can use `$(CURDIR)` as it's done in here.
+
+* The variable `QUIET`, which is either `1` or `0`, defines whether to print verbose compile information, or hide them, respectively.
+
+* The last line of your Makefile must be `include $(RIOTBASE)/Makefile.include`.
+
+The code itself may look like your usual *C* beginners hello-world example.

01-hello-world/main.c

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2014 Freie Universität Berlin
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       Hello World application
+ *
+ * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ * @author      Ludwig Knüpfer <ludwig.knuepfer@fu-berlin.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+int main(void)
+{
+    puts("Hello World!");
+
+    printf("You are running RIOT on a(n) %s board.\n", RIOT_BOARD);
+    printf("This board features a(n) %s MCU.\n", RIOT_MCU);
+
+    return 0;
+}

02-timers/Makefile

@@ -0,0 +1,23 @@
+# name of the application
+APPLICATION = timers-example
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= nrf52840dk
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../RIOT
+
+# required modules
+USEMODULE += ztimer
+USEMODULE += ztimer_msec
+USEMODULE += ztimer_sec
+
+# 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

02-timers/README.md

@@ -0,0 +1,35 @@
+# Simple timer example
+
+In this example we see to fundamental ways of using the timers of your hardware.
+First, we configure a timer to trigger an event that gets executed in the future.
+Second, we use the timer to sleep (block the thread) for a known amount of time.
+
+In order to interact with timers, we need to use the `ztimer` module. To make it
+available to us, we add it to the list of used modules in the application's
+Makefile: `USEMODULE += ztimer`. Depending on the granularity that we want when
+handling time, we can specify different extra modules:
+
+```Makefile
+USEMODULE += ztimer_usec # microsecond precision
+USEMODULE += ztimer_msec # millisecond precision
+USEMODULE += ztimer_sec  # second precision
+```
+
+To learn more about the `ztimer` module, visit the [documentation page](https://doc.riot-os.org/group__sys__ztimer.html).
+
+## Task
+
+Add a new timer to turn LED1 on after 1 second. For this you will need to:
+1. Define a new callback function to execute the task:
+```C
+void led_callback(void *argument)
+{
+    (void) argument; /* we don't use the argument */
+    LED1_ON;         /* turn LED 1 on */
+}
+```
+
+2. Instantiate and configure a new `ztimer_t`. The callback should be `led_callback`. As the
+argument is not used, you can set it to `NULL`.
+
+3. Set the timer to fire in 1 second.

02-timers/main.c

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+#include <stdio.h>
+
+#include "ztimer.h"
+/* needed to manipulate the LEDs */
+#include "board.h"
+
+void message_callback(void *argument)
+{
+    char *message = (char *)argument;
+    puts(message);
+}
+
+int main(void)
+{
+    puts("This is a timers example");
+
+    /* we can configure an event to occur in the future by setting a timer */
+    ztimer_t timeout;                     /* create a new timer */
+    timeout.callback = message_ callback; /* set the function to execute */
+    timeout.arg = "Timeout!";             /* set the argument that the function will receive */
+    ztimer_set(ZTIMER_SEC, &timeout, 2);  /* set the timer to trigger in 2 seconds */
+
+    /* in parallel, we can perform other tasks on this thread */
+    while (1) {
+        /* this blinks an LED twice a second */
+        LED0_TOGGLE;
+        ztimer_sleep(ZTIMER_MSEC, 500);
+    }
+
+    return 0;
+}

04-coap/Makefile

@@ -0,0 +1,45 @@
+# name of your application
+APPLICATION = coap-example
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= nrf52840dk
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../RIOT
+
+# enable default networking devides in the platform
+USEMODULE += netdev_default
+
+# automatically initialize network interfaces for enabled devices
+USEMODULE += auto_init_gnrc_netif
+
+# add minimal IPv6 support
+USEMODULE += gnrc_ipv6_default
+
+# add ICMPv6 support (ping)
+USEMODULE += gnrc_icmpv6_echo
+
+# add CoAP module
+USEMODULE += gcoap
+
+# object dump allows use to print streams of bytes
+USEMODULE += od
+
+# fmt allows use to format strings
+USEMODULE += fmt
+
+USEMODULE += netutils
+# Add also the shell, some shell commands
+USEMODULE += shell
+USEMODULE += shell_commands
+USEMODULE += ps
+
+# 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

04-coap/README.md

@@ -0,0 +1,85 @@
+## About
+
+This application provides command line access to gcoap, a high-level API for
+CoAP messaging. See the [CoAP spec][1] for background, and the
+Modules>Networking>CoAP topic in the source documentation for detailed usage
+instructions and implementation notes.
+
+We support two setup options for this example:
+
+### Native networking
+
+Build with the standard `Makefile`. Follow the setup [instructions][2] for
+the gnrc_networking example.
+
+### SLIP-based border router
+
+Build with `Makefile.slip`. Follow the setup instructions in README-slip.md,
+which are based on the [SLIP instructions][3] for the gnrc_border_router
+example. We also plan to provide or reference the ethos/UHCP instructions,
+but we don't have it working yet.
+
+
+## Example Use
+
+This example uses gcoap as a server on RIOT native. Then we send a request
+from a libcoap example client on the Linux host.
+
+### Verify setup from RIOT terminal
+
+    > coap info
+
+Expected response:
+
+    CoAP server is listening on port 5683
+     CLI requests sent: 0
+    CoAP open requests: 0
+
+### Query from libcoap example client
+
+gcoap does not provide any output to the CoAP terminal when it handles a
+request. We recommend use of Wireshark to see the request and response. You
+also can add some debug output in the endpoint function callback.
+
+    ./coap-client -N -m get -p 5683 coap://[fe80::1843:8eff:fe40:4eaa%tap0]/.well-known/core
+
+Example response:
+
+    v:1 t:NON c:GET i:0daa {} [ ]
+    </cli/stats>
+
+The response shows the endpoint registered by the gcoap CLI example.
+
+### Send query to libcoap example server
+
+Start the libcoap example server with the command below.
+
+    ./coap-server
+
+Enter the query below in the RIOT CLI.
+
+    > coap get fe80::d8b8:65ff:feee:121b%6 5683 /.well-known/core
+
+CLI output:
+
+    gcoap_cli: sending msg ID 743, 75 bytes
+    > gcoap: response Success, code 2.05, 105 bytes
+    </>;title="General Info";ct=0,</time>;if="clock";rt="Ticks";title="Internal Clock";ct=0;obs,</async>;ct=0
+
+
+## Other available CoAP implementations and applications
+
+RIOT also provides package imports and test applications for other CoAP
+implementations:
+
+* [Nanocoap](../nanocoap_server): a very lightweight CoAP server based on the
+  [nanocoap library](https://github.com/kaspar030/sock/tree/master/nanocoap)
+  implementation
+
+* [Microcoap](../../tests/pkg_microcoap): another lightweight CoAP server based
+  on the [microcoap library](https://github.com/1248/microcoap) implementation
+
+
+[1]: https://tools.ietf.org/html/rfc7252    "CoAP spec"
+[2]: https://github.com/RIOT-OS/RIOT/tree/master/examples/gnrc_networking    "instructions"
+[3]: https://github.com/RIOT-OS/RIOT/tree/master/examples/gnrc_border_router    "SLIP instructions"