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 get 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 have not authenticated using auth-cli yet, 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. Note that in these examples, the nodes are flashed with the default firmware “Idle”.

There are two ways to submit an experiment  :

  • based on nodes id list. The testbed grants you nodes M3 with Id 2,4, 5, 9 and 11 on Grenoble site (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 desired. The testbed grants 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

The following command gives you the status of experiment with Id 7412.

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

Get the list of resources/nodes of an experiment

The following command returns the list of nodes involved in experiment with id 7412, its architecture, its mobility feature, site, state and coordinates.

<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 the list of your experiments

The following command returns the list of all experiments run by the user who authenticated, past, waiting and running.

<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

By default, if you don’t make associations :

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

You can associate every node of your experiment with different firmwares and Profile configurations.

Here are the different examples :

  • Associate 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
  • Associate all nodes with a Profile. You must have uploaded 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
  • Associate 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

 

Submit a schedule experiment

To schedule an experiment,  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
....