FIT/IoT-LAB tutorials #

This tutorial illustrates the use of EnOSlib to interact with FIT/IoT-LAB testbed.

Hint

For a complete schema reference see FIT/IoT-LAB Schema

Installation #

We strongly suggest to use a virtual environment to install and run your experiments.

$ python3 -m venv venv/
$ source venv/bin/activate
$ pip install -U pip
$ pip install enoslib[iotlab]

The Iotlab provider is built on top of 2 libraries provided by the FIT/IoT-LAB platform: cli-tools (iot-lab/cli-tools) and ssh-cli-tools (iot-lab/ssh-cli-tools). Underlying, these tools use the REST API to access and manipulate the platform.

To access the REST API, user must be authenticated. These tools relies on the configuration file “.iotlabrc” located at the home directory. It can be created by using the CLI tools, so inside the virtual environment:

iotlab-auth -u USERNAME -p PASSWORD

For more details, read the documentation of iotlab-auth (iotlab-auth -h).

External access#

Pre-requisites: Configure your SSH access to the FIT/IoT-LAB platform (https://www.iot-lab.info/legacy/tutorials/ssh-access/index.html).

To be able to access the A8 nodes from your PC, it’s necessary to configure the proxy ssh accordingly.

Configure you ~/.ssh/config properly, example:

Host *.grenoble.iot-lab.info
ProxyCommand ssh -A <user>@grenoble.iot-lab.info -W "$(basename %h):%p"
User <user>
ForwardAgent yes

Remember to set the site used (e.g. grenoble).

Basic examples #

Getting started tutorial#

This script implements a similar behavior as the getting started tutorial from FIT/IoT-LAB (https://www.iot-lab.info/legacy/tutorials/getting-started-tutorial/index.html).

Requirement: M3 image (tutorial_m3.elf)

The M3 image can be download from the website: https://www.iot-lab.info/testbed/resources/firmware.
It is available at the “Presets tab” under the name iotlab_m3_tutorial.
Download and save it in the same folder as the script.

import logging
import threading
import time

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

stop_reading = False


def reading_thread(serial):
    """
    Reading thread. Continuously read the serial from node.

    Necessary since the getting started tutorial supposes a user interaction
    to send and receive packets at the same time.
    """
    while not stop_reading:
        print(serial.read())


# IoT-LAB provider configuration
provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["sensor", "sender"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 1,
                "image": "tutorial_m3.elf",
            },
            {
                "roles": ["sensor", "receiver"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 1,
                "image": "tutorial_m3.elf",
            },
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
try:
    roles, networks = p.init()
    print(roles)

    sender = roles["sender"][0]
    receiver = roles["receiver"][0]
    with en.IotlabSerial(sender, interactive=True) as s_sender, en.IotlabSerial(
        receiver, interactive=True
    ) as s_receiver:

        # Initializing read thread
        print("Initializing reading thread")
        read_thread = threading.Thread(target=reading_thread, args=(s_receiver,))
        read_thread.start()
        time.sleep(1)

        # Sending packets
        print("Sensor (%s) sending small packet" % sender.address)
        s_sender.write("s")
        time.sleep(1)
        print("Sensor (%s) sending big packet" % sender.address)
        s_sender.write("b")
        time.sleep(1)

        stop_reading = True
        read_thread.join()

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

The test creates a thread to read serial while the test ask the sensor to send messages. We don’t recommend doing this in your tests. Anyway, this is necessary in this example since the getting started tutorial supposes the user interaction.

You can launch the script using :

$ python tuto_iotlab_getting_started.py

Using A8 nodes#

This script shows how to use the A8 node available in the platform. They have a Linux OS installed, so we can access them through SSH and run simple linux commands.

import json
import logging
import sys

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

# IoT-LAB provider configuration
provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["my_a8"],
                "archi": "a8:at86rf231",
                "site": "grenoble",
                "number": 2,
            }
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
try:
    roles, networks = p.init()
    roles = en.sync_info(roles, networks)
    print(roles)
    print("A8 nodes have a simple linux OS. We can run 'date' command in them.")
    result = en.run_command(command="date", pattern_hosts="my_a8*", roles=roles)
    print("Results:")
    json.dump(result["ok"], sys.stdout, indent=2)
    json.dump(result["error"], sys.stderr, indent=2)

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

Note that the Linux version installed on nodes has limited capabilities.

You can launch the script using :
$ python tuto_iotlab_a8_basic.py

Using RPi nodes#

This script shows how to use the RPI node available in the platform. They have a Linux OS installed, so we can access them through SSH and run simple linux commands.

import json
import logging
import sys

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

# IoT-LAB provider configuration
provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["my_rpi"],
                "archi": "rpi3:at86rf233",
                "site": "grenoble",
                "number": 2,
            }
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
roles, networks = p.init()
roles = en.sync_info(roles, networks)
print(roles)
print("RPis nodes have a simple linux OS. We can run 'date' command in them.")
result = en.run_command(command="date", roles=roles)
print("Results:")
json.dump(result.to_dict(), sys.stdout, indent=2)

Note

Note that the Linux version installed on nodes has limited capabilities.

You can launch the script using :
$ python tuto_iotlab_rpi_basic.py

Advanced examples #

Monitor M3 consumption#

Simple example of using the monitoring tools in FIT/IoT-LAB testbed.

This script implements a similar behavior as the “Monitor the consumption of M3 node during an experiment” (https://www.iot-lab.info/legacy/tutorials/monitoring-consumption-m3/index.html).

Requirement: M3 image (tutorial_m3.elf)

The M3 image can be download from the website: https://raw.githubusercontent.com/wiki/iot-lab/iot-lab/firmwares/tutorial_m3.elf
Download and rename it properly, saving in the same folder as the script.

import logging
import time

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["sensor"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 1,
                "image": "tutorial_m3.elf",
                "profile": "test_profile",
            },
        ]
    },
    "monitoring": {
        "profiles": [
            {
                "name": "test_profile",
                "archi": "m3",
                "consumption": {
                    "current": True,
                    "power": True,
                    "voltage": True,
                    "period": 8244,
                    "average": 4,
                },
            }
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
try:

    roles, networks = p.init()
    print(roles)

    print("Running experiment for 60s")
    time.sleep(60)

    print("Collecting experiment data")
    p.collect_data_experiment()  # collect experiment data

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

The monitoring files are compressed and saved in the current folder.

You can launch the script using :
$ python tuto_iotlab_m3_consumption.py
Finally, you can evaluate and plot the results as done in the tutorial. It uses the plot_oml_consum tool (Available at: iot-lab/oml-plot-tools).
$ tar xfz <expid>-grenoble.iot-lab.info.tar.gz $ plot_oml_consum -p -i <expid>/consumption/m3_<id>.oml

Radio Monitoring for M3 nodes#

Simple example of using the monitoring tools in FIT/IoT-LAB testbed.

This script implements a similar behavior as the “Radio monitoring for M3 nodes” (https://www.iot-lab.info/legacy/tutorials/monitoring-radio-m3/index.html).

Requirement: M3 image (tutorial_m3.elf)

Please follow the steps 1-4 in the FIT/IoT-LAB tutorial to create the image.
Save it in the same folder as the script.
Adjust the channels (11, 14) used during the test accordingly (see step 5 in the FIT/IoT-LAB tutorial).

import logging
import time

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["sensor"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 2,
                "image": "tutorial_m3.elf",
                "profile": "test_profile",
            },
        ]
    },
    "monitoring": {
        "profiles": [
            {
                "name": "test_profile",
                "archi": "m3",
                "radio": {
                    "mode": "rssi",
                    "num_per_channel": 1,
                    "period": 1,
                    "channels": [11, 14],
                },
            }
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
try:

    roles, networks = p.init()
    print(roles)

    print("Opening serial connection to sensor")
    sender = roles["sensor"][0]

    with en.IotlabSerial(sender, interactive=True) as serial_sender:
        num_packets = 5
        num_burst = 5
        print(
            "M3 sensor(%s): sending %d sets of %d packets"
            % (sender.alias, num_burst, num_packets)
        )
        for i in range(0, num_burst):
            for j in range(0, num_packets):
                serial_sender.write("b")
            time.sleep(5)

    print("Collecting experiment data")
    time.sleep(20)
    p.collect_data_experiment()  # collect experiment data

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

The monitoring files are compressed and saved in the current folder.

You can launch the script using :

$ python tuto_iotlab_m3_radio_monitoring.py

Finally, you can evaluate and plot the results as done in the tutorial. It uses the plot_oml_consum tool (Available at: iot-lab/oml-plot-tools).
$ tar xfz <expid>-grenoble.iot-lab.info.tar.gz $ plot_oml_radio -a -i <expid>/radio/m3_<id>.oml

Radio Sniffer with M3 nodes#

Simple example of using the monitoring tools in FIT/IoT-LAB testbed.

This script implements a similar behavior as the “Radio sniffer with M3 nodes” (https://www.iot-lab.info/legacy/tutorials/monitoring-sniffer-m3/index.html).

Requirement: M3 image (tutorial_m3.elf)

The M3 image can be download from the website: https://raw.githubusercontent.com/wiki/iot-lab/iot-lab/firmwares/tutorial_m3.elf
Download and save it in the same folder as the script.

import contextlib
import logging
import time

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["sniffer"],
                "hostname": ["m3-7.grenoble.iot-lab.info"],
                "image": "tutorial_m3.elf",
                "profile": "sniff_11",
            },
            {
                "roles": ["sensor"],
                "hostname": [
                    "m3-8.grenoble.iot-lab.info",
                    "m3-9.grenoble.iot-lab.info",
                    "m3-10.grenoble.iot-lab.info",
                    "m3-11.grenoble.iot-lab.info",
                ],
                "image": "tutorial_m3.elf",
            },
        ]
    },
    "monitoring": {
        "profiles": [
            {
                "name": "sniff_11",
                "archi": "m3",
                "radio": {
                    "mode": "sniffer",
                    "channels": [11],
                },
            }
        ]
    },
}

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)
try:

    roles, networks = p.init()
    print(roles)

    sniffer = roles["sniffer"][0]
    sensor = roles["sensor"][0]

    with contextlib.ExitStack() as stack:
        stack.enter_context(en.IotlabSniffer(sniffer))
        s_sniffer = stack.enter_context(en.IotlabSerial(sniffer, interactive=True))
        s_sensor = stack.enter_context(en.IotlabSerial(sensor, interactive=True))

        print("Send a small packet with the sniffer (%s)" % sniffer.alias)
        s_sniffer.write("s")
        print("Send a big packet with another node (%s)" % sensor.alias)
        s_sensor.write("b")

    print("Collecting experiment data")
    time.sleep(1)
    p.collect_data_experiment()  # collect experiment data

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

