RIOT/pkg/nimble/README.ipv6-over-ble.md

# IPv6-over-BLE: Connecting Linux with RIOT using BLE

This README contains information how to establish an IPv6-over-BLE connection
between Linux and RIOT (using GNRC and NimBLE).

**NOTE 1:** IPv6-over-BLE between RIOT and Linux is **highly experimental** at
the moment and does suffer stability issues!

**NOTE 2:** Currently, Linux does not support 6LoWPAN neighbor discovery (which
RIOT uses per default with BLE), so RIOT needs to be compiled to use stateless
address auto configuration (SLAAC) -> `CFLAGS=-DCONFIG_GNRC_IPV6_NIB_SLAAC=1`.

## Prerequisites

You need a BLE (NimBLE) capable RIOT board (currently only `nrf52`-based boards
are supported), and a Linux host with at least Bluetooth 4.0 capabilities.

Any Linux distribution should do fine, however this guide was tested with the
following:
- Mint 18.3
- Kernel 4.15.0
- bluez 5.37
- [optional] radvd 2.11


## Preparing the RIOT node

First, you compile and flash the `examples/gnrc_networking` application to your
RIOT device. When doing this, make sure to enable SLAAC
(`CFLAGS=-DCONFIG_GNRC_IPV6_NIB_SLAAC=1`), see note above.

Once the firmware is running, you can verify it by typing

    ble info

This should give you some information about your device's BLE address and
status information about open connections. It should look similar to the
following:

    Own Address: UU:VV:WW:XX:YY:ZZ -> [FE80::UUVV:WWFF:FEXX:YYZZ]
     Free slots: 3/3
    Advertising: no
       Contexts:
    [ 0] state: 0x8000 - unused
    [ 1] state: 0x8000 - unused
    [ 2] state: 0x8000 - unused

Once this is working, you need to tell the node to accept incoming connections
and start advertising itself:

    ble adv

That's it, the node can now be seen and connected to from Linux.


## Establishing a connection from Linux

### Preparing Linux

First of all, the Linux kernel needs to be configured to use 6lowpan over BLE.
This needs to be done only once per session and consists of the following steps:

    # Log in as a root user (IMPORTANT, as the following steps will not work
    # using explicit `sudo` for each step...)
    sudo su

    # Mount debugfs file system, already the case on many distributions
    mount -t debugfs none /sys/kernel/debug

    # Load 6LoWPAN module
    modprobe bluetooth_6lowpan

    # Enable the bluetooth 6lowpan module.
    echo 1 > /sys/kernel/debug/bluetooth/6lowpan_enable

Next, we should verify that our Bluetooth device is configured properly:

    # Look for available HCI devices.
    hciconfig

This should show us some information about the available Bluetooth devices. If no
device is listed here, something is wrong...


### Connecting to the RIOT node

When connecting to the RIOT device, you need to know the BLE address of the
device. There are two ways to find out:

a) use `ble info` or `ifconfig` on the RIOT device directly and copy the address

b) use `bluetoothctl` on Linux to scan for the device. Once `bluetoothctl` has
   started, issue `scan on` to start scanning. The default name for the RIOT
   device is set to `RIOT-GNRC`, so you should see it pop up.

c) use `hcitool lescan` on the Linux host (older tool, predecessor of
   `bluetoothctl`...)

Once you have the address, you simply connect Linux to RIOT using the following
command:

    # Put your device address here...
    # Note: the 2 after the address denotes a BLE public random address, default
    #       used by `nimble_netif`
    echo "connect UU:VV:WW:XX:YY:ZZ 2" > /sys/kernel/debug/bluetooth/6lowpan_control

That's it, you now have a IPv6 connection to your RIOT node. You can verify this
using `ifconfig`, where something like the following should be visible:

    bt0       Link encap:UNSPEC  HWaddr 00-19-86-00-16-CA-00-00-00-00-00-00-00-00-00-00
          inet6 addr: fe80::19:86ff:fe00:16ca/64 Scope:Link
          UP RUNNING MULTICAST  MTU:1280  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:18 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:0 (0.0 B)  TX bytes:1624 (1.6 KB)

You should also be able to ping your RIOT node. The devices link local address
is also printed when running `ble info` on your RIOT device.

    # Substitute the actual device address,
    ping fe80::uuvv:wwff:fexx:yyzz%bt0

Now everything should be fine :-)


## [optional] Distributing a routeable Prefix

You can use the Router Advertisement Daemon (`radvd`) in Linux to automatically
distribute prefixes in your BLE network. For the following, you need to make
sure that `radvd` is installed on your Linux host.

As a first step, we need to enable IPv6 forwarding in Linux:

    sudo sysctl -w net.ipv6.conf.all.forwarding=1

Next, we configure `radvd` (`etc/radvc.conf`) by using a configuration like
this:

    interface bt0
    {
        AdvSendAdvert on;
        prefix 2001:db8::/64
        {
            AdvOnLink off;
            AdvAutonomous on;
            AdvRouterAddr on;
        };
        abro 2001:db8::zzyy:xxff:feuu:vvww
        {
            AdvVersionLow 10;
            AdvVersionHigh 2;
            AdvValidLifeTime 2;
        };
    };

This will tell Linux to advertise the prefix `2001:db8::/64`. Do not forget to
substitute the suffix of global address given in the `abro` section
with the one of the BLE device on your Linux host.

**NOTE:** The `abro` section is needed as otherwise the RIOT node will discard
router advertisements, as it is in 6LN configuration
(see https://tools.ietf.org/html/rfc6775#section-4.3).

With this, simply (re-)start the daemon:

    sudo service radvd restart

or

    sudo systemctl restart radvd

Again, that's it. Your RIOT node should now have an address using the above
prefix assigned. Simply verify with `ifconfig` on the RIOT node.

Also you should be able to ping the RIOT node from Linux:

    # make sure to use the actual devices address here...
    ping -I bt0 2001:db8::uuvv:wwff:fexx:yyzz