User Tools

Site Tools


lora_dynamic_phy_layer_example

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
lora_dynamic_phy_layer_example [2021/06/23 16:23] pestevelora_dynamic_phy_layer_example [2021/07/08 11:35] (current) pesteve
Line 1: Line 1:
-# GNU Radio benchmark example with docker+# GNU Radio LoRa PHY layer for MAC experimentation 
  
-This tutorial executes a LoRa transmission between a node and a gateway using docker in CorteXlab, transmitting dummy packets between them.+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 [[https://www.epfl.ch/labs/tcl/resources-and-sw/lora-phy/|EPFL]]+It shows how to use the interface of a plug and play complete LoRa dynamic physical layer, that can be found inside the following [docker image](https://hub.docker.com/repository/docker/amauryparis/cxlb_lora) or on this [GitHub repository](https://github.com/AmauryPARIS/LoRa_PHY_Cxlb/). It allows to connect any upper layer that will control the physical layer (message and parameters), and receive all the information it needs (SNR, message and noise energy levels, crc presence, coding rate, number of (corrected) errors...).
  
-In this tutorial, we will first deploy on CorteXlab a basic upper layer connected to the LoRa physical layerAfter showing the functioning of this simple scenario, we will then pull the docker image in order to modify it, add a basic functionnality on the upper layer and redeploy it on CorteXlab.+This implementation stands on the original LoRa PHY version made by [[https://www.epfl.ch/labs/tcl/resources-and-sw/lora-phy/|EPFL]].
  
-## Basic upper layer/original experiment+In this tutorial, we will first deploy on CorteXlab two examples of upper layers connected to the LoRa physical layer. After showing the functioning of this simple scenario, we will then pull the docker image in order to modify it, add a basic functionnality on the upper layer and redeploy it on CorteXlab. 
 + 
 +## Example upper layer/original experiment
  
 ### Docker ### Docker
  
-In this tutorial, we will use the docker image found on [Dockerhub](https://hub.docker.com/repository/docker/estevep/lora_dyn_phy-cxlb), which includes the CorteXlab toolchain, alongside a [GitHub repository](https://github.com/AmauryPARIS/LoRa_PHY_Cxlb/) providing the LoRa physical layer properly configured and a basic upper layer.+In this tutorial, we will use the docker image available on [Dockerhub](https://hub.docker.com/r/amauryparis/cxlb_lora), which includes the CorteXlab toolchain, alongside a [GitHub repository](https://github.com/AmauryPARIS/LoRa_PHY_Cxlb/) providing the LoRa physical layer properly configured and an upper layer example.
  
-Thanks to docker, it is possible to deploy a suitable environment on CorteXlab, with gnuradio and needed software.+Thanks to docker image, it is possible to easily run on your local machine an environment suitable for CorteXlab, with gnuradio and needed software. Once your project is ready, you can use your upgraded docker image in the testbed. This will allow you to quickly transfer all of your project, files and environment, as in your local computer but to be used within the testbed on SDR nodes.
  
 ### Create the scenario ### Create the scenario
Line 49: Line 51:
   node14:   node14:
     container:     container:
-    - image: estevep/lora_dyn_phy-cxlb:latest+    - image: amauryparis/cxlb_lora:master
       command: /usr/sbin/sshd -p 2222 -D       command: /usr/sbin/sshd -p 2222 -D
  
   node16:   node16:
     container:     container:
-    - image: estevep/lora_dyn_phy-cxlb:latest+    - image: amauryparis/cxlb_lora:master
       command: /usr/sbin/sshd -p 2222 -D       command: /usr/sbin/sshd -p 2222 -D
 </code> </code>
Line 119: Line 121:
  
 ### Run the experiment ### Run the experiment
 +
 +#### Setup
  
 Now the node we want to use are up and running with the docker image we set up earlier. We can access them with ssh to run our experiment. To do so, open a new terminal per node you want to use, here two, access Airlock and run the following command, here for node 14: Now the node we want to use are up and running with the docker image we set up earlier. We can access them with ssh to run our experiment. To do so, open a new terminal per node you want to use, here two, access Airlock and run the following command, here for node 14:
Line 132: Line 136:
 In order to run this example you should launch 4 terminals: 2 for each USRP. Therefore, use the same `ssh` command to connect to the node 14 or 16 on each of the 3 remaining terminals. In order to run this example you should launch 4 terminals: 2 for each USRP. Therefore, use the same `ssh` command to connect to the node 14 or 16 on each of the 3 remaining terminals.
  
-The part we are intersted in can be found in `/root/LoRa_PHY_Cxlb.git`, and more specifically in the `gr-lora_sdr/apps` subfolder.+The part we are interested in can be found in `/root/LoRa_PHY_Cxlb.git`, and more specifically in the `gr-lora_sdr/apps` sub-folder.
  
 <code> <code>
Line 156: Line 160:
 In order to show its utility, two python scripts are provided: In order to show its utility, two python scripts are provided:
  
-* `udp_Node.py`: basic upper layer for a node, connected to the `lora_dyn_node` script through its udp JSON interface. Sends the message given by the user +* `udp_Node.py`: upper layer example for a node, connected to the `lora_dyn_node` script through its udp JSON interface. Sends the message given by the user 
-* `udp_BS.py`: basic upper layer for a base station, connected to the `lora_dyn_node` script through its udp JSON interface. Sends an acknoledgment.+* `udp_BS.py`: upper layer example for a base station, connected to the `lora_dyn_node` script through its udp JSON interface. Sends an acknoledgment.
      
 :warning: Both `udp_BS.py` and `udp_Node.py` have to be run with python3, whereas `lora_dyn_node` has to be run with python2. :warning: Both `udp_BS.py` and `udp_Node.py` have to be run with python3, whereas `lora_dyn_node` has to be run with python2.
  
-Enter the following commands on the specified terminal to begin the experiment:+Open two terminals on each of the two nodes through SSH. The cortexlab node 14 will be used as the LoRa node and the cortexlab node 16 as the base station. Enter the following commands on the specified terminal to begin the experiment:
  
 <code> <code>
-# From node 14 - on the 1st terminal, refered to as 14-a+# From node 14 - on the 1st terminal, refered to as NODE.phy
 root@mnode14:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python2 lora_dyn_node.py root@mnode14:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python2 lora_dyn_node.py
 </code> </code>
  
 <code> <code>
-# From node 14 - on the 2nd terminal, refered to as 14-b+# From node 14 - on the 2nd terminal, refered to as NODE.up
 root@mnode14:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python3 udp_Node.py root@mnode14:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python3 udp_Node.py
 </code> </code>
  
 <code> <code>
-# From node 16 - on the 3rd terminal, refered to as 16-a+# From node 16 - on the 3rd terminal, refered to as BS.phy
 root@mnode16:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python2 lora_dyn_node.py root@mnode16:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python2 lora_dyn_node.py
 </code> </code>
  
 <code> <code>
-# From node 16 - on the 4th terminal, refered to as 16-b+# From node 16 - on the 4th terminal, refered to as BS.up
 root@mnode16:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python3 udp_BS.py root@mnode16:~/LoRa_PHY_Cxlb.git/gr-lora_sdr/apps# python3 udp_BS.py
 </code> </code>
  
-On the 14-b terminal and the 16-b one, first choose your UDP TX and RX port. On CorteXlab using the default ports (6788 and 6790) for both the base station and the node will work since they are connected to different computers.+#### Send and receive messages
  
-Then enter one of the following keywords to change the corresponding parameter if needed on the 14-b terminal.+On the NODE.up terminal and the BS.up one, first choose your UDP TX and RX port. On CorteXlab use the default ports (6788 and 6790) for both the base station and the node will work since they are connected to different computers. 
 + 
 +Then enter one of the following keywords to change the corresponding parameter if needed on the NODE.up terminal.
  
 ``` ```
Line 199: Line 205:
 Enter the new value, then type `send` to send this new parameter to the physical layer. If a new `MSG` value is sent to the physical layer it is transmitted to the base station, which should respond with an acknowledgment. Enter the new value, then type `send` to send this new parameter to the physical layer. If a new `MSG` value is sent to the physical layer it is transmitted to the base station, which should respond with an acknowledgment.
  
-For example, try running the following commands on terminal 14-b in order to modify the RX gain of the node:+For example, try running the following commands on terminal NODE.up in order to modify the RX gain of the node:
  
 <code> <code>
Line 213: Line 219:
 </code> </code>
  
-Check out the results on terminal 14-a:+Check out the results on terminal NODE.phy:
  
 <code> <code>
Line 260: Line 266:
 </code> </code>
  
-Check out the results on terminal 14-a.+Check out the results on terminal NODE.phy.
 <code> <code>
  
Line 281: Line 287:
 * The first line confirms that the message "test" has indeed been sent. * The first line confirms that the message "test" has indeed been sent.
 * The node then waits for an acknoledgment from the base station and enters receiving mode. * The node then waits for an acknoledgment from the base station and enters receiving mode.
-* The next ones concern the received acknoldgement. Before understanding them, check out the other terminals, starting with terminal 16-a.+* The next ones concern the received acknoldgement. Before understanding them, check out the other terminals, starting with terminal BS.phy.
  
 <code> <code>
Line 299: Line 305:
 </code> </code>
  
-This confirms that the physical layer received a message "test", and the RX UDP line shows the information sent via UDP protocol to the upper layer on terminal 16-b.+This confirms that the physical layer received a message "test", and the RX UDP line shows the information sent via UDP protocol to the upper layer on terminal BS.up.
  
 <code> <code>
Line 325: Line 331:
 On this last terminal, you should first see these information, and then the reaction of the base station upper layer: sending an acknoledgment. On this last terminal, you should first see these information, and then the reaction of the base station upper layer: sending an acknoledgment.
  
-This acknoledgment is then sent by the physical layer as indicated by the TX UDP line on terminal 16-a, and finally received by the physical layer of the node:+This acknoledgment is then sent by the physical layer as indicated by the TX UDP line on terminal BS.phy, and finally received by the physical layer of the node:
  
 <code> <code>
Line 344: Line 350:
 ## Customized experiment ## Customized experiment
  
-This experiment is quite basic, even though it demonstrates how to connect an upper layer to the dynamic LoRa physical layer and to change the physical layer parameter. The node only sends a message and waits for eternity for an acknoledgment of the base station. The purpose of the physical layer is to be used by more complex upper layers. +This experiment is quite basic, even though it demonstrates how to connect an upper layer to the dynamic LoRa physical layer and to change the physical layer parameter. The node only sends a message and waits for an acknoledgment of the base station. The purpose of the physical layer is to be used by more complex upper layers. 
  
 In this part, we will see how to modify the upper layer and redeploy it on CorteXlab. If you want to develop your own upper layer, you can refer to this tutorial to deploy it. In this part, we will see how to modify the upper layer and redeploy it on CorteXlab. If you want to develop your own upper layer, you can refer to this tutorial to deploy it.
Line 356: Line 362:
  
 <code> <code>
-you@yourpc:~$ docker pull estevep/lora_dyn_phy-cxlb +you@yourpc:~$ docker pull amauryparis/cxlb_lora:master 
-you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged [--name CONTAINER_NAME] lora_dyn_phy-cxlb+you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged [--name CONTAINER_NAME] amauryparis/cxlb_lora:master
 </code> </code>
  
Line 376: Line 382:
 #### Customize the UDP Base Station #### Customize the UDP Base Station
  
-Here, we will just add a simple functionnality to the base station. If the SNR is higher than a threshold, then the GTX of the BS will be reduced, and if it is lower than a second threshold, then the GTx will be augmented. +Here, we will just add a simple functionnality to the base station. If the SNR is higher than a threshold, then the transmission gain of the BS will be reduced, and if it is lower than a second threshold, then the gain will be augmented. 
  
 This simulates a simple logic behavior: if the receiving SNR is low, then the acknoledgment should be emitted with a high gain in order to be correctly received by the node. On the contrary, if the receiving SNR is very high, then there is no need to emit with a high gain. This simulates a simple logic behavior: if the receiving SNR is low, then the acknoledgment should be emitted with a high gain in order to be correctly received by the node. On the contrary, if the receiving SNR is very high, then there is no need to emit with a high gain.
Line 425: Line 431:
 ### Deploy the experiment on CorteXlab ### Deploy the experiment on CorteXlab
  
-In order to send this environment on CorteXlab, follow the same procedure as in subsections [[lora_dynamic_phy_layer_example#create_the_scenario|Create the scenario]] to [[lora_dynamic_phy_layer_example#run_the_experiment|Run the experiment]]. Just **change the docker image name in `scenario.yaml`** from `estevep/lora_dyn_phy-cxlb:latest` to `[DOCKER USERNAME]/[IMAGE NAME]`.+In order to send this environment on CorteXlab, follow the same procedure as in subsections [[lora_dynamic_phy_layer_example#create_the_scenario|Create the scenario]] to [[lora_dynamic_phy_layer_example#setup|Setup]]. Just **change the docker image name in `scenario.yaml`** from `amauryparis/cxlb_lora:master` to `[DOCKER USERNAME]/[IMAGE NAME]`.
  
 ### Results ### Results
  
-You should now follow the same steps as in the first part to connect to the nodes 14 and 16 with four terminals, refered to as 14-a to 16-b, and execute `lora_dyn_node.py`, `udp_Node.py` and `udp_BS.py`.+You should now follow the same steps as in the first part to connect to the nodes 14 and 16 with four terminals, refered to as NODE.phy, NODE.up, BS.phy and BS.up, and execute `lora_dyn_node.py`, `udp_Node.py` and `udp_BS.py`.
  
 #### Default GTX #### Default GTX
  
-First send a message with the default GTX on terminal 14-b.+First send a message with the default GTX on terminal NODE.up.
  
 <code> <code>
Line 443: Line 449:
 </code> </code>
  
-You should now see the following answer on terminal 14-a.+You should now see the following answer on terminal NODE.phy.
  
 <code> <code>
Line 462: Line 468:
 </code> </code>
  
-And the following ones on terminal 16-a and 16-b+And the following ones on terminal BS.phy and BS.up.
  
-16 - a+* BS.phy
  
 <code> <code>
Line 481: Line 487:
     TX UDP : {"GTX": "10", "MSG": "ACK-test"}     TX UDP : {"GTX": "10", "MSG": "ACK-test"}
 </code> </code>
 +
 +* BS.up
  
 <code> <code>
Line 506: Line 514:
 In this case, the SNR is higher than 90 so the base station GTX is set to 10 instead of 30.  In this case, the SNR is higher than 90 so the base station GTX is set to 10 instead of 30. 
  
-The acknoledgment is still received correctly by the node as shown in terminal 14-a.+The acknoledgment is still received correctly by the node as shown in terminal NODE.phy.
  
 #### Simulate distance #### Simulate distance
  
-In order to simulate a less ideal situation and reduce the SNR, you can set the node GTX to 5 in terminal 14-b and send a new message.+In order to simulate a less ideal situation and reduce the SNR, you can set the node GTX to 5 in terminal NODE.up and send a new message.
  
 <code> <code>
Line 526: Line 534:
  
 Look at the answers in the other terminals: Look at the answers in the other terminals:
-14-a+ 
 +NODE.phy
  
 <code> <code>
Line 544: Line 553:
 </code> </code>
  
-16-a+BS.phy
  
 <code> <code>
Line 563: Line 572:
  
  
-16-b+BS.up
  
 <code> <code>
lora_dynamic_phy_layer_example.1624458227.txt.gz · Last modified: 2021/06/23 16:23 by pesteve

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki