== Outdoor spectrum usage and allocation ==

=== Description ===

Demonstrate outdoor spectrum usage using the RF control service and verify spectrum access by running a sdr application to transfer data on shared / non-federal frequency band.

=== Prerequisites  ===

In order to access the test bed, create a reservation and have it approved by the reservation service. Access to the resources is granted after the reservation is confirmed. Please follow the process shown on the COSMOS [wiki:GettingStarted getting started] page to get started.

=== Resources utilized ===
* This example will use two x310 SDR on bed.cosmos-lab.org
 * sdr2-s3-lg1.bed.cosmos-lab.org as the transmitting SDR
 * sdr2-s2-lg1.bed.cosmos-lab.org as the receiving SDR
* ''baseline-uhd.ndz'' : operating system to load onto above resources.

* [wiki:Resources/Services/RFControl RF control service] to configure the [wiki:Hardware/rf-front-end#RFFrontEnd RF front end's TX chain] on the transmitting SDR.

* [https://www.influxdata.com/products/influxdb-overview/ Influx database] - time series database supporting SQL-like queries. 
* [https://grafana.com/docs/grafana/latest/ Grafana] - a front end visualization and analytic tool for Influx database.


=== Steps ===
 1. Sign up for a [https://cosmos-lab.org/portal-2/ COSMOS account]
 2. [UserGuide/CreateRes Create a resource reservation on bed.cosmos-lab.org]
 3. [UserGuide/RemoteAccess/Console Login to your reserved domain.]
 4. Load baseline-uhd.ndz on your resource. [UserGuide/OmfQuickStart  - this is done via OMF]
 
 First make sure the resources are turned off
{{{#!shell-session
user@console:~$ omf tell -a offh -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org
}}}
	
 Load the resources with the image
{{{#!shell-session
user@console:~$ omf load -i baseline-uhd.ndz -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org
}}}

 Turn on the resources
{{{#!shell-session
user@console:~$ omf tell -a on -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org
}}}
	 
	 
 5. Download the application source code from the attachment section below.
{{{#!shell-session
user@console:~$ wget https://wiki.cosmos-lab.org/raw-attachment/wiki/Tutorials/Wireless/OutdoorSpectrumUsage/SDRAPP.tar.gz
user@console:~$ tar -zxvf SDRAPP.tar.gz
user@console:~$ cd SDRAPP
}}}


=== Configure transmitter and receive SDRs ===
 Most of this part is scripted via the Makefile. This is to simplify the download and installation of the required libraries onto the resources so we don't have to go back and forth between the console and the resource node.

 6. Build the transmit side sdr application.[[BR]]
 Open a terminal and equate the enviroment variable (NODE) to specify the transmitting SDR.
{{{#!shell-session
user@console:~$ export NODE=sdr2-s3-lg1.bed.cosmos-lab.org
}}}

 Next the following make commands are run on the above NODE. This should install all the dependencies to make the sdr application: ''sdrapp'' 
{{{#!shell-session
user@console:~$ make remote-install-deps
user@console:~$ make remote-install-websocket
user@console:~$ make remote-make
}}}


 Now ssh into the NODE and run sdrapp 
{{{#!shell-session
user@console:~$ ssh root@$NODE
root@sdr2-s3-lg1:~# cd SDRAPP/build/
root@sdr2-s3-lg1:~/SDRAPP/build# ./sdrapp --cmd "make resource=rio0"
}}}


 7. Build the receiving side sdr application.[[BR]]
 This is exactly the same as the above step but the environment variable NODE points to a different resource.
	
 Open a terminal again and equate the environment variable (NODE) to specify the receiving SDR.
{{{#!shell-session
user@console:~$ export NODE=sdr2-s2-lg1.bed.cosmos-lab.org
}}}

 Next the following make commands are run on the above NODE. This should install all the dependencies to make the sdr application: ''sdrapp''
{{{#!shell-session
user@console:~$ make remote-install-deps
user@console:~$ make remote-install-websocket
user@console:~$ make remote-make
}}}

 Now ssh into the NODE and run sdrapp 
{{{#!shell-session
user@console:~$ ssh root@$NODE
root@sdr2-s3-lg1:~# cd SDRAPP/build/
root@sdr2-s3-lg1:~/SDRAPP/build# ./sdrapp --cmd "make resource=rio0"
}}}

 Keep track of these two terminals. The sdr application will output text as it detected the radios on both transmitter and receiver. When both radios are ready, output similar to the following is shown
{{{#!shell-session
:
Number mboards        = 1
Number of rx channels = 2
Number of tx channels = 2
Setting device timestamp to 0...
Device storage: TX
 channels:          2
 buffers  / channel 80
 samples / buffer   256
 bytes / sample     8
 shared memory      0
Device storage: RX
 channels:          2
 buffers  / channel 78125
 samples / buffer   256
 bytes / sample     8
 shared memory      0
[INFO] [main.cpp] Rsp: make resource=rio0

[INFO] [main.cpp] Starting data server at 6180
[INFO] [main.cpp] Starting command server at 5180
[INFO] [main.cpp] Starting websock server at 9002


}}}


=== Turn on the transmitter's power amplifier ===

 8. Configure the transmit antenna using the RF Control service. Please check [wiki:Resources#RFControl here] for more details on the service. 
	
 Open another terminal - this is the 3rd terminal. First we'll configure the TX path, power amplifier and frequency ranges for the transmitting side. 

 Get current configuration 
{{{#!shell-session
user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/get_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org"

<response status="OK">
  <nodes>
    <node name="sdr2-s3-lg1.bed.cosmos-lab.org">
      <rf_port number="0" antenna="1" connected="true" power_amp="OFF" f_lower="2350" f_upper="2800"/>
      <rf_port number="1" antenna="3" connected="true" power_amp="OFF" f_lower="2350" f_upper="2800"/>
    </node>
  </nodes>
</response>
}}}

 Turn on  the power amplifier and set frequency appropriately. Check the [wiki:PoliciesCompliance#OutdoorRadioFrequencyAllocation Outdoor frequency allocation table] for acceptable frequency bands. 
 In this example a center frequency of 2600MHz is used.  
{{{#!shell-session
user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/set_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org&rf_port=0&power_amp=on&f_lower=2500&f_upper=2680"
}}}

=== Transmit and receive over the air ===
 9. Execute the run script to configure and stream both SDRs for receiving and transmitting bursts of packet data. The details in this script are shown below.
{{{#!shell-session
user@console:~$ sh run_data_script.sh
}}}

 The script configures sdr application with radio parameters and begins streaming packets for a few seconds. As long as everything is working fine the script will exit out but the sdr applications will continue to stream packets for a few seconds.

 On the transmit side the output should have rows of ''INFO'' statements similar to the following.
{{{#!shell-session
:
[INFO] [tx_data_link_0]   [sent]   seq_num: 62  pkt_len: 29
[INFO] [tx_data_link_0]   [sent]   seq_num: 63  pkt_len: 8
[INFO] [tx_data_link_0]   [sent]   seq_num: 64  pkt_len: 49
[INFO] [tx_data_link_0]   [sent]   seq_num: 65  pkt_len: 42
[INFO] [tx_data_link_0]   [sent]   seq_num: 66  pkt_len: 63
[INFO] [tx_data_link_0]   [sent]   seq_num: 67  pkt_len: 34
[INFO] [tx_data_link_0]   [sent]   seq_num: 68  pkt_len: 2
:
[INFO] [tx_data_link_0] Transmit complete - summary:
[INFO] [tx_data_link_0] --raw packets:   80 / 21760 bytes
[INFO] [tx_data_link_0] Exitting
:
}}}
	
 On the receive side a similar output is expected
{{{#!shell-session
:
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 55  pkt_len: 18  corr_strength: 18131.3
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 56  pkt_len: 15  corr_strength: 18124.4
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 57  pkt_len: 3  corr_strength: 18132.9
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 58  pkt_len: 53  corr_strength: 18148.1
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 59  pkt_len: 2  corr_strength: 18128.3
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 60  pkt_len: 34  corr_strength: 18161.1
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 61  pkt_len: 62  corr_strength: 18135.7
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 62  pkt_len: 29  corr_strength: 18164.7
:
[INFO] [rx_data_link_0] Receive complete - summary:
[INFO] [rx_data_link_0] --raw packets:   79 / 21488 bytes
[INFO] [rx_data_link_0] Avg correlation threshold of successful detections: 18148.4
[INFO] [rx_data_link_0] Exitting
:
}}}


 10. Lastly turn off the RF front end with the following command.
{{{#!shell-session
user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/set_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org&rf_port=0&power_amp=off"
<response status="OK">
  <message>OK</message>
</response>
}}}

 11. Execute the run script again and verify that no packets are received. The transmitters output will show the radio trying to send packets but since the power amplifier is turned on nothing is actually sent over the air. On the receiving end, the radio will still listen for packets however the summary should show 0 packets received.
{{{#!shell-session
:
[INFO] [rx_data_link_0] Receive complete - summary:
[INFO] [rx_data_link_0] --raw packets:   0 / 0 bytes
[INFO] [rx_data_link_0] Avg correlation threshold of successful detections: nan
[INFO] [rx_data_link_0] Exitting
:
}}}


====  Run script details ====
 View the run_data_script.sh file. A python script is used to remotely configure the sdr application on both the receiving and transmitting side from the console. 
{{{#!shell
user@console:~$ cat run_data_script.sh
## DESCRIPTION
##  Performs one way data transfer over the air using x310 USRPS.
##  sdrapp daemon must be running on the nodes specified under CONFIGURABLES.

## Python is used to script the sequence of commands issued to the sdrapp daemon.
## Usage:
##   python rc.py <MACHINE_NAME> <PORT> <sdrapp sub-command>
##
##     <MACHINE_NAME> is hostname of machine running sdrapp daemon
##     <PORT>         command listening port
## Format of python sub-commands are described below.
## Sub-commands have a companion handler in the sdrapp daemon.

## Note: This script can be run multiple times while sdrapp is running.
## However this is subject to the following known gotchas:
##  1) if the <rate> parameter is changed in the set up section
##     then the sdrapp must be restarted.
##  2) when rerunning this script the running handlers in sdrapp
##     must finish and exit first.


}}}

 The ''CONFIGURABLES'' section must have the target node variables pointing at the appropriate   devices:
{{{#!shell
## CONFIGURABLES
export TXNODE=sdr2-s3-lg1.bed.cosmos-lab.org
export RXNODE=sdr2-s2-lg1.bed.cosmos-lab.org
}}}

 The radio parameters are set up with the following lines.
{{{#!shell
## SET UP RADIO PORTION HERE
##  Script is set up for x310 which has 2 daughter cards hence 2 channels: {0,1}
##  Both channels must be set to the same sampling rate otherwise HW will barf!


##  Set up transmit / receive chain
##                       txconfig <ch> <freq> <rate> <gain>
##                       rxconfig <ch> <freq> <rate> <gain>

python rc.py $TXNODE 5180 "txconfig 0 2600e6 10e6 25"
python rc.py $TXNODE 5180 "rxconfig 0 2400e6 10e6 5"
python rc.py $TXNODE 5180 "txconfig 1 2000e6 10e6 0"
python rc.py $TXNODE 5180 "rxconfig 1 2050e6 10e6 5"

python rc.py $RXNODE 5180 "rxconfig 0 2600e6 10e6 5"
python rc.py $RXNODE 5180 "txconfig 0 2400e6 10e6 25"
python rc.py $RXNODE 5180 "rxconfig 1 2000e6 10e6 5"
python rc.py $RXNODE 5180 "txconfig 1 2050e6 10e6 0"

}}}

 After the set up is done, the sdr applications begin streaming data. The receiving end is started first with the specified runtime of 20 seconds. At the same time the transmitting end starts sending packets for 20 seconds at intervals of 250 milliseconds.
{{{#!shell
## BEGIN data transfer
##  Invoke receive handler
##                       rxsig_data <runtime_in_milliseconds> <correlation threshold>
python rc.py $RXNODE 5180 "rxsig_data 20000 10000"


##  Invoke transmit handler
##                       txsig_data <runtime_in_milliseconds> <delay_between_burst_in_msec>
python rc.py $TXNODE 5180 "txsig_data 20000 250"

echo "DONE!"
}}}

 After the run script initiates the receive and transmitter handlers on the sdr applications, the script will exit out back to the console but the sdr application handlers should be running for the specified run times. This script can be rerun only after the handlers exit.


In the [next part of this tutorial] we'll edit the the receiving sdr application to store measured data to a remote network Influx database.