Experiment CLI client

difficulty Difficulty: Medium

duration Duration: 20 minutes

Description: This document shows how to use the Experiment CLI Tool utility on the frontend SSH. You will learn how to submit an experiment, start an experiment, and so much. The supported format for IoT-LAB API requests and responses with CLI Tools is JSON representation.

First step

Connect to frontend SSH and getting help :

my_computer$ ssh <login>@<site>.iot-lab.info (site = euratech, grenoble, lille, rennes, saclay, strasbourg)
<login>@<site>:~$ experiment-cli -h
usage: experiment-cli [-h] [-u USERNAME] [-p PASSWORD] [-v]
                      {submit,stop,get,load,info,wait} ...

experiment-cli command-line manage experiments on testbed.

positional arguments:
  {submit,stop,get,load,info,wait}
    submit              submit user experiment
    stop                stop user experiment
...

If you didn’t authenticate using auth-cli, do it now:

<login>@<site>:~$ auth-cli -u <login>

Submit an experiment

<login>@<site>:~$ experiment-cli submit -h

For example we want to book five M3 nodes on Grenoble site for 30 minutes as soon as possible.
There is two kind of experiment submission :

  • based on nodes id list. The testbed allow you nodes m3-{2,4,5,9,11}.grenoble.iot-lab.info
<login>@<site>:~$ experiment-cli submit -n tuto_cli -d 30 -l grenoble,m3,2+4-5+9+11
{
    "id": 7412
}
  • based on nodes properties list (archi, site) and the number of nodes expected. The testbed allow for you five nodes with these properties.
<login>@<site>:~$ experiment-cli submit -n tuto_cli -d 30 -l 5,archi=m3:at86rf231+site=grenoble
{
    "id": 7413
}

The response is the id of your experiment.

Get experiment state

<login>@<site>:~$ experiment-cli get -i 7412 -s
{
    "state": "Running"
}

Get experiment nodes list

<login>@<site>:~$ experiment-cli get -i 7412 -r
{
    "items": [
        {
            "archi": "m3:at86rf231", 
            "mobile": "false", 
            "network_address": "m3-9.grenoble.iot-lab.info", 
            "site": "grenoble", 
            "state": "Alive", 
            "x": "25.75", 
            "y": "26.76", 
            "z": "-0.04"
        }, 
        ....
}

Get experiments list

<login>@<site>:~$ experiment-cli get -l
{
    "items": [
        {
            "date": 1490771215, 
            "duration": 1327, 
            "id": 11943, 
            "name": "", 
            "nb_resources": 5, 
            "owner": "login", 
            "resources": [
                            "m3-10.grenoble.iot-lab.info", 
                            "m3-11.grenoble.iot-lab.info", 
                            "m3-12.grenoble.iot-lab.info", 
                            "m3-13.grenoble.iot-lab.info", 
                            "m3-14.grenoble.iot-lab.info"
                         ], 
            "state": "Terminated"
        }, 
        ...
    ]
}

<login>@<site>:~$ experiment-cli get -l --state Running
...

Get experiments list with state Running

<login>@<site>:~$ experiment-cli get -e
{
 "Running": [
 7412,
 7413
 ]
}

Submit an experiment with associations

You can specify the node associations between firmware and Profile configuration.

  • one node with a firmware and other nodes with another firmware
<login>@<site>:~$ experiment-cli submit -d 30 -l grenoble,m3,2,sink_node.elf -l grenoble,m3,4-5+9+11,node.elf
  • all nodes with a Profile. You must have upload on the server a Profile with name “profile_name”, see Profile CLI Client tutorial.
<login>@<site>:~$ experiment-cli submit -d 30 -l grenoble,m3,2+4-5+9+11,,profile_name
  • all nodes with a firmware and Profile
<login>@<site>:~$ experiment-cli submit -d 30 -l grenoble,m3,2+4-5+9+11,node.elf,profile_radio

By default if you don’t make associations :

  • without profile nodes are configured with a power supply method dc
  • without firmware the sensor nodes are programmed with the firmware “idle”.

Submit a schedule experiment

For this we use Linux epoch timestamp. Submit experiment with a schedule date (e.g. 20 May 2014 14:00:00)

<login>@<site>:~$ experiment-cli submit -d 20 -l grenoble,m3,2+4-5+9+11 -r $(date +%s -d "20 May 2014 14:00:00 UTC")

Stop experiment

<login>@<site>:~$ experiment-cli stop -i 7412

Get platform nodes list representation

<login>@<site>:~$ experiment-cli info -li
{
    "items": [
        {
            "grenoble": {
                "m3": {
                    "Alive": "13-15+17-18+21+23+25+29-33+35+37-40+44-45+48-49+51+55+59+61+63+65+68-69+71-73+77+80+85+88+91+94+101-102+105-106+109+113-118+122-125+129-136+139-142+146-147+151-152+155+157-162+167+169+171+174-175+178-182+185+187-189+191-192+194+196-198+203-204+206+208+210+212-214+216+219-220+222+226-227+231-232+234-237+239+241-242+244-246+248+253-254+257-258+260+262-265+267+271-273+278+280+282+285+288-290+292-293+297-301+303+307+309-314+317-318+321-322+324-325+328+335+337-339+343-344+346+348-349+354+359-360+363+366-368+371+374-377+379-380", 
                    "Busy": "2+4-5+9+11", 
                    "Suspected": "138+148+150+252"
                },
              ..... 
}
<login>@<site>:~$ experiment-cli info -l
{
    "items": [
        {
            "archi": "m3:at86rf231", 
            "mobile": 0, 
            "network_address": "m3-2.grenoble.iot-lab.info", 
            "site": "grenoble", 
            "state": "Busy", 
            "uid": "9982", 
            "x": "20.70", 
            "y": "26.76", 
            "z": "-0.04"
        }, 
        .....
}

<login>@<site>:~$ experiment-cli info -l --site grenoble --archi m3
....

<login>@<site>:~$ experiment-cli info -li --site saclay --archi a8
....