The pcap file is compressed and saved in the current folder.

You can launch the script using :

$ python tuto_iotlab_m3_radio_sniffer.py

Finally, you can analyze the packets with wireshark.

$ tar xfz <expid>-grenoble.iot-lab.info.tar.gz
$ wireshark <expid>/sniffer/m3-7.pcap

IPv6 - Interacting with frontend#

Some tutorials in FIT/IoT-LAB run commands directly in the frontend node. You can script this interaction using a combination of Static and IoT-LAB providers in EnOSlib.

This script implements a similar behavior as the “Public IPv6 (6LoWPAN/RPL) network with M3 nodes” (https://www.iot-lab.info/legacy/tutorials/contiki-public-ipv6-m3/index.html). This tutorial runs the tunslip tool in the frontend node to bridge packets between the external network and M3 sensors in the platform.

Requirement: M3 images (border-router.iotlab-m3 and http-server.iotlab-m3)

Please follow Step 4 in the original tutorial to download the images.

import logging
import re

import iotlabcli.auth

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

provider_conf = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["border_router"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 1,
                "image": "border-router.iotlab-m3",
            },
            {
                "roles": ["http_server"],
                "archi": "m3:at86rf231",
                "site": "grenoble",
                "number": 9,
                "image": "http-server.iotlab-m3",
            },
        ]
    },
}

