Merge pull request #3520 from backenklee/ng_networking-extended-documentation

extended the documentation for the ng_networking example

examples/ng_networking/README.md

@@ -2,18 +2,21 @@
 
 ## Connecting RIOT native and the Linux host
 
-To establish a connection between RIOT and the Linux host, the following dependencies are required:
+> **Note:** RIOT does not support IPv4, so you need to stick to IPv6 anytime. To establish a connection between RIOT and the Linux host,
+you will need `netcat` (with IPv6 support). Ubuntu 14.04 comes with netcat IPv6 support pre-installed. On Debian it's available in the
+package `netcat-openbsd`. Be aware that many programs require you to add an option such as -6 to tell them to use IPv6, otherwise they
+will fail. If you're using a _Raspberry Pi_, run `sudo modprobe ipv6` before trying this example, because raspbian does not load the
+IPv6 module automatically.  
+On some systems (openSUSE for example), the _firewall_ may interfere, and prevent some packets to arrive at the application (they will
+however show up in Wireshark, which can be confusing). So be sure to adjust your firewall rules, or turn it off (who needs security anyway).
 
-* netcat (with IPv6 support)
-
-Ubuntu 14.04 comes with netcat IPv6 support pre-installed. On Debian it's available in the package `netcat-openbsd`.
-
-After installing, create a tap interface (to which RIOT will connect) and a bridge (to which Linux will connect):
+First, create a tap interface (to which RIOT will connect) and a bridge (to which Linux will connect):
 
     sudo ip tuntap add tap0 mode tap user ${USER}
     sudo ip link set tap0 up
 
-Now you can start the `ng_networking` example by invoking `make term`. This should automatically connect to the `tap0` interface.
+Now you can start the `ng_networking` example by invoking `make term`. This should automatically connect to the `tap0` interface. If
+this doesn't work for some reason, run `make` without any arguments, and then run the binary manually like so (assuming you are in the `examples/ng_networking` directory):
 
 To verify that there is connectivity between RIOT and Linux, go to the RIOT console and run `ifconfig`:
 
@@ -23,7 +26,7 @@ To verify that there is connectivity between RIOT and Linux, go to the RIOT cons
     inet6 addr: fe80::ccf5:e1ff:fec5:f75a/64  scope: local
     inet6 addr: ff02::1:ffc5:f75a/128  scope: local [multicast]
 
-Copy the link-local address of the RIOT node (prefixed with `fe80`) and try to ping it **from the Linux node**:
+Copy the [link-local address](https://en.wikipedia.org/wiki/Link-local_address) of the RIOT node (prefixed with `fe80`) and try to ping it **from the Linux node**:
 
     ping6 fe80::ccf5:e1ff:fec5:f75a%tap0
 
@@ -38,6 +41,8 @@ Now, on the Linux host, you can run netcat to connect with RIOT's UDP server:
 
     nc -6uv fe80::ccf5:e1ff:fec5:f75a%tap0 8808
 
+The `-6` option is necessary to tell netcat to use IPv6 only, the `-u` option tells it to use UDP only, and the `-v` option makes it give more verbose output (this one is optional).
+
 You should now see that UDP messages are received on the RIOT side. Opening a UDP server on the Linux side is also possible. Do do that, write down the IP address of the host (run on Linux):
 
     ifconfig tap0
@@ -49,10 +54,13 @@ You should now see that UDP messages are received on the RIOT side. Opening a UD
             collisions:0 txqueuelen:0
             RX bytes:488 (488.0 B)  TX bytes:3517 (3.5 KB)
 
-Then open a UDP server on Linux:
+Then open a UDP server on Linux (the `-l` option makes netcat listen for incoming connections):
 
     nc -6ul 8808
 
 Now, on the RIOT side, send a UDP packet using:
 
     udp send fe80::4049:5fff:fe17:b3ae 8808 testmessage
+
+You should see `testmessage` appear in netcat. Instead of using netcat, you can of course write your own software, but you may have to bind the socket to a specific interface (tap0 in this case). For an example that shows how to do so, see [here](https://gist.github.com/backenklee/dad5e80b764b3b3d0d3e).
+