Merge pull request #3886 from authmillenon/examples/feat/border_router

examples: provide example application for a 6LoWPAN border router

examples/gnrc_border_router/Makefile

@@ -0,0 +1,54 @@
+# name of your application
+APPLICATION = gnrc_border_router
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= samr21-xpro
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../..
+
+BOARD_INSUFFICIENT_MEMORY := airfy-beacon nrf51dongle nrf6310 pca10000 pca10005 nucleo-f334 \
+                             spark-core stm32f0discovery yunjia-nrf51822
+
+BOARD_BLACKLIST := arduino-mega2560     # panic_arch not defined
+
+ifeq (,$(SLIP_UART))
+  # set default (last available UART)
+  SLIP_UART="(UART_NUMOF-1)"
+endif
+ifeq (,$(SLIP_BAUDRATE))
+  # set default
+  SLIP_BAUDRATE=115200
+endif
+
+GNRC_NETIF_NUMOF := 2
+INCLUDES += -I$(CURDIR)
+CFLAGS += -DSLIP_UART=$(SLIP_UART)
+CFLAGS += -DSLIP_BAUDRATE=$(SLIP_BAUDRATE)
+
+# Include packages that pull up and auto-init the link layer.
+# NOTE: 6LoWPAN will be included if IEEE802.15.4 devices are present
+USEMODULE += gnrc_netif_default
+USEMODULE += auto_init_gnrc_netif
+# Include SLIP package for IP over Serial communication
+USEMODULE += gnrc_slip
+# Specify the mandatory networking modules for 6LoWPAN border router
+USEMODULE += gnrc_sixlowpan_border_router_default
+# Add forwarding table
+USEMODULE += fib
+# Additional networking modules that can be dropped if not needed
+USEMODULE += gnrc_icmpv6_echo
+# 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:
+CFLAGS += -DDEVELHELP
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+include $(RIOTBASE)/Makefile.include

examples/gnrc_border_router/README.md

@@ -0,0 +1,62 @@
+# gnrc_networking_border_router example
+
+## Requirements
+
+In order to setup a 6LoWPAN border router on RIOT, you need either a board that
+offers an IPv6 capable network interface (e.g. the `encx24j600` Ethernet chip)
+or connect it over the serial interface to a Linux host and use the SLIP
+standard [1]. The example application in this folder assumes as a default to be
+run on an Atmel SAM R21 Xplained Pro evaluation board using an external UART
+adapter for the second serial interface. However, it is feasible to run the
+example on any RIOT supported platform that offers either more than one UART or
+be equipped with an IPv6 capable network device. In this case only the Makefile
+of this application has to be slightly modified (e.g. by replacing the line
+```
+USEMODULE += gnrc_slip
+```
+by something like
+```
+USEMODULE += encx24j600
+```
+and specify the target platform as `BOARD = myplatform`.
+In order to use the border router over SLIP, please check the `periph_conf.h`
+of the corresponding board and look out for the `UART_NUMOF` parameter. Its
+value has to be bigger than 1.
+
+## Configuration
+
+In order to connect a RIOT 6LoWPAN border router over SLIP you run a small
+program called tunslip (imported from Contiki) [2] on the Linux host. The
+program can be found in the `dist/tools/tunslip` folder and has to be compiled
+before first use (simple calling `make` should be enough). Now one can start
+the program, by calling something like:
+```bash
+cd dist/tools/tunslip
+make
+sudo ./tunslip6 affe::1/64 -t tun0 -s /dev/ttyUSB0
+```
+Assuming that `/dev/ttyUSB0` is the device descriptor for the (additional) UART
+interface of your RIOT board.
+
+On the RIOT side you have to configure the SLIP interface by configuring a
+corresponding IPv6 address, e.g.
+```
+ifconfig 6 add affe::2
+```
+and adding the SLIP interface to the neighbor cache (because Linux won't
+respond to neighbor solicitations on an interface without a link-layer address)
+by calling
+```
+ncache add 6 affe::1
+```
+After this you're basically done and should be able to ping between the border
+router and the outside world (assuming that the Linux host is properly
+forwarding your traffic).
+
+Additionally, you can configure IPv6 addresses on the 6LoWPAN interface for
+communication with other 6LoWPAN nodes. See also the `gnrc_networking` example
+for further help.
+
+[1] https://tools.ietf.org/html/rfc1055
+
+[2] https://github.com/contiki-os/contiki/blob/master/tools/tunslip.c

examples/gnrc_border_router/main.c

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2015 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       Example application for demonstrating the RIOT network stack
+ *
+ * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+#include "shell.h"
+
+int main(void)
+{
+    puts("RIOT border router example application");
+
+    /* start shell */
+    puts("All up, running the shell now");
+    char line_buf[SHELL_DEFAULT_BUFSIZE];
+    shell_run(NULL, line_buf, SHELL_DEFAULT_BUFSIZE);
+
+    /* should be never reached */
+    return 0;
+}

examples/gnrc_border_router/slip_params.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2015 Martine Lenders <mlenders@inf.fu-berlin.de>
+ *
+ * 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 tests
+ * @{
+ *
+ * @file
+ * @brief   slip parameters example, used by auto_init_gnrc_netif
+ *
+ * @author  Martine Lenders <mlenders@inf.fu-berlin.de>
+ */
+
+#ifndef SLIP_PARAMS_H
+#define SLIP_PARAMS_H
+
+#include "net/gnrc/slip.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static gnrc_slip_params_t gnrc_slip_params[] = {
+    {
+        .uart = SLIP_UART,
+        .baudrate = SLIP_BAUDRATE,
+    },
+};
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* SLIP_PARAMS_H */
+/** @} */