This tutorial executes a LoRa transmission between a node and a gateway using docker in CorteXlab, transmitting dummy packets between them.

This implementation stands on the original LoRa version made by EPFL

In order to follow this tutorial, we will use the docker image found on Dockerhub, which includes the CorteXlab toolchain, alongside a GitHub repository properly configured.

Thanks to docker, it is possible to deploy a suitable environment on CorteXlab, with gnuradio and needed software.

The necessary commands have already been executed on the given image, so it is not necessary to modify it or to commit and push a new image. However, if you want to create new scenarios or applications, follow the guidelines in the section below. If not, go directly to the create the scenario section.

Using docker, we will enable on your laptop an environment suitable for Cortexlab with gnuradio and needed software. Your goal is to develop this image (with new software and files) so you can run your experiment. It will only modify the environment of the image and not your laptop. Then you will be able to save and deploy the new image on cortexlab, without having to re-install everything and dealing with software compatibility and versioning.

Therefore, you can retrieve and run the following image.

you@yourpc:~$ docker pull estevep/lora_dyn_phy-cxlb
you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged [--name CONTAINER_NAME] lora_dyn_phy-cxlb

Access the docker container using ssh :

you@yourpc:~$ ssh -Xp 2222 root@localhost

Add this option to the run command if you want to use a USRP plugged in with a USB port on you local machine : -v /dev/bus/usb:/dev/bus/usb . Also, a new host key is created when running the container. The following command could be necessary to add the new key to the known hosts list before using ssh.

you@yourpc:~$ ssh-keygen -f "/home/[YOUR NAME]/.ssh/known_hosts" -R "[localhost]:2222"

When in the container, you can modify any of the given files and python scripts. To understand more depply the structure of the project and the role of all the python scripts, see TODO : create the section explaining each file and add a reference here.

We can test it on our local machine before sending it to cortexlab (it won't work if you don't have an USRP available).

Once you are satisfied with your modifications and the scripts are working properly, you can exit the container with Ctrl + d. Now, let's save our updated container as a new docker image. We can then push it on dockerhub (dockerhub is a repository of docker images, you need to create an account on it).

you@yourpc:~$ docker ps -a 
you@yourpc:~$ docker commit [CONTAINER ID] [NEW IMAGE NAME] 
you@yourpc:~$ docker tag [NEW IMAGE NAME] [DOCKER USERNAME]/[NEW IMAGE NAME] 
you@yourpc:~$ docker login 
you@yourpc:~$ docker push [DOCKER USERNAME]/[NEW IMAGE NAME] 

For the following, the task will refer to the instructions given by Airlock, the scenario file and minus. The experiment will refer to the LoRa transmissions.

Create on your machine a folder task_lora and in it a file scenario.yaml which will indicate the nodes to use and how to use them. It should look like this:

# Example scenario description file
#
#   All lines starting with "#" and empty lines are ignored
#
#
# Scenario textual description
#   simple string (a one liner)
description: Lora Dynamic Physical Layer - Docker and Cortexlab
#
# Experiment maximum duration
#   Time after which the experiment is forced to stop
#   integer (seconds)
duration: 600
#
# Node list
#
#   format:
#
#   nodes:
#     (machine):
#       command: (entry point script relative to the task root)

nodes:
  node14:
    container:
    - image: estevep/lora_dyn_phy-cxlb:latest
      command: /usr/sbin/sshd -p 2222 -D

  node16:
    container:
    - image: estevep/lora_dyn_phy-cxlb:latest
      command: /usr/sbin/sshd -p 2222 -D

This scenario runs the given docker image on nodes 14 and 16, and opens the containers to a ssh connection.

If you want to modify this scenario, for example in order to automatize the experiment, check out the first tutorial on how to use docker with CorteXlab here. It explains the functioning of the scenario.yaml file and the other possibilities it offers.

For more info on where these nodes are located inside the platform, please check the node position map at the home of this wiki here.

Assuming your account has been correctly created, you can now copy the folder with the scenario file into the Airlock SSH front-end:

you@yourpc:~$ scp -P 2269 -v [-i path/to/your/key] [-r] path/to/local/file/task_lora username@gw.cortexlab.fr:/cortexlab/homes/[YOUR CORTEXLAB USERNAME]/workspace/

You can now access the Airlock SSh server that will allow you to manage your task.

you@yourpc:~$ ssh -X -v [-i path/to/the/key] username@gw.cortexlab.fr

On airlock, before submitting the task to the nodes, we need first to put the task into a format that can be readily understood by Minus. See [here|gnuradiodockerbenchmarkexample#creatingthetask_file] for more information on minus.

you@srvairlock:~/ cd /cortexlab/homes/[YOUR CORTEXLAB USERNAME]/workspace/
you@srvairlock:~/workspace$ minus task create task_lora
you@srvairlock:~/workspace$ ls
task_lora  task_lora.task

Now we need to give the task to Minus, so that it can operate its magic.

First we need to reserve the CorteXlab room:

you@srvairlock:~/workspace$ oarsub -l nodes=BEST,walltime=0:30:00 -I

(If you're running your reservation in a container reservation):

you@srvairlock:~/workspace$ oarsub -t inner=<id of container> -l {"network_address in ('mnode4.cortexlab.fr', 'mnode6.cortexlab.fr')"}/nodes=2,walltime=0:30:00 -I

(Be sure that no one else is using the same node as you)

This will run a 30 minute job and open a sub-shell in which you can run minus tasks. This sub-shell will be killed after 30 minutes, and if you leave the shell earlier, it will terminate the corresponding oar job. More documentation on oar can be found here. You can also monitor the current jobs in the gantt web interface.

We then submit the minus task:

you@srvairlock:~/workspace$ minus task submit task_lora.task
Task with id 15 enqueued user <login>.

You'll see that Minus recognizes you as the submitter of the task and gives you a task number (15 in this example). You'll want to write down the number of the task as it will be important for checking its status or to abort it, if necessary.

Bear in mind that your task has been put on a queue and will await running tasks and other scheduled tasks to start, so it may take a while before it runs.

Minus can also help you check the status of the queue:

you@srvairlock:~/workspace$ minus testbed status
num total tasks:   2540
num tasks waiting: 0
num tasks running: 0
tasks currently running:
  (none)

These information are returned:

• num total tasks: This is the number of the last created task
• num tasks waiting: This is the number of tasks currently awaiting in the queue
• num tasks running: This is the number of tasks currently executing (most of the time, there can only be one task running at the same time. Only in special situations, such as demos, tutorials, can several users run tasks concurrently).
• tasks currently running: This is a detailed list of tasks currently running.

Work in progress