[[Include(WikiToC)]]

= !SigComm 2022 Cosmos Testbed Tutorial =

== Dolphin Group ==
In this tutorial we'll demonstrate how to run a basic wireless experiment using software defined radios in the COSMOS testbed. Two COSMOS nodes will be used: one to transmit a signal, and the other to receive it.

=== Resources Used ===
For this example we'll use two USRP x310 SDRs on [https://www.orbit-lab.org/wiki/Hardware/bDomains/aGrid grid]. These SDRs have a PCIE connection to a PC, which is the device you're loading the orbit image onto and connecting to over ssh. They also have an fpga connected to the four antennas. We won't have to worry about the specifics of the USRP for this tutorial but you can look at the links on [https://www.ettus.com/all-products/x310-kit/ this page] for more information. 

=== Tutorial Setup ===
 Follow the steps below to gain access to the console and set up your node with an appropriate image. 
 1. Use ssh to connect to the console for the grid domain:
 {{{
 ssh your-username@console.grid.orbit-lab.org
 }}}
 NOTE: typically when using the testbed, you will have to reserve the domain you wish to use on the [https://www.orbit-lab.org/cPanel/controlPanel/start scheduler page]. We have already made the reservation for you.

 2. Use OMF commands to load the baseline-uhd.sdr image on your resources.

 OMF is a command line utility that is run from the console in order to manage nodes: turn them on and off, save the contents of the hard disk as an "image", and load saved images back onto them.

 In this case, we're loading the "baseline-sdr.ndz" image, which is a pre-built image provided for researchers to use as a starting point. The image contains UHD 3.15 and Gnuradio 3.8 and uses Ubuntu 18.04.
 {{{
 omf load -i baseline-sdr.ndz -t node3-1,node3-20
 }}}
 The output of this command can be a little intimidating, but make sure you should look for confirmation that both of your nodes were successfully imaged. An example of the output is below, with the outcome of the loading process highlighted in red.
 
 [[Image(wiki:Workshops/SigComm2022/group/labrador:load_example.png)]]

 3. Once the nodes are successfully imaged, turn them on and check the status
 {{{
 omf tell -a on -t node3-1,node3-20
 }}}
 {{{
 omf stat -t node3-1,node3-20
 }}}
 4. After waiting for the nodes to power up and boot, you will be able to ssh to them from the console:
 {{{
 ssh root@node3-1
 }}}
 
=== Experiment Execution ===

==== Configure and detect the radio ====

 1. Use {{{uhd_find_devices}}} to make sure that the onboard x310 SDR is detected as in the following image:

 [[Image(wiki:Tutorials/Wireless/introTutorial:find_devices.png)]]

 Notice that running this command with no arguments will sometimes detect other SDR resources in the testbed which are reachable over the network. We can ignore those for now and focus just on the onboard x310. 

 2.  Use the {{{uhd_usrp_probe}}} command to get more details on the x310 as in the following image. Specifying {{{--args="resource=rio0,type=x300"}}} ensures only the directly connected radio is probed, instead of the radios on the network.

 [[Image(wiki:Tutorials/Wireless/introTutorial:uhd_probe.png)]]

=== Run the experiment ===
For this demo, we'll be running some of the demo applications that are installed with uhd. Source code for all of the samples can be found here: [https://github.com/EttusResearch/uhd/tree/UHD-3.15.LTS/host/examples]
 1. ssh to node3-2 and start the rx_ascii_art_dft demo with the following command: 
 {{{
 /usr/lib/uhd/examples/rx_ascii_art_dft --args "resource=rio0,type=x300" --freq 2400e6 --rate 5e6 --frame-rate 10 --gain 10 --ref-lvl -30 --dyn-rng 70
 }}}
 Note that we are looking at the frequency band around 2.4GHz. You should see an output similar to this:

 [[Image(wiki:Tutorials/Wireless/introTutorial:rx-ascii-no-sig.png, width=1000px)]]

 2. ssh to node8-7 and start the tx_waveforms demo with the following command:
 {{{
 /usr/lib/uhd/examples/tx_waveforms --args="resource=rio0,type=x300" --wave-freq 1e6 --wave-type SINE --freq 2400e6 --rate 5e6 --gain 10 --ampl 0.2
 }}}

 As we can see from the arguments passed to the application, we are transmitting a 1MHz sine wave as a signal using 2.4GHz as the carrier frequency. On the DFT visualization on sdr2-md1, you should see a peak representing the transmitted signal:
 
 [[Image(wiki:Tutorials/Wireless/introTutorial:rx-ascii-sine-sig.png, width=1000px)]]

 We can generate a different type of signal by changing the {{{wave-type}}} argument. For instance, if we transmit a square wave:
 {{{
 /usr/lib/uhd/examples/tx_waveforms --args="resource=rio0,type=x300" --wave-freq 1e6 --wave-type SQUARE --freq 2400e6 --rate 5e6 --gain 10 --ampl 0.2
 }}}

 We can see that the spectrum of the received signal now contains multiple peaks. This is the result of the spectral characteristics of a square wave.
  
 [[Image(wiki:Tutorials/Wireless/introTutorial:rx-ascii-square-sig.png, width=1000px)]]

 Both {{{tx_waveforms}}} and {{{rx_ascii_art_dft}}} can take {{{--help}}} as a command line argument, which will display the lists of arguments that you can provide and what each argument does. There are also a number of other demo applications in the {{{/usr/lib/uhd/examples}}} directory, which you can take a look at.