# gets the username for accessing the IoT-LAB platform from ~/.iotlabrc file
# you probably can set it hardcoded

iotlab_user, _ = iotlabcli.auth.get_user_credentials()

conf = en.IotlabConf.from_dictionary(provider_conf)

p = en.Iotlab(conf)

try:
    roles, networks = p.init()

    print("Iotlab provider: M3 resources")
    print(roles)

    frontend = en.Host("grenoble.iot-lab.info", user=iotlab_user)

    border = roles["border_router"][0]

    tun_cmd = (
        "sudo tunslip6.py -v2 -L "
        "-a %s -p 20000 2001:660:5307:3100::1/64 > tunslip.output 2>&1" % border.alias
    )

    print(f"Running {tun_cmd} command on frontend: {frontend.alias}")
    en.run_command(tun_cmd, roles=frontend, asynch=3600, poll=0)

    # resetting border router
    border.reset()

    # getting server addr from tunslip output saved in file
    result = en.run_command("cat tunslip.output", roles=frontend)
    out = result["ok"]["grenoble"]["stdout"]
    match = re.search(
        r"Server IPv6 addresses:\n.+(2001:660:5307:3100::\w{4})",
        out,
        re.MULTILINE | re.DOTALL,
    )
    server_addr = match.groups()[0]
    print("Get the Border Router IPv6 address from tunslip output: %s" % server_addr)

    # ping
    print("Ping6 BR node using global address:")
    result = en.run_command("ping6 -c3 %s" % server_addr, roles=frontend)
    print(result["ok"]["grenoble"]["stdout"])

    # get list of nodes from web interface
    print("View BR’s web-interface: ")
    result = en.run_command("lynx --dump http://[%s]" % server_addr, roles=frontend)
    print(result["ok"]["grenoble"]["stdout"])

    print("Stopping tunslip process")
    en.run_command('pgrep -u "$(whoami)" tunslip6 | xargs kill', roles=frontend)

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    p.destroy()

Note

IPv6 address used in M3 sensors are globally accessible.

You can launch the script using :
$ python tuto_iotlab_m3_ipv6.py

Monitoring A8 nodes - IPv6#

This example shows how to install a monitoring stack (Grafana/Prometheus/Telegraf) on Grid’5000 and FIT/IoT-LAB nodes to collect infrastructure metrics. By using the IPv6 network and Prometheus, we’re able to collect data from both testbed. Note that IPv6 connection from Grid’5000 to IoT-LAB is allowed (the inverse isn’t true unless you open the firewall port accordingly).

Summarizing, the example does the following:

Install Grafana in a node: Grafana accepts connections in the port 3000, user: admin, password: admin.
Install Prometheus database in a node: accessible at port 9090. It is installed with the following parameters (scrape_interval: 10s, scrape_timeout: 10s, eval_interval: 15s). They are defined at: enoslib/service/monitoring/roles/prometheus/defaults/main.yml).
Install Telegraf on remaining nodes: Telegraf is configured to receive incoming connections from Prometheus at port 9273.

import logging
import time
from ipaddress import IPv6Network

import enoslib as en

en.init_logging(level=logging.INFO)
en.check()

# IoT-LAB provider configuration
iotlab_dict = {
    "walltime": "01:00",
    "resources": {
        "machines": [
            {
                "roles": ["a8"],
                "archi": "a8:at86rf231",
                "site": "grenoble",
                "number": 2,
            }
        ]
    },
}
iotlab_conf = en.IotlabConf.from_dictionary(iotlab_dict)
iotlab_provider = en.Iotlab(iotlab_conf)

g5k_dict = {
    "job_type": [],
    "walltime": "01:00:00",
    "resources": {
        "machines": [
            {
                "roles": ["control"],
                "cluster": "parasilo",
                "nodes": 1,
                "primary_network": "default",
            },
            {
                "roles": ["compute"],
                "cluster": "parasilo",
                "nodes": 1,
                "primary_network": "default",
            },
        ],
        "networks": [
            {"id": "default", "type": "prod", "roles": ["prod"], "site": "rennes"}
        ],
    },
}
g5k_conf = en.G5kConf.from_dictionary(g5k_dict)
g5k_provider = en.G5k(g5k_conf)


try:
    iotlab_roles, iotlab_networks = iotlab_provider.init()
    g5k_roles, g5k_networks = g5k_provider.init()

    print("Enabling IPv6 on Grid'5000 nodes")
    en.run_command("dhclient -6 br0", roles=g5k_roles)

    g5k_roles = en.sync_info(g5k_roles, g5k_networks)
    iotlab_roles = en.sync_info(iotlab_roles, iotlab_networks)

    print("Deploy monitoring stack on Grid'5000")
    print("Install Grafana and Prometheus at: %s" % str(g5k_roles["control"]))
    print("Install Telegraf at: %s" % str(g5k_roles["compute"]))

    def get_nets(networks, net_type):
        """Aux method to filter networs from roles"""
        return [
            n
            for net_list in networks.values()
            for n in net_list
            if isinstance(n.network, net_type)
        ]

    m = en.TPGMonitoring(
        collector=g5k_roles["control"][0],
        agent=g5k_roles["compute"] + iotlab_roles["a8"],
        ui=g5k_roles["control"][0],
        networks=get_nets(g5k_networks, IPv6Network)
        + get_nets(iotlab_networks, IPv6Network),
    )
    m.deploy()

    ui_address = g5k_roles["control"][0].address
    print("The UI is available at http://%s:3000" % ui_address)
    print("user=admin, password=admin")

    sleep_time = 60
    print("Sleeping for %d seconds before finishing the test" % sleep_time)
    time.sleep(sleep_time)
    m.backup()
    m.destroy()

except Exception as e:
    print(e)
finally:
    # Delete testbed reservation
    iotlab_provider.destroy()
    g5k_provider.destroy()

Note

The Prometheus database is compressed and saved in the current folder.

You can launch the script using :

$ python tuto_iotlab_ipv6_monitoring.py

FIT/IoT-LAB tutorials #

Installation #

Configuration #

External access#

Basic examples #

Getting started tutorial#

Using A8 nodes#

Using RPi nodes#

Advanced examples #

Monitor M3 consumption#

Radio Monitoring for M3 nodes#

Radio Sniffer with M3 nodes#

IPv6 - Interacting with frontend#

Monitoring A8 nodes - IPv6#

Jupyter Notebooks #

Grid5000 and FIT/IoT-LAB - IPv6 #

FIT/IoT-LAB tutorials#

Installation#

Configuration#

External access#

Basic examples#

Getting started tutorial#

Using A8 nodes#

Using RPi nodes#

Advanced examples#

Monitor M3 consumption#

Radio Monitoring for M3 nodes#

Radio Sniffer with M3 nodes#

IPv6 - Interacting with frontend#

Monitoring A8 nodes - IPv6#

Jupyter Notebooks#

Grid5000 and FIT/IoT-LAB - IPv6#

FIT/IoT-LAB tutorials #

Installation #

Configuration #

Basic examples #

Advanced examples #

Jupyter Notebooks #

Grid5000 and FIT/IoT-LAB - IPv6